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.
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.
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.
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 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
SHA256SUMSfile using the instructions available on HashiCorp's security page.
- Extract the release archive. The
unziputility is available on most Linux distributions, and you can invoke it by running
unzip <archive file>. The
unzipcommand extracts two individual binaries (
tfc-agent-core). These binaries must reside in the same directory for the agent to function properly.
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.
|Matches the default behavior, automatically updates the agent to the latest minor version.|
|The agent only updates to the newest patch version, new minor versions require a manual update.|
|Disables automatic updates, all updates are manual.|
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
- (Optional) Set the
TFC_AGENT_NAMEenvironment 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.
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
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.
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.
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-Cin an interactive terminal.
- The agent process ID receives one of
SIGQUIT. 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.
-name <name>: An optional user-specified name for the agent. This name may be used in the Terraform Cloud user interface to help easily identify the agent.
The agent's ephemeral ID, assigned during boot.
-log-level <level>: The log verbosity expressed as a level string. Level options include "trace", "debug", "info", "warn", and "error". Log levels have a progressive level of data sensitivy. The "info", "warn", and "error" levels are considered generally safe for log collection and don't include sensitive information. The "debug" log level may include internal system details, such as specific commands and arguments including paths to user data on the local filesystem. The "trace" log level is the most sensitive and may include personally identifiable information, secrets, pre-authorized internal URLs, and other sensitive material.
-log-json: Enable JSON logging mode.
-data-dir <path>: The path to a directory to store all agent-related data, including Terraform configurations, cached Terraform release archives, etc. It is important to ensure that the given directory is backed by plentiful storage.
-cache-dir <path>: The path to a directory to store all agent-related cache data, including cached Terraform release archives, policy binaries, etc. It is important to ensure that the given directory is backed by plentiful storage.
-single: Enable single mode. This causes the agent to handle at most one job and immediately exit thereafter. Useful for running agents as ephemeral containers, VMs, or other isolated contexts with a higher-level scheduler or process supervisor.
-auto-update: Controls automatic core updates behavior. Acceptable values include "disabled", "patch", and "minor".
-address <addr>: The HTTP or HTTPS address of the Terraform Cloud API.
-token <token>: The agent token to use when making requests to the Terraform Cloud API. This token must be obtained from the API or UI. It is recommended to use the environment variable whenever possible for configuring this setting due to the sensitive nature of API tokens.
Required, no default. Environment variable:
-otlp-address <addr>: Optional host:port address of an OpenTelemetry collector to send telemetry data to, including metrics and tracing. Currently the agent connects to this address using the gRPC protocol.
-otlp-cert-file <path>: Optional path to a client TLS certificate file to load. When present, the given certificate is used to encrypt the client connection to the OpenTelemetry collector. When omitted, client connections are not secure.
-accept <job_types>: Optional string of comma-separated job types that this agent may run. Acceptable job types are "plan", "apply", "policy", and "assessment". Do not put whitespace inbetween entries.