How to add AWS, GCP, and Azure CLI to your custom tfc-agent image – HashiCorp Help Center

Introduction

This article outlines how to install the AWS, Google Cloud, and Azure command-line interface (CLI) tools into a custom agent image for use with HCP Terraform or Terraform Enterprise.

Some Terraform workflows depend on having a cloud provider's CLI available in the agent's execution environment. For example, you might use the aws eks get-token command to authenticate with Amazon Elastic Kubernetes Service (EKS).

Prerequisites

To follow this guide, you need:

Docker installed on your local machine.
A text editor to create a Dockerfile.
Access to a container registry, such as Docker Hub, GHCR, Quay, or Artifactory.

Background

HCP Terraform and Terraform Enterprise agents are based on the hashicorp/tfc-agent image available on Docker Hub. You can create a custom agent by using a Dockerfile to add software to this base image.

A Dockerfile is a text document that contains commands to assemble a container image. For a full reference, refer to the official Dockerfile documentation.

Key Dockerfile Instructions

FROM: Defines the base image to build upon. You can specify a version tag, such as hashicorp/tfc-agent:1.15.0, or use latest. You can find available tags on the tfc-agent tags page.
USER: Sets the user account for subsequent instructions. The tfc-agent user has limited permissions, so you must switch to USER root to install software and then switch back to USER tfc-agent for security.
RUN: Executes commands in a shell inside the container during the build process.

Building, Tagging, and Pushing

After creating your Dockerfile, you will perform these steps:

Build the image: Use the docker build command to create the image from your Dockerfile.
Tag the image: Use the -t flag during the build to tag the image with a name that includes your container registry, username, and image name (e.g., quay.io/my-org/custom-tfc-agent:1.0.0).
Push the image: Use the docker push command to upload your tagged image to your container registry. You may need to run docker login first to authenticate.

Procedure

Create a file named Dockerfile and add the contents from one of the options below. Each option provides a complete Dockerfile for adding one or more CLIs.

Option 1: Add AWS CLI

This Dockerfile follows the installation instructions from the AWS CLI documentation.

FROM hashicorp/tfc-agent:latest

USER root

# Install AWS CLI
RUN curl "https://awscli.amazonaws.com/awscli-exe-linux-x86_64.zip" -o "awscliv2.zip" \
    && unzip awscliv2.zip \
    && ./aws/install

# Clean up package cache
RUN apt-get clean && \
    rm -rf /var/lib/apt/lists/*

USER tfc-agent

# Verify installation
RUN aws --version

Option 2: Add Azure CLI

This Dockerfile follows the installation instructions from the Azure CLI documentation.

FROM hashicorp/tfc-agent:latest

USER root

# Install Azure CLI
RUN curl -L https://aka.ms/InstallAzureCLIDeb | bash

# Clean up package cache
RUN apt-get clean && \
    rm -rf /var/lib/apt/lists/*

USER tfc-agent

# Verify installation
RUN az --version

Option 3: Add Google Cloud CLI

This Dockerfile follows the installation instructions from the Google Cloud SDK documentation. This CLI requires updating the PATH environment variable.

FROM hashicorp/tfc-agent:latest

USER root

# Install Google Cloud CLI
RUN mkdir -p /opt/gcloud \
    && curl -O https://dl.google.com/dl/cloudsdk/channels/rapid/downloads/google-cloud-cli-450.0.0-linux-x86_64.tar.gz \
    && tar -C /opt/gcloud -xf google-cloud-cli-450.0.0-linux-x86_64.tar.gz \
    && /opt/gcloud/google-cloud-sdk/install.sh --quiet

# Clean up package cache
RUN apt-get clean && \
    rm -rf /var/lib/apt/lists/*

USER tfc-agent

# Add the gcloud SDK to the PATH
ENV PATH="${PATH}:/opt/gcloud/google-cloud-sdk/bin"

# Verify installation
RUN gcloud --version

Option 4: Add All Three CLIs

This Dockerfile combines the installation steps for the AWS, Azure, and Google Cloud CLIs.

FROM hashicorp/tfc-agent:latest

USER root

# Install AWS CLI
RUN curl "https://awscli.amazonaws.com/awscli-exe-linux-x86_64.zip" -o "awscliv2.zip" \
    && unzip awscliv2.zip \
    && ./aws/install

# Install Azure CLI
RUN curl -L https://aka.ms/InstallAzureCLIDeb | bash

# Install Google Cloud CLI
RUN mkdir -p /opt/gcloud \
    && curl -O https://dl.google.com/dl/cloudsdk/channels/rapid/downloads/google-cloud-cli-450.0.0-linux-x86_64.tar.gz \
    && tar -C /opt/gcloud -xf google-cloud-cli-450.0.0-linux-x86_64.tar.gz \
    && /opt/gcloud/google-cloud-sdk/install.sh --quiet

# Clean up package cache
RUN apt-get clean && \
    rm -rf /var/lib/apt/lists/*

USER tfc-agent

# Add the gcloud SDK to the PATH
ENV PATH="${PATH}:/opt/gcloud/google-cloud-sdk/bin"

# Verify installations
RUN aws --version
RUN az --version
RUN gcloud --version

Build and Push Your Image

After saving your chosen Dockerfile, run the following commands in your terminal in the same directory.

Build and tag the image. Replace $REGISTRY_IMAGE with the full name for your image in your container registry (e.g., quay.io/my-org/custom-agent:1.0).
```
$ docker build -t $REGISTRY_IMAGE .
```
Push the image to your registry.
```
$ docker push $REGISTRY_IMAGE
```

Your custom agent image is now available in your registry and can be configured for use in HCP Terraform or Terraform Enterprise.