Zum Hauptinhalt springen

Terraform

Mit dem Provider lionbackup legen Sie Projekte, Backup-Token, Mitglieder und Berechtigungsgruppen als Infrastruktur-Code an. Er verwendet die öffentliche API und damit dieselben Rechte wie Ihr Dienstkonto im Portal. Der Provider läuft mit Terraform ab 1.9 und mit OpenTofu.

Bezugsquelle​

Der Provider wird nicht über die öffentliche Terraform-Registry verteilt, sondern über einen Network Mirror von lionbackup. Tragen Sie ihn einmalig in Ihre CLI-Konfiguration ~/.terraformrc ein (oder in die Datei, auf die TF_CLI_CONFIG_FILE zeigt):

provider_installation {
network_mirror {
url = "https://git.prod.lionbackup.cloud/terraform/providers/"
include = ["git.lionbackup.cloud/*/*"]
}
direct {
exclude = ["git.lionbackup.cloud/*/*"]
}
}

Getestet mit Terraform 1.16 und OpenTofu 1.12. OpenTofu liest dieselbe Konfiguration aus ~/.tofurc oder, falls die fehlt, aus ~/.terraformrc.

Der direct-Block sorgt dafür, dass Terraform den lionbackup-Provider ausschließlich vom Mirror bezieht; alle anderen Provider laden weiterhin wie gewohnt aus ihren Registries.

Provider einbinden​

Die Quelladresse ist git.lionbackup.cloud/lionbackup/lionbackup. Verwenden Sie den Provider ab Version 0.1.4:

terraform {
required_providers {
lionbackup = {
source = "git.lionbackup.cloud/lionbackup/lionbackup"
version = "~> 0.1.4"
}
}
}

provider "lionbackup" {
# Der API-Schlüssel kommt aus der Umgebung:
# export LIONBACKUP_API_KEY=... (Portal → Entwickler)
# environment = "prod" # Standard; "dev" für die Entwicklungsumgebung
}

Den API-Schlüssel legen Sie im Portal unter Entwickler an (siehe API) und übergeben ihn als Umgebungsvariable LIONBACKUP_API_KEY. Das Attribut api_key gibt es ebenfalls, doch ein Schlüssel in der Konfiguration landet leicht in der Versionsverwaltung.

Beispiel​

Das Beispiel ermittelt Ihre Organisation, legt darin ein Projekt in der Zone de01-1 an, erzeugt ein Write-Token und gibt dessen Geheimnis als sensiblen Output aus:

data "lionbackup_organizations" "mine" {}

locals {
organization_id = one([
for o in data.lionbackup_organizations.mine.organizations : o.id
if o.name == "Beispiel GmbH"
])
}

resource "lionbackup_project" "backup" {
organization_id = local.organization_id
name = "web-servers"
availability_zone = "de01-1"
alert_email = "ops@example.com"
}

resource "lionbackup_project_token" "writer" {
project_id = lionbackup_project.backup.id
type = "write"
}

output "backup_token" {
value = lionbackup_project_token.writer.secret
sensitive = true
}

Die Organisation wird über ihren Namen gewählt, nicht über die Position in der Liste: Ein Dienstkonto kann mehrere Organisationen sehen, die Liste ist nach Namen sortiert, und jede neue Organisation verschiebt die Positionen. one() bricht bei mehreren Treffern ab; gibt es keinen, bleibt organization_id leer und Terraform verweigert den Plan. In keinem Fall entsteht das Projekt still in der falschen Organisation.

availability_zone erwartet den Namen der Zone, wie ihn die Seite Regionen und die Data Source lionbackup_zones nennen; die Auflösung zur Kennung übernimmt der Provider.

Anwenden:

export LIONBACKUP_API_KEY=...
terraform init
terraform apply
terraform output -raw backup_token

terraform init lädt den Provider vom Mirror und prüft ihn gegen die dort hinterlegten Prüfsummen. Die Ausgabe sollte so enden:

