Plan Storage

OpenTofu or Terraform plans may contain sensitive information. In order to give the user control over their security, Terrateam supports users defining where plans are stored. Plans must be stored between a plan operation and an apply operation to ensure that the change that is reviewed is what is applied.

By default, plans are stored on the Terrateam backend. Terrateam supports two other methods of storing plans:

1. Any S3-compatible storage (AWS S3, Google GCS, Minio, etc)
2. Custom commands. User defines what commands should be run for store, fetch, and delete steps.

Terrateam Configuration

Terrateam behavior can be configured via a config.yml. This file is located in a directory named .terrateam at the root of your Terraform repository: .terrateam/config.yml.

See Configuration documentation for details.

Configuration

Top-level key: storage Sub key: plans

See Configuration Reference documentation for details.

Key	Type	Description
method	String	Specify how to story plans, valid options: terrateam, s3, cmd. Default is terrateam

For method s3:

Key	Type	Description
bucket	String	Specify bucket to store plan. Can reference environment variables. Required.
region	String	Specify region in which the bucket exists. Can be an environment variable, for example: $PLAN_STORE_REGION. Required.
path	String	The path to store the value in. Default is terrateam/plans/$dir/$workspace/$date-$time-$token. See template variables for details on available variables.
access_key_id	String	Access key ID. Can reference environment variables. Optional.
secret_access_key	String	Secret access key. Can reference environment variables. Optional.
delete_used_plans	Boolean	Delete plan after used. Default is true.
store_extra_args	List	Extra args to use with aws s3 cp when storing a plan file. Optional.
fetch_extra_args	List	Extra args to use with aws s3 cp when fetching a plan file. Optional.
delete_extra_args	List	Extra args to use with aws s3 rm when deleting a plan file. Optional.

For method cmd:

Key	Type	Description
delete	String list	Command to run in order to delete the plan after use. Can reference environment variables. See template variables for details on available variables. Optional.
fetch	String list	Command to run to fetch the plan. Can reference environment variables. See template variables for details on available variables. Required.
store	String list	Command to run to store the plan. Can reference environment variables. See template variables for details on available variables. Required.

In all cases, environment variables can be referenced using the syntax $ENV_VARIABLE.

Default configuration:

storage:
  plans:
    method: terrateam

Example s3 configuration:

storage:
  plans:
    method: s3
    bucket: plan-bucket
    region: us-east-1

Example cmd configuration:

storage:
  plans:
    method: cmd
    delete: ['aws', 's3', 'rm', 's3://$PLAN_BUCKET/terrateam/plans/$dir/$workspace/$date-$time-$token'],
    fetch: ['aws', 's3', 'cp', 's3://$PLAN_BUCKET/terrateam/plans/$dir/$workspace/$date-$time-$token', '$plan_dst_path'],
    store: ['aws', 's3', 'cp', '$plan_path', 's3://$PLAN_BUCKET/terrateam/plans/$dir/$workspace/$date-$time-$token'],

Template Variables

In all parameters, environment variables can be referenced. Additionally, several variables are available that are specific to the run. These variables are stored between the plan and apply operation. For example, if the plan was performed on 2023-10-20 and the apply is performed on 2023-10-25, the $date variable will be 2023-10-20 when the apply is executed. This way, the variables can be used to construct the path that the plan is stored in and it is the same in the plan and apply.

Variable	Description
date	The current date in format YYYY-MM-DD.
dir	The directory being processed, for example: foo/bar/baz.
plan_path	The path on disk to that the plan is stored.
plan_dst_path	When fetching a plan, the location on disk the plan should be put.
time	The current time in the format HHMMSS.
token	The token of the work manifest, unique to every run.
workspace	The workspace being processed. For example default.

Note on environment variables

The value of template variables is retained between a plan operation and an apply operation. However, environment variables are not. If an environment variable is referenced between a plan and apply, ensure that it does not change between runs.

For example, do not reference the following environment variable because it will be different in the apply. This is because the date program outputs the date and time of when it was run.:

hooks:
  all:
    pre:
      - type: env
        name: ENV_VAR_THAT_CHANGES_BETWEEN_RUNS
        cmd: ['date']