How to create a custom tfc-agent image with hooks

Expected Outcome

Create a custom tfc-agent image to be used with Terraform Cloud or Terraform Enterprise

Prerequisites

•  Terraform Cloud
•  Terraform Enterprise

Use Case

• If an organization's Terraform configurations are expected to use additional tools not available in the default image and/or migrating from an alternative worker image.

Procedure

• Create the directory structure where the Dockerfile and agent hook scripts will be created and copy the certificates to the custom_tfc_agent folder if needed.
  

  mkdir -p ~/custom_tfc_agent/hooks
  cd ~/custom_tfc_agent

• Use vim or nano to create the Dockerfile and paste the template below. Modify it if necessary and save the changes.
  

  FROM hashicorp/tfc-agent:latest
  
  # Switch the to root user in order to perform privileged actions such as
  # installing software.
  USER root
  
  # Install sudo. The container runs as a non-root user, but people may rely on
  # the ability to apt-get install things.
  RUN apt-get -y install sudo
  
  # Permit tfc-agent to use sudo apt-get commands.
  RUN echo 'tfc-agent ALL=NOPASSWD: /usr/bin/apt-get , /usr/bin/apt' >> /etc/sudoers.d/50-tfc-agent
  
  # Install required packages, awscli, Ansible, JQ, and python3-pip
  RUN apt-get update && DEBIAN_FRONTEND=noninteractive apt-get install -y --no-install-recommends unzip curl ca-certificates ansible jq python3-pip && wget -qO awscliv2.zip https://awscli.amazonaws.com/awscli-exe-linux-x86_64.zip && unzip awscliv2.zip && ./aws/install && rm -rf ./aws && rm -rf /var/lib/apt/lists/*
  
  # Adding hooks before plan and applies. https://developer.hashicorp.com/terraform/cloud-docs/agents/hooks#supported-hooks
  ADD --chown=tfc-agent:tfc-agent hooks /home/tfc-agent/.tfc-agent/hooks
  
  # Include all necessary CA certificates. Modify or comment as needed.
  ADD example-root-ca.crt /usr/local/share/ca-certificates/
  ADD example-intermediate-ca.crt /usr/local/share/ca-certificates/
  RUN update-ca-certificates
  
  # Switch back to the tfc-agent user as needed by Terraform agents.
  USER tfc-agent

• Proceed to create or copy the hooks scripts to ~/custom_tfc_agent/hooks and enable the executable bit. Example to modify the .terraformrc with a provider_installation block: 
  

  # Edit the terraform-pre-plan hook with your favorite editor
  vim ~/custom_tfc_agent/hooks/terraform-pre-plan
  # Example script content below

  #!/bin/bash
  cat <<EOF >> $HOME/.terraformrc
  
  provider_installation {
    network_mirror {
      url = "https://mirror.example.com/repository/providers/"
      include = ["example.com/*/*"]
    }
    direct {
      exclude = ["example.com/*/*"]
    }
  }
  EOF

  # Save and exit, make a copy of the file as terraform-pre-apply and add
  # the executable bit
  cp ~/custom_tfc_agent/hooks/terraform-pre-plan ~/custom_tfc_agent/hooks/terraform-pre-apply
  chmod +x ~/custom_tfc_agent/hooks/*

• Verify the directory structure before building the image.  

  .
  ├── Dockerfile
  ├── example-intermediate-ca.crt
  ├── example-root-ca.crt
  └── hooks
      ├── terraform-pre-apply
      └── terraform-pre-plan

• Build the docker image with repo/name:tag format, example: 

  docker build -t custom/tfc-agent:2.0 .
  [+] Building 4.0s (14/14) FINISHED docker:default
  => [internal] load build definition from Dockerfile 0.1s
  => => transferring dockerfile: 1.36kB 0.0s
  => [internal] load .dockerignore 0.1s
  => => transferring context: 2B 0.0s
  => [internal] load metadata for docker.io/hashicorp/tfc-agent:latest 0.5s
  => [auth] hashicorp/tfc-agent:pull token for registry-1.docker.io 0.0s
  => [1/8] FROM docker.io/hashicorp/tfc-agent:latest@sha256:7c85b457e5f28845ef43b477e63044000c6c76a4b93fba6b682c7e8944263aa3 0.0s
  => [internal] load build context 0.1s
  => => transferring context: 1.06kB 0.0s
  => CACHED [2/8] RUN apt-get -y install sudo 0.0s
  => CACHED [3/8] RUN echo 'tfc-agent ALL=NOPASSWD: /usr/bin/apt-get , /usr/bin/apt' >> /etc/sudoers.d/50-tfc-agent 0.0s
  => CACHED [4/8] RUN apt-get update && DEBIAN_FRONTEND=noninteractive apt-get install -y --no-install-recommends unzip curl ca-certificates sudo ansible jq python3-pip && wget -qO a 0.0s
  => CACHED [5/8] ADD --chown=tfc-agent:tfc-agent hooks /home/tfc-agent/.tfc-agent/hooks 0.0s
  => [6/8] ADD example-root-ca.crt /usr/local/share/ca-certificates/ 0.1s
  => [7/8] ADD example-intermediate-ca.crt /usr/local/share/ca-certificates/ 0.1s
  => [8/8] RUN update-ca-certificates 2.8s
  => exporting to image 0.2s
  => => exporting layers 0.1s
  => => writing image sha256:ec1cee98a27b840fa01bd2947cf15b54e609d6fd821600f3d8389a0e8f20444e 0.0s
  => => naming to docker.io/custom/tfc-agent:2.0 0.0s

• List the built image.  

  docker image ls custom/tfc-agent:2.0
  REPOSITORY TAG IMAGE ID CREATED SIZE
  custom/tfc-agent 2.0 ec1cee98a27b 15 hours ago 756MB

Additional Information

• tfc-agent examples

• How to Add Custom Certificates to Terraform Agents for use with Terraform Enterprise

• tfc-agent hooks official documentation