13 Min. Lesezeit

Lernziele

Am Ende dieses Moduls werden Sie in der Lage sein:

  • Den IONOS CLOUD Terraform Provider mit einer festgelegten Version und Token-Authentifizierung aus der Umgebung konfigurieren
  • Eine Terraform-Konfiguration erstellen, die ein Rechenzentrum, ein LAN, einen Server, eine NIC und ein Volume mit `ionoscloud_`-Ressourcen bereitstellt
  • Betriebssystem-Images und Standorte im Planungszeitpunkt mit den `ionoscloud_image`- und `ionoscloud_location`-Datensources auflösen
  • Den Terraform-Zustand remote in IONOS Cloud Object Storage über das S3-Backend speichern
  • Bestehende Ressourcen in Terraform importieren und ephemere Umgebungen mit `terraform destroy` abbauen

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 apply hat vier Ressourcen ohne Fehler erstellt
  • [ ] ionosctl zeigt den Server als AVAILABLE im neuen Rechenzentrum
  • [ ] Der Server hat zwei angehängte Volumes
  • [ ] Ein zweiter terraform plan meldet 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:

  1. 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 version in required_providers kann terraform init auf 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.hcl und führen Sie Upgrades in einem dedizierten Pull Request durch.
  2. Ändern eines unveränderlichen Arguments

    • Problem: Sie ändern location an einem Rechenzentrum oder type an 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 = true sie, 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 Sie allow_replace nur, wenn Sie die Neuerstellung akzeptieren.
  3. Mehrdeutige Image-Abfragen

    • Problem: terraform plan schlägt in der ionoscloud_image-Datenquelle mit einem Fehler zu mehreren Treffern fehl.
    • Ursache: Die Suchargumente entsprechen mehr als einem Bild, beispielsweise ein Alias ohne type oder location.
    • Lösung: Fügen Sie location, type und cloud_init zur Datenquelle hinzu und führen Sie mit TF_LOG=debug aus, um zu sehen, welche Bilder zugeordnet wurden.

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/ionoscloud in required_providers auf eine exakte Version fest; authentifizieren Sie sich mit IONOS_TOKEN
  • location auf einem Rechenzentrum und type auf einem Server sind unveränderlich; Änderungen führen zur Neuerschaffung der Ressource
  • Der Provider wartet auf jede asynchrone Anfrage; passen Sie die Wartezeiten mit timeouts an (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-out und entfernen Sie ephemere Umgebungen

Wichtige Begriffe:

  • Provider-Festlegung: Eine exakte version in required_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: