Terraform
Install and Run Agents
The agent software runs on your own infrastructure. The token you provide when starting the agent assigns it to a Terraform Cloud agent pool.
Operational Considerations
Agents do not guarantee a clean working environment per Terraform execution. Each execution occurs in its own temporary directory with a clean environment, but references to absolute file paths or other machine state may cause interference between Terraform executions. We strongly recommend that you write your Terraform code to be stateless and idempotent. You may also want to consider using single-execution mode to ensure your agent only runs a single workload.
Run Multiple Agents
You may choose to run multiple agents within your network, up to the organization's purchased agent limit. If there are multiple agents available within an organization, Terraform Cloud selects the first available agent within the target pool.
Each agent process runs a single Terraform run at a time. Multiple agent processes can be concurrently run on a single instance, license limit permitting.
Resilience
The agent distributes as a standalone binary that runs on any supported system. By default, the agent runs in the foreground as a long-running process that continuously polls for workloads from Terraform Cloud. An agent process may terminate unexpectedly due to stopping the process forcefully, power cycling the host machine, and other methods. We strongly recommend pairing the agent with a process supervisor to ensure that it automatically restarts in case of an error.
Download and Install the Agent
- Download the latest agent release, the associated checksum file (.SHA256sums), and the checksum signature (.sig).
- Verify the integrity of the downloaded archive, as well as the signature of the
SHA256SUMS
file using the instructions available on HashiCorp's security page. - Extract the release archive. The
unzip
utility is available on most Linux distributions, and you can invoke it by runningunzip <archive file>
. Theunzip
command extracts two individual binaries (tfc-agent
andtfc-agent-core
). These binaries must reside in the same directory for the agent to function properly.
Updates
By default, the agent automatically updates itself to the latest minor version. Administrators must update the host operating system and all other installed software.
To customize this update behavior, pass the flag -auto-update
or set the environment variable TFC_AGENT_AUTO_UPDATE
to one of the following settings.
Update Setting | Behavior |
---|---|
minor | Matches the default behavior, automatically updates the agent to the latest minor version. |
patch | The agent only updates to the newest patch version, new minor versions require a manual update. |
disabled | Disables automatic updates, all updates are manual. |
Start the Agent
To start the agent and connect it to a Terraform Cloud agent pool:
- Retrieve the token from the Terraform Cloud agent pool you want to use.
- Set the
TFC_AGENT_TOKEN
environment variable. - (Optional) Set the
TFC_AGENT_NAME
environment variable. This name is for your reference only. The agent ID appears in logs and API requests.
export TFC_AGENT_TOKEN=your-token
export TFC_AGENT_NAME=your-agent-name
./tfc-agent
Once complete, your agent and its status appear on the Agents page in the Terraform Cloud UI. Workspaces can now use this agent pool for runs. Refer to Configure Workspaces to Use the Agent for details.
Optional Configuration: Run an Agent Using Docker
Alternatively, you can use our official agent Docker container to run the agent.
docker pull hashicorp/tfc-agent:latest
docker run -e TFC_AGENT_TOKEN=your-token -e TFC_AGENT_NAME=your-agent-name hashicorp/tfc-agent
This Docker image executes the tfc-agent
process as the non-root tfc-agent
user. For some workflows, such as workflows requiring the ability to install software using apt-get
during local-exec
scripts, you may need to build a customized version of the agent Docker image for your internal use.
FROM hashicorp/tfc-agent:latest
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
USER tfc-agent
An image customized in this way permits installation of additional software via sudo apt-get.
Optional Configuration: Single-Execution Mode
You can also configure the agent to run in single-execution mode, which ensures that the agent only runs a single workload, then terminates. You can use this configuration in combination with Docker and a process supervisor to ensure a clean working environment for every Terraform run.
To use single-execution mode, start the agent with the -single
command line argument.
Stop the Agent
Important: We strongly recommend that you only terminate the agent using one of these methods. Abruptly terminating an agent by forcefully stopping the process or power cycling the host does not let the agent deregister and results in an Unknown agent status. Abrupt termination may cause further capacity issues. Refer to capacity issues for details.
The agent maintains a registration and a liveness indicator within Terraform Cloud during the entire course of its runtime. When an agent retires, it must deregister itself from Terraform Cloud. The agent deregisters automatically as part of its shutdown procedure in the following scenarios:
- You enter
Ctrl-C
in an interactive terminal. - The agent process ID receives one of
SIGINT
,SIGTERM
, orSIGQUIT
. It is important to send only one signal. The agent interprets a second signal as forceful termination signal exits immediately.
After initiating a graceful shutdown by either of these methods, the terminal user or parent program should wait for the agent to exit. The amount of time this exit takes depends on the agent's current workload. The agent waits for any current operations to complete before deregistering and exiting.