Backend de state · Firstlume Docs

O Firstlume é o backend de state dos stacks. Ele usa o backend http do Terraform e do OpenTofu, sem plugin. O código declara o backend e o Firstlume preenche o endereço e a credencial em cada run.

terraform {
  backend "http" {}
}

Em todo run, o executor exporta TF_HTTP_ADDRESS, TF_HTTP_LOCK_ADDRESS, TF_HTTP_UNLOCK_ADDRESS, TF_HTTP_USERNAME e TF_HTTP_PASSWORD, então nada do backend aparece no código.

Com Terragrunt

No Terragrunt, cada unit tem o seu state. O root.hcl monta o endereço de cada uma a partir de FIRSTLUME_STATE_URL:

remote_state {
  backend  = "http"
  generate = { path = "backend.tf", if_exists = "overwrite_terragrunt" }
  config = {
    address        = "${get_env("FIRSTLUME_STATE_URL")}/${path_relative_to_include()}"
    lock_address   = "${get_env("FIRSTLUME_STATE_URL")}/${path_relative_to_include()}"
    unlock_address = "${get_env("FIRSTLUME_STATE_URL")}/${path_relative_to_include()}"
  }
}

A chave de uma unit é o caminho relativo dela, como net ou zone-a/node01. Um stack de Terraform puro tem um state só, na raiz.

Como ele se comporta

Lock por unit. Num run --all, cada unit grava o seu state quando o apply dela termina: se uma unit falha, as outras ficam salvas.
Plan não grava. A credencial da fase de plan (e do drift) só lê e trava o state. Só o apply grava.
Versões. Cada gravação vira uma versão imutável, cifrada com uma chave própria. Gravações que perderiam state (serial menor, lineage de outra infraestrutura) são recusadas.
As travas de um run são soltas quando a fase termina, de qualquer jeito que termine.
Um stack com recursos no state não pode ser excluído. Rode um destroy ou exclua o state antes, com DELETE /api/v1/orgs/{org}/stacks/{id}/state e o nome do stack no corpo, como {"confirm": "<nome>"}. O state excluído fica guardado por 30 dias.

Código sem backend falha no Init. O state ficaria no disco do runner e se perderia. No run --all, em que o Terragrunt inicializa as units durante o plan, a falha vem ao fim do passo Plan. A mensagem cita a unit.

Código com outro backend continua funcionando. Com s3, por exemplo, as variáveis do Firstlume são ignoradas e o state fica onde o código manda.

Mais sobre state

Onde o state fica: Postgres ou um bucket S3, escolhido na instalação
O bucket da organização: um bucket próprio da organização
Tokens "só state": use este backend fora dos runs do Firstlume
Importar um state existente e Migrar uma pipeline

A aba State na UI, com versões, diferença, rollback e destravar à força, está planejada. Hoje a página do run mostra o backend que cada unit usou, e a aba Resources do stack lista o que há no state atual, sem valores de atributos.