How to create a custom tfc-agent image with hooks

Avatar
Irving
  • Updated

Introduction

This guide provides instructions on how to build a custom tfc-agent image. A custom image allows you to include additional tools or custom certificates required by your organization's Terraform configurations.

Expected Outcome

You will create a custom tfc-agent Docker image that can be used with HCP Terraform or Terraform Enterprise.

Prerequisites

  • HCP Terraform or Terraform Enterprise
  • Docker installed on your local machine

Use Case

This procedure is for organizations whose Terraform configurations require tools not available in the default agent image or for those migrating from an alternative worker image.

Procedure

Follow these steps to build your custom agent image.

1. Create Directory Structure

First, create the directory structure for the Dockerfile and agent hook scripts. If you need to include custom certificates, copy them into the custom_tfc_agent folder.

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

2. Create the Dockerfile

Use a text editor to create a file named Dockerfile and add the following content. Modify the package installation and certificate paths as necessary for your environment.

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

3. Create Agent Hook Scripts

Create your hook scripts in the ~/custom_tfc_agent/hooks directory. The following example creates a terraform-pre-plan hook that modifies the .terraformrc file to include a provider installation block.

Create the terraform-pre-plan script.

$ cat <<EOF > ~/custom_tfc_agent/hooks/terraform-pre-plan
#!/bin/bash
cat <<EOT >> \$HOME/.terraformrc
provider_installation {
  network_mirror {
    url     = "https://mirror.example.com/repository/providers/"
    include = ["example.com/*/*"]
  }
  direct {
    exclude = ["example.com/*/*"]
  }
}
EOT
EOF

Copy the file to create a terraform-pre-apply hook and make both scripts executable.

$ cp ~/custom_tfc_agent/hooks/terraform-pre-plan ~/custom_tfc_agent/hooks/terraform-pre-apply
$ chmod +x ~/custom_tfc_agent/hooks/*

4. Verify Directory Structure

Before building the image, verify that your directory structure matches the following example.

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

5. Build the Docker Image

Build the Docker image using a repo/name:tag format.

$ docker build -t custom/tfc-agent:2.0 .

The output shows the build process.

[+] 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

6. Verify the Custom Image

List the Docker images to confirm your custom image was created.

$ docker image ls custom/tfc-agent:2.0

The output displays your new image.

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

Additional Information

Articles in this section

See more

Related articles