- Installing git.lionbackup.cloud/lionbackup/lionbackup v0.1.4...
- Installed git.lionbackup.cloud/lionbackup/lionbackup v0.1.4 (verified checksum)

Die Prüfsumme landet in .terraform.lock.hcl. Nehmen Sie diese Datei in die Versionsverwaltung auf, dann installiert jeder Lauf exakt dieselbe Provider-Version.

Hält Ihre .terraform.lock.hcl noch eine ältere Version fest, weist terraform init die Bedingung ~> 0.1.4 zurück; terraform init -upgrade wählt dann die neue Version und schreibt sie in die Datei. Die Data Source lionbackup_organization und das Attribut payment_method gibt es erst ab 0.1.3. Das Attribut anomaly_detection gibt es ab 0.1.4, die Ressourcen für Mitglieder und Berechtigungsgruppen ab 0.1.6.

Mitglieder und Berechtigungsgruppen​

Was Sie im Portal auf der Seite Berechtigungen einstellen, verwaltet der Provider ab Version 0.1.6 ebenfalls. Das Beispiel lädt eine Kollegin in die Organisation ein und gibt ihr über eine Berechtigungsgruppe Lesezugriff auf das Projekt aus dem Beispiel oben:

resource "lionbackup_organization_member" "alice" {
organization_id = local.organization_id
email = "alice@example.com"
# role = "member" (Standard): gewährt allein nichts
}

resource "lionbackup_permission_group" "backup_readers" {
organization_id = local.organization_id
project_id = lionbackup_project.backup.id
name = "Backup-Leser"
level = "reader"
}

resource "lionbackup_permission_group_member" "alice" {
organization_id = local.organization_id
group_id = lionbackup_permission_group.backup_readers.id
user_id = lionbackup_organization_member.alice.user_id
}

Einladen lassen sich nur Personen, die bereits ein lionbackup-Konto haben; eine Einladungs-E-Mail gibt es nicht. Wer neu in die Organisation kommt, erhält die Rolle member, die allein keine Rechte gewährt. Die Rechte auf ein Projekt kommen dann aus den Berechtigungsgruppen: Jedes Mitglied einer Gruppe hat auf dem Projekt der Gruppe die Rolle aus level. Eine Gruppe ohne project_id gilt für die ganze Organisation, ist aber an kein Projekt gebunden und gewährt deshalb keine Projektrolle.

Bestehende Mitglieder und Gruppen übernehmen Sie mit terraform import. Die Kennungen liefern die Data Sources lionbackup_organization_members und lionbackup_permission_groups:

terraform import lionbackup_organization_member.alice <organization_id>/<user_id>
terraform import lionbackup_permission_group.backup_readers <organization_id>/<group_id>
terraform import lionbackup_permission_group_member.alice <organization_id>/<group_id>/<user_id>

Jede Änderung über den Provider erscheint im Audit-Log der Organisation, mit dem Vermerk, dass sie über die API und mit welchem Dienstkonto erfolgt ist.

