Run Terraform (or any infra glue) from a hook

Provision DNS, certificates, databases, or other external resources in a pre-deploy hook that runs on your computer and reads the sealed bundle through a secrets profile.

Read as MarkdownEdit on GitHub

A pre-deploy hook runs a command before the service swap, with access to the sealed bundle. A secrets_profile names the env that the tool needs. For the two hook flavors, see Pre-deploy hooks.

In this example, a Terraform module in terraform/cloudflare/ owns the Cloudflare DNS and the Authenticated Origin Pulls of a service. The hook runs terraform apply on that module. It is a subprocess hook: yoink runs the terraform binary directly on your computer.

Layout

deploy-prod/
├── yoink.yaml          # the deploy config below
└── secrets.age         # sealed bundle, includes CLOUDFLARE_API_TOKEN
                        # + TFSTATE_B2_KEY_ID/_APPLICATION_KEY

terraform/cloudflare/
├── main.tf             # zone, dns, origin_pulls, …
├── terraform.tfvars
└── …

Run Terraform from a pre-deploy hook

Define the profile

Declare a profile in deploy-prod/yoink.yaml. The profile holds the env that the Cloudflare provider and the S3-compatible state backend of Terraform need.

secrets:
  provider: age
  recipients: [age1…]
  profiles:
    terraform-cloudflare:
      include: [CLOUDFLARE_API_TOKEN,
                TFSTATE_B2_KEY_ID, TFSTATE_B2_APPLICATION_KEY]
      rename:
        TFSTATE_B2_KEY_ID:          AWS_ACCESS_KEY_ID
        TFSTATE_B2_APPLICATION_KEY: AWS_SECRET_ACCESS_KEY
      unset: [B2_ENDPOINT, B2_BUCKET_NAME,
              B2_ACCESS_KEY_ID, B2_SECRET_ACCESS_KEY]
  • include is the allowlist. The env of the hook does not contain the other keys of the bundle.
  • rename maps the key names of the bundle to the env names that the providers expect.
  • unset clears each conflicting key that your parent shell exported. For example, the init_hook of devbox sets B2_ENDPOINT for the runtime app. Without unset, the b2 SDK below the Terraform provider routes auth to that endpoint.

Add the hook

hooks:
  pre_deploy:
    - name: cloudflare-tf-apply
      working_dir: ../terraform/cloudflare
      cmd: ["sh", "-c",
            "terraform init -input=false && terraform apply -auto-approve"]
      secrets_profile: terraform-cloudflare

The hook has no image: and no tag:, so yoink runs cmd[0] directly. yoink resolves working_dir: relative to the directory of yoink.yaml, so yoink up works from any directory.

The hook inherits your env, so terraform is on PATH and Terraform finds its plugin cache and its .terraform/ directory. Then yoink changes the env:

  • It removes every unset key of the profile.
  • It adds CLOUDFLARE_API_TOKEN, AWS_ACCESS_KEY_ID, and AWS_SECRET_ACCESS_KEY from the sealed bundle, with the rename applied.

stdout and stderr of the hook stream live to your terminal.

Make sure that the profile reference resolves

yoink validate

yoink resolves the profile when it loads the config. An unknown name, such as the typo secrets_profile: terraform-cloudfare, fails here, before yoink takes a deploy lock:

yoink: hook `cloudflare-tf-apply` references unknown secrets profile "terraform-cloudfare";
       known: terraform-backblaze, terraform-cloudflare

Only a subprocess hook accepts a profile with unset:. A container hook has no parent env to clear, and validation rejects that combination.

Deploy

yoink up

The hook is a top-level hook, so each yoink up runs this sequence:

  1. The pre-deploy hook starts a child process with the resolved env. terraform apply reconciles the Cloudflare zone against the module.
  2. If terraform apply exits non-zero, the hook fails and the deploy stops. No service swap occurs. The RunFinished event in the audit log has the error message.
  3. On success, yoink continues with the container reconcile.

If the hook fails

If terraform apply fails partway, run yoink up again. yoink runs the hook again, and Terraform converges.

To debug, load the same profile into your shell with yoink secrets env --profile terraform-cloudflare. Then terraform plan in your shell gives the same result as in the hook.

Rotate a credential

  1. Change the bundle entry.
  2. Run yoink up.

A top-level hook runs on every yoink up, so terraform apply uses the new value. The hook config is not an input of the spec hash of a service, so a profile change alone does not redeploy a service.

See also

Type a flag, a config field, or a task.