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.
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]
includeis the allowlist. The env of the hook does not contain the other keys of the bundle.renamemaps the key names of the bundle to the env names that the providers expect.unsetclears each conflicting key that your parent shell exported. For example, theinit_hookof devbox setsB2_ENDPOINTfor the runtime app. Withoutunset, 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
unsetkey of the profile. - It adds
CLOUDFLARE_API_TOKEN,AWS_ACCESS_KEY_ID, andAWS_SECRET_ACCESS_KEYfrom 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:
- The pre-deploy hook starts a child process with the resolved env.
terraform applyreconciles the Cloudflare zone against the module. - If
terraform applyexits non-zero, the hook fails and the deploy stops. No service swap occurs. TheRunFinishedevent in the audit log has the error message. - 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
- Change the bundle entry.
- 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
- Pre-deploy hooks: the two hook flavors, when a container hook fits, and tools other than Terraform.
- Secrets profiles: the schema reference for
include,renameandunset. - Sealed secrets workflow: the same profile in your shell and in CI.
- Read the audit log: the hook events and the
RunFinishederror of a failed run.