Lifecycle Hooks
A lifecycle hook runs a check or action automatically before or after an Atmos
component operation. For example, a hook on before.terraform.plan can require
an owner in the component configuration before allowing the plan to start.
Hooks make checks part of the operation your team already runs. Callers do not need to remember a separate validation command. Your script receives the resolved component configuration, so the check can use inherited settings and variables directly. After-hooks can report results or start follow-up work.
This guide uses the owner-check example. Install
Atmos and Terraform and put them on your PATH. The example includes the Atmos
configuration and a Terraform module with no providers or resources; it needs
no cloud credentials.
Add a check before planning
This stack defines an api component and a hook requiring it to have an owner:
The hook selects before.terraform.plan and uses kind: step with type: script
to run one script step. Its with block configures that step, including
interpreter: starlark for the Atmos Automation Language.
on_failure: fail makes a failed check stop the operation. The script reads
ctx.component.vars, calls fail() if the owner is absent, and otherwise prints
a success message with ui.success().
The component is named api in the stack; its implementation directory is
service. ctx.component.name retains the component name used by the caller,
so messages identify api.
Run the passing case
Run from the example's directory:
atmos terraform plan api -s dev
The hook prints:
Owner check passed: api belongs to platform (dev).
Terraform then reports no changes.
Stop an invalid operation
The unowned stack imports the same configuration and clears the owner:
Run the same operation against that stack:
atmos terraform plan api -s unowned
The command fails with Set an owner before planning api. Because the check runs
before the plan and has a failing policy, the Terraform plan does not start.
The inherited hook protects both stacks using the same logic.
Work with lifecycle context
Hook scripts receive read-only objects describing their invocation:
| Object | Use it for |
|---|---|
ctx.component | Component name, stack, implementation path, resolved variables, settings, and metadata |
ctx.hook | Hook name and the canonical event that triggered it |
ctx.operation | Parent command and the operation outcome supplied to an after-hook |
A before-hook has no operation outcome yet: status, exit code, and error are
None. After-hooks expose the supplied outcome. Ordinary lifecycle hooks do not
capture the parent command's stdout or stderr, and Terraform outputs are not
automatically attached to the component context.
Choose events and failure behavior
Declare the events your hook handles explicitly. Use before-events for checks that must pass first and after-events for follow-up work. Keep a hook's failure policy visible alongside its event so the effect on the parent command is clear.
See the hooks reference for supported events, kinds, inheritance, and failure policies. The lifecycle context reference lists script fields and their behavior, including hooks without an individual component binding. Browse the runnable example for the complete project used in this guide.
