Agent Hooks

HCP Terraform Agents support running custom programs, or hooks, during strategic points of a Terraform run. These hooks allow you to extend the functionality of Terraform runs. For example, you may create a hook to dynamically download software required by the Terraform run or send an HTTP request to a system to kick off an external workflow.

Note

Agent hooks do not support Stack workflows in HCP Terraform.

Supported Hooks

HCP Terraform Agents support the following hooks:

pre-plan - Runs before terraform init during a plan operation.
post-plan - Runs after terraform plan during a plan operation regardless of whether or not terraform plan completed successfully.
pre-apply - Runs before terraform init during an apply operation.
post-apply - Runs after terraform apply during an apply operation regardless of whether or not terraform apply completed successfully.

Hook Behavior

Please note the following behavior when using hooks:

If a hook exits with a non-zero exit code, the Terraform run will fail immediately.
The standard output and standard error from the hook will be printed alongside the Terraform run output in the HCP Terraform or Terraform Enterprise user interface.
The hook name must match one of the supported hooks. You cannot customize or change these names. Because of this, there can only be one hook of each type configured for each agent. For example, you could create a pre-plan and pre-apply hook, but you cannot create two pre-plan hooks.
Each hook must have the execute permission set.
Each hook has a default timeout of 60 seconds and a max timeout of 10 minutes. You can configure hook timeouts using global timeouts or hook-specific timeouts. You can set the value of any hook timeout in seconds. If a hook times out, the Terraform run fails immediately.
- To set global timeouts, use the TFC_AGENT_HOOK_TIMEOUT environment variable.
- To set hook-specific timeouts, use an environment variable with the hook’s name TFC_AGENT_HOOK_[HOOK NAME]_TIMEOUT. For example, you can set the timeout for the pre-plan hook to 2 minutes by setting TFC_AGENT_HOOK_PRE_PLAN_TIMEOUT=120. A hook-specific timeout takes precedence over the global hook timeout.
Terraform environment variables do not persist across hooks. For example, if a pre-plan hook exports environment variables, they will not be available during the post-plan hook. Similarly, if terraform plan exports environment variables, they will not be available during the post-plan hook.

Setting Terraform Environment Variables

Hooks may be used to set environment variables for subsequent terraform commands to use. To set an environment variable, write lines in KEY=value format to the file pointed to by the $TFC_AGENT_ENV environment variable. Newlines are used to separate multiple environment variables. For example, to set the FOO and BAR environment variables for the terraform plan operation to consume, write the following in a pre-plan hook script:

#!/bin/sh
echo FOO=hello >> $TFC_AGENT_ENV
echo BAR=world >> $TFC_AGENT_ENV

Environment variables set by a hook script in this way are only applicable to the current operation, and are not persisted for later operations. For example, if FOO=bar is set in the pre-plan hook, then FOO=bar will be set during the terraform plan command, but will not be set during terraform apply. To use the variable during the apply phase, write the variable to the $TFC_AGENT_ENV file again in the pre-apply hook script.

Configuration

Hooks are stored within the hooks subdirectory of the agent's data directory. By default, that's ~/.tfc-agent/hooks.

To configure a hook, create a file named terraform-${HOOK} where ${HOOK} is one of the hooks listed above. Then store that file within the hooks subdirectory and make it executable. The agent will trigger configured hooks at the appropriate points during Terraform runs.

For example, a pre-plan hook is an executable file named ~/.tfc-agent/hooks/terraform-pre-plan. When this hook is configured, an agent will run this hook before terraform init during a plan operation.

Running an Agent as a Binary

To configure hooks when running the tfc-agent binary directly on a Linux instance:

Create the hooks directory within the agent's data directory.
```
mkdir -p ~/.tfc-agent/hooks
```
Create one or more hooks inside the hooks directory. The following example creates a pre-plan hook that prints a message when it runs.
```
cat <<EOF > ~/.tfc-agent/hooks/terraform-pre-plan
#!/bin/bash
echo "Example hook output."
EOF
```

Make the hooks executable.

chmod +x ~/.tfc-agent/hooks/terraform-pre-plan

Start the agent.
```
tfc-agent
```
The agent will now trigger configured hooks at the appropriate points during Terraform runs. The standard output and standard error from the hook will be printed alongside the Terraform run in the HCP Terraform or Terraform Enterprise user interface.
```
Terraform v1.1.0
Executing pre-plan hook...
Example hook output.
Initializing plugins and modules...
```

Running an Agent with Docker

When running tfc-agent using Docker, you must build a new Docker image containing the hooks. To configure hooks:

Create a new directory and navigate into it. This limits the Docker build context to this new directory.
```
mkdir hooks-docker-example
cd hooks-docker-example
```
Create a hooks directory.
```
mkdir hooks
```
Create one or more hooks inside the hooks directory. The following example creates a pre-plan hook that prints a message when it runs.
```
cat <<EOF > hooks/terraform-pre-plan
#!/bin/bash
echo "Example hook output."
EOF
```
Make the hooks executable.
```
chmod +x hooks/terraform-pre-plan
```

Create a Dockerfile with the following content.

FROM hashicorp/tfc-agent:latest
RUN mkdir /home/tfc-agent/.tfc-agent
ADD --chown=tfc-agent:tfc-agent hooks /home/tfc-agent/.tfc-agent/hooks

Build a new hashicorp/tfc-agent Docker image using the Dockerfile.
```
docker build -t hashicorp/tfc-agent:your-tag .
```

Start the agent using the Docker image.

docker run -e TFC_AGENT_TOKEN=your-token -e TFC_AGENT_NAME=your-agent-name \
  hashicorp/tfc-agent:your-tag

The agent will now trigger configured hooks at the appropriate points during Terraform runs. The standard output and standard error from the hook will be printed alongside the Terraform run in the HCP Terraform or Terraform Enterprise user interface.
```
Terraform v1.1.0
Executing pre-plan hook...
Example hook output.
Initializing plugins and modules...
```