Skip to content

tofu-plan

OIDC-authenticated tofu plan against AWS. GitLab CI mints an OIDC ID token; the AWS provider exchanges it for short-lived credentials via AssumeRoleWithWebIdentity (AWS_ROLE_ARN + AWS_WEB_IDENTITY_TOKEN_FILE) — no aws sts call, no static credentials. State auth uses gitlab-ci-token + state_token (default $CI_JOB_TOKEN) against the GitLab-managed HTTP backend.

Produces tfplan.cache (binary plan, artifact) for tofu-apply to consume, and tfplan.json as a GitLab terraform report so the MR widget shows the add/change/destroy summary.

Runs on MR pipelines (review the plan) and the default branch only (bank the plan artifact for a ref-mode apply) — the contexts whose OIDC subject the standard automation-role trust policy accepts.

Provider config requirement

The stack's aws provider must not hardcode a profile — that short-circuits the web-identity credential chain. See Explanation: OpenTofu state and caching.

Jobs

Job What it runs
tofu-plan Writes the OIDC token to a file, exports AWS_ROLE_ARN/AWS_WEB_IDENTITY_TOKEN_FILE/AWS_REGION, tofu init -input=false, tofu plan -input=false -out=tfplan.cache (with -var-file if set), tofu show -json → tfplan.json.

Inputs

Input Type Default Description
image_version string "v0.3.0" infra-tools image tag.
stage string plan GitLab CI stage.
working_directory string "." The stack directory — contains the root *.tf and the http backend block.
role_arn string (required) ARN of the AWS IAM role to assume via OIDC.
aws_region string "eu-west-2" AWS region the provider operates in.
aud string "sts.amazonaws.com" OIDC audience claim. Must match the IAM OIDC provider's client_id_list and the role trust policy's aud condition.
var_file string "" Optional -var-file path, relative to working_directory. Empty = none.
state_token string "$CI_JOB_TOKEN" Token for the GitLab HTTP state backend (TF_HTTP_PASSWORD). Override for a cross-project or external state backend.

Usage

include:
  - component: gitlab.com/phpboyscout/cicd/[email protected]
    inputs:
      role_arn: "arn:aws:iam::<account>:role/phpboyscout-automation"

See also