Unité 1.2 : Fournisseur Terraform et modèles de base

Introduction

Dans l'unité 1.1, vous avez provisionné un serveur de trois manières : via l'API brute avec curl, le SDK Python, et ionosctl. Les trois approches sont impératives. Vous émettez une POST, interrogez /requests/{id}/status jusqu'à ce que DONE, puis vous émettez l'appel suivant. Cela fonctionne, mais cela ne vous fournit pas une description reproductible et sous contrôle de version de votre infrastructure. Pour TaskBoard, l'API de gestion des tâches et le front-end que vous développez au cours de ce module, vous avez besoin d'une infrastructure qui réside dans Git, qui est examinée comme du code, et qui se démantèle proprement afin que les environnements de test ne vous facturent jamais silencieusement.

Cette unité vous amène vers le provisionnement déclaratif avec le fournisseur Terraform IONOS CLOUD. Vous rédigerez le HCL qui construit le VDC de base de TaskBoard, observerez ce que Terraform fait en interne avec l'API asynchrone IONOS CLOUD, stockerez l'état à distance dans Object Storage, et adopterez le modèle d'environnement éphémère qui permet de maîtriser les coûts. L'interrogation asynchrone que vous avez gérée manuellement dans l'unité 1.1 est désormais la responsabilité du fournisseur.

1. Configuration et authentification du fournisseur

Le fournisseur IONOS CLOUD pour Terraform interagit avec les ressources de calcul, de stockage et de réseau d'IONOS CLOUD. Il prend actuellement en charge les offres API V5 et V6 les plus récentes, et est publié sur le Terraform Registry sous ionos-cloud/ionoscloud. Avant que quoi que ce soit fonctionne, vous devez disposer d'un compte IONOS CLOUD dont les identifiants s'authentifient auprès de l'API Cloud, exactement comme dans l'Unité 1.1.

1.1 Déclaration et verrouillage de la version du fournisseur

Verrouillez toujours la version du fournisseur. Le bloc required_providers de Terraform vous permet de vous verrouiller sur une version connue et fiable, afin qu'un terraform init le mois prochain n'entraîne pas un changement cassant dans votre pipeline.

# versions.tf
terraform {
  required_version = ">= 1.5.0"

  required_providers {
    ionoscloud = {
      source  = "ionos-cloud/ionoscloud"
      version = "~> 6.4"
    }
  }
}

La contrainte ~> 6.4 autorise les mises à jour de correctif et mineures au sein de la ligne 6.x, mais bloque le passage à la version 7.0. Exécutez terraform init pour télécharger le fournisseur épinglé dans .terraform/. Commitez le fichier .terraform.lock.hcl généré afin que chaque membre de l'équipe et chaque exécuteur CI résolve la même version du fournisseur.

1.2 Authentification : variable d'environnement par rapport au bloc de fournisseur

Le modèle le plus propre consiste à s'authentifier à l'aide du jeton d'accès de Token Manager (décrit dans l'unité 1.1) via la variable d'environnement IONOS_TOKEN. Aucune information confidentielle ne touche alors votre HCL ni votre historique Git.

export IONOS_TOKEN="eyJ0eXAiOiJKV1QiLCJraWQiO..."
terraform plan

La variable étant définie, le bloc provider peut être vide :

# provider.tf
provider "ionoscloud" {}

Vous pouvez également transmettre explicitement les identifiants dans le bloc de fournisseur, ce qui est utile lorsqu'une configuration unique gère des ressources sur plus d'un compte. L'authentification par nom d'utilisateur et mot de passe (authentification de base) est prise en charge en alternative au jeton.

provider "ionoscloud" {
  token = var.ionos_token   # never hardcode; pass via TF_VAR_ionos_token
}

Préférez la variable d'environnement IONOS_TOKEN à un jeton enregistré dans un fichier .tfvars. Si vous devez utiliser une variable, marquez-la sensitive = true et fournissez-la via TF_VAR_ionos_token dans votre shell ou votre magasin de secrets CI.

2. Ressources principales : création d'un VDC

Un environnement de base TaskBoard nécessite un centre de données virtuel, un LAN, un serveur, un volume de démarrage et une carte réseau (NIC) reliant le serveur au LAN. Chaque ressource Terraform d'IONOS CLOUD est préfixée par ionoscloud_, ce qui les rend non ambiguës lorsqu'une configuration mélange plusieurs fournisseurs.

2.1 Centre de données, LAN, serveur, Volume, NIC

Les noms de ressources ci-dessous (ionoscloud_datacenter, ionoscloud_lan, ionoscloud_server, ionoscloud_nic) et leurs schémas d'attributs suivent la documentation du fournisseur Terraform d'IONOS CLOUD. La valeur de localisation et la sélection d'image sont fondées sur les sections de sources de données de cette unité.

# main.tf
resource "ionoscloud_datacenter" "taskboard" {
  name        = "taskboard-base"
  location    = "de/fra"
  description = "TaskBoard base VDC, managed by Terraform"
}

resource "ionoscloud_lan" "app" {
  datacenter_id = ionoscloud_datacenter.taskboard.id
  name          = "taskboard-app-lan"
  public        = true
}

resource "ionoscloud_server" "api" {
  name              = "taskboard-api"
  datacenter_id     = ionoscloud_datacenter.taskboard.id
  cores             = 2
  ram               = 4096
  cpu_family        = "INTEL_SKYLAKE"
  availability_zone = "AUTO"

  volume {
    name           = "taskboard-api-boot"
    size           = 20
    disk_type      = "SSD"
    image_name     = data.ionoscloud_image.ubuntu.id
    image_password = var.server_password
  }

  nic {
    lan  = ionoscloud_lan.app.id
    dhcp = true
  }
}

Remarquez que les blocs volume et nic en ligne vous permettent d'exprimer le disque de démarrage et la connexion réseau en tant que partie du serveur. Pour un Volume de données que vous attachez après le démarrage, ou pour gérer le cycle de vie d'un disque de manière indépendante, déclarez à la place un ionoscloud_volume autonome.

2.2 Volume et NIC autonomes

resource "ionoscloud_volume" "data" {
  datacenter_id = ionoscloud_datacenter.taskboard.id
  server_id     = ionoscloud_server.api.id
  name          = "taskboard-data"
  size          = 50
  disk_type     = "SSD"
  licence_type  = "OTHER"
}

resource "ionoscloud_nic" "extra" {
  datacenter_id = ionoscloud_datacenter.taskboard.id
  server_id     = ionoscloud_server.api.id
  lan           = ionoscloud_lan.app.id
  dhcp          = true
}

Les références telles que ionoscloud_datacenter.taskboard.id et ionoscloud_server.api.id sont ce qui confère à Terraform son ordonnancement. Étant donné que le server_id du volume lit à partir de la ressource serveur, Terraform sait que le serveur doit exister en premier. Vous n'écrivez jamais de logique explicite de type « attendre le centre de données ». Ce graphe de dépendances est l'essence même de l'abandon des scripts impératifs de l'Unité 1.1.

3. Le cycle de vie plan/apply/destroy

Les trois commandes que vous utiliserez constamment sont terraform plan, terraform apply et terraform destroy. Comprendre ce que chacune fait par rapport à l'API asynchrone IONOS CLOUD vous fera gagner des heures et évitera de nombreuses confusions.

3.1 Ce qui se passe en coulisses

terraform plan lit votre HCL, lit l'état actuel, interroge l'API IONOS CLOUD pour obtenir l'état en direct de chaque ressource gérée, et affiche les différences. Il ne modifie rien. terraform apply exécute ces différences en émettant les mêmes appels POST, PUT et DELETE que vous avez effectués manuellement dans la section 1.1.

Voici le point clé : les opérations de l'API IONOS CLOUD sont asynchrones. Un POST renvoie un identifiant de requête et la ressource n'est pas encore prête. Dans l'unité 1.1, vous avez interrogé /requests/{id}/status jusqu'à ce que DONE soit atteint avant l'appel suivant. Le fournisseur Terraform IONOS CLOUD effectue cette interrogation en interne pour chaque ressource. Lorsque apply indique qu'une ressource est encore en cours de création, il attend précisément cet état de requête avant de passer aux ressources dépendantes.

terraform plan -out=taskboard.tfplan
terraform apply taskboard.tfplan

La capture du plan dans un fichier à l'aide de -out et l'application de ce fichier exact garantissent que apply exécute précisément ce qui a été examiné, sans dérive entre le plan et l'application. Il s'agit du modèle sûr pour CI/CD.

3.2 Destruction et opérations ciblées

# Preview what will be torn down
terraform plan -destroy

# Tear it all down
terraform destroy

# Operate on a single resource (use sparingly)
terraform apply -target=ionoscloud_server.api

terraform destroy parcourt le graphe de dépendances en sens inverse : les interfaces réseau et les volumes avant le serveur, le serveur avant le LAN, le LAN avant le centre de données. Cet ordre inverse est la raison pour laquelle vous devez laisser Terraform gérer l'ensemble de la pile plutôt que de supprimer manuellement des ressources dans le DCD, ce qui peut laisser l'état de Terraform désynchronisé par rapport à la réalité.

4. État distant sur Object Storage

Par défaut, Terraform écrit l'état dans un fichier local terraform.tfstate. Cela ne fonctionne pas pour une équipe ou un pipeline. L'état doit être stocké dans un emplacement partagé, et IONOS Cloud Object Storage est compatible avec S3, ce qui en fait un backend adapté pour Terraform.

4.1 Configuration du backend S3

IONOS CLOUD Object Storage s'authentifie à l'aide d'une Access Key et d'une Secret Key, et non de jetons bearer. Il s'agit des mêmes identifiants S3 que vous générez dans la gestion des clés Object Storage. Object Storage est disponible dans plusieurs régions, chacune ayant son propre point d'accès, y compris Francfort (de) à s3.eu-central-1.ionoscloud.com, Berlin (eu-central-2) à s3.eu-central-2.ionoscloud.com, et Logroño (eu-south-2) à s3.eu-south-2.ionoscloud.com.

# backend.tf
terraform {
  backend "s3" {
    bucket   = "taskboard-tfstate"
    key      = "base/terraform.tfstate"
    region   = "eu-central-1"
    endpoints = {
      s3 = "https://s3.eu-central-1.ionoscloud.com"
    }
    skip_credentials_validation = true
    skip_region_validation      = true
    skip_requesting_account_id  = true
    skip_s3_checksum            = true
  }
}

Les drapeaux skip_* sont obligatoires, car il s'agit d'un fournisseur S3 externe (non-AWS). Sans eux, le back-end tente d'appeler des points de terminaison spécifiques à AWS, tels que le Security Token Service, et échoue. Fournissez les identifiants via les variables d'environnement S3 standard afin qu'ils n'apparaissent jamais dans votre HCL :

export AWS_ACCESS_KEY_ID="your-object-storage-access-key"
export AWS_SECRET_ACCESS_KEY="your-object-storage-secret-key"
terraform init   # migrates local state into the bucket

4.2 Considérations relatives au verrouillage de l'état

Le verrouillage de l'état empêche deux exécutions apply de corrompre l'état simultanément. Les backends AWS S3 s'appuient traditionnellement sur une table DynamoDB pour les verrous, ce que IONOS CLOUD Object Storage ne fournit pas. Considérez le backend IONOS CLOUD S3 comme non verrouillé : sérialisez les applications via un unique pipeline CI/CD, n'exécutez jamais d'appliqués simultanés sur la même clé d'état, et utilisez une clé d'état key distincte pour chaque environnement (par exemple base/, staging/, prod/) afin que des piles non liées ne soient jamais en concurrence.

5. Sources de données, importations et contrôle des coûts

L'écriture en dur des identifiants d'images et des chaînes de caractères de région rend les configurations fragiles. Les sources de données interrogent l'API IONOS CLOUD au moment de la planification afin que votre HCL reste portable. Les importations permettent de placer sous gestion les ressources créées en dehors de Terraform. Et une destruction rigoureuse permet de garder vos factures honnêtes.

5.1 Sources de données pour les images et les emplacements

data "ionoscloud_location" "frankfurt" {
  name    = "fra"
  feature = "SSD"
}

data "ionoscloud_image" "ubuntu" {
  type     = "HDD"
  location = "de/fra"
  cloud_init = "V1"
  image_alias = "ubuntu:latest"
}

La source de données ionoscloud_image résout une image actuelle afin que vous ne fixiez pas un UUID d'image obsolète susceptible d'être retiré. La source de données ionoscloud_location confirme une région et la disponibilité de ses fonctionnalités avant que vous ne la provisionniez. Référencez le résultat avec data.ionoscloud_image.ubuntu.id dans le bloc volume du serveur, comme indiqué à la section 2.

Le tableau suivant résume les quatre méthodes pour piloter le provisionnement IONOS CLOUD que vous avez vues dans les unités 1.1 et 1.2.

Utilisez Terraform lorsque l'infrastructure doit être reproductible et examinée. Utilisez le SDK ou ionosctl pour les opérations d'exécution et les vérifications rapides qui n'appartiennent pas à votre pile déclarative.

5.2 Importation de ressources existantes

Si un datacenter ou un serveur existe déjà, peut-être créé dans le DCD ou par un script curl antérieur, importez-le plutôt que de le recréer. Rédigez d'abord un bloc de ressource correspondant, puis importez-le. Les importations IONOS CLOUD utilisent un ID composite associant l'ID du datacenter et l'ID de la ressource.

# Import an existing server: format is datacenter_id/server_id
terraform import ionoscloud_server.api \
  3fa85f64-5717-4562-b3fc-2c963f66afa6/9bc92f81-1234-4cde-8901-abcdef012345

# Import a datacenter (single ID)
terraform import ionoscloud_datacenter.taskboard 3fa85f64-5717-4562-b3fc-2c963f66afa6

Après l'importation, exécutez terraform plan. Si le plan affiche des modifications, votre HCL ne correspond pas encore à la réalité. Réconciliez les attributs du bloc de ressource avec la configuration en cours d'exécution jusqu'à ce que plan ne signale plus de modifications. Ce n'est qu'à ce moment que la ressource est gérée en toute sécurité.

5.3 Prise de conscience des coûts et environnements éphémères

Chaque ressource que Terraform provisionne sur apply génère des frais dès le moment où elle existe. Le flux de travail discipliné consiste à : toujours plan avant apply, et toujours destroy ce que vous avez déployé pour les tests. Le modèle d'environnement éphémère crée une pile complète pour une exécution de test, puis la démantèle.

# Spin up a throwaway environment for a feature branch
terraform workspace new pr-142
terraform apply -auto-approve

# ... run integration tests against the live infrastructure ...

# Tear it all down so it stops billing
terraform destroy -auto-approve
terraform workspace delete pr-142

Intégrer terraform destroy à l'étape de démantèlement d'un job CI garantit qu'un environnement de branche oublié ne puisse pas accumuler silencieusement des coûts pendant des semaines.

Fiche de référence rapide de l'API

Le fournisseur Terraform IONOS CLOUD appelle ces points de terminaison de l'API Cloud en arrière-plan. Les connaître vous aide à déboguer un apply bloqué.

URL de base : https://api.ionos.com/cloudapi/v6 Authentification : Authorization: Bearer <token> (le fournisseur lit IONOS_TOKEN)

Atelier de code

Objectif : Construire le VDC de base de TaskBoard avec Terraform : un datacenter, un LAN et un serveur avec un volume attaché. Planifier, appliquer, vérifier et détruire.

Prérequis :

• Compte IONOS CLOUD avec un jeton API exporté en tant que IONOS_TOKEN
• Terraform 1.5 ou ultérieur installé localement
• ionosctl configuré (depuis l'Unité 1.1) pour la vérification

Étape 1 : Créer la structure de la configuration

mkdir taskboard-base && cd taskboard-base
touch versions.tf provider.tf main.tf

Sortie attendue :

(no output; three empty files created)

Étape 2 : Ajouter le fournisseur et épingler la version

Placez le contenu versions.tf de la section 1.1 et provider "ionoscloud" {} de la section 1.2 dans vos fichiers, puis initialisez.

terraform init

Sortie attendue :

Initializing provider plugins...
- Installing ionos-cloud/ionoscloud v6.4.x...
Terraform has been successfully initialized!

Étape 3 : Écrire les ressources VDC

Ajoutez les blocs ionoscloud_datacenter, ionoscloud_lan et ionoscloud_server de la section 2.1, ainsi que la source de données ionoscloud_image de la section 5.1, à main.tf.

Étape 4 : Planifier et examiner

export TF_VAR_server_password="ChangeMe-Strong-Pw-1"
terraform plan -out=taskboard.tfplan

Sortie attendue :

Plan: 3 to add, 0 to change, 0 to destroy.

Étape 5 : Appliquer

terraform apply taskboard.tfplan

Sortie attendue :

ionoscloud_datacenter.taskboard: Creation complete after 25s [id=3fa85f64-...]
ionoscloud_server.api: Still creating... [1m20s elapsed]
ionoscloud_server.api: Creation complete after 2m10s [id=9bc92f81-...]
Apply complete! Resources: 3 added, 0 changed, 0 destroyed.

Étape 6 : Vérifier avec ionosctl

terraform output -raw datacenter_id 2>/dev/null || true
ionosctl server list --datacenter-id $(terraform state show ionoscloud_datacenter.taskboard | grep -m1 'id ' | awk '{print $3}' | tr -d '"')

Sortie attendue :

ServerId   Name            State       Cores   Ram
9bc92f81   taskboard-api   AVAILABLE   2       4096

Étape 7 : Inspecter l'état

terraform state list

Sortie attendue :

data.ionoscloud_image.ubuntu
ionoscloud_datacenter.taskboard
ionoscloud_lan.app
ionoscloud_server.api

Liste de contrôle de validation :

• [ ] terraform apply terminé avec 3 ressources ajoutées
• [ ] ionosctl server list affiche le serveur comme AVAILABLE
• [ ] terraform state list affiche toutes les ressources gérées

Nettoyage :

terraform destroy -auto-approve

Erreurs courantes

1. Suppression de ressources dans le DCD gérées par Terraform

   • Problème : Vous supprimez le serveur manuellement dans l'interface web, puis terraform apply génère une erreur ou tente de recréer des ressources non liées.
   • Cause : L'état de Terraform enregistre toujours le serveur supprimé. L'API en cours d'exécution ne le contient plus, ce qui entraîne une divergence entre l'état et la réalité.
   • Correction : Supprimez l'entrée obsolète de l'état, puis laissez Terraform effectuer la réconciliation :

   terraform state rm ionoscloud_server.api
   terraform plan   # now matches reality
   

2. Oubli des drapeaux d'ignorance du backend S3

   • Problème : terraform init contre le backend Object Storage reste suspendu ou échoue avec une erreur STS ou d'identifiant de compte.
   • Cause : Le backend S3 suppose qu'il s'agit d'AWS et tente des appels spécifiques à AWS que IONOS CLOUD Object Storage n'implémente pas.
   • Correction : Ajoutez les drapeaux d'ignorance et le point de terminaison explicite au bloc backend :

   skip_credentials_validation = true
   skip_region_validation      = true
   skip_requesting_account_id  = true
   endpoints = { s3 = "https://s3.eu-central-1.ionoscloud.com" }
   

3. Épingler un UUID d'image obsolète au lieu d'utiliser une source de données

   • Problème : terraform apply échoue avec une erreur d'image introuvable des mois après le dernier bon fonctionnement de la configuration.
   • Cause : Un UUID d'image codé en dur a été retiré en amont. La création asynchrone du serveur est interrompue car son volume de démarrage référence une image manquante.
   • Correction : Résoudre l'image au moment de la planification à l'aide de la source de données et y faire référence :

   data "ionoscloud_image" "ubuntu" {
     type        = "HDD"
     location    = "de/fra"
     image_alias = "ubuntu:latest"
   }
   # volume { image_name = data.ionoscloud_image.ubuntu.id }
   

Résumé

Vous pouvez désormais décrire l'infrastructure IONOS CLOUD de manière déclarative et gérer son cycle de vie complet à partir du code. Vous avez configuré et verrouillé la version du fournisseur Terraform IONOS CLOUD, vous êtes authentifié avec IONOS_TOKEN, et vous avez construit le VDC de base de TaskBoard à partir de ressources ionoscloud_datacenter, ionoscloud_lan, ionoscloud_server, ionoscloud_volume et ionoscloud_nic. Vous avez déplacé l'état vers un backend Object Storage compatible S3, utilisé des sources de données pour résoudre dynamiquement les images et les emplacements, importé des ressources existantes et adopté le modèle d'environnement éphémère afin que l'infrastructure de test soit démantelée proprement.

Le modèle d'approvisionnement asynchrone que vous avez géré manuellement dans l'unité 1.1 est désormais une préoccupation interne du fournisseur : Terraform interroge le statut des requêtes pour vous et ordonne les opérations via son graphe de dépendances. À partir d'ici, chaque unité d'infrastructure de ce cours s'appuie sur cette même base Terraform.

Points clés :

• Le fournisseur IONOS CLOUD prend en charge les offres API V5 et V6 ; verrouillez toujours la version avec required_providers et committez le fichier de verrouillage
• Authentifiez-vous avec IONOS_TOKEN afin qu'aucun secret n'entre dans votre HCL ; toutes les ressources sont préfixées par ionoscloud_
• Terraform interroge l'endpoint asynchrone /requests/{id}/status en interne et ordonne les opérations via le graphe de dépendances des ressources
• Le backend Object Storage S3 nécessite les drapeaux skip_* et un endpoint IONOS CLOUD explicite, et s'authentifie avec une Access Key et une Secret Key, et non avec un jeton bearer
• Effectuez toujours plan avant apply et destroy les environnements éphémères pour contrôler les coûts

Terminologie importante :

• Fournisseur : Le plugin qui traduit les ressources HCL en appels API IONOS CLOUD, publié sous la forme ionos-cloud/ionoscloud
• État : L'enregistrement de Terraform des ressources IONOS CLOUD réelles qu'il gère, stocké localement ou dans un backend Object Storage
• Source de données : Une requête en lecture seule sur l'API IONOS CLOUD au moment de la planification, telle que ionoscloud_image, utilisée pour éviter de coder en dur les identifiants
• Import : La prise en charge d'une ressource IONOS CLOUD existante par Terraform à l'aide d'un identifiant composé datacenter_id/resource_id
• Environnement éphémère : Une pile complète créée pour une exécution de test et démantelée avec terraform destroy pour éviter les frais résiduels

Prochaines étapes

Continuer l'apprentissage : Unité 1.3 : Vérification des connaissances - Fondements de la programmation

Sujets connexes :

• Unité 1.1 : IONOS CLOUD API, authentification et modèle asynchrone
• Unité 2.1 : Calcul et automatisation des serveurs