Einheit 1.2: Terraform Provider und Kernmuster
Einführung
In Einheit 1.1 haben Sie das Rechenzentrum von TaskBoard mit curl erstellt und den Status der Anfrage manuell abgefragt. Für ein echtes Projekt benötigen Sie die Infrastruktur in Git, geprüft in Pull Requests und reproduzierbar für jede Entwicklerin und jeden Entwickler sowie für jeden Branch.
Der IONOS CLOUD Terraform Provider bietet Ihnen genau das. Er übersetzt HCL-Ressourcen in dieselben API v6-Aufrufe, die Sie manuell ausgeführt haben, und wartet auf jede asynchrone Anfrage. In dieser Einheit konfigurieren Sie den Provider, verwenden die fünf Kernressourcen eines grundlegenden virtuellen Rechenzentrums (VDC), suchen nach Images und Standorten, speichern den State remote und importieren bestehende Ressourcen. Im Code Lab erstellen Sie das Basis-VDC von TaskBoard, verifizieren es und zerstören es.
1. Anbieter-Einrichtung und Authentifizierung
terraform {
required_providers {
ionoscloud = {
source = "ionos-cloud/ionoscloud"
version = "6.7.39"
}
}
}
provider "ionoscloud" {}
Der required_providers-Block ist obligatorisch: Ohne ihn kann Terraform den Provider nicht finden und herunterladen. Eine exakte Version festpinnen, damit jede Entwicklerin und jeder Entwickler sowie jeder CI-Lauf dieselbe Version verwendet, und Upgrades in einem separaten Pull Request vornehmen.
1.1 Token-Authentifizierung
Die Token-Authentifizierung ist die Methode, die die Provider-Dokumentation dringend empfiehlt. Bei einem leeren Provider-Block liest der Provider die Umgebungsvariable IONOS_TOKEN:
export IONOS_TOKEN="$(vault kv get -field=token secret/taskboard/ionos)"
terraform init
Der Anbieter akzeptiert auch username und password (oder IONOS_USERNAME und IONOS_PASSWORD), wenn kein Token festgelegt ist.
1.2 Übergeben des Tokens über eine Variable
Wenn Sie ein explizites Argument bevorzugen, deklarieren Sie eine sensible Variable und setzen Sie sie mit TF_VAR_:
variable "ionos_token" {
type = string
sensitive = true
}
provider "ionoscloud" {
token = var.ionos_token
}
export TF_VAR_ionos_token="$IONOS_TOKEN"
Anmeldedaten in einer .tf-Datei überschreiben die Anmeldedaten aus Umgebungsvariablen. Schreiben Sie niemals ein Token direkt in eine .tf-Datei: Es landet in der Git-Verlaufshistorie.
Um IONOS Cloud Object Storage-Ressourcen mit dem Provider zu verwalten, setzen Sie auch IONOS_S3_ACCESS_KEY und IONOS_S3_SECRET_KEY.
2. Kernressourcen
Jede Ressource des Anbieters wird mit ionoscloud_ als Präfix versehen. Ein grundlegendes VDC verwendet fünf davon.
| Ressource | Erforderliche Argumente | Hinweise |
|---|---|---|
ionoscloud_datacenter |
name, location |
location ist unveränderlich |
ionoscloud_lan |
datacenter_id |
public = true für ein internetorientiertes LAN |
ionoscloud_server |
name, datacenter_id |
type ist unveränderlich; Inline-volume- und nic-Blöcke |
ionoscloud_volume |
datacenter_id, disk_type, size |
disk_type ist unveränderlich; server_id hängt es an |
ionoscloud_nic |
datacenter_id, server_id, lan |
Fügt einem Server eine weitere NIC hinzu |
2.1 Rechenzentrum und 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"
}
Die location eines Rechenzentrums ist unveränderlich. Eine Änderung im Code führt zu einem neuen Rechenzentrum, daher sollte sie einmalig pro Umgebung festgelegt und in einer Variable gespeichert werden. Wenn ipv4_cidr_block auf einem privaten LAN weggelassen wird, weist der Anbieter einen /23-Block aus dem 10.0.0.0/8-Bereich zu.
2.2 Server mit Inline-Volume und NIC
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
}
}
Für ENTERPRISE-Server müssen Sie cores, ram (in MB) sowie die Größe des Volumes size (in GB) angeben. Für CUBE-Server geben Sie stattdessen template_uuid an, und cores, ram sowie volume.size sind nicht zulässig. ssh_keys akzeptiert den Schlüsseltext direkt, und SSH-Schlüssel funktionieren nur mit öffentlichen Linux-Images. Für neue Volumes verwenden Sie die Block Storage-Leistungsklassen (ESSENTIAL, BALANCED, PERFORMANCE), die in der Dokumentation empfohlen werden.
2.3 Zusätzliche Volumes und NICs
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"
}
Das primäre Volume wird mit dem Server erstellt; ionoscloud_volume fügt weitere hinzu. Entweder image_name oder licence_type ist erforderlich. server_id für ein Volume, das keinem Server zugewiesen ist, leer lassen; eine Änderung löst das Volume zunächst vom alten Server ab. Für eine zweite Netzwerkschnittstelle funktioniert das ionoscloud_nic-Ressource auf dieselbe Weise mit datacenter_id, server_id und lan.
3. Datenquellen: Bilder und Speicherorte
Bilden Sie keine Bild-UUIDs hart ein. Ermitteln Sie diese zur Planungszeit.
3.1 Ermitteln eines OS-Bilds
data "ionoscloud_image" "ubuntu" {
image_alias = "ubuntu:latest"
type = "HDD"
cloud_init = "V1"
location = var.location
}
Die Image-Datenquelle liefert genau einen Treffer zurück. Wenn Ihre Suche mehr als ein Bild entspricht, wird ein Fehler zurückgegeben, und Sie verfeinern die Argumente. Um den Namen und den Speicherort der übereinstimmenden Bilder anzuzeigen, führen Sie mit TF_LOG=debug aus. Übergeben Sie stets location, das auf den Standort Ihres Rechenzentrums festgelegt ist, damit die Abfrage das Bild für diesen Standort zurückgibt.
3.2 Überprüfung eines Standorts
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]
}
Entweder name oder feature muss gesetzt sein, andernfalls gibt die Datenquelle einen Fehler zurück. Das Attribut cpu_architecture listet die CPU-Familien, max_cores und max_ram (in MB) für den Standort auf, was Ihnen hilft, ein cpu_family zu validieren, bevor Sie es anwenden.
4. Lebenszyklus, asynchrone Verarbeitung und Zustand
4.1 Was im Hintergrund geschieht
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
Während apply gibt jede create-Aufruf eine asynchrone Anfrage zurück, genau wie in Einheit 1.1. Der Provider wartet darauf, dass die Ressource bereitgestellt wurde, bevor er Ressourcen erstellt, die auf sie verweisen. Verweise wie ionoscloud_datacenter.taskboard.id geben Terraform die implizite Reihenfolge vor: Rechenzentrum, dann LAN, dann Server, dann das zusätzliche Volume.
Jede Ressource, die dies unterstützt, verfügt über einen timeouts-Block. Die Standardwerte betragen 60 Minuten für create, update und delete:
resource "ionoscloud_server" "api" {
# ...
timeouts {
create = "30m"
delete = "20m"
}
}
Terraform rollt bei Fehlern nicht automatisch zurück. Ihre Zustandsdatei wird teilweise aktualisiert und enthält alle Ressourcen, die erfolgreich abgeschlossen wurden. Beheben Sie die Ursache und führen Sie apply erneut aus.
4.2 Fehlerbehebung bei Provider-Fehlern
Standardmäßig gibt der Provider nur HTTP-Client-Fehler zurück, die in der Regel nur aus dem Statuscode bestehen. Um die API-Fehlermeldung anzuzeigen, erhöhen Sie das Protokollierungsniveau:
export IONOS_LOG_LEVEL=debug
terraform apply
Der Antwortinhalt zeigt dann httpStatus und messages mit dem VDC- Fehlercode. Verwenden Sie trace nur zur Fehlersuche: Es protokolliert die vollständige Anfrage und Antwort, einschließlich sensibler Daten.
4.3 Remote State in IONOS Cloud Object Storage
Lokaler State eignet sich für eine einzelne Entwicklerin oder einen einzelnen Entwickler. Für ein Team speichern Sie den State in einem Bucket. IONOS Cloud Object Storage ist mit dem S3 Protokoll kompatibel und authentifiziert sich mit einem Access Key und einem Secret Key. Verwenden Sie daher den in Terraform integrierten s3 Backend:
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
Die Einstellungen für skip_* deaktivieren AWS-spezifische Prüfungen, auf die ein S3-kompatibler Dienst nicht antworten kann. State Locking verhindert, dass zwei Applies denselben Zustand gleichzeitig schreiben. Bis Sie eine Sperrmethode für Ihren Bucket verifiziert haben, serialisieren Sie Applies in CI, sodass pro Umgebung nur eine Pipeline gleichzeitig ausgeführt wird.
5. Import und Kostenbewusstsein
5.1 Importieren vorhandener Ressourcen
Die Server, die Sie in Einheit 1.1 erstellt haben, befinden sich nicht in einer Zustandsdatei. Bringen Sie eine Ressource unter Terraform mit einem import-Block:
import {
to = ionoscloud_server.legacy_api
id = "<datacenter-id>/<server-id>"
}
terraform plan -generate-config-out=generated.tf
Der Befehl schreibt einen passenden Ressourcenblock in generated.tf. Die ältere Befehlszeilensyntax wird weiterhin unterstützt:
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>
Das Importieren eines Servers mit nur der Rechenzentrums-ID und Server-ID führt zu einem Import ohne einen Inline-nic-Block. Seine NICs werden als separate ionoscloud_nic-Ressourcen behandelt, die Sie eigenständig importieren. Überprüfen Sie die generierte Konfiguration und führen Sie terraform plan aus, bis keine Änderungen mehr angezeigt werden.
5.2 Ephemere Umgebungen
Jede apply provisioniert Ressourcen, für die Sie bezahlen. Drei Gewohnheiten halten die Kosten unter Kontrolle:
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
Erstellen Sie kurzlebige Umgebungen pro Feature-Branch mit einem separaten State key (zum Beispiel branches/<branch>/terraform.tfstate) und zerstören Sie diese, wenn der Branch gemerged wurde. Sie automatisieren diesen Abbau in Modul 5.
Schnellübersicht zur API-Referenz
Die wichtigsten API-Endpunkte für die Ressourcen dieser Einheit:
| Methode | Endpunkt | Beschreibung |
|---|---|---|
POST |
/datacenters |
Erzeugt von ionoscloud_datacenter |
POST |
/datacenters/{datacenterId}/lans |
Erzeugt von ionoscloud_lan |
POST |
/datacenters/{datacenterId}/servers |
Erzeugt von ionoscloud_server |
GET |
/images |
Abgefragt von der ionoscloud_image-Datenquelle |
GET |
/requests/{requestId}/status |
Abgefragt, während der Provider auf die Bereitstellung wartet |
Basis-URL: https://api.ionos.com/cloudapi/v6
Authentifizierung: Authorization: Bearer <token>
Code Lab
Ziel: Erstellen Sie das Basis-VDC von TaskBoard mit Terraform (Rechenzentrum, LAN, Server mit angehängtem Volume) und planen, wenden, verifizieren und zerstören Sie es anschließend.
Voraussetzungen:
- IONOS CLOUD-Konto mit einem API-Token in
IONOS_TOKEN - Lokal installiertes Terraform
ionosctl(Einheit 1.1) und ein SSH-Öffentlicher-Schlüssel
Schritt 1: Erstellen Sie das Projekt mit versions.tf und 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
}
Erwartete Ausgabe:
(files saved)
Schritt 2: main.tf und outputs.tf schreiben
Kopieren Sie die Image-Datenquelle (Abschnitt 3.1), das Rechenzentrum und das LAN (Abschnitt 2.1), den Server (Abschnitt 2.2) und das Datenvolumen (Abschnitt 2.3) in main.tf. Fügen Sie anschließend Folgendes hinzu:
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 }
Erwartete Ausgabe:
(files saved)
Schritt 3: Initialisieren und planen
export TF_VAR_ssh_public_key="$(cat ~/.ssh/id_ed25519.pub)"
terraform init
terraform plan -out=tfplan
Erwartete Ausgabe:
Terraform has been successfully initialized!
...
Plan: 4 to add, 0 to change, 0 to destroy.
Schritt 4: Anwenden
terraform apply tfplan
Erwartete Ausgabe:
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.
Schritt 5: Verifizierung außerhalb von 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
Erwartete Ausgabe:
Name Type Cores State
taskboard-api-01 ENTERPRISE 2 AVAILABLE
Name Size Type State
system 20 BALANCED AVAILABLE
taskboard-data 10 BALANCED AVAILABLE
Schritt 6: Keine Drift bestätigen
terraform plan
Erwartete Ausgabe:
No changes. Your infrastructure matches the configuration.
Prüfliste:
- [ ]
terraform applyhat vier Ressourcen ohne Fehler erstellt - [ ]
ionosctlzeigt den Server alsAVAILABLEim neuen Rechenzentrum - [ ] Der Server hat zwei angehängte Volumes
- [ ] Ein zweiter
terraform planmeldet keine Änderungen
Aufräumarbeiten:
terraform destroy -auto-approve
Häufige Fehler
Fehler von Entwicklerinnen und Entwicklern, die bei dem Thema dieser Einheit zu vermeiden sind:
-
Nicht fixierte Anbieterversion
- Problem: Ein Plan, der gestern noch sauber war, zeigt plötzlich Änderungen an, oder ein Argument funktioniert in CI nicht mehr.
- Ursache: Ohne eine exakte
versioninrequired_providerskannterraform initauf einem neuen Runner eine neuere Anbieterversion herunterladen als die, die Sie getestet haben. - Lösung: Fixieren Sie
version = "6.7.39", commiten Sie.terraform.lock.hclund führen Sie Upgrades in einem dedizierten Pull Request durch.
-
Ändern eines unveränderlichen Arguments
- Problem: Sie ändern
locationan einem Rechenzentrum odertypean einem Server, und der Plan möchte es zerstören und neu erstellen. - Ursache: Diese Argumente sind unveränderlich. Bei einem Server aktualisiert
allow_replace = truesie, indem er den Server zerstört und neu erstellt. - Lösung: Bewahren Sie unveränderliche Werte in umgebungsabhängigen Variablen auf, prüfen Sie jede
-/+-Zeile im Plan und verwenden Sieallow_replacenur, wenn Sie die Neuerstellung akzeptieren.
- Problem: Sie ändern
-
Mehrdeutige Image-Abfragen
- Problem:
terraform planschlägt in derionoscloud_image-Datenquelle mit einem Fehler zu mehreren Treffern fehl. - Ursache: Die Suchargumente entsprechen mehr als einem Bild, beispielsweise ein Alias ohne
typeoderlocation. - Lösung: Fügen Sie
location,typeundcloud_initzur Datenquelle hinzu und führen Sie mitTF_LOG=debugaus, um zu sehen, welche Bilder zugeordnet wurden.
- Problem:
Zusammenfassung
Sie können nun die Basisinfrastruktur von TaskBoard als Code beschreiben. Der festgelegte Provider authentifiziert sich mit einem Token aus der Umgebung und wandelt fünf zentrale ionoscloud_-Ressourcen in API v6-Aufrufe um, wobei er auf jede asynchrone Anfrage wartet. Bilder stammen aus Datenquellen, der Zustand wird in IONOS Cloud Object Storage gespeichert, manuell erstellte Ressourcen können importiert werden, und jede Umgebung wird aus einem geprüften Plan erstellt und anschließend wieder entfernt.
Wichtige Punkte:
- Legen Sie
ionos-cloud/ionoscloudinrequired_providersauf eine exakte Version fest; authentifizieren Sie sich mitIONOS_TOKEN locationauf einem Rechenzentrum undtypeauf einem Server sind unveränderlich; Änderungen führen zur Neuerschaffung der Ressource- Der Provider wartet auf jede asynchrone Anfrage; passen Sie die Wartezeiten mit
timeoutsan (Standardwert: 60 Minuten) - Verwenden Sie das S3-Backend mit einem IONOS Cloud Object Storage-Endpunkt sowie Access Key und Secret Key für einen gemeinsam genutzten Zustand
- Importieren Sie mit
<datacenter-id>/<server-id>, generieren Sie Konfigurationen mit-generate-config-outund entfernen Sie ephemere Umgebungen
Wichtige Begriffe:
- Provider-Festlegung: Eine exakte
versioninrequired_providers, damit jede Ausführung dieselbe Provider-Version verwendet - Datenquelle: Eine schreibgeschützte Abfrage zur Planungszeit, beispielsweise
ionoscloud_image, die entweder genau einen Treffer zurückgibt oder fehlschlägt - Unveränderliches Argument: Ein Argument, das die API nicht an Ort und Stelle ändern kann, beispielsweise
location; Änderungen erzwingen die Neuerschaffung - Remote-Backend: Das
s3-Backend, das auf einen IONOS Cloud Object Storage-Endpunkt zeigt, um den Zustand innerhalb eines Teams zu teilen - Import-Block: HCL, das eine vorhandene Ressource anhand ihrer ID in den Zustand übernimmt und optional deren Konfiguration generiert
Nächste Schritte
Weiter lernen: Einheit 1.3: Wissensprüfung - Programmatische Grundlagen
Verwandte Themen: