Build and deploy a custom worker image

This topic describes how to build and deploy a custom worker image so that you can add custom tools or logic to your Terraform run environments.

Introduction

Terraform Enterprise performs Terraform runs in ephemeral containers using a built-in tfc-agent container image by default. To add custom tools or logic to your Terraform run environment, you must build a custom image and configure Terraform Enterprise to use it.

Terraform Enterprise also uses the custom image for agent jobs that perform VCS ingress. On Kubernetes, Terraform Enterprise adds the CA bundle from TFE_TLS_CA_BUNDLE_FILE to agent pods only when you use the default image. If your VCS server uses a certificate issued by a private CA, include that CA certificate in your custom image.

Requirements

The base image must be hashicorp/tfc-agent:1.6.0 or later.

Dockerfile

Build your custom image using the below Dockerfile.

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

# Switch back to the tfc-agent user as needed by Terraform agents.
USER tfc-agent

Agent

Update the environment variable TFE_RUN_PIPELINE_IMAGE in your yaml file:

TFE_RUN_PIPELINE_IMAGE: registry.example.com/example/tfc-agent:custom-tag