Skip to content

tofu-stop

The trunk-pipeline stop lane for a stoppable environment (spec 0056, stoppable environments). Emits one manual job (default-branch pipelines only, allow_failure: true) carrying environment: action: stop — the job the Environments-page Stop button plays.

Stop = strip to baseline, never destroy. The job runs an overlay apply — the environment's normal var-file plus a stop overlay var-file, later file winning:

tofu apply -input=false -auto-approve \
  -var-file=<var_file> -var-file=<stop_var_file>

The overlay forces the environment's fail-closed enable flags off, destroying exactly the gated optional concerns while the baseline — audit trail, account alias, alerting — stays up. The next normal deploy restores full configuration and flips the environment back to available. (tofu destroy is deliberately not offered: non-empty audit buckets fail it, account-alias import blocks jam every plan afterwards, and alert subscriptions would need re-confirming on every restart.)

Why a trunk job: GitLab plays a stop action from the pipeline of the environment's latest deployment. An environment that auto-deploys from the default branch almost always has a trunk pipeline as its latest deployment — a stop lane only in release-tag child pipelines (the tofu-deploy-generate stoppable catalog flag) would rarely be the one GitLab runs. Pair both.

Tier guard: deployment_tier accepts only development and staging (spec:inputs:options) — a production or control-plane trunk stop job is unexpressible. Because those environments never get an on_stop job, their Stop button stays cosmetic on GitLab Free.

Jobs

Job What it runs
tofu-stop OIDC token → AWS env vars, tofu init -input=false, then the overlay apply above. Manual, allow_failure: true, environment: {name, deployment_tier, action: stop}, resource_group.

Inputs

Input Type Default Description
image_version string "v0.1.0" tofu-tools image tag.
stage string apply GitLab CI stage.
job_name string "tofu-stop" The paired tofu-apply's on_stop input must equal this exactly. Override for one stop lane per stoppable environment.
working_directory string "." Must match the paired tofu-apply's.
role_arn string (required) ARN of the AWS IAM role to assume via OIDC.
aws_region string "eu-west-2" AWS region.
aud string "sts.amazonaws.com" OIDC audience claim.
var_file string (required) The environment's normal var-file, relative to working_directory — the same one its plan/apply jobs use.
stop_var_file string (required) The stop overlay, applied after var_file (later file wins).
environment_name string (required) Environment to stop — must match the paired tofu-apply's environment_name.
deployment_tier string (development|staging) (required) The fail-closed tier guard — nothing else is accepted.
resource_group string (required) Set to the paired tofu-apply's group so stops serialize with deploys.
state_token string "$CI_JOB_TOKEN" Token for the GitLab HTTP state backend.

Usage

See the paired example on tofu-apply — include tofu-apply with environment_mode: stoppable / on_stop: tofu-stop and this component with matching environment_name, working_directory, and resource_group. For the release-tag side of the same environment, set stoppable: true in the tofu-deploy-generate catalog.

See also