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 : raw API avec curl, le Python SDK, et ionosctl. Les trois sont impératifs. Vous émettez un POST, interrogez /requests/{id}/status jusqu'à DONE, puis émettez l'appel suivant. Cela fonctionne, mais cela ne vous donne pas une description reproductible et contrôlée par version de votre infrastructure. Pour TaskBoard, l'outil de gestion de tâches API et le frontend que vous créez tout au long de ce cours, vous avez besoin d'une infrastructure qui vit dans Git, qui passe en revue comme du code, et qui se détruit proprement afin que les environnements de test ne vous facturent jamais en silence.

Cette unité vous amène à la mise en place déclarative avec le fournisseur IONOS Terraform. Vous écrirez le HCL qui construit la VDC de base de TaskBoard, vous verrez ce que Terraform fait sous le capot avec l'IONOS API asynchrone, vous stockerez l'état à distance dans Object Storage, et vous adopterez le modèle d'environnement éphémère qui maintient les coûts sous contrôle. L'interrogation asynchrone que vous avez gérée manuellement dans 1.1 est maintenant la tâche du fournisseur.

1. Configuration et authentification du fournisseur

Le fournisseur IONOS pour Terraform interagit avec les ressources de calcul, de stockage et de réseau d'IONOS Cloud. Il prend actuellement en charge les dernières offres V5 et V6 API, et est publié sur le Registre Terraform sous ionos-cloud/ionoscloud. Avant que tout ne fonctionne, vous devez avoir un compte IONOS dont les informations d'identification s'authentifient contre le Cloud API, exactement comme dans l'Unité 1.1.

1.1 Déclaration et fixation du fournisseur

Fixez toujours la version du fournisseur. Le bloc required_providers de Terraform vous verrouille sur une version de release connue pour être bonne, afin qu'une terraform init le mois prochain ne tire pas de modification de rupture 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 permet les mises à jour de correctif et mineures dans la ligne 6.x, mais bloque un saut vers 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 coéquipier et chaque exécuteur CI résolve la même version de construction du fournisseur.

1.2 Authentification : variable d'environnement vs bloc de fournisseur

Le modèle le plus propre consiste à s'authentifier avec le jeton porteur de Token Manager (présenté dans l'unité 1.1) via la variable d'environnement IONOS_TOKEN. Ainsi, rien de secret ne touche votre HCL ou votre historique Git.

export IONOS_TOKEN="eyJ0eXAiOiJKV1QiLCJraWQiO..."
terraform plan

Avec la variable définie, le bloc fournisseur peut être vide :

# provider.tf
provider "ionoscloud" {}

Vous pouvez également passer les informations d'identification explicitement dans le bloc fournisseur, ce qui est utile lorsque une seule configuration gère des ressources sur plus d'un compte. Le nom d'utilisateur et le mot de passe (authentification de base) sont pris en charge comme 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 plutôt qu'un jeton commité 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 le magasin de secrets CI.

2. Ressources de base : Construction d'un centre de données virtuel

Un environnement de base TaskBoard nécessite un centre de données virtuel, un LAN, un serveur, un disque de démarrage Volume, et une carte réseau connectant le serveur au LAN. Chaque ressource IONOS Terraform est préfixée avec ionoscloud_, ce qui les rend non ambigus lorsque une configuration combine des fournisseurs.

2.1 Centre de données, LAN, Serveur, Volume, Carte réseau

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 IONOS Terraform. La valeur d'emplacement et la sélection d'images sont basées sur les sections de source 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 permettent d'exprimer le disque de démarrage et l'attachement réseau comme faisant partie du serveur. Pour une donnée Volume 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 plutôt un ionoscloud_volume autonome.

2.2 Disque et carte réseau Volume 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 comme ionoscloud_datacenter.taskboard.id et ionoscloud_server.api.id sont ce qui donne à Terraform son ordre. Parce que le Volume lit server_id à partir de la ressource du serveur, Terraform sait que le serveur doit exister en premier. Vous n'écrivez jamais de logique explicite "attendre le centre de données". Ce graphique de dépendances est le but même de passer des scripts impératifs de l'Unité 1.1.

