Hooks

Hooks in Terrateam allow you to run commands or set environment variables before (pre-hooks) and after (post-hooks) workflows. Pre and post hooks are only executed a single time during a Terrateam operation. Commands are executed from the repository checkout directory $TERRATEAM_ROOT.

Configuration

Hooks are configured in the .terrateam/config.yml file under the hooks key. Here’s the default configuration:

hooks:
  all:
    pre: []
    post: []
  plan:
    pre: []
    post: []
  apply:
    pre: []
    post: []

All hooks

All hooks are executed for both plan and apply operations.

Key	Type	Description
pre	Pre	Commands to run before any hooks.
post	Post	Commands to run after any hooks.

Plan hooks

Plan hooks are executed only for plan operations.

Key	Type	Description
pre	Pre	Commands to run before a plan workflow.
post	Post	Commands to run after a plan workflow.

Apply hooks

Apply hooks are executed only for apply operations.

Key	Type	Description
pre	Pre	Commands to run before an apply workflow.
post	Post	Commands to run after an apply workflow.

Hook types

Env

The env hook type allows you to set environment variables that will be available during the Terrateam operation.

Key	Type	Description
name	String	Name of the environment variable.
cmd	List	Command to use to set the environment variable.
trim_trailing_newlines	Boolean	Trim trailing newlines. Default is `true`.

Run

The run hook type executes a command from the directory that Terrateam is operating against.

Key	Type	Description
cmd	List	Command to run.
run_on	String	Run the command on step `success`, `failure`, or `always`. Default is `success`.
capture_output	Boolean	When set to `true`, command output is included in the GitHub pull request comment on a failure. Sensitive data is not masked. Be aware, this data is sent back to the Terrateam backend for processing. Default is `false`.

OIDC

An OIDC connection to a cloud provider can be initiated using the oidc hook type, which supports AWS and GCP providers.

Key	Type	Provider	Description
oidc	List		Initiate an OIDC connection to a cloud provider.
provider	String		Name of provider: `aws` or `gcp`.
role_arn	String	aws	Specifies the ARN of an IAM role that you want to use. Value can be specified using a GitHub Secret / environment variable with `${ENV_VAR}`.
assume_role_arn	String	aws	Specifies the ARN of an IAM role that you want to assume into. Default is the value of `role_arn`. Value can be specified using a GitHub Secret / environment variable with `${ENV_VAR}`.
assume_role_enabled	Boolean	aws	Retrieve a set of temporary security credentials from AWS and set the `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, and `AWS_SESSION_TOKEN` environment variables. Default is `true`.
audience	String	aws	Specifies the AWS audience name to use. Default is `sts.amazonaws.com`. Value can be specified using a GitHub Secret / environment variable with `${ENV_VAR}`.
region	String	aws	Specifies the AWS region to use and sets the `AWS_REGION` environment variable. Default is `us-east-1`.
session_name	String	aws	Specifies the AWS session name. Default is `terrateam`.
duration	Integer	aws	Specifies the AWS session duration in seconds. Default is `3600`.
service_account	String	gcp	Email address or unique identifier of the Google Cloud service account for which to generate credentials. Value can be specified using a GitHub Secret / environment variable with `${ENV_VAR}`.
workload_identity_provider	String	gcp	The full identifier of the Workload Identity Provider, including the project number, pool name, and provider name. Value can be specified using a GitHub Secret / environment variable with `${ENV_VAR}`.
access_token_lifetime	Integer	gcp	Desired lifetime duration of the access token, in seconds. Default is `3600`.
audience	String	gcp	Specifies the GCP audience name to use. Default is `https://iam.googleapis.com/` + `workload_identity_provider`.
access_token_subject	String	gcp	Email address of a user to impersonate for Domain-Wide Delegation. Value can be specified using a GitHub Secret / environment variable with `${ENV_VAR}`.

Examples

Setting environment variables

You can use the env hook type to set environment variables that will be available during the Terrateam operation.

hooks:
  plan:
    pre:
      - type: env
        name: TF_VAR_example
        cmd: ['echo', 'example_value']

This pre-hook for the plan operation sets the TF_VAR_example environment variable to example_value.

Running scripts

The run hook type allows you to execute scripts or commands before or after Terrateam operations.

hooks:
  apply:
    post:
      - type: run
        cmd: ['./cleanup_script.sh']
        run_on: always

This post-hook for the apply operation runs the cleanup_script.sh script, regardless of the operation’s success or failure (run_on: always).

AWS OIDC authentication

hooks:
  all:
    pre:
      - type: oidc
        provider: aws
        role_arn: ${AWS_ROLE_ARN}

This pre-hook for all operations initiates an OIDC connection to AWS using the role ARN specified in the AWS_ROLE_ARN environment variable.

GCP OIDC authentication

hooks:
  all:
    pre:
      - type: oidc
        provider: gcp
        service_account: ${GCP_SERVICE_ACCOUNT}
        workload_identity_provider: ${GCP_WORKLOAD_IDENTITY_PROVIDER}

This pre-hook for all operations initiates an OIDC connection to GCP using the service account and workload identity provider specified in the GCP_SERVICE_ACCOUNT and GCP_WORKLOAD_IDENTITY_PROVIDER environment variables.

Considerations

When using hooks in your Terrateam configuration, keep the following considerations in mind:

Hooks are executed in the order they are defined within each section (pre or post) and each operation type (all, plan, or apply).
Pre-hooks are executed before the corresponding workflow steps, while post-hooks are executed after the workflow steps.
Hooks can significantly impact the execution time of your Terrateam operations, especially if they involve long-running commands or scripts. Be mindful of the performance implications when configuring hooks.
Hooks have access to the repository checkout directory ($TERRATEAM_ROOT) and can modify files within that directory. Ensure that your hooks are carefully tested and do not unintentionally modify or delete important files.
When using the run hook type, make sure that the specified command or script is available and executable within the Terrateam environment. Consider using absolute paths or ensuring that the necessary dependencies are installed.
Be cautious when using the capture_output option with the run hook type, as it may expose sensitive information in the GitHub pull request comment if the command fails. Ensure that you properly sanitize or mask any sensitive data before enabling this option.
When setting environment variables using the env hook type, be aware that the values will be visible in the Terrateam logs and may be accessible to other hooks or workflow steps. Avoid storing sensitive information directly in the hook configuration.
If you need to use sensitive information in your hooks, consider using GitHub Secrets or other secure methods to store and retrieve the values.