Storage

OpenTofu or Terraform plans may contain sensitive information. In order to give users control over their security, Terrateam supports 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.

Configuration

plan storage is configured in the .terrateam/config.yml file under the storage key. Here’s the default configuration:

storage:
  plans:
    method: terrateam

Storage methods

The method key specifies how to store plans. Valid options are:

terrateam: Store plans on the Terrateam backend (default).
s3: Store plans in an S3-compatible storage.
cmd: Use custom commands to store, fetch, and delete plans.

S3 storage

To store plans in an S3-compatible storage, use the following configuration:

Key	Type	Description
bucket	String	Specify the bucket to store plans. Can reference environment variables. Required.
region	String	Specify the region in which the bucket exists. Can be an environment variable, for example: `$PLAN_STORE_REGION`. Required.
path	String	The path to store the plan 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 use. 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.

Example s3 configuration:

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

Custom command storage

To use custom commands for storing, fetching, and deleting plans, use the following configuration:

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

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 where the plan is stored, and it is the same in the plan and apply.

Variable	Description
date	The date when the `plan` was performed, in the format `YYYY-MM-DD`.
dir	The directory being processed, for example: `foo/bar/baz`.
plan_path	The path on disk where the plan is stored.
plan_dst_path	When fetching a plan, the location on disk where the plan should be put.
time	The time when the `plan` was performed, 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']

Examples

Storing plans in AWS S3

storage:
  plans:
    method: s3
    bucket: my-plan-bucket
    region: us-west-2
    access_key_id: $AWS_ACCESS_KEY_ID
    secret_access_key: $AWS_SECRET_ACCESS_KEY

This configuration stores plans in an AWS S3 bucket named my-plan-bucket in the us-west-2 region. The AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY environment variables are used for authentication.

Using custom commands for plan storage

storage:
  plans:
    method: cmd
    store: ['gsutil', 'cp', '$plan_path', 'gs://my-plan-bucket/terrateam/plans/$dir/$workspace/$date-$time-$token']
    fetch: ['gsutil', 'cp', 'gs://my-plan-bucket/terrateam/plans/$dir/$workspace/$date-$time-$token', '$plan_dst_path']
    delete: ['gsutil', 'rm', 'gs://my-plan-bucket/terrateam/plans/$dir/$workspace/$date-$time-$token']

This configuration uses custom commands to store, fetch, and delete plans using Google Cloud Storage. The gsutil command-line tool is used to interact with the storage bucket.