Terraform

Con il provider lionbackup create progetti e token di backup come infrastruttura come codice. Usa l'API pubblica e quindi gli stessi permessi del vostro account di servizio nel portale. Il provider funziona con Terraform dalla versione 1.9 e con OpenTofu.

Fonte di distribuzione

Il provider non viene distribuito tramite il registry pubblico di Terraform, ma tramite un network mirror di lionbackup. Inseritelo una sola volta nella vostra configurazione CLI ~/.terraformrc (o nel file a cui punta TF_CLI_CONFIG_FILE):

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

Testato con Terraform 1.16 e OpenTofu 1.12. OpenTofu legge la stessa configurazione da ~/.tofurc oppure, in mancanza, da ~/.terraformrc.

Il blocco direct fa sì che Terraform scarichi il provider lionbackup esclusivamente dal mirror; tutti gli altri provider continuano a essere scaricati come di consueto dai rispettivi registry.

Integrare il provider

L'indirizzo di origine è git.lionbackup.cloud/lionbackup/lionbackup. Usate il provider dalla versione 0.1.1:

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

provider "lionbackup" {
  # La chiave API proviene dall'ambiente:
  #   export LIONBACKUP_API_KEY=...   (Portale → Sviluppatori)
  # environment = "prod"   # predefinito; "dev" per l'ambiente di sviluppo
}

La chiave API la create nel portale alla voce Sviluppatori (vedi API) e la passate come variabile d'ambiente LIONBACKUP_API_KEY. Esiste anche l'attributo api_key, ma una chiave nella configurazione finisce facilmente nel controllo di versione.

Esempio

L'esempio determina la vostra organizzazione, vi crea un progetto nella zona de01-1, genera un token di scrittura e ne emette il segreto come output sensibile:

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
}

L'organizzazione viene scelta per nome, non per posizione nell'elenco: un account di servizio può vedere più organizzazioni e l'ordine non è garantito. one() fallisce con più corrispondenze; se non ce n'è nessuna, organization_id resta vuoto e Terraform rifiuta il piano. In nessun caso il progetto viene creato silenziosamente nell'organizzazione sbagliata.

availability_zone si aspetta il nome della zona, come lo indicano la pagina Regioni e la data source lionbackup_zones; la risoluzione nell'identificativo la esegue il provider.

Applicare:

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

terraform init scarica il provider dal mirror e lo verifica rispetto alle somme di controllo lì depositate. L'output dovrebbe terminare così:

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

La somma di controllo finisce in .terraform.lock.hcl. Includete questo file nel controllo di versione: così ogni esecuzione installa esattamente la stessa versione del provider.

Cosa è bene sapere

terraform destroy chiude un progetto, non lo cancella. È la semantica della piattaforma: i token di scrittura vengono revocati immediatamente, i backup archiviati restano leggibili fino alla fine del periodo di conservazione. Un progetto chiuso scompare dallo state di Terraform. Vengono revocati anche i token gestiti dalla stessa configurazione, compresi quelli di lettura. Per conservare un token di lettura dopo lo smantellamento, rimuovetelo prima dallo state (terraform state rm <indirizzo>) oppure createlo nel portale.
Ogni modifica a un token lo sostituisce. Tutti gli attributi di un lionbackup_project_token si possono scegliere solo alla creazione; chi ne modifica uno ottiene un nuovo token (il vecchio revocato, il nuovo generato) — e con esso un nuovo segreto.
Il segreto è nello state. L'API consegna un token di backup una sola volta; il provider lo conserva come attributo sensibile secret nello state di Terraform. Proteggete il file di state come una password — per esempio in un backend remoto cifrato.
Zona, organizzazione e immutabilità sono decisioni prese alla creazione. Una modifica di organization_id, availability_zone, immutable_storage, retention_days o auto_delete_after_retention sostituisce il progetto (plan: must be replaced). Modificabili durante l'esercizio sono name, alert_email e billing_reference.
Limiti di frequenza. L'API consente 60 richieste al minuto per account di servizio e per indirizzo IP. Il provider ripete 429 e 503 fino a tre volte, attendendo il tempo Retry-After annunciato; un apply di grandi dimensioni diventa così più lento, non viene interrotto.
Permessi. Il provider può fare esattamente ciò che può fare la persona a cui appartiene l'account di servizio. Creare e chiudere progetti richiede il ruolo owner o admin nell'organizzazione.

Riferimento

Provider

Attributo	Significato
`api_key`	chiave API; meglio tramite `LIONBACKUP_API_KEY` nell'ambiente
`environment`	`prod` (predefinito) o `dev`; sceglie l'endpoint API e dei token
`api_url`	URL di base personalizzato dell'API, sovrascrive `environment`
`token_url`	endpoint dei token personalizzato, sovrascrive `environment`

Risorsa `lionbackup_project`

Attributo	Obbligatorio	Significato
`organization_id`	sì	identificativo dell'organizzazione (data source `lionbackup_organizations`)
`name`	sì	nome del progetto, al massimo 100 caratteri
`availability_zone`	sì	nome della zona, per esempio `de01-1`
`alert_email`	no	indirizzo per le notifiche
`billing_reference`	no	testo libero per la vostra fatturazione
`immutable_storage`	no	archiviazione immutabile, predefinito `false`
`retention_days`	no	periodo di conservazione con archiviazione immutabile; senza indicazione il predefinito della piattaforma
`auto_delete_after_retention`	no	predefinito `true`
`id`, `status`	—	assegnati dalla piattaforma

Risorsa `lionbackup_project_token`

Attributo	Obbligatorio	Significato
`project_id`	sì	identificativo del progetto
`type`	no	`write` (predefinito) per i backup, `read` per i ripristini
`operating_system`	no	`Linux` (predefinito) o `Windows`
`usage_count_limit`	no	al massimo questo numero di utilizzi
`rate_limit_per_minute`	no	richieste al minuto per questo token
`rate_limit_per_hour`	no	richieste all'ora per questo token
`id`	—	assegnato dalla piattaforma
`secret`	—	il token di backup, sensibile, solo nello state

Data source

lionbackup_organizations restituisce organizations con id, name, status e role (il vostro ruolo nell'organizzazione). lionbackup_zones restituisce zones con id, name, status, provider, location_city e storage_type; sono prenotabili le zone con status = active.

Inoltre lionbackup_projects (tutti i progetti di un'organizzazione, indicare organization_id, chiusi compresi), lionbackup_project (un progetto tramite il suo id) e lionbackup_whoami (l'account di servizio che agisce, il suo proprietario e il ruolo di questo per organizzazione).

OpenTofu

OpenTofu usa la stessa configurazione. Mettete il blocco provider_installation in ~/.tofurc (se il file manca, OpenTofu legge anche ~/.terraformrc) e nei comandi sostituite terraform con tofu. Anche tofu init segnala verified checksum.

Ambiente di sviluppo

Per i test contro l'ambiente di sviluppo impostate nel provider environment = "dev" e usate una chiave creata lì. Il provider stesso può inoltre essere scaricato dal mirror dell'ambiente di sviluppo; per farlo sostituite l'URL in ~/.terraformrc:

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

L'indirizzo di origine git.lionbackup.cloud/lionbackup/lionbackup resta uguale in entrambi i casi.

Fonte di distribuzione​

Integrare il provider​

Esempio​

Cosa è bene sapere​

Riferimento​

Provider​

Risorsa lionbackup_project​

Risorsa lionbackup_project_token​

Data source​

OpenTofu​

Ambiente di sviluppo​