14 min de lecture

Objectifs d'apprentissage

À la fin de ce module, vous serez en mesure de:

  • Configurer le fournisseur Terraform IONOS CLOUD avec une version verrouillée et une authentification par jeton à partir de l'environnement
  • Créer une configuration Terraform qui déploie un centre de données, un LAN, un serveur, une carte réseau et un volume en utilisant les ressources `ionoscloud_`
  • Résoudre les images système d'exploitation et les emplacements au moment de la planification à l'aide des sources de données `ionoscloud_image` et `ionoscloud_location`
  • Stocker l'état Terraform à distance dans IONOS Cloud Object Storage via le backend S3
  • Importer des ressources existantes dans Terraform et démanteler les environnements éphémères avec `terraform destroy`

Unité 1.2 : Fournisseur Terraform et motifs fondamentaux

Introduction

Dans l'unité 1.1, vous avez créé le centre de données de TaskBoard avec curl et vérifié manuellement l'état de la requête. Pour un projet réel, vous avez besoin que l'infrastructure soit sous Git, examinée dans des pull requests, et reproductible pour chaque développeur et chaque branche.

Le IONOS CLOUD Terraform Provider vous le permet. Il traduit les ressources HCL en appels API v6 identiques à ceux que vous avez effectués manuellement et attend la complétion de chaque requête asynchrone. Dans cette unité, vous configurez le provider, utilisez les cinq ressources de base d'un centre de données virtuel (VDC) standard, recherchez des images et des emplacements, stockez l'état à distance et importez des ressources existantes. Dans le Code Lab, vous construisez le VDC de base de TaskBoard, le vérifiez, puis le supprimez.

1. Configuration du fournisseur et authentification

terraform {
  required_providers {
    ionoscloud = {
      source  = "ionos-cloud/ionoscloud"
      version = "6.7.39"
    }
  }
}

provider "ionoscloud" {}

Le bloc required_providers est obligatoire : sans lui, Terraform ne peut pas localiser et télécharger le fournisseur. Fixez une version exacte afin que chaque développeur et chaque exécution CI utilise la même version, et effectuez la mise à niveau dans une demande d'extraction distincte.

1.1 Authentification par jeton

L'authentification par jeton est la méthode fortement recommandée par la documentation du fournisseur. Avec un bloc de fournisseur vide, le fournisseur lit la variable d'environnement IONOS_TOKEN :

export IONOS_TOKEN="$(vault kv get -field=token secret/taskboard/ionos)"
terraform init

Le fournisseur accepte également username et password (ou IONOS_USERNAME et IONOS_PASSWORD) lorsqu'aucun jeton n'est défini.

1.2 Transmission du jeton via une variable

Lorsque vous préférez un argument explicite, déclarez une variable sensible et définissez-la à l'aide de TF_VAR_ :

variable "ionos_token" {
  type      = string
  sensitive = true
}

provider "ionoscloud" {
  token = var.ionos_token
}
export TF_VAR_ionos_token="$IONOS_TOKEN"

Les identifiants dans un fichier .tf remplacent les identifiants issus des variables d'environnement. N'inscrivez jamais un jeton littéral dans un fichier .tf : il finit par être enregistré dans l'historique Git.

Pour gérer les ressources IONOS Cloud Object Storage avec le fournisseur, définissez également IONOS_S3_ACCESS_KEY et IONOS_S3_SECRET_KEY.

2. Ressources principales

Chaque ressource du fournisseur est préfixée par ionoscloud_. Un VDC de base en utilise cinq.

Ressource Arguments requis Remarques
ionoscloud_datacenter name, location location est immuable
ionoscloud_lan datacenter_id public = true pour un LAN orienté Internet
ionoscloud_server name, datacenter_id type est immuable ; blocs volume et nic intégrés
ionoscloud_volume datacenter_id, disk_type, size disk_type est immuable ; server_id l'attache
ionoscloud_nic datacenter_id, server_id, lan Ajoute une carte réseau supplémentaire à un serveur