Was Sie wissen sollten​

  • terraform destroy schließt ein Projekt, es löscht es nicht. Das ist die Semantik der Plattform: Write-Token werden sofort widerrufen, gespeicherte Backups bleiben bis zum Ende der Vorhaltezeit lesbar. Ein geschlossenes Projekt verschwindet aus dem Terraform-State. Token, die dieselbe Konfiguration verwaltet, widerruft destroy dabei ebenfalls, auch Read-Token. Soll ein Read-Token den Abbau überleben, nehmen Sie es vorher aus dem State (terraform state rm <Adresse>) oder legen es im Portal an.
  • Jede Änderung an einem Token ersetzt es. Alle Attribute eines lionbackup_project_token sind nur beim Anlegen wählbar; wer eines ändert, bekommt ein neues Token (altes widerrufen, neues erzeugt) — und damit ein neues Geheimnis.
  • Das Geheimnis liegt im State. Die API liefert ein Backup-Token genau einmal aus; der Provider bewahrt es als sensibles Attribut secret im Terraform-State auf. Schützen Sie die State-Datei wie ein Passwort — etwa in einem verschlüsselten Remote-Backend.
  • Zone, Organisation und Unveränderbarkeit sind Anlage-Entscheidungen. Eine Änderung von organization_id, availability_zone, immutable_storage, retention_days oder auto_delete_after_retention ersetzt das Projekt (Plan: must be replaced). Im laufenden Betrieb änderbar sind name, alert_email, billing_reference und anomaly_detection.
  • anomaly_detection folgt der Konfiguration. Ohne das Attribut gilt false: Ein apply schaltet eine im Portal eingeschaltete Anomalieerkennung wieder aus. Verwalten Sie die Einstellung an einer Stelle oder ergänzen Sie lifecycle { ignore_changes = [anomaly_detection] }.
  • Ratenbegrenzung. Die API erlaubt 60 Anfragen pro Minute je Dienstkonto und je IP-Adresse. Der Provider wiederholt 429 und 503 bis zu dreimal und wartet dabei die angekündigte Retry-After-Zeit ab; ein großes apply wird dadurch langsamer, nicht abgebrochen.
  • Rechte. Der Provider kann genau das, was der Mensch darf, dem das Dienstkonto gehört. Projekte anlegen und schließen setzt die Rolle owner oder admin in der Organisation voraus.
  • Mitglieder: einladen dürfen owner und admin, Rollen ändern nur owner. Eine andere role als member setzt der Provider nach der Einladung; lehnt die Plattform das ab, nimmt er die Einladung zurück, und es bleibt alles beim Alten. Die Rolle eines Mitglieds ändert sich im laufenden Betrieb, Organisation und E-Mail-Adresse ersetzen es. Ohne role gilt member: Ein apply nimmt eine im Portal vergebene Rolle wieder zurück. Die Adresse schreiben Sie klein, so wie die Plattform sie führt.
  • terraform destroy auf ein Mitglied entfernt die Person aus der Organisation — aus jeder Rolle und jeder Berechtigungsgruppe, ihre direkten Projektrechte entfallen. Das letzte owner-Mitglied einer Organisation lässt sich nicht entfernen.
  • Berechtigungsgruppen. name und level ändern sich im laufenden Betrieb, project_id und organization_id ersetzen die Gruppe. Wer ein Projekt besitzt, verwaltet die Gruppen seiner Projekte; niemand legt eine Gruppe über der eigenen Rolle an oder hebt sie darüber. Gelöscht wird eine Gruppe nur, wenn sie leer ist: Mitglieder aus derselben Konfiguration entfernt Terraform vorher selbst, im Portal hinzugefügte lassen das Löschen mit group_not_empty scheitern. Die Gruppe selbst führt keine Mitgliederliste, im Portal hinzugefügte Mitglieder sind daher keine Abweichung im Plan.

Referenz​

Provider​

AttributBedeutung
api_keyAPI-Schlüssel; besser über LIONBACKUP_API_KEY in der Umgebung
environmentprod (Standard) oder dev; wählt API- und Token-Endpunkt
api_urleigene Basis-URL der API, überschreibt environment
token_urleigener Token-Endpunkt, überschreibt environment
zone_ready_timeoutSekunden, die ein neues Token auf seine Zone wartet (Standard 60, 0 wartet nicht)

Ressource lionbackup_project​

AttributPflichtBedeutung
organization_idjaKennung der Organisation (Data Source lionbackup_organizations)
namejaProjektname, höchstens 100 Zeichen
availability_zonejaName der Zone, zum Beispiel de01-1
alert_emailneinAdresse für Benachrichtigungen
billing_referenceneinfreier Text für Ihre Abrechnung
anomaly_detectionneinAnomalieerkennung für die Backups des Projekts einschalten, Standard false
immutable_storageneinunveränderbare Ablage, Standard false
retention_daysneinVorhaltezeit bei unveränderbarer Ablage; ohne Angabe der Plattformstandard
auto_delete_after_retentionneinStandard true
id, status—werden von der Plattform vergeben

Ressource lionbackup_project_token​

