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 applya créé quatre ressources sans erreur - [ ]
ionosctlaffiche le serveur commeAVAILABLEdans le nouveau centre de données - [ ] Le serveur a deux volumes attachés
- [ ] Un second
terraform planne signale aucune modification
Nettoyage :
terraform destroy -auto-approve
Erreurs courantes
Erreurs de développement à éviter avec le sujet de cette unité :
-
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
versiondansrequired_providers,terraform initsur 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.hclet effectuer la mise à niveau dans une demande d'extraction dédiée.
-
Modification d'un argument immuable
- Problème : Vous modifiez
locationsur un centre de données, outypesur 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 = trueles 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 utiliserallow_replaceuniquement si vous acceptez la recréation.
- Problème : Vous modifiez
-
Recherches d'image ambiguës
- Problème :
terraform planéchoue dans la source de donnéesionoscloud_imageavec une erreur concernant plusieurs correspondances. - Pourquoi cela se produit : Les arguments de recherche correspondent à plus d'une image, par exemple un alias sans
typenilocation. - Correction : Ajouter
location,typeetcloud_inità la source de données, et exécuter avecTF_LOG=debugpour voir quelles images ont correspondu.
- Problème :
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 dansrequired_providers; s'authentifier avecIONOS_TOKEN locationsur un centre de données ettypesur 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
versionexacte dansrequired_providersafin 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
s3pointant 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 :