2.1 Centre de données et LAN

variable "location" {
  type    = string
  default = "de/txl"
}

resource "ionoscloud_datacenter" "taskboard" {
  name        = "taskboard-dev"
  location    = var.location
  description = "TaskBoard development environment"
}

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

Le location d'un centre de données est immuable. Le modifier dans le code implique la création d'un nouveau centre de données, il convient donc de le choisir une seule fois par environnement et de le conserver dans une variable. Si vous omettez ipv4_cidr_block sur un LAN privé, le fournisseur attribue un bloc /23 à partir de la plage 10.0.0.0/8.

2.2 Serveur avec Volume en ligne et carte réseau

resource "ionoscloud_server" "api" {
  name              = "taskboard-api-01"
  datacenter_id     = ionoscloud_datacenter.taskboard.id
  type              = "ENTERPRISE"
  cores             = 2
  ram               = 2048
  availability_zone = "AUTO"
  image_name        = data.ionoscloud_image.ubuntu.id
  ssh_keys          = [var.ssh_public_key]

  volume {
    name      = "system"
    size      = 20
    disk_type = "BALANCED"
    bus       = "VIRTIO"
  }

  nic {
    lan             = ionoscloud_lan.public.id
    name            = "public"
    dhcp            = true
    firewall_active = false
  }
}

Pour les serveurs ENTERPRISE, vous devez fournir cores, ram (en Mo) et la taille du volume size (en Go). Pour les serveurs CUBE, vous fournissez template_uuid à la place, et cores, ram et volume.size ne sont pas autorisés. ssh_keys accepte le texte de la clé directement, et les clés SSH ne fonctionnent qu'avec les images Linux publiques. Pour les nouveaux volumes, utilisez les classes de performance Block Storage (ESSENTIAL, BALANCED, PERFORMANCE), que la documentation recommande.

2.3 Volumes et NIC supplémentaires

resource "ionoscloud_volume" "data" {
  datacenter_id = ionoscloud_datacenter.taskboard.id
  server_id     = ionoscloud_server.api.id
  name          = "taskboard-data"
  size          = 10
  disk_type     = "BALANCED"
  bus           = "VIRTIO"
  licence_type  = "OTHER"
}

Le volume principal est créé avec le serveur ; ionoscloud_volume en ajoute d'autres. image_name ou licence_type est requis. Laissez server_id non défini pour un volume qui n'est attaché à aucun serveur ; sa modification détache d'abord le volume de l'ancien serveur. Pour une seconde interface réseau, la ressource ionoscloud_nic fonctionne de la même manière avec datacenter_id, server_id et lan.

3. Sources de données : images et emplacements

Ne codifiez pas en dur les UUID des images. Recherchez-les au moment de la planification.

3.1 Recherche d'une image système d'exploitation

data "ionoscloud_image" "ubuntu" {
  image_alias = "ubuntu:latest"
  type        = "HDD"
  cloud_init  = "V1"
  location    = var.location
}

La source de données d'image renvoie une seule correspondance. Si votre recherche correspond à plus d'une image, une erreur est renvoyée et vous affinez les arguments. Pour afficher le nom et l'emplacement des images correspondantes, exécutez la commande avec TF_LOG=debug. Transmettez toujours location, défini sur l'emplacement de votre centre de données, afin que la recherche renvoie l'image pour cet emplacement.

3.2 Inspection d'un emplacement

data "ionoscloud_location" "selected" {
  name    = var.location_name
  feature = "SSD"
}

output "cpu_families" {
  value = [for c in data.ionoscloud_location.selected.cpu_architecture : c.cpu_family]
}

Soit name, soit feature doit être défini, sinon la source de données renvoie une erreur. L'attribut cpu_architecture répertorie les familles de CPU, max_cores et max_ram (en Mo) pour l'emplacement, ce qui vous aide à valider un cpu_family avant de l'appliquer.

4. Cycle de vie, gestion asynchrone et état

4.1 Ce qui se passe en interne

terraform init      # downloads ionos-cloud/ionoscloud 6.7.39
terraform plan      # reads current resources, computes the diff, changes nothing
terraform apply     # sends create/update/delete requests and waits for each one
terraform destroy   # deletes every resource in the state

Lors de apply, chaque opération de création renvoie une requête asynchrone, exactement comme dans l'unité 1.1. Le fournisseur attend que la ressource soit provisionnée avant de créer les ressources qui y font référence. Les références telles que ionoscloud_datacenter.taskboard.id donnent à Terraform l'ordre implicite : centre de données, puis LAN, puis serveur, puis le volume supplémentaire.

Chaque ressource qui le prend en charge possède un bloc timeouts. Les valeurs par défaut sont de 60 minutes pour create, update et delete :

resource "ionoscloud_server" "api" {
  # ...
  timeouts {
    create = "30m"
    delete = "20m"
  }
}

Terraform ne procède pas automatiquement à un retour arrière en cas d'erreurs. Votre fichier d'état est partiellement mis à jour avec les ressources qui ont été terminées. Corrigez la cause et exécutez à nouveau apply.

4.2 Débogage des erreurs du fournisseur

Par défaut, le fournisseur ne renvoie que les erreurs du client HTTP, qui consistent généralement uniquement en un code d'état. Pour afficher le message d'erreur de l'API, augmentez le niveau de journalisation :

export IONOS_LOG_LEVEL=debug
terraform apply

Le corps de la réponse affiche ensuite httpStatus et messages avec le code d'erreur VDC-. Utilisez trace uniquement pour le débogage : il journalise la requête et la réponse complètes, y compris les données sensibles.

4.3 État distant dans IONOS Cloud Object Storage

L'état local convient à un seul développeur. Pour une équipe, stockez l'état dans un seau. IONOS Cloud Object Storage est compatible avec le protocole S3 et s'authentifie à l'aide d'une Access Key et d'une Secret Key, vous utilisez donc le backend s3 intégré de Terraform :

terraform {
  backend "s3" {
    bucket = "taskboard-tfstate"
    key    = "dev/terraform.tfstate"
    region = "eu-central-3"
    endpoints = {
      s3 = "https://s3.eu-central-3.ionoscloud.com"
    }
    skip_credentials_validation = true
    skip_region_validation      = true
    skip_requesting_account_id  = true
  }
}
export AWS_ACCESS_KEY_ID="<object-storage-access-key>"
export AWS_SECRET_ACCESS_KEY="<object-storage-secret-key>"
terraform init -migrate-state

Les paramètres skip_* désactivent les vérifications spécifiques à AWS auxquelles un service compatible S3 ne peut pas répondre. Le verrouillage de l'état empêche deux applications d'écrire le même état simultanément. Jusqu'à ce que vous ayez vérifié une méthode de verrouillage par rapport à votre bucket, sérialisez les applications dans CI afin qu'un seul pipeline par environnement s'exécute à la fois.

5. Prise en charge de l'importation et des coûts

5.1 Importation de ressources existantes

Les serveurs que vous avez créés dans l'unité 1.1 ne figurent dans aucun fichier d'état. Pour placer une ressource sous la gestion de Terraform, utilisez un bloc import :

import {
  to = ionoscloud_server.legacy_api
  id = "<datacenter-id>/<server-id>"
}
terraform plan -generate-config-out=generated.tf

La commande écrit un bloc de ressource correspondant dans generated.tf. La syntaxe de ligne de commande plus ancienne est toujours prise en charge :

terraform import ionoscloud_server.example <datacenter-id>/<server-id>
terraform import ionoscloud_lan.public <datacenter-id>/<lan-id>
terraform import ionoscloud_datacenter.taskboard <datacenter-id>

L'importation d'un serveur à l'aide uniquement de l'identifiant du centre de données et de l'identifiant du serveur l'importe sans bloc nic intégré. Ses cartes réseau sont laissées à des ressources ionoscloud_nic distinctes, que vous importez séparément. Examinez la configuration générée et exécutez terraform plan jusqu'à ce qu'aucune modification ne soit affichée.

5.2 Environnements éphémères

Chaque apply provisionne des ressources pour lesquelles vous payez. Trois habitudes permettent de maîtriser les coûts :

terraform plan -out=tfplan        # review what will be created
terraform apply tfplan            # apply exactly the reviewed plan
terraform destroy -auto-approve   # tear down when the test is finished

Créez des environnements à durée limitée pour chaque branche de fonctionnalité avec un état distinct key (par exemple branches/<branch>/terraform.tfstate), et supprimez-les lorsque la branche est fusionnée. Vous automatisez cette suppression dans le Module 5.

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

Principaux points de terminaison de l'API derrière les ressources de cette unité :

Méthode Point de terminaison Description
POST /datacenters Créé par ionoscloud_datacenter
POST /datacenters/{datacenterId}/lans Créé par ionoscloud_lan
POST /datacenters/{datacenterId}/servers Créé par ionoscloud_server
GET /images Recherché par la source de données ionoscloud_image
GET /requests/{requestId}/status Interrogé pendant que le fournisseur attend le provisionnement

URL de base : https://api.ionos.com/cloudapi/v6 Authentification : Authorization: Bearer <token>

Atelier de code

Objectif : Construire le VDC de base de TaskBoard avec Terraform (centre de données, LAN, serveur avec volume attaché), puis le planifier, l'appliquer, le vérifier et le détruire.

Prérequis :

  • Compte IONOS CLOUD avec un jeton API dans IONOS_TOKEN
  • Terraform installé localement
  • ionosctl (Unité 1.1) et une clé publique SSH

Étape 1 : Créer le projet avec versions.tf et variables.tf

# mkdir taskboard-infra && cd taskboard-infra
# versions.tf: the terraform block from Section 1, with an empty provider "ionoscloud" {}

# variables.tf
variable "location" {
  type    = string
  default = "de/txl"
}
variable "ssh_public_key" {
  type = string
}

Sortie attendue :

(files saved)

Étape 2 : Écrire main.tf et outputs.tf

Copiez la source de données d'image (section 3.1), le centre de données et le LAN (section 2.1), le serveur (section 2.2) et le volume de données (section 2.3) dans main.tf. Puis ajoutez :

output "datacenter_id" { value = ionoscloud_datacenter.taskboard.id }
output "server_id"     { value = ionoscloud_server.api.id }
output "server_ip"     { value = ionoscloud_server.api.primary_ip }

Sortie attendue :

(files saved)

Étape 3 : Initialiser et planifier

export TF_VAR_ssh_public_key="$(cat ~/.ssh/id_ed25519.pub)"
terraform init
terraform plan -out=tfplan

Sortie attendue :

Terraform has been successfully initialized!
...
Plan: 4 to add, 0 to change, 0 to destroy.

Étape 4 : Appliquer

terraform apply tfplan

Sortie attendue :

ionoscloud_datacenter.taskboard: Creation complete after ...
ionoscloud_lan.public: Creation complete after ...
ionoscloud_server.api: Creation complete after ...
ionoscloud_volume.data: Creation complete after ...
Apply complete! Resources: 4 added, 0 changed, 0 destroyed.

Étape 5 : Vérifier en dehors de Terraform

DC=$(terraform output -raw datacenter_id)
ionosctl compute server list --datacenter-id "$DC" --cols Name,Type,Cores,State
ionosctl compute server volume list --datacenter-id "$DC" \
  --server-id "$(terraform output -raw server_id)" --cols Name,Size,Type,State

Sortie attendue :

Name               Type         Cores   State
taskboard-api-01   ENTERPRISE   2       AVAILABLE
Name             Size   Type       State
system           20     BALANCED   AVAILABLE
taskboard-data   10     BALANCED   AVAILABLE

Étape 6 : Vérifier l'absence de dérive

