.firstlume/config.yaml

Uma pasta .firstlume com um config.yaml marca a raiz de uma infraestrutura no repositório. A pasta que contém o .firstlume é onde o Terraform ou o Terragrunt roda. O arquivo define a engine e também pode declarar o que um run precisa: arquivos montados em um formato, variáveis de ambiente, variáveis do Terraform e credenciais de registry.

O arquivo é lido do commit que está sendo executado. Trocar a versão do Terraform é um commit, e o apply usa a mesma configuração do plan.

O básico

version: 1                   # obrigatório; hoje só 1
engine: terraform            # obrigatório: terraform ou opentofu
engine_version: 1.15.6       # obrigatório: versão exata
terragrunt_version: 1.1.6    # opcional: se presente, roda via Terragrunt
run_all: true                # opcional: exige terragrunt_version

Campos desconhecidos são erro, para pegar erros de digitação. Um arquivo ausente ou inválido falha o run no plan, com o arquivo e o erro:

environments/prod/.firstlume/config.yaml: engine_version must be an exact version like 1.9.8

Com run_all: true, o stack roda terragrunt run --all a partir dessa pasta, cobrindo todas as units abaixo dela. O plan salva o plano de cada unit, e o apply aplica exatamente esses planos, unit por unit. É um run só para todas as units. Units nativas, com um run cada, estão planejadas.

Um exemplo completo

version: 1
engine: terraform
engine_version: 1.15.6
terragrunt_version: 1.1.6
run_all: true

files:
  # Um arquivo em cada pasta que casa com zones/*/*; ${name} é o nome da pasta, ${dir} o caminho.
  - path: zones/*/*/connection.hcl
    format: hcl
    block: locals            # read_terragrunt_config não aceita atributos soltos
    values:
      host: "${name}.internal.example.com"
      user: { var: SSH_USER } # variável das configurações do Firstlume
      port: 22
  - path: credentials.auto.tfvars.json
    format: json
    values:
      buckets: { logs: { var: LOGS_KEY } }
  - path: ssh/id_ed25519
    format: raw
    content: { var: SSH_KEY }

env:
  TF_LOG: ""
terraform:
  zone: zone-a               # vira TF_VAR_zone; mapas e listas viram JSON

Formatos

O Firstlume faz o escape. No hcl, um valor com ${ ou %{ continua texto, nunca vira expressão do Terraform.

Fontes

Um valor da declaração pode ser:

• um literal
• {var: NOME}, que lê uma variável env ou terraform das configurações
• {vault: caminho, field: campo}, um campo de um segredo do Vault. Veja Segredos do Vault

Por pastas

• O curinga só vale nas pastas do path, não no nome do arquivo, e não casa com pastas ocultas (.terragrunt-cache).
• Um padrão que não casa com nenhuma pasta falha o run, para um erro de digitação não passar despercebido.
• ${stack_dir} é o caminho absoluto da pasta do stack no run, em qualquer texto da declaração. Serve para apontar um arquivo gerado a partir de código que roda dentro do .terragrunt-cache, como a chave SSH: ssh_private_key_path: "${stack_dir}/ssh/id_ed25519". $${ escreve um ${ literal.

Quando os arquivos são escritos

Os arquivos são escritos depois do checkout e antes do init, no passo Prepare, em toda fase. O apply recebe os mesmos valores do plan.

Segurança

• Um arquivo que usa uma variável sensível é sensível: sai com permissão 0600 e o conteúdo é mascarado no log, linha a linha.
• O Firstlume não sobrescreve um arquivo que já existe no repositório, não escreve o mesmo arquivo duas vezes e não segue link simbólico para fora da pasta do stack. Nesses casos o run falha.
• O path não pode ter .. nem apontar para .git ou .firstlume.
• Uma fase escreve até 1.000 arquivos, com 256 KiB por arquivo e 16 MiB no total.

Variáveis com o mesmo nome

Com o mesmo nome em env ou terraform da declaração e nas configurações, vencem as configurações, e o log registra a troca, sem valores.

Variáveis do tipo arquivo nas configurações

Além de env e terraform, as configurações aceitam variáveis com "category": "file". A chave é o caminho do arquivo, relativo à pasta do stack, e o valor é o conteúdo. São herdadas como as outras e servem para quem não usa Vault, ou para um arquivo comum a muitos stacks.

Veja o que um commit declara

GET /api/v1/orgs/{org}/stacks/{id}/declaration mostra o que o último commit declara, com as referências e sem valores.

Credenciais de registry

registries neste arquivo está em Credenciais de registry.