Passa al contenuto principale

Terraform

Con il provider lionbackup create progetti, token di backup, membri e gruppi di autorizzazione 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.4:

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

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, l'elenco è ordinato per nome e ogni nuova organizzazione sposta le posizioni. 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.4...
- Installed git.lionbackup.cloud/lionbackup/lionbackup v0.1.4 (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.

Se il vostro .terraform.lock.hcl fissa ancora una versione precedente, terraform init rifiuta il vincolo ~> 0.1.4; terraform init -upgrade sceglie allora la nuova versione e la registra nel file. Il data source lionbackup_organization e l'attributo payment_method esistono solo dalla 0.1.3. L'attributo anomaly_detection esiste dalla 0.1.4, le risorse per membri e gruppi di autorizzazione dalla 0.1.6.

Membri e gruppi di autorizzazione​

Quello che impostate nel portale nella pagina Autorizzazioni lo gestisce anche il provider, dalla versione 0.1.6. L'esempio invita nell'organizzazione una persona del vostro team e, tramite un gruppo di autorizzazione, le dà accesso in lettura al progetto dell'esempio precedente:

resource "lionbackup_organization_member" "alice" {
organization_id = local.organization_id
email = "alice@example.com"
# role = "member" (predefinito): da solo non concede nulla
}

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

Possono essere invitate solo persone che hanno già un account lionbackup; non viene inviata alcuna e-mail di invito. Chi entra nell'organizzazione riceve il ruolo member, che da solo non concede alcun permesso. I permessi su un progetto derivano poi dai gruppi di autorizzazione: ogni membro di un gruppo ha sul progetto del gruppo il ruolo indicato in level. Un gruppo senza project_id vale per l'intera organizzazione, ma non è legato a nessun progetto e quindi non concede alcun ruolo di progetto.

Membri e gruppi esistenti li importate con terraform import. Gli identificativi li forniscono le data source lionbackup_organization_members e 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>

Ogni modifica eseguita tramite il provider compare nel registro audit dell'organizzazione, con l'indicazione che è avvenuta tramite l'API e con quale account di servizio.

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, billing_reference e anomaly_detection.
  • anomaly_detection segue la configurazione. Senza l'attributo vale false: un apply disattiva un rilevamento anomalie attivato nel portale. Gestite l'impostazione in un solo punto oppure aggiungete lifecycle { ignore_changes = [anomaly_detection] }.
  • 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.
  • Membri: invitano owner e admin, solo owner cambia i ruoli. Un role diverso da member il provider lo imposta dopo l'invito; se la piattaforma lo rifiuta, ritira l'invito e tutto resta com'era. Il ruolo di un membro è modificabile durante l'esercizio; una modifica dell'organizzazione o dell'indirizzo e-mail sostituisce il membro. Senza role vale member: un apply annulla un ruolo assegnato nel portale. Scrivete l'indirizzo in minuscolo, così come lo registra la piattaforma.
  • terraform destroy su un membro rimuove la persona dall'organizzazione — da ogni ruolo e da ogni gruppo di autorizzazione, e i suoi permessi diretti sui progetti decadono. L'ultimo membro owner di un'organizzazione non può essere rimosso.
  • Gruppi di autorizzazione. name e level sono modificabili durante l'esercizio, project_id e organization_id sostituiscono il gruppo. Chi possiede un progetto gestisce i gruppi dei propri progetti; nessuno crea un gruppo al di sopra del proprio ruolo né ne alza uno oltre. Un gruppo viene eliminato solo se è vuoto: i membri della stessa configurazione li rimuove prima Terraform stesso, quelli aggiunti nel portale fanno fallire l'eliminazione con group_not_empty. Il gruppo stesso non tiene un elenco dei membri, quindi i membri aggiunti nel portale non risultano come differenza nel piano.

Riferimento​

Provider​

AttributoSignificato
api_keychiave API; meglio tramite LIONBACKUP_API_KEY nell'ambiente
environmentprod (predefinito) o dev; sceglie l'endpoint API e dei token
api_urlURL di base personalizzato dell'API, sovrascrive environment
token_urlendpoint dei token personalizzato, sovrascrive environment
zone_ready_timeoutsecondi di attesa di un nuovo token sulla sua zona (predefinito 60, 0 non attende)

Risorsa lionbackup_project​

AttributoObbligatorioSignificato
organization_idsìidentificativo dell'organizzazione (data source lionbackup_organizations)
namesìnome del progetto, al massimo 100 caratteri
availability_zonesìnome della zona, per esempio de01-1
alert_emailnoindirizzo per le notifiche
billing_referencenotesto libero per la vostra fatturazione
anomaly_detectionnoattivare il rilevamento anomalie per i backup del progetto, predefinito false
immutable_storagenoarchiviazione immutabile, predefinito false
retention_daysnoperiodo di conservazione con archiviazione immutabile; senza indicazione il predefinito della piattaforma
auto_delete_after_retentionnopredefinito true
id, status—assegnati dalla piattaforma

Risorsa lionbackup_project_token​

AttributoObbligatorioSignificato
project_idsìidentificativo del progetto
typenowrite (predefinito) per i backup, read per i ripristini
operating_systemnoLinux (predefinito), Windows o macOS (beta)
usage_count_limitnoal massimo questo numero di utilizzi
rate_limit_per_minutenorichieste al minuto per questo token
rate_limit_per_hournorichieste all'ora per questo token
id—assegnato dalla piattaforma
secret—il token di backup, sensibile, solo nello state

Risorsa lionbackup_organization_member​

AttributoObbligatorioSignificato
organization_idsìidentificativo dell'organizzazione
emailsìindirizzo di una persona con account lionbackup, in minuscolo
rolenoowner, admin, writer, reader, billing, auditor o member (predefinito)
user_id—identificativo della persona, per lionbackup_permission_group_member
id—<organization_id>/<user_id>

Risorsa lionbackup_permission_group​

AttributoObbligatorioSignificato
organization_idsìidentificativo dell'organizzazione
project_idnoprogetto a cui è legato il gruppo; senza indicazione il gruppo non concede alcun ruolo di progetto
namesìnome del gruppo, da 1 a 100 caratteri
levelsìruolo di progetto dei membri: owner, admin, writer, reader, billing, auditor
id—assegnato dalla piattaforma

Risorsa lionbackup_permission_group_member​

AttributoObbligatorioSignificato
organization_idsìidentificativo dell'organizzazione
group_idsìidentificativo del gruppo di autorizzazione
user_idsìidentificativo di un membro dell'organizzazione
id—<organization_id>/<group_id>/<user_id>

Data source​

lionbackup_organizations restituisce organizations, ordinate per nome, con id, name, status, role (il vostro ruolo nell'organizzazione) e payment_method: sepa_debit finché è attivo un mandato di addebito diretto SEPA, altrimenti transfer, e null dove il vostro ruolo è solo member. lionbackup_zones restituisce zones con id, name, status, provider, location_city e storage_type; sono prenotabili le zone con status = active.

lionbackup_organization legge un'organizzazione tramite il suo id: il suo payment_method e il blocco sepa_mandate con status, reference, iban_masked, account_holder, granted_at e revoked_at (UTC, YYYY-MM-DD HH:MM:SS). Senza mandato il blocco è null; dopo una revoca mostra il mandato revocato finché non ne viene concesso uno nuovo. L'IBAN è mascherato, il BIC non viene esposto. Può leggerla qualsiasi ruolo tranne member, che non vede dati di pagamento nemmeno nel portale.

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).

lionbackup_organization_members restituisce i membri di un'organizzazione (indicare organization_id) con id, email, name e il loro ruolo role; possono leggerla i ruoli owner e admin dell'organizzazione e chi possiede uno dei suoi progetti. lionbackup_permission_groups restituisce i gruppi di autorizzazione che gestite, con id, name, level, project_ids e members.

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.