terraform plan

Sortie attendue :

No changes. Your infrastructure matches the configuration.

Liste de contrôle de validation :

  • [ ] terraform apply a créé quatre ressources sans erreur
  • [ ] ionosctl affiche le serveur comme AVAILABLE dans le nouveau centre de données
  • [ ] Le serveur a deux volumes attachés
  • [ ] Un second terraform plan ne signale aucune modification

Nettoyage :

terraform destroy -auto-approve

Erreurs courantes

Erreurs de développement à éviter avec le sujet de cette unité :

  1. Version du fournisseur non épinglée

    • Problème : Un plan qui était propre hier montre soudain des modifications, ou un argument cesse de fonctionner dans la CI.
    • Pourquoi cela se produit : Sans une version exacte de version dans required_providers, terraform init sur un exécuteur neuf peut télécharger une version plus récente du fournisseur que celle que vous avez testée.
    • Correction : Épingler version = "6.7.39", commettre .terraform.lock.hcl et effectuer la mise à niveau dans une demande d'extraction dédiée.
  2. Modification d'un argument immuable

    • Problème : Vous modifiez location sur un centre de données, ou type sur un serveur, et le plan souhaite le détruire et le recréer.
    • Pourquoi cela se produit : Ces arguments sont immuables. Sur un serveur, allow_replace = true les met à jour en détruisant et en recréant le serveur.
    • Correction : Conserver les valeurs immuables dans des variables par environnement, examiner chaque ligne -/+ du plan et utiliser allow_replace uniquement si vous acceptez la recréation.
  3. Recherches d'image ambiguës

    • Problème : terraform plan échoue dans la source de données ionoscloud_image avec une erreur concernant plusieurs correspondances.
    • Pourquoi cela se produit : Les arguments de recherche correspondent à plus d'une image, par exemple un alias sans type ni location.
    • Correction : Ajouter location, type et cloud_init à la source de données, et exécuter avec TF_LOG=debug pour voir quelles images ont correspondu.

Résumé

Vous pouvez désormais décrire l'infrastructure de base de TaskBoard sous forme de code. Le fournisseur épinglé s'authentifie à l'aide d'un jeton issu de l'environnement et transforme cinq ressources principales ionoscloud_ en appels API v6, en attendant chaque requête asynchrone. Les images proviennent de sources de données, l'état est stocké dans IONOS Cloud Object Storage, les ressources créées manuellement peuvent être importées, et chaque environnement est créé à partir d'un plan validé puis détruit.

Points clés :

  • Épingler ionos-cloud/ionoscloud à une version exacte dans required_providers ; s'authentifier avec IONOS_TOKEN
  • location sur un centre de données et type sur un serveur sont immuables ; les modifier recrée la ressource
  • Le fournisseur attend chaque requête asynchrone ; ajuster les attentes avec timeouts (60 minutes par défaut)
  • Utiliser le backend S3 avec un point de terminaison IONOS Cloud Object Storage et une Access Key ainsi qu'une Secret Key pour l'état partagé
  • Importer avec <datacenter-id>/<server-id>, générer la configuration avec -generate-config-out, et détruire les environnements éphémères

Terminologie importante :

  • Épinglage du fournisseur : Une version exacte dans required_providers afin que chaque exécution utilise la même version du fournisseur
  • Source de données : Une consultation en lecture seule au moment de la planification, telle que ionoscloud_image, qui renvoie une seule correspondance ou échoue
  • Argument immuable : Un argument que l'API ne peut pas modifier sur place, tel que location ; les modifications forcent la recréation
  • Backend distant : Le backend s3 pointant vers un point de terminaison IONOS Cloud Object Storage pour partager l'état au sein d'une équipe
  • Bloc d'importation : Du HCL qui adopte une ressource existante dans l'état par son identifiant, en générant éventuellement sa configuration

Prochaines étapes

Continuer à apprendre : Unité 1.3 : Vérification des connaissances - Fondements de la programmation

Sujets connexes :