• HashiCorp Developer

  • HashiCorp Cloud Platform
  • Terraform
  • Packer
  • Consul
  • Vault
  • Boundary
  • Nomad
  • Waypoint
  • Vagrant
Terraform
  • Install
  • Tutorials
    • About the Docs
    • Configuration Language
    • Terraform CLI
    • Terraform Cloud
    • Terraform Enterprise
    • CDK for Terraform
    • Provider Use
    • Plugin Development
    • Registry Publishing
    • Integration Program
  • Registry(opens in new tab)
  • Try Cloud(opens in new tab)
  • Sign up
Terraform Cloud

Cloud Docs Agents

Skip to main content
  • Cloud Docs Agents
  • Requirements
  • Install and Run Agents
  • Inject Custom Run Actions (Hooks)
  • Manage Agent Pools
  • Logging
  • Telemetry
  • Changelog

  • Resources

  • Tutorial Library
  • Certifications
  • Community Forum
    (opens in new tab)
  • Support
    (opens in new tab)
  • GitHub
    (opens in new tab)
  • Terraform Registry
    (opens in new tab)
  1. Developer
  2. Terraform
  3. Terraform Cloud
  4. Cloud Docs Agents
  5. Inject Custom Run Actions (Hooks)
  • Terraform Cloud Agents
  • v1.5.x
  • v1.4.x
  • v1.3.x
  • v1.2.x

ยปHooks

Terraform Cloud 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.

Supported Hooks

Terraform Cloud 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 Terraform Cloud/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 60 second timeout. If a hook times out the Terraform run will fail immediately.
  • Environment variables do not persist across hooks. For example, if a pre-plan hook exports environment variables, they will not be available during terraform plan or during the post-plan hook. Similarly, if terraform plan exports environment variables, they will not be available during the post-plan hook.

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:

  1. Create the hooks directory within the agent's data directory.

    mkdir -p ~/.tfc-agent/hooks
    
  2. 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
    
  3. Make the hooks executable.

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

    tfc-agent
    
  5. 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 Terraform Cloud/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:

  1. 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
    
  2. Create a hooks directory.

    mkdir hooks
    
  3. 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
    
  4. Make the hooks executable.

    chmod +x hooks/terraform-pre-plan
    
  5. 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
    
  6. Build a new hashicorp/tfc-agent Docker image using the Dockerfile.

    docker build -t hashicorp/tfc-agent:your-tag .
    
  7. 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
    
  8. 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 Terraform Cloud/Enterprise user interface.

    Terraform v1.1.0
    Executing pre-plan hook...
    Example hook output.
    Initializing plugins and modules...
    
Edit this page on GitHub

On this page

  1. Hooks
  2. Supported Hooks
  3. Hook Behavior
  4. Configuration
Give Feedback(opens in new tab)
  • Certifications
  • System Status
  • Terms of Use
  • Security
  • Privacy
  • Trademark Policy
  • Trade Controls
  • Give Feedback(opens in new tab)