Mise à jour vers une nouvelle version de Terraform

Les outils IaC open source utilisés par Schematics évoluent, avec de nouvelles versions de Terraform et de Helm, ainsi que les fournisseurs Terraform de support. Au fil du temps, il est nécessaire de mettre à niveau les environnements d'espace de travail à longue durée de vie afin d'utiliser la dernière version de Terraform car les versions plus anciennes sont obsolètes et ne sont plus prises en charge.

Tous les utilisateurs de Schematics sont encouragés à effectuer une mise à niveau régulière vers la dernière version de Terraform afin d'assurer la continuité des opérations et de la prise en charge. Schematics suit le modèle de prise en charge Hashicorp pour les éditions Terraform et déprécie les versions en ligne avec Hashicorp.

Terraform v1.0 était une édition majeure de Terraform, marquant la transition vers une édition 1.x stable. Hashicorp a fait des promesses de compatibilité pour les éditions 1.x, que pour les fonctions de base, aucune modification supplémentaire n'est requise pour la mise à niveau via les éditions 1.x.

En résumé, il vise à simplifier les mises à niveau entre les éditions v1.x, en ne nécessitant aucune modification de votre configuration, aucune commande pour exécuter les étapes de mise à niveau et aucune modification de l'automatisation que vous avez configurée autour de Terraform.

La mise à niveau vers les éditions 1.x ne nécessite aucune action d'espace de travail Schematics spécifique. Consultez les guides de mise à niveau Terraform pour connaître les modifications spécifiques à l'édition qui peuvent nécessiter des mises à jour TF config/template.

Mise à niveau du modèle Terraform version 1.x et ultérieure

Depuis Terraform 1.0, les espaces de travail Schematics peuvent être mis à jour vers des éditions 1.x plus récentes, en modifiant simplement la version de l'espace de travail. Pour mettre à jour à partir des éditions 0.x, voir la section Mise à niveau du modèle Terraform version 0.x

Schematics prend en charge Terraform_v1.x et prévoit de rendre les éditions disponibles 45-60 days après une disponibilité générale. Il est recommandé que les modèles Terraform utilisent une contrainte de plage de versions, telle que >, >= ou ~> pour le paramètre required_version dans le fichier versions.tf du modèle Terraform, qui permet la mise à niveau pour les éditions mineures et les correctifs. Cela permet à Schematics d'adopter automatiquement le dernier correctif ou l'édition mineure de la version Terraform, comme défini par la version de l'espace de travail.

terraform {
required_version = "~> 1.1"
}

Mise à jour de l'espace de travail Terraform 1.x version

La version en cours d'utilisation de Terraform pour un espace de travail peut être mise à jour via l' Schematics espace de travail API de mise à jour.

Le paramètre de version terraform de l'espace de travail est au format terraform_v1.4 ou terraform_v1.5

Sélectionnez l'espace de travail à mettre à jour et vérifiez qu'il est à l'état Normal et qu'une opération de plan ne génère aucune modification de ressource proposée. Sauvegardez le fichier workspace_id et notez la région dans laquelle l'espace de travail est hébergé.
Mettez à jour la version terraform de l'espace de travail à l'aide de l'interface de ligne de commande et de l'API IBM Cloud. Ces opérations d'espace de travail sont spécifiques à la région. Notez la région de l'espace de travail à partir de l'interface utilisateur car elle est requise pour les commandes suivantes:
- Connectez-vous à l'interface de ligne de commande IBM Cloud avec ibmcloud login
- Définissez la région cible de l'interface de ligne de commande avec ibmcloud target -r <region> pour qu'elle soit identique à l'espace de travail que vous mettez à jour.
- Générez un jeton IAM oauth à utiliser avec l'API Schematics, avec la commande ibmcloud iam oauth-tokens.
- Copiez les données du jeton et insérez-le dans le texte de commande suivant, en remplaçant la chaîne <token-data>, définissez <terraform_version> sur la version Terraform requise et sur <workspace_id>:
- L'espace de travail est mis à jour en exécutant une commande cURL pour appeler l'API de mise à jour Schematics pour mettre à jour la version Terraform. Cette opération est spécifique à la région et doit spécifier le noeud final de région d'APISchematics souhaité pour la région cible de l'espace de travail. Remplacez le texte <schematics-region-endpoint> dans la commande par le noeud final de la région de l'espace de travail cible.
```
    curl -X PUT https://<schematics-region-endpoint>.cloud.ibm.com/v1/workspaces/<w_id> \
    -H 'Authorization: Bearer <token>' \
    -H 'refresh_token: <token>' \
    -d '{
    "type": [
        "<terraform_version>"
    ],
    "template_data": [
        {
            "folder": ".",
            "type": "<terraform_version>"
        }
    ]
    }'
```
Vérifiez dans la page des paramètres de l'espace de travail que la version TF est désormais définie sur la version souhaitée.
Exécutez une opération Générer un plan sur l'espace de travail. Vérifiez que la commande s'exécute correctement sans erreur et qu'aucun message inattendu n'est consigné. Le plan ne devrait pas entraîner de changements proposés aux ressources.
Exécutez une opération Appliquer le plan sur l'espace de travail. Vérifiez que la commande s'exécute correctement sans erreur et qu'aucun message inattendu n'est consigné.
La mise à niveau a abouti.