3. Le cycle de vie plan/apply/destroy

Les trois commandes que vous exécuterez constamment sont terraform plan, terraform apply, et terraform destroy. Comprendre ce que chaque commande fait contre l'IONOS API async vous évitera des heures de confusion.

3.1 Ce qui se passe sous le capot

terraform plan lit votre HCL, lit l'état actuel, interroge l'IONOS API pour l'état réel de chaque ressource gérée, et imprime la différence. Il ne modifie rien. terraform apply exécute cette différence en émettant les mêmes appels POST, PUT, et DELETE que vous avez faits manuellement à la section 1.1.

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

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

La capture du plan dans un fichier avec -out et l'application de ce fichier exact garantit que apply fait précisément ce que vous avez revu, sans dérive entre le plan et l'application. C'est le modèle sécurisé 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 graphique de dépendance à l'envers : les cartes 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 devriez laisser Terraform gérer la pile complète plutôt que de supprimer des ressources manuellement dans le DCD, ce qui peut laisser l'état de Terraform hors de synchronisation avec la réalité.

4. État distant sur Object Storage

Par défaut, Terraform écrit l'état dans un fichier terraform.tfstate local. Cela ne fonctionne pas pour une équipe ou un pipeline. L'état doit être stocké quelque part de partagé, et IONOS Cloud Object Storage est compatible avec S3, il sert donc de backend pour Terraform.

4.1 Configuration du backend S3

IONOS Object Storage s'authentifie avec une clé d'accès et une clé secrète, et non avec des jetons porteurs. Ce sont les mêmes informations d'identification S3 que vous générez dans la gestion des clés Object Storage. Object Storage est disponible dans plusieurs régions, chacune avec son propre point de terminaison, notamment 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 flags skip_* sont nécessaires car il s'agit d'un fournisseur externe (non-AWS) S3. Sans eux, le backend tente d'appeler des points de terminaison spécifiques à AWS comme le Security Token Service et échoue. Fournissez les informations d'identification via les variables d'environnement standard S3 afin qu'elles n'entrent 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 d'état

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

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

Le durcissement des ID d'images et des chaînes de région rend les configurations fragiles. Les sources de données interrogent l'IONOS API au moment de la planification, de sorte que votre HCL reste portable. Les imports placent les ressources créées en dehors de Terraform sous gestion. Et la destruction disciplinée garantit l'honnêteté de votre facture.

5.1 Sources de données d'image et de localisation

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, de sorte que vous n'êtes pas lié à un ID d'image UUID obsolète qui peut être retiré. La source de données ionoscloud_location confirme une région et sa disponibilité de fonctionnalités avant que vous ne la provisionniez. Référez le résultat avec data.ionoscloud_image.ubuntu.id dans le bloc volume du serveur, comme indiqué dans la section 2.

Le tableau suivant résume les quatre façons de piloter la provision d'IONOS que vous avez maintenant vues dans les unités 1.1 et 1.2.

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

5.2 Importation de ressources existantes

Si un centre de données 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. Écrivez d'abord un bloc de ressource correspondant, puis importez. Les imports IONOS utilisent un ID composé reliant l'ID du centre de données 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'import, exécutez terraform plan. Si le plan montre des modifications, votre HCL ne correspond pas encore à la réalité. Réconciliez les attributs du bloc de ressource avec la configuration live jusqu'à ce que plan ne signale plus de modifications. Seulement alors la ressource est-elle en toute sécurité sous gestion.

5.3 Conscience des coûts et environnements éphémères

Chaque ressource Terraform provisionnée sur apply entraîne des frais dès son existence. Le flux de travail discipliné est : toujours plan avant apply, toujours destroy ce que vous créez 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étruit.

# 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

Le branchement de terraform destroy dans l'étape de démantèlement d'un travail CI garantit qu'un environnement de branche oublié ne peut pas s'accumuler en silence des coûts pendant des semaines.

API Référence Carte Rapide

Le fournisseur IONOS Terraform appelle ces points de terminaison Cloud API en interne. 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)

Laboratoire de code

