.firstlume/config.yaml · Firstlume Docs

A .firstlume folder with a config.yaml marks the root of an infrastructure in a repository. The folder that contains .firstlume is where Terraform or Terragrunt runs. The file sets the engine, and can also declare what a run needs: files mounted in a given format, environment variables, Terraform variables and registry credentials.

The file is read from the commit being run. Changing the Terraform version is a commit, and the apply uses the same configuration as its plan.

The basics

version: 1                   # required; only 1 today
engine: terraform            # required: terraform or opentofu
engine_version: 1.15.6       # required: an exact version
terragrunt_version: 1.1.6    # optional: when present, runs through Terragrunt
run_all: true                # optional: needs terragrunt_version

Unknown fields are an error, to catch typos. A missing or invalid file fails the run at plan, with the file and the error:

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

With run_all: true, the stack runs terragrunt run --all from that folder, covering every unit below it. The plan saves each unit's plan, and the apply applies exactly those, unit by unit. It is one run for all units. Native units, with one run each, are planned.

A full example

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

files:
  # One file in each folder matching zones/*/*; ${name} is the folder's name, ${dir} its path.
  - path: zones/*/*/connection.hcl
    format: hcl
    block: locals            # read_terragrunt_config doesn't accept loose attributes
    values:
      host: "${name}.internal.example.com"
      user: { var: SSH_USER } # a variable from Firstlume's settings
      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               # becomes TF_VAR_zone; maps and lists become JSON

Formats

Format	Writes
`hcl`	`key = value` for each item in `values`. `block` wraps them in a block, such as `locals`
`json`	a JSON object, good for `*.auto.tfvars.json`
`yaml`	a YAML document
`env`	`KEY=value` lines, read by the shell's `source`
`raw`	the value of `content`, as it is

Firstlume does the escaping. In hcl, a value with ${ or %{ stays text and never becomes a Terraform expression.

Sources

A value in the declaration can be:

a literal
{var: NAME}, which reads an env or terraform variable from the settings
{vault: path, field: field}, a field of a Vault secret. See Vault secrets

By folder

The wildcard only works in the folders of path, not in the file name, and doesn't match hidden folders such as .terragrunt-cache.
A pattern that matches no folder fails the run, so a typo doesn't go unnoticed.
${stack_dir} is the absolute path of the stack's folder in the run, in any text in the declaration. Use it to point at a generated file from code running inside .terragrunt-cache, as with the SSH key: ssh_private_key_path: "${stack_dir}/ssh/id_ed25519". $${ writes a literal ${.

When files are written

Files are written after the checkout and before init, in the Prepare step of every phase. The apply gets the same values as the plan.

Safety

A file that uses a sensitive variable is sensitive: it gets 0600 permissions, and its content is masked in the log, line by line.
Firstlume doesn't overwrite a file that already exists in the repository, doesn't write the same file twice, and doesn't follow a symbolic link out of the stack's folder. In those cases, the run fails.
path can't contain .. or point to .git or .firstlume.
A phase can write up to 1,000 files, with 256 KiB per file and 16 MiB in total.

Variables with the same name

If a name in the declaration's env or terraform also exists in the settings, the settings win, and the log records the swap, with no values.

File variables in the settings

Besides env and terraform variables, settings accept variables with "category": "file". The key is the file's path, relative to the stack's folder, and the value is the content. They are inherited like the others, and suit anyone not using Vault, or a file common to many stacks.

See what a commit declares

GET /api/v1/orgs/{org}/stacks/{id}/declaration shows what the last commit declares, with the references and no values.

Registry credentials

registries in this file is covered in Registry credentials.