Mise à niveau du modèle Terraform version 0.x vers 1.x

Dans les éditions 0.x, la mise à niveau de la version de Terraform est un processus pas à pas, qui passe par chaque édition. La mise à niveau ne prend pas en charge la mise à niveau entre plusieurs éditions et doit être effectuée, édition par édition. Certaines mises à jour nécessitent l'exécution de commandes upgrade Terraform pour modifier les fichiers de configuration. Les modifications apportées au fichier d'état Terraform sont également nécessaires. Ces étapes ne peuvent pas être effectuées dans Schematics. Les modèles Terraform de l'espace de travail doivent être mis à niveau à l'aide d'une copie locale de Terraform. Suivez les étapes de mise à niveau des éditions 0.x.

Liste des versions Terraform
Version	Recommandation
`v0.12`	Consultez le guide de mise à niveau dev0.13 et suivez les instructions Mise à niveau d'un espace de travail Terraform v0.12 vers v0.13. Schematics est obsolète `Terraform v0.12`.
`v0.13`	Pour la mise à niveau de `Terraform v0.14`, vous devez exécuter `terraform apply` avec `Terraform v0.14` pour terminer les mises à niveau de son format d'état. Si vous rencontrez des erreurs, reportez-vous au document v0.14-Guide de mise à niveau. Suivez les instructions upgrade-13-to10
`v0.14`	Vous pouvez effectuer une mise à niveau directement vers la version `Terraform v1.0`. Consultez le guide de mise à niveau d'v0.15.
`v0.15`	Vous pouvez effectuer une mise à niveau directement vers la version `Terraform v1.0`. Consultez le document v1.0-Guide de mise à niveau.

Mise à niveau d'un espace de travail Terraform v0.12 vers v0.13

La mise à niveau d'un espace de travail v0.12 pour utiliser la version v0.13 de Terraform est une tâche en plusieurs étapes. Vous devez consulter attentivement le guide de mise à niveau Terraform pour la mise à niveau de la version associée.

Suivez les étapes suivantes pour passer à la version actuelle de Terraform dans l'espace de travail Schematics.

Mettez à niveau les fichiers de configuration Terraform en vue de l'utilisation de la syntaxe et de la sémantique les plus récentes.
Migrer le fichier d'état Terraform pour qu'il soit compatible avec la nouvelle version. Schematics ne prend pas en charge la modification intégrée du fichier d'état Terraform. Par conséquent, vous devez procéder comme indiqué.
1. Préparez la version mise à niveau des fichiers de configuration de Terraform et le fichier d'état de Terraform sur votre machine locale.
2. Créez le nouvel espace de travail Schematics avec les nouveaux fichiers de configuration Terraform et le fichier d'état Terraform.
3. Supprimez l'ancien espace de travail sans détruire les ressources.

Les étapes détaillées de la mise à niveau de 0.12 vers 0.13:

Vérifiez si vos espaces de travail Schematics à l'adresse v0.12 comportent des ressources, si la dernière application a abouti et si l'espace de travail est à l'état normal. Vérifiez que les fichiers de configuration Terraform et le fichier d'état Terraform sont dans un état cohérent pour Terraform v0.12.
Téléchargez ou clonez le dépôt Git utilisé par votre espace de travail Terraform v0.12 Schematics sur votre machine locale.
Installez Terraform 0.13 sur votre machine locale.
Changez de répertoire vers votre dépôt cloné et mettez à jour vos fichiers de configuration vers Terraform v0.13 en exécutant la commande Terraform v0.13upgrade. Pour plus d'informations, voir la documentation sur la mise à niveau vers Terraform v0.13. La commande de mise à niveau génère un fichier versions.tf avec un bloc de configuration terraform.

Editez le fichier versions.tf pour définir le paramètre source sur source = "IBM-Cloud/ibm" comme indiqué dans le bloc de code.

Fichier versions.tf

terraform {
    required_providers {
    ibm = {
      # TF-UPGRADE-TODO
      #
      # No source detected for this provider. You must add a source address
      # in the following format:
      #
      source = "IBM-Cloud/ibm"
      #
      # For more information, see the provider source documentation:
      #
    }
    }
    required_version = ">= 0.13"
}

Téléchargez le fichier d'état de Terraform à partir de l'espace de travail Schematics existant, à l'aide de la commande Schematics state pull.

Lorsque l'espace de travail est créé avec tfstate Schematics, il est considéré comme un fichier sécurisé. En outre, vous ne pouvez pas extraire le fichier tfstate créé via l'interface utilisateur. Vous devez utiliser la ligne de commande pour extraire le fichier d'état et créer un espace de travail.

Copiez le fichier d'état téléchargé en tant que terraform.tfstate dans le dossier d'exécution Terraform.
Exécutez la commande de fournisseur de remplacement d'état sur la ligne de commande pour mettre à jour la version de fournisseur IBM Cloud dans le fichier d'état.
```
terraform state replace-provider registry.terraform.io/-/ibm registry.terraform.io/ibm-cloud/ibm.
```
Vérifiez que les mises à jour sont apportées au fichier terraform.tfstate avec la mise à jour de la version Terraform de 1.3 vers >= 1.4 et le fournisseur mis à jour en tant que registry.terraform.io/ibm-cloud/ibm.
Envoyez par commande push les fichiers de configuration TF mis à niveau et version.tf vers votre référentiel Git.
Copiez le contenu du fichier terraform.tfstate modifié dans le fichier state.json.
Créez ou mettez à jour un fichier workspace.json comme indiqué dans le bloc de code.

{
    "name": "gb",
    "type": [
        "terraform_v1.4"
    ],
    "description": "migration workspace",
    "template_repo": {
        "url": "Provide your Git repository link"
    },
    "workspace_status" : {
        "frozen": false
    },
    "template_data": [{
        "folder": ".",
        "type": "terraform_v1.4"
    }]
}

Exécutez ces commandes en ligne de commande pour créer un nouvel espace de travail Terraform v0.13 :

ibmcloud schematics workspace new --file workspace.json --state state.json.
ibmcloud schematics workspace get --id <workspace-id>. Si l'état de votre espace de travail n'est pas inactive, attendez quelques secondes et réessayez la commande.
ibmcloud schematics plan id <workspace id>.
ibmcloud schematics job get --id <job-id form plan>. Si l'état du plan de l'espace de travail n'est pas success, attendez quelques secondes et réessayez la commande.
ibmcloud schematics apply --id <workspace id>.
ibmcloud schematics job get --id <job-id from apply>.

[En option], vous pouvez supprimer l'espace de travail Schematics qui utilise Terraform v0.12.

Ne détruisez pas les ressources utilisées par votre ancien espace de travail.

Mise à niveau du modèle Terraform de `v0.13` et versions ultérieures vers `v1.0`

Les versions 0.13 à 0.15 nécessitent une mise à niveau progressive, 0.13 to 0.14, 0.14 to 0.15, 0.15 to 1.0.

Le processus est le même pour chaque étape de version. Il est obligatoire qu'une application Terraform soit exécutée après chaque changement de version. Le fichier d'état Terraform est mis à jour avec les modifications de schéma liées à cette version et à cette version uniquement. Après la mise à niveau réussie d'une version unique, la mise à jour de version suivante peut être effectuée.