AttributPflichtBedeutung
project_idjaKennung des Projekts
typeneinwrite (Standard) für Backups, read für Wiederherstellungen
operating_systemneinLinux (Standard), Windows oder macOS (Beta)
usage_count_limitneinhöchstens so viele Verwendungen
rate_limit_per_minuteneinAnfragen je Minute für dieses Token
rate_limit_per_hourneinAnfragen je Stunde für dieses Token
id—wird von der Plattform vergeben
secret—das Backup-Token, sensibel, nur im State

Ressource lionbackup_organization_member​

AttributPflichtBedeutung
organization_idjaKennung der Organisation
emailjaAdresse einer Person mit lionbackup-Konto, kleingeschrieben
roleneinowner, admin, writer, reader, billing, auditor oder member (Standard)
user_id—Kennung der Person, für lionbackup_permission_group_member
id—<organization_id>/<user_id>

Ressource lionbackup_permission_group​

AttributPflichtBedeutung
organization_idjaKennung der Organisation
project_idneinProjekt, an das die Gruppe gebunden ist; ohne Angabe gewährt die Gruppe keine Projektrolle
namejaName der Gruppe, 1 bis 100 Zeichen
leveljaProjektrolle der Mitglieder: owner, admin, writer, reader, billing, auditor
id—wird von der Plattform vergeben

Ressource lionbackup_permission_group_member​

AttributPflichtBedeutung
organization_idjaKennung der Organisation
group_idjaKennung der Berechtigungsgruppe
user_idjaKennung eines Mitglieds der Organisation
id—<organization_id>/<group_id>/<user_id>

Data Sources​

lionbackup_organizations liefert organizations, nach Namen sortiert, mit id, name, status, role (Ihre Rolle in der Organisation) und payment_method: sepa_debit, solange ein SEPA-Lastschriftmandat aktiv ist, sonst transfer, und null, wo Ihre Rolle nur member ist. lionbackup_zones liefert zones mit id, name, status, provider, location_city und storage_type; buchbar sind Zonen mit status = active.

lionbackup_organization liest eine Organisation über ihre id: ihr payment_method und den Block sepa_mandate mit status, reference, iban_masked, account_holder, granted_at und revoked_at (UTC, YYYY-MM-DD HH:MM:SS). Ohne Mandat ist der Block null; nach einem Widerruf zeigt er das widerrufene Mandat, bis ein neues erteilt ist. Die IBAN ist maskiert, die BIC wird nicht ausgegeben. Lesen darf jede Rolle außer member: Diese Rolle sieht auch im Portal keine Zahlungsdaten.

Dazu lionbackup_projects (alle Projekte einer Organisation, organization_id angeben, geschlossene eingeschlossen), lionbackup_project (ein Projekt über seine id) und lionbackup_whoami (das handelnde Dienstkonto, sein Besitzer und dessen Rolle je Organisation).

lionbackup_organization_members liefert die Mitglieder einer Organisation (organization_id angeben) mit id, email, name und ihrer Rolle role; lesen dürfen owner und admin der Organisation und wer eines ihrer Projekte besitzt. lionbackup_permission_groups liefert die Berechtigungsgruppen, die Sie verwalten, mit id, name, level, project_ids und members.

OpenTofu​

OpenTofu verwendet dieselbe Konfiguration. Legen Sie den provider_installation-Block in ~/.tofurc ab (fehlt die Datei, liest OpenTofu auch ~/.terraformrc) und ersetzen Sie in den Befehlen terraform durch tofu. Auch tofu init meldet verified checksum.

Entwicklungsumgebung​

Für Tests gegen die Entwicklungsumgebung setzen Sie im Provider environment = "dev" und verwenden einen dort angelegten Schlüssel. Der Provider selbst kann zusätzlich vom Mirror der Entwicklungsumgebung bezogen werden; dazu tauschen Sie in ~/.terraformrc die URL:

url = "https://git.dev.lionbackup.cloud/terraform/providers/"

Die Quelladresse git.lionbackup.cloud/lionbackup/lionbackup bleibt in beiden Fällen gleich.