Saltar al contenido principal

Terraform

Con el proveedor lionbackup crea proyectos, tokens de copia de seguridad, miembros y grupos de permisos como infraestructura como código. Utiliza la API pública y, por tanto, los mismos permisos que su cuenta de servicio en el portal. El proveedor funciona con Terraform a partir de la versión 1.9 y con OpenTofu.

Dónde obtenerlo​

El proveedor no se distribuye a través del registro público de Terraform, sino mediante un network mirror de lionbackup. Regístrelo una sola vez en su configuración de la CLI ~/.terraformrc (o en el archivo al que apunte 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/*/*"]
}
}

Probado con Terraform 1.16 y OpenTofu 1.12. OpenTofu lee la misma configuración desde ~/.tofurc o, si no existe, desde ~/.terraformrc.

El bloque direct garantiza que Terraform obtenga el proveedor de lionbackup exclusivamente del mirror; todos los demás proveedores se siguen descargando como de costumbre desde sus registros.

Incluir el proveedor​

La dirección de origen es git.lionbackup.cloud/lionbackup/lionbackup. Utilice el proveedor a partir de la versión 0.1.4:

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

provider "lionbackup" {
# La clave de API procede del entorno:
# export LIONBACKUP_API_KEY=... (Portal → Desarrollo)
# environment = "prod" # por defecto; "dev" para el entorno de desarrollo
}

La clave de API se crea en el portal, en Desarrollo (véase API), y se pasa como variable de entorno LIONBACKUP_API_KEY. El atributo api_key también existe, pero una clave en la configuración acaba fácilmente en el control de versiones.

Ejemplo​

El ejemplo determina su organización, crea en ella un proyecto en la zona de01-1, genera un token de escritura y emite su secreto como 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
}

La organización se selecciona por su nombre, no por su posición en la lista: una cuenta de servicio puede ver varias organizaciones, la lista está ordenada por nombre y cada organización nueva desplaza las posiciones. one() falla si hay más de una coincidencia; si no hay ninguna, organization_id queda vacío y Terraform rechaza el plan. En ningún caso se crea el proyecto en silencio en la organización equivocada.

availability_zone espera el nombre de la zona, tal como lo indican la página Regiones y la data source lionbackup_zones; de la resolución al identificador se encarga el proveedor.

Aplicar:

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

terraform init descarga el proveedor del mirror y lo verifica contra las sumas de comprobación allí depositadas. La salida debería terminar así:

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

La suma de comprobación queda en .terraform.lock.hcl. Incluya este archivo en el control de versiones y cada ejecución instalará exactamente la misma versión del proveedor.

Si su .terraform.lock.hcl aún fija una versión anterior, terraform init rechaza la condición ~> 0.1.4; terraform init -upgrade elige entonces la versión nueva y la anota en el archivo. El data source lionbackup_organization y el atributo payment_method existen a partir de la 0.1.3. El atributo anomaly_detection existe a partir de la 0.1.4; los recursos para miembros y grupos de permisos, a partir de la 0.1.6.

Miembros y grupos de permisos​

Lo que configura en el portal en la página Permisos también lo gestiona el proveedor a partir de la versión 0.1.6. El ejemplo invita a una persona de su equipo a la organización y, mediante un grupo de permisos, le da acceso de lectura al proyecto del ejemplo anterior:

resource "lionbackup_organization_member" "alice" {
organization_id = local.organization_id
email = "alice@example.com"
# role = "member" (por defecto): no concede nada por sí solo
}

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

Solo se puede invitar a personas que ya tengan una cuenta de lionbackup; no se envía ningún correo electrónico de invitación. Quien se incorpora a la organización recibe el rol member, que por sí solo no concede ningún derecho. Los derechos sobre un proyecto provienen entonces de los grupos de permisos: cada miembro de un grupo tiene en el proyecto del grupo el rol indicado en level. Un grupo sin project_id se aplica a toda la organización, pero no está vinculado a ningún proyecto y, por tanto, no otorga ningún rol de proyecto.

Para incorporar miembros y grupos existentes, utilice terraform import. Los identificadores los proporcionan los data sources lionbackup_organization_members y 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>

Cada cambio realizado mediante el proveedor figura en el registro de auditoría de la organización, con la indicación de que se hizo a través de la API y con qué cuenta de servicio.

Lo que debe saber​

  • terraform destroy cierra un proyecto, no lo borra. Esa es la semántica de la plataforma: los tokens de escritura se revocan de inmediato y las copias guardadas siguen siendo legibles hasta el final del período de retención. Un proyecto cerrado desaparece del state de Terraform. También se revocan los tokens que gestiona la misma configuración, incluidos los de lectura. Para conservar un token de lectura tras el desmontaje, quítelo antes del state (terraform state rm <dirección>) o créelo en el portal.
  • Cualquier cambio en un token lo sustituye. Todos los atributos de un lionbackup_project_token solo pueden elegirse al crearlo; quien cambie uno obtiene un token nuevo (el antiguo se revoca, se genera uno nuevo) — y con ello un secreto nuevo.
  • El secreto reside en el state. La API entrega un token de copia de seguridad una sola vez; el proveedor lo conserva como atributo sensible secret en el state de Terraform. Proteja el archivo de state como una contraseña — por ejemplo en un backend remoto cifrado.
  • Zona, organización e inmutabilidad son decisiones de creación. Un cambio en organization_id, availability_zone, immutable_storage, retention_days o auto_delete_after_retention sustituye el proyecto (plan: must be replaced). Durante la operación pueden cambiarse name, alert_email, billing_reference y anomaly_detection.
  • anomaly_detection sigue a la configuración. Sin el atributo vale false: un apply desactiva una detección de anomalías activada en el portal. Gestione el ajuste en un solo lugar o añada lifecycle { ignore_changes = [anomaly_detection] }.
  • Límites de frecuencia. La API permite 60 peticiones por minuto por cuenta de servicio y por dirección IP. El proveedor reintenta 429 y 503 hasta tres veces y espera entretanto el tiempo Retry-After anunciado; un apply grande se vuelve así más lento, no se interrumpe.
  • Permisos. El proveedor puede hacer exactamente lo que puede hacer la persona a la que pertenece la cuenta de servicio. Crear y cerrar proyectos requiere el rol owner o admin en la organización.
  • Miembros: invitan owner y admin, solo owner cambia roles. El proveedor establece un role distinto de member después de la invitación; si la plataforma lo rechaza, retira la invitación y todo queda como estaba. El rol de un miembro puede cambiarse durante la operación; un cambio de organización o de dirección de correo electrónico sustituye al miembro. Sin role vale member: un apply revierte un rol asignado en el portal. Escriba la dirección en minúsculas, tal como la guarda la plataforma.
  • terraform destroy sobre un miembro quita a la persona de la organización — de cada rol y de cada grupo de permisos, y sus derechos directos sobre proyectos desaparecen. El último miembro owner de una organización no se puede quitar.
  • Grupos de permisos. name y level pueden cambiarse durante la operación; project_id y organization_id sustituyen el grupo. Quien posee un proyecto gestiona los grupos de sus proyectos; nadie crea un grupo por encima de su propio rol ni lo eleva por encima de él. Un grupo solo se elimina si está vacío: Terraform quita antes por sí mismo los miembros de la misma configuración; los añadidos en el portal hacen que la eliminación falle con group_not_empty. El propio grupo no lleva una lista de miembros, por lo que los miembros añadidos en el portal no son una desviación en el plan.

Referencia​

Proveedor​

AtributoSignificado
api_keyclave de API; mejor mediante LIONBACKUP_API_KEY en el entorno
environmentprod (por defecto) o dev; elige el endpoint de la API y del token
api_urlURL base propia de la API, sobrescribe environment
token_urlendpoint de token propio, sobrescribe environment
zone_ready_timeoutsegundos que un token nuevo espera a su zona (60 por defecto, 0 no espera)

Recurso lionbackup_project​

AtributoObligatorioSignificado
organization_idsíidentificador de la organización (data source lionbackup_organizations)
namesínombre del proyecto, 100 caracteres como máximo
availability_zonesínombre de la zona, por ejemplo de01-1
alert_emailnodirección para notificaciones
billing_referencenotexto libre para su facturación
anomaly_detectionnoactivar la detección de anomalías para los backups del proyecto, por defecto false
immutable_storagenoalmacenamiento inmutable, por defecto false
retention_daysnoperíodo de retención con almacenamiento inmutable; sin indicación, el valor de la plataforma
auto_delete_after_retentionnopor defecto true
id, status—los asigna la plataforma

Recurso lionbackup_project_token​

AtributoObligatorioSignificado
project_idsíidentificador del proyecto
typenowrite (por defecto) para copias de seguridad, read para restauraciones
operating_systemnoLinux (por defecto), Windows o macOS (beta)
usage_count_limitnocomo máximo este número de usos
rate_limit_per_minutenopeticiones por minuto para este token
rate_limit_per_hournopeticiones por hora para este token
id—lo asigna la plataforma
secret—el token de copia de seguridad, sensible, solo en el state

Recurso lionbackup_organization_member​

AtributoObligatorioSignificado
organization_idsíidentificador de la organización
emailsídirección de una persona con cuenta de lionbackup, en minúsculas
rolenoowner, admin, writer, reader, billing, auditor o member (por defecto)
user_id—identificador de la persona, para lionbackup_permission_group_member
id—<organization_id>/<user_id>

Recurso lionbackup_permission_group​

AtributoObligatorioSignificado
organization_idsíidentificador de la organización
project_idnoproyecto al que está vinculado el grupo; sin indicarlo, el grupo no otorga ningún rol de proyecto
namesínombre del grupo, de 1 a 100 caracteres
levelsírol de proyecto de los miembros: owner, admin, writer, reader, billing, auditor
id—lo asigna la plataforma

Recurso lionbackup_permission_group_member​

AtributoObligatorioSignificado
organization_idsíidentificador de la organización
group_idsíidentificador del grupo de permisos
user_idsíidentificador de un miembro de la organización
id—<organization_id>/<group_id>/<user_id>

Data sources​

lionbackup_organizations devuelve organizations, ordenadas por nombre, con id, name, status, role (su rol en la organización) y payment_method: sepa_debit mientras esté activo un mandato de adeudo directo SEPA, transfer en caso contrario, y null donde su rol es solo member. lionbackup_zones devuelve zones con id, name, status, provider, location_city y storage_type; son contratables las zonas con status = active.

lionbackup_organization lee una organización por su id: su payment_method y el bloque sepa_mandate con status, reference, iban_masked, account_holder, granted_at y revoked_at (UTC, YYYY-MM-DD HH:MM:SS). Sin mandato el bloque es null; tras una revocación muestra el mandato revocado hasta que se otorgue uno nuevo. El IBAN se muestra enmascarado y el BIC no se expone. Puede leerlo cualquier rol salvo member, que tampoco ve datos de pago en el portal.

Además lionbackup_projects (todos los proyectos de una organización, indique organization_id, incluidos los cerrados), lionbackup_project (un proyecto por su id) y lionbackup_whoami (la cuenta de servicio que actúa, su propietario y el rol de este en cada organización).

lionbackup_organization_members devuelve los miembros de una organización (indique organization_id) con id, email, name y su rol role; pueden leerlo los roles owner y admin de la organización, así como quien posea uno de sus proyectos. lionbackup_permission_groups devuelve los grupos de permisos que usted gestiona, con id, name, level, project_ids y members.

OpenTofu​

OpenTofu utiliza la misma configuración. Coloque el bloque provider_installation en ~/.tofurc (si el archivo no existe, OpenTofu lee también ~/.terraformrc) y sustituya en los comandos terraform por tofu. También tofu init informa de verified checksum.

Entorno de desarrollo​

Para pruebas contra el entorno de desarrollo, establezca en el proveedor environment = "dev" y utilice una clave creada allí. El propio proveedor puede obtenerse además del mirror del entorno de desarrollo; para ello cambie la URL en ~/.terraformrc:

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

La dirección de origen git.lionbackup.cloud/lionbackup/lionbackup es la misma en ambos casos.