Aller au contenu principal

Terraform

Avec le fournisseur lionbackup, vous créez des projets, des jetons de sauvegarde, des membres et des groupes d'autorisations en infrastructure as code. Il utilise l'API publique et donc les mêmes droits que votre compte de service dans le portail. Le fournisseur fonctionne avec Terraform à partir de la version 1.9 et avec OpenTofu.

Source d'installation​

Le fournisseur n'est pas distribué via le registre public de Terraform, mais via un network mirror de lionbackup. Inscrivez-le une seule fois dans votre configuration CLI ~/.terraformrc (ou dans le fichier désigné par 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/*/*"]
}
}

Testé avec Terraform 1.16 et OpenTofu 1.12. OpenTofu lit la même configuration dans ~/.tofurc ou, à défaut, dans ~/.terraformrc.

Le bloc direct garantit que Terraform récupère le fournisseur lionbackup exclusivement depuis le mirror ; tous les autres fournisseurs continuent de se charger comme d'habitude depuis leurs registres.

Intégrer le fournisseur​

L'adresse source est git.lionbackup.cloud/lionbackup/lionbackup. Utilisez le fournisseur à partir de la version 0.1.4 :

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

provider "lionbackup" {
# La clé d'API provient de l'environnement :
# export LIONBACKUP_API_KEY=... (Portail → Développeurs)
# environment = "prod" # par défaut ; "dev" pour l'environnement de développement
}

Vous créez la clé d'API dans le portail sous Développeurs (voir API) et la transmettez comme variable d'environnement LIONBACKUP_API_KEY. L'attribut api_key existe aussi, mais une clé dans la configuration finit facilement dans le gestionnaire de versions.

Exemple​

L'exemple détermine votre organisation, y crée un projet dans la zone de01-1, génère un jeton d'écriture et expose son secret comme output sensible :

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'organisation est choisie par son nom, pas par sa position dans la liste : un compte de service peut voir plusieurs organisations, la liste est triée par nom et chaque nouvelle organisation décale les positions. one() échoue s'il y a plusieurs correspondances ; s'il n'y en a aucune, organization_id reste vide et Terraform refuse le plan. Dans aucun cas le projet n'est créé silencieusement dans la mauvaise organisation.

availability_zone attend le nom de la zone, tel que l'indiquent la page Régions et la data source lionbackup_zones ; la résolution vers l'identifiant est prise en charge par le fournisseur.

Appliquer :

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

terraform init télécharge le fournisseur depuis le mirror et le vérifie par rapport aux sommes de contrôle qui y sont déposées. La sortie devrait se terminer ainsi :

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

La somme de contrôle est enregistrée dans .terraform.lock.hcl. Ajoutez ce fichier au gestionnaire de versions : chaque exécution installera alors exactement la même version du fournisseur.

Si votre .terraform.lock.hcl retient encore une version antérieure, terraform init refuse la contrainte ~> 0.1.4 ; terraform init -upgrade choisit alors la nouvelle version et l'inscrit dans le fichier. La data source lionbackup_organization et l'attribut payment_method n'existent qu'à partir de la 0.1.3. L'attribut anomaly_detection existe à partir de la 0.1.4, les ressources pour les membres et les groupes d'autorisations à partir de la 0.1.6.

Membres et groupes d'autorisations​

Ce que vous réglez dans le portail sur la page Autorisations, le fournisseur le gère lui aussi à partir de la version 0.1.6. L'exemple invite une personne de votre équipe dans l'organisation et lui donne, via un groupe d'autorisations, un accès en lecture au projet de l'exemple ci-dessus :

resource "lionbackup_organization_member" "alice" {
organization_id = local.organization_id
email = "alice@example.com"
# role = "member" (par défaut) : n'accorde rien à lui seul
}

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

Seules les personnes qui possèdent déjà un compte lionbackup peuvent être invitées ; aucun e-mail d'invitation n'est envoyé. Toute personne qui rejoint l'organisation reçoit le rôle member, qui n'accorde à lui seul aucun droit. Les droits sur un projet proviennent alors des groupes d'autorisations : chaque membre d'un groupe dispose, sur le projet du groupe, du rôle indiqué dans level. Un groupe sans project_id s'applique à toute l'organisation, mais n'est rattaché à aucun projet et n'accorde donc aucun rôle de projet.

Reprenez les membres et groupes existants avec terraform import. Les data sources lionbackup_organization_members et lionbackup_permission_groups fournissent les identifiants :

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>

Chaque modification effectuée via le fournisseur apparaît dans le journal d'audit de l'organisation, avec la mention qu'elle a été faite via l'API et avec quel compte de service.

Ce qu'il faut savoir​

  • terraform destroy ferme un projet, il ne le supprime pas. C'est la sémantique de la plateforme : les jetons d'écriture sont révoqués immédiatement, les sauvegardes stockées restent lisibles jusqu'à la fin de la durée de rétention. Un projet fermé disparaît de l'état Terraform. Les jetons gérés par la même configuration sont aussi révoqués, jetons de lecture compris. Pour garder un jeton de lecture après le démontage, retirez-le d'abord de l'état (terraform state rm <adresse>) ou créez-le dans le portail.
  • Toute modification d'un jeton le remplace. Tous les attributs d'un lionbackup_project_token ne se choisissent qu'à la création ; qui en modifie un obtient un nouveau jeton (l'ancien révoqué, un nouveau généré) — et donc un nouveau secret.
  • Le secret est dans l'état. L'API ne délivre un jeton de sauvegarde qu'une seule fois ; le fournisseur le conserve comme attribut sensible secret dans l'état Terraform. Protégez le fichier d'état comme un mot de passe — par exemple dans un backend distant chiffré.
  • Zone, organisation et immuabilité sont des décisions prises à la création. Une modification de organization_id, availability_zone, immutable_storage, retention_days ou auto_delete_after_retention remplace le projet (plan : must be replaced). Modifiables en cours d'exploitation : name, alert_email, billing_reference et anomaly_detection.
  • anomaly_detection suit la configuration. Sans l'attribut, la valeur est false : un apply désactive une détection d'anomalies activée dans le portail. Gérez le réglage à un seul endroit, ou ajoutez lifecycle { ignore_changes = [anomaly_detection] }.
  • Limite de débit. L'API autorise 60 requêtes par minute par compte de service et par adresse IP. Le fournisseur répète 429 et 503 jusqu'à trois fois en respectant le délai Retry-After annoncé ; un grand apply devient ainsi plus lent, mais n'est pas interrompu.
  • Droits. Le fournisseur peut faire exactement ce que peut faire la personne à qui appartient le compte de service. Créer et fermer des projets exige le rôle owner ou admin dans l'organisation.
  • Membres : owner et admin invitent, seul owner modifie les rôles. Le fournisseur définit un role autre que member après l'invitation ; si la plateforme le refuse, il retire l'invitation et rien ne change. Le rôle d'un membre est modifiable en cours d'exploitation ; un changement d'organisation ou d'adresse e-mail remplace le membre. Sans role, la valeur est member : un apply annule un rôle attribué dans le portail. Écrivez l'adresse en minuscules, telle que la plateforme la conserve.
  • terraform destroy sur un membre retire la personne de l'organisation — de chaque rôle et de chaque groupe d'autorisations, et ses droits directs sur les projets disparaissent. Le dernier membre owner d'une organisation ne peut pas être retiré.
  • Groupes d'autorisations. name et level sont modifiables en cours d'exploitation, project_id et organization_id remplacent le groupe. Qui possède un projet gère les groupes de ses projets ; personne ne crée de groupe au-dessus de son propre rôle ni n'en élève un au-delà. Un groupe n'est supprimé que s'il est vide : Terraform retire d'abord lui-même les membres issus de la même configuration, ceux ajoutés dans le portail font échouer la suppression avec group_not_empty. Le groupe lui-même ne tient pas de liste de membres ; les membres ajoutés dans le portail n'apparaissent donc pas comme un écart dans le plan.

Référence​

Fournisseur​

AttributSignification
api_keyclé d'API ; de préférence via LIONBACKUP_API_KEY dans l'environnement
environmentprod (par défaut) ou dev ; sélectionne le point de terminaison API et jeton
api_urlURL de base propre pour l'API, remplace environment
token_urlpoint de terminaison propre pour le jeton, remplace environment
zone_ready_timeoutsecondes pendant lesquelles un nouveau jeton attend sa zone (60 par défaut, 0 n'attend pas)

Ressource lionbackup_project​

AttributObligatoireSignification
organization_idouiidentifiant de l'organisation (data source lionbackup_organizations)
nameouinom du projet, 100 caractères au maximum
availability_zoneouinom de la zone, par exemple de01-1
alert_emailnonadresse pour les notifications
billing_referencenontexte libre pour votre facturation
anomaly_detectionnonactiver la détection d'anomalies pour les sauvegardes du projet, par défaut false
immutable_storagenonstockage immuable, par défaut false
retention_daysnondurée de rétention pour le stockage immuable ; sans indication, la valeur par défaut de la plateforme
auto_delete_after_retentionnonpar défaut true
id, status—attribués par la plateforme

Ressource lionbackup_project_token​

AttributObligatoireSignification
project_idouiidentifiant du projet
typenonwrite (par défaut) pour les sauvegardes, read pour les restaurations
operating_systemnonLinux (par défaut), Windows ou macOS (bêta)
usage_count_limitnonau maximum ce nombre d'utilisations
rate_limit_per_minutenonrequêtes par minute pour ce jeton
rate_limit_per_hournonrequêtes par heure pour ce jeton
id—attribué par la plateforme
secret—le jeton de sauvegarde, sensible, uniquement dans l'état

Ressource lionbackup_organization_member​

AttributObligatoireSignification
organization_idouiidentifiant de l'organisation
emailouiadresse d'une personne disposant d'un compte lionbackup, en minuscules
rolenonowner, admin, writer, reader, billing, auditor ou member (par défaut)
user_id—identifiant de la personne, pour lionbackup_permission_group_member
id—<organization_id>/<user_id>

Ressource lionbackup_permission_group​

AttributObligatoireSignification
organization_idouiidentifiant de l'organisation
project_idnonprojet auquel le groupe est rattaché ; sans indication, le groupe n'accorde aucun rôle de projet
nameouinom du groupe, de 1 à 100 caractères
levelouirôle de projet des membres : owner, admin, writer, reader, billing, auditor
id—attribué par la plateforme

Ressource lionbackup_permission_group_member​

AttributObligatoireSignification
organization_idouiidentifiant de l'organisation
group_idouiidentifiant du groupe d'autorisations
user_idouiidentifiant d'un membre de l'organisation
id—<organization_id>/<group_id>/<user_id>

Data sources​

lionbackup_organizations renvoie organizations, triées par nom, avec id, name, status, role (votre rôle dans l'organisation) et payment_method : sepa_debit tant qu'un mandat de prélèvement SEPA est actif, sinon transfer, et null là où votre rôle n'est que member. lionbackup_zones renvoie zones avec id, name, status, provider, location_city et storage_type ; seules les zones avec status = active peuvent être réservées.

lionbackup_organization lit une organisation par son id : son payment_method et le bloc sepa_mandate avec status, reference, iban_masked, account_holder, granted_at et revoked_at (UTC, YYYY-MM-DD HH:MM:SS). Sans mandat, le bloc vaut null ; après une révocation, il montre le mandat révoqué jusqu'à ce qu'un nouveau soit accordé. L'IBAN est masqué, le BIC n'est pas exposé. Tout rôle peut la lire sauf member, qui ne voit pas non plus de données de paiement dans le portail.

S'y ajoutent lionbackup_projects (tous les projets d'une organisation, indiquer organization_id, projets fermés compris), lionbackup_project (un projet par son id) et lionbackup_whoami (le compte de service qui agit, son propriétaire et le rôle de celui-ci par organisation).

lionbackup_organization_members renvoie les membres d'une organisation (indiquer organization_id) avec id, email, name et leur rôle role ; peuvent la lire les rôles owner et admin de l'organisation ainsi que quiconque possède l'un de ses projets. lionbackup_permission_groups renvoie les groupes d'autorisations que vous gérez, avec id, name, level, project_ids et members.

OpenTofu​

OpenTofu utilise la même configuration. Placez le bloc provider_installation dans ~/.tofurc (si le fichier manque, OpenTofu lit aussi ~/.terraformrc) et remplacez terraform par tofu dans les commandes. tofu init signale lui aussi verified checksum.

Environnement de développement​

Pour des tests contre l'environnement de développement, définissez environment = "dev" dans le fournisseur et utilisez une clé créée dans cet environnement. Le fournisseur lui-même peut en outre être récupéré depuis le mirror de l'environnement de développement ; pour cela, remplacez l'URL dans ~/.terraformrc :

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

L'adresse source git.lionbackup.cloud/lionbackup/lionbackup reste la même dans les deux cas.