Ga naar hoofdinhoud

Terraform

Met de provider lionbackup maakt u projecten, back-uptokens, leden en rechtengroepen aan als infrastructuurcode. Hij gebruikt de publieke API en daarmee dezelfde rechten als uw serviceaccount in het portaal. De provider werkt met Terraform vanaf 1.9 en met OpenTofu.

Bronadres​

De provider wordt niet via de publieke Terraform-registry verspreid, maar via een network mirror van lionbackup. Neem hem eenmalig op in uw CLI-configuratie ~/.terraformrc (of in het bestand waarnaar TF_CLI_CONFIG_FILE verwijst):

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

Getest met Terraform 1.16 en OpenTofu 1.12. OpenTofu leest dezelfde configuratie uit ~/.tofurc of, als die ontbreekt, uit ~/.terraformrc.

Het direct-blok zorgt ervoor dat Terraform de lionbackup-provider uitsluitend van de mirror haalt; alle andere providers laden zoals gebruikelijk uit hun registry's.

De provider opnemen​

Het bronadres is git.lionbackup.cloud/lionbackup/lionbackup. Gebruik de provider vanaf versie 0.1.4:

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

provider "lionbackup" {
# De API-sleutel komt uit de omgeving:
# export LIONBACKUP_API_KEY=... (portaal → Ontwikkelaars)
# environment = "prod" # standaard; "dev" voor de ontwikkelomgeving
}

De API-sleutel maakt u in het portaal aan onder Ontwikkelaars (zie API) en geeft u door als omgevingsvariabele LIONBACKUP_API_KEY. Het attribuut api_key bestaat ook, maar een sleutel in de configuratie belandt gemakkelijk in het versiebeheer.

Voorbeeld​

Het voorbeeld bepaalt uw organisatie, maakt daarin een project aan in de zone de01-1, genereert een schrijftoken en geeft het geheim ervan uit als gevoelige output:

data "lionbackup_organizations" "mine" {}

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

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
}

De organisatie wordt op naam gekozen, niet op positie in de lijst: een serviceaccount kan meerdere organisaties zien, de lijst is op naam gesorteerd en elke nieuwe organisatie verschuift de posities. one() breekt af bij meer dan één treffer; is er geen, dan blijft organization_id leeg en weigert Terraform het plan. In geen geval wordt het project stilletjes in de verkeerde organisatie aangemaakt.

availability_zone verwacht de naam van de zone, zoals de pagina Regio's en de data source lionbackup_zones die noemen; het omzetten naar de identifier doet de provider.

Toepassen:

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

terraform init laadt de provider van de mirror en controleert hem tegen de daar vastgelegde checksums. De uitvoer hoort zo te eindigen:

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

De checksum belandt in .terraform.lock.hcl. Neem dit bestand op in het versiebeheer, dan installeert elke run exact dezelfde providerversie.

Legt uw .terraform.lock.hcl nog een oudere versie vast, dan weigert terraform init de voorwaarde ~> 0.1.4; terraform init -upgrade kiest dan de nieuwe versie en legt die in het bestand vast. De data source lionbackup_organization en het attribuut payment_method bestaan pas vanaf 0.1.3. Het attribuut anomaly_detection bestaat vanaf 0.1.4, de resources voor leden en rechtengroepen vanaf 0.1.6.

Leden en rechtengroepen​

Wat u in het portaal op de pagina Rechten instelt, beheert de provider vanaf versie 0.1.6 ook. Het voorbeeld nodigt een collega uit in de organisatie en geeft die collega via een rechtengroep leestoegang tot het project uit het voorbeeld hierboven:

resource "lionbackup_organization_member" "alice" {
organization_id = local.organization_id
email = "alice@example.com"
# role = "member" (standaard): geeft op zichzelf niets
}

resource "lionbackup_permission_group" "backup_readers" {
organization_id = local.organization_id
project_id = lionbackup_project.backup.id
name = "Back-uplezers"
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
}

Alleen personen die al een lionbackup-account hebben, kunnen worden uitgenodigd; een uitnodigingsmail is er niet. Wie nieuw in de organisatie komt, krijgt de rol member, die op zichzelf geen rechten geeft. De rechten op een project komen dan uit de rechtengroepen: elk lid van een groep heeft op het project van de groep de rol uit level. Een groep zonder project_id geldt voor de hele organisatie, maar is aan geen enkel project gekoppeld en geeft daarom geen projectrol.

Bestaande leden en groepen neemt u over met terraform import. De identifiers krijgt u uit de data sources lionbackup_organization_members en 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>

Elke wijziging via de provider verschijnt in het auditlog van de organisatie, met de vermelding dat ze via de API is gedaan en met welk serviceaccount.

Wat u moet weten​

  • terraform destroy sluit een project, het verwijdert het niet. Dat is de semantiek van het platform: schrijftokens worden meteen ingetrokken, opgeslagen back-ups blijven tot het einde van de bewaartermijn leesbaar. Een gesloten project verdwijnt uit de Terraform-state. Tokens die dezelfde configuratie beheert, worden ook ingetrokken, leestokens inbegrepen. Wilt u een leestoken na het afbreken behouden, haal het dan eerst uit de state (terraform state rm <adres>) of maak het aan in het portaal.
  • Elke wijziging aan een token vervangt het. Alle attributen van een lionbackup_project_token zijn alleen bij het aanmaken te kiezen; wie er een wijzigt, krijgt een nieuw token (oude ingetrokken, nieuwe aangemaakt) — en daarmee een nieuw geheim.
  • Het geheim staat in de state. De API levert een back-uptoken precies één keer uit; de provider bewaart het als gevoelig attribuut secret in de Terraform-state. Bescherm het statebestand als een wachtwoord — bijvoorbeeld in een versleutelde remote backend.
  • Zone, organisatie en onveranderbaarheid zijn beslissingen bij het aanmaken. Een wijziging van organization_id, availability_zone, immutable_storage, retention_days of auto_delete_after_retention vervangt het project (plan: must be replaced). Tijdens het gebruik te wijzigen zijn name, alert_email, billing_reference en anomaly_detection.
  • anomaly_detection volgt de configuratie. Zonder het attribuut geldt false: een apply schakelt een in het portaal ingeschakelde anomaliedetectie weer uit. Beheer de instelling op één plek of voeg lifecycle { ignore_changes = [anomaly_detection] } toe.
  • Snelheidslimiet. De API staat 60 verzoeken per minuut toe per serviceaccount en per IP-adres. De provider herhaalt 429 en 503 tot drie keer en wacht daarbij de aangekondigde Retry-After-tijd af; een grote apply wordt daardoor trager, niet afgebroken.
  • Rechten. De provider kan precies wat de persoon mag die het serviceaccount bezit. Projecten aanmaken en sluiten vereist de rol owner of admin in de organisatie.
  • Leden: owner en admin mogen uitnodigen, alleen owner wijzigt rollen. Een andere role dan member stelt de provider na de uitnodiging in; weigert het platform dat, dan trekt hij de uitnodiging in en blijft alles bij het oude. De rol van een lid is tijdens het gebruik te wijzigen; een andere organisatie of een ander e-mailadres vervangt het lid. Zonder role geldt member: een apply draait een in het portaal toegekende rol weer terug. Schrijf het adres in kleine letters, zoals het platform het bijhoudt.
  • terraform destroy op een lid verwijdert de persoon uit de organisatie — uit elke rol en elke rechtengroep, en diens directe projectrechten vervallen. Het laatste owner-lid van een organisatie kan niet worden verwijderd.
  • Rechtengroepen. name en level zijn tijdens het gebruik te wijzigen, project_id en organization_id vervangen de groep. Wie een project bezit, beheert de groepen van de eigen projecten; niemand maakt een groep aan boven de eigen rol of verhoogt er een tot daarboven. Een groep wordt alleen verwijderd als hij leeg is: leden uit dezelfde configuratie verwijdert Terraform eerst zelf, in het portaal toegevoegde leden laten het verwijderen mislukken met group_not_empty. De groep zelf houdt geen ledenlijst bij; in het portaal toegevoegde leden zijn daarom geen afwijking in het plan.

Referentie​

Provider​

AttribuutBetekenis
api_keyAPI-sleutel; liever via LIONBACKUP_API_KEY in de omgeving
environmentprod (standaard) of dev; kiest API- en token-endpoint
api_urleigen basis-URL van de API, overschrijft environment
token_urleigen token-endpoint, overschrijft environment
zone_ready_timeoutseconden die een nieuw token op zijn zone wacht (standaard 60, 0 wacht niet)

Resource lionbackup_project​

AttribuutVerplichtBetekenis
organization_idjaidentifier van de organisatie (data source lionbackup_organizations)
namejaprojectnaam, maximaal 100 tekens
availability_zonejanaam van de zone, bijvoorbeeld de01-1
alert_emailneeadres voor meldingen
billing_referenceneevrije tekst voor uw facturering
anomaly_detectionneeanomaliedetectie voor de back-ups van het project inschakelen, standaard false
immutable_storageneeonveranderbare opslag, standaard false
retention_daysneebewaartermijn bij onveranderbare opslag; zonder opgave de platformstandaard
auto_delete_after_retentionneestandaard true
id, status—worden door het platform toegekend

Resource lionbackup_project_token​

AttribuutVerplichtBetekenis
project_idjaidentifier van het project
typeneewrite (standaard) voor back-ups, read voor herstel
operating_systemneeLinux (standaard), Windows of macOS (bèta)
usage_count_limitneemaximaal zoveel keer te gebruiken
rate_limit_per_minuteneeverzoeken per minuut voor dit token
rate_limit_per_hourneeverzoeken per uur voor dit token
id—wordt door het platform toegekend
secret—het back-uptoken, gevoelig, alleen in de state

Resource lionbackup_organization_member​

AttribuutVerplichtBetekenis
organization_idjaidentifier van de organisatie
emailjaadres van een persoon met een lionbackup-account, in kleine letters
roleneeowner, admin, writer, reader, billing, auditor of member (standaard)
user_id—identifier van de persoon, voor lionbackup_permission_group_member
id—<organization_id>/<user_id>

Resource lionbackup_permission_group​

AttribuutVerplichtBetekenis
organization_idjaidentifier van de organisatie
project_idneeproject waaraan de groep is gekoppeld; zonder opgave geeft de groep geen projectrol
namejanaam van de groep, 1 tot 100 tekens
leveljaprojectrol van de leden: owner, admin, writer, reader, billing, auditor
id—wordt door het platform toegekend

Resource lionbackup_permission_group_member​

AttribuutVerplichtBetekenis
organization_idjaidentifier van de organisatie
group_idjaidentifier van de rechtengroep
user_idjaidentifier van een lid van de organisatie
id—<organization_id>/<group_id>/<user_id>

Data sources​

lionbackup_organizations levert organizations, gesorteerd op naam, met id, name, status, role (uw rol in de organisatie) en payment_method: sepa_debit zolang een SEPA-incassomachtiging actief is, anders transfer, en null waar uw rol alleen member is. lionbackup_zones levert zones met id, name, status, provider, location_city en storage_type; te boeken zijn zones met status = active.

lionbackup_organization leest één organisatie via haar id: haar payment_method en het blok sepa_mandate met status, reference, iban_masked, account_holder, granted_at en revoked_at (UTC, YYYY-MM-DD HH:MM:SS). Zonder machtiging is het blok null; na een intrekking toont het de ingetrokken machtiging tot er een nieuwe is verleend. Het IBAN is gemaskeerd, de BIC wordt niet getoond. Elke rol behalve member mag haar lezen; die rol ziet ook in het portaal geen betaalgegevens.

Daarnaast lionbackup_projects (alle projecten van één organisatie, organization_id opgeven, gesloten projecten inbegrepen), lionbackup_project (één project via zijn id) en lionbackup_whoami (het handelende serviceaccount, de eigenaar ervan en diens rol per organisatie).

lionbackup_organization_members levert de leden van één organisatie (organization_id opgeven) met id, email, name en hun rol role; lezen mogen owner en admin van de organisatie en wie een van haar projecten bezit. lionbackup_permission_groups levert de rechtengroepen die u beheert, met id, name, level, project_ids en members.

OpenTofu​

OpenTofu gebruikt dezelfde configuratie. Zet het provider_installation-blok in ~/.tofurc (ontbreekt dat bestand, dan leest OpenTofu ook ~/.terraformrc) en vervang in de commando's terraform door tofu. Ook tofu init meldt verified checksum.

Ontwikkelomgeving​

Voor tests tegen de ontwikkelomgeving zet u in de provider environment = "dev" en gebruikt u een daar aangemaakte sleutel. De provider zelf kan bovendien van de mirror van de ontwikkelomgeving worden gehaald; daarvoor wisselt u in ~/.terraformrc de URL:

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

Het bronadres git.lionbackup.cloud/lionbackup/lionbackup blijft in beide gevallen hetzelfde.