Objectif : Construire la base de TaskBoard avec Terraform : un centre de données, 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 version ultérieure installé localement
• ionosctl configuré (à partir de l'Unité 1.1) pour la vérification

Étape 1 : Créer le squelette 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 fixer 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 du centre de données virtuel

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 : Examiner l'état

terraform state list

Sortie attendue :

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

Liste 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

Pièges courants

1. Suppression de ressources dans le DCD que Terraform gère

   • Problème : Vous supprimez le serveur manuellement dans l'interface web, puis terraform apply erreurs ou tente de recréer des ressources non liées.
   • Pourquoi cela se produit : L'état de Terraform conserve toujours le serveur supprimé. Le API live ne le possède plus, donc l'état et la réalité divergent.
   • Correction : Supprimez l'entrée obsolète de l'état, puis laissez Terraform réconcilier :

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

2. Oubli des flags de saut de backend S3

   • Problème : terraform init contre le backend Object Storage est suspendu ou échoue avec une erreur STS ou account-ID.
   • Pourquoi cela se produit : Le backend S3 suppose AWS et tente des appels AWS uniquement que IONOS Object Storage n'implémente pas.
   • Correction : Ajoutez les flags de saut et le point de terminaison explicite au bloc de 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 non trouvée des mois après que la configuration ait fonctionné pour la dernière fois.
   • Pourquoi cela se produit : Un UUID d'image codé en dur a été mis à la retraite en amont. La création de serveur asynchrone est annulée car son amorçage Volume fait référence à une image manquante.
   • Correction : Résolvez l'image à l'époque de la planification avec la source de données et référez-la :

   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 maintenant décrire l'infrastructure IONOS de manière déclarative et gérer son cycle de vie complet à partir du code. Vous avez configuré et fixé la version du fournisseur IONOS Terraform, vous êtes authentifié avec IONOS_TOKEN, et vous avez construit la base VDC de TaskBoard à partir des ressources ionoscloud_datacenter, ionoscloud_lan, ionoscloud_server, ionoscloud_volume, et ionoscloud_nic. Vous avez déplacé l'état dans un backend S3-compatible Object Storage, utilisé des sources de données pour résoudre les images et les emplacements de manière dynamique, importé des ressources existantes, et adopté le modèle d'environnement éphémère pour que les infrastructures de test soient détruites proprement.

Le modèle de provisionnement asynchrone que vous avez géré manuellement dans l'unité 1.1 est maintenant l'affaire interne du fournisseur : Terraform interroge le statut des demandes pour vous et ordonne les opérations via son graphique de dépendances. À partir de là, chaque unité d'infrastructure dans ce cours repose sur la même fondation Terraform.

Points clés :

• Le fournisseur IONOS prend en charge les offres V5 et V6 API ; vous devez toujours fixer la version avec required_providers et valider le fichier de verrouillage
• Authentifiez-vous avec IONOS_TOKEN pour que aucun secret n'entre dans votre HCL ; toutes les ressources sont préfixées ionoscloud_
• Terraform interroge l'endpoint asynchrone /requests/{id}/status internement et ordonne les opérations via le graphique de dépendances des ressources
• Le backend Object Storage S3 nécessite les indicateurs skip_* et un point de terminaison IONOS explicite, et s'authentifie avec la clé d'accès plus la clé secrète, et non un jeton porteur
• Vous devez 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 réelles qu'il gère, stocké localement ou dans un backend Object Storage
• Source de données : Une requête en lecture seule contre l'API IONOS au moment de la planification, telle que ionoscloud_image, utilisée pour éviter de durcir les ID
• Importation : L'importation d'une ressource IONOS existante sous la gestion de Terraform en utilisant une datacenter_id/resource_id composée
• Environnement éphémère : Une pile complète créée pour une exécution de test et détruite avec terraform destroy pour éviter les frais persistants

Prochaines étapes

Continuer l'apprentissage : Unité 1.3 : Vérification des connaissances - Fondements programmatiques

Sujets connexes :

• Unité 1.1 : IONOS API, authentification, et modèle asynchrone
• Unité 2.1 : Calcul et automatisation du serveur