Plan file storage

Terrateam allows you to store Terraform plan files in various locations, providing flexibility and control over how and where your plan files are stored. By configuring plan file storage, you can ensure that your plan files are securely stored and easily accessible when needed.

Why store plan files?

Storing plan files is important for several reasons:

Plan files contain a snapshot of the desired state of your infrastructure at a specific point in time. By storing them, you can easily reference and compare different versions of your infrastructure.
Plan files are used during the apply process to ensure that the changes being applied match the changes that were previously planned and reviewed.
Storing plan files externally provides an additional layer of security.

Configuring plan file storage

To configure plan file storage in Terrateam, you need to modify the storage section in your Terrateam configuration file (.terrateam/config.yml).

storage:
  plans:
    method: s3
    bucket: my-terraform-plans
    region: us-east-1

In this example, we set the method to s3 to indicate that we want to store plan files in an AWS S3 bucket. We then specify the bucket and region where the plan files should be stored.

Storage methods

Terrateam supports several storage methods for plan files:

terrateam (default): Plan files are stored within the Terrateam backend. This is the default behavior and requires no additional configuration.
s3: Plan files are stored in an AWS S3 bucket. You need to provide the bucket and region in your configuration.
cmd: Plan files are stored using a custom command. You need to provide the store, fetch, and delete commands in your configuration.

S3 storage

To store plan files in an AWS S3 bucket, you need to configure the following options:

bucket: The name of the S3 bucket where plan files will be stored.
region: The AWS region where the S3 bucket is located.
path (optional): The path within the S3 bucket where plan files will be stored. Defaults to terrateam/plans/$dir/$workspace/$date-$time-$token.
access_key_id (optional): The AWS access key ID to use for authentication. If not provided, Terrateam will use the default AWS credentials chain.
secret_access_key (optional): The AWS secret access key to use for authentication. If not provided, Terrateam will use the default AWS credentials chain.

Custom command storage

To store plan files using a custom command, you need to configure the following options:

store: The command to run when storing a plan file. The command should accept the plan file path as an argument.
fetch: The command to run when fetching a plan file. The command should accept the plan file path as an argument and output the plan file contents to stdout.
delete (optional): The command to run when deleting a plan file. The command should accept the plan file path as an argument.

Using plan file storage

Once you’ve configured plan file storage in your Terrateam configuration file, Terrateam will automatically store and retrieve plan files as needed during the plan and apply process.

Open a pull request with changes to your Terraform code.
Terrateam automatically runs a plan operation and stores the resulting plan file using the configured storage method.
Review the plan output and collaborate with your team to ensure the changes are as expected.
Once the pull request is approved, comment terrateam apply to trigger an apply operation.
Terrateam retrieves the stored plan file and uses it during the apply process to ensure the changes match the previously reviewed plan.
After the apply is complete, Terrateam deletes the stored plan file (if configured to do so).

Considerations

When using S3 storage, ensure that the AWS credentials used by Terrateam have the necessary permissions to read, write, and delete objects in the specified S3 bucket.
If using custom command storage, ensure that the commands are properly secured and have access to the necessary resources (e.g., storage systems, credentials) to store and retrieve plan files.
Plan files may contain sensitive information about your infrastructure. Always ensure that your storage method is properly secured and that access to the stored plan files is restricted to authorized users.
Terrateam provides several built-in variables that you can use in your storage configuration, such as $dir, $workspace, and $date. These variables allow you to create dynamic paths for storing plan files based on the current directory, workspace, and timestamp.

Example

Here’s an example of a Terrateam configuration file that uses a custom command to store plan files in a Google Cloud Storage bucket:

storage:
  plans:
    method: cmd
    store: ["gsutil", "cp", "$plan_path", "gs://my-terraform-plans/$dir/$workspace/$date-$time-$token"]
    fetch: ["gsutil", "cp", "gs://my-terraform-plans/$dir/$workspace/$date-$time-$token", "-"]
    delete: ["gsutil", "rm", "gs://my-terraform-plans/$dir/$workspace/$date-$time-$token"]

In this example, we use the gsutil command-line tool to interact with Google Cloud Storage. The store command pipes the plan file contents to gsutil cp, which uploads the file to the specified bucket and path. The fetch command downloads the plan file from the bucket and outputs its contents to stdout. The delete command removes the plan file from the bucket after the apply is complete.

Best practices

Use a consistent naming convention for your stored plan files to make it easy to identify and manage them.
Consider implementing a retention policy for your stored plan files to avoid accumulating unnecessary files over time.
Use Terrateam’s built-in variables to create dynamic and unique paths for your stored plan files, reducing the risk of conflicts and making it easier to identify specific plan files.