Skip to content

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.

KeyTypeDescription
methodStringSpecify how to story plans, valid options: terrateam, s3, cmd. Default is terrateam

For method s3:

KeyTypeDescription
bucketStringSpecify bucket to store plan. Can reference environment variables. Required.
regionStringSpecify region in which the bucket exists. Can be an environment variable, for example: $PLAN_STORE_REGION. Required.
pathStringThe 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_idStringAccess key ID. Can reference environment variables. Optional.
secret_access_keyStringSecret access key. Can reference environment variables. Optional.
delete_used_plansBooleanDelete plan after used. Default is true.
store_extra_argsListExtra args to use with aws s3 cp when storing a plan file. Optional.
fetch_extra_argsListExtra args to use with aws s3 cp when fetching a plan file. Optional.
delete_extra_argsListExtra args to use with aws s3 rm when deleting a plan file. Optional.

For method cmd:

KeyTypeDescription
deleteString listCommand to run in order to delete the plan after use. Can reference environment variables. See template variables for details on available variables. Optional.
fetchString listCommand to run to fetch the plan. Can reference environment variables. See template variables for details on available variables. Required.
storeString listCommand 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.

VariableDescription
dateThe current date in format YYYY-MM-DD.
dirThe directory being processed, for example: foo/bar/baz.
plan_pathThe path on disk to that the plan is stored.
plan_dst_pathWhen fetching a plan, the location on disk the plan should be put.
timeThe current time in the format HHMMSS.
tokenThe token of the work manifest, unique to every run.
workspaceThe 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']
We use cookies and similar technologies to provide certain features, enhance the user experience and deliver content that is relevant to your interests. Depending on their purpose, analysis and marketing cookies may be used in addition to technically necessary cookies. By clicking on "Agree and continue", you declare your consent to the use of the aforementioned cookies. Here you can make detailed settings or revoke your consent (in part if necessary) with effect for the future. For further information, please refer to our Privacy Policy .