Skip to content

Commit

Permalink
Update HCP Terraform naming on installation page (#99)
Browse files Browse the repository at this point in the history
  • Loading branch information
danbarr authored May 6, 2024
1 parent 1161dd4 commit 7780919
Showing 1 changed file with 9 additions and 9 deletions.
18 changes: 9 additions & 9 deletions website/docs/cloud-docs/agents/agents.mdx
Original file line number Diff line number Diff line change
@@ -1,26 +1,26 @@
---
page_title: Terraform Cloud Agents - Install and Run Agents - Terraform Cloud and Terraform Enterprise
page_title: HCP Terraform Agents - Install and Run Agents - HCP Terraform and Terraform Enterprise
description: >-
Install, configure, and run agents on your own infrastructure.
---

# 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](/terraform/cloud-docs/agents/agent-pools).
The agent software runs on your own infrastructure. The token you provide when starting the agent assigns it to an HCP Terraform [agent pool](/terraform/cloud-docs/agents/agent-pools).

## 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](#optional-configuration-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.
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, HCP Terraform 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.
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 HCP Terraform. 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

Expand All @@ -42,9 +42,9 @@ To customize this update behavior, pass the flag `-auto-update` or set the envir

## Start the Agent

To start the agent and connect it to a Terraform Cloud agent pool:
To start the agent and connect it to an HCP Terraform agent pool:

1. Retrieve the [token](/terraform/cloud-docs/agents/agent-pools#create-an-agent-pool) from the Terraform Cloud agent pool you want to use.
1. Retrieve the [token](/terraform/cloud-docs/agents/agent-pools#create-an-agent-pool) from the HCP Terraform agent pool you want to use.
1. Set the `TFC_AGENT_TOKEN` environment variable.
1. (Optional) Set the `TFC_AGENT_NAME` environment variable. This name is for your reference only. The agent ID appears in logs and API requests.

Expand All @@ -53,7 +53,7 @@ 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](/terraform/cloud-docs/agents/agent-pools#configure-workspaces-to-use-the-agent) for details.
Once complete, your agent and its status appear on the **Agents** page in the HCP Terraform UI. Workspaces can now use this agent pool for runs. Refer to [Configure Workspaces to Use the Agent](/terraform/cloud-docs/agents/agent-pools#configure-workspaces-to-use-the-agent) for details.

### Optional Configuration: Run an Agent Using Docker

Expand Down Expand Up @@ -91,15 +91,15 @@ To use single-execution mode, start the agent with the `-single` command line ar

### Optional Configuration: Request Forwarding

You can configure the agent to accept forwarded requests from Terraform Cloud. Request forwarding enables Terraform Cloud to securely access private infrastructure resources, such as private VCS systems. See [Request Forwarding](/terraform/cloud-docs/agents/request-forwarding) for more details. By default, request forwarding is disabled. To enable it, start the agent with the `-request-forwarding` command line argument.
You can configure the agent to accept forwarded requests from HCP Terraform. Request forwarding enables HCP Terraform to securely access private infrastructure resources, such as private VCS systems. See [Request Forwarding](/terraform/cloud-docs/agents/request-forwarding) for more details. By default, request forwarding is disabled. To enable it, start the agent with the `-request-forwarding` command line argument.

Agents handle forwarded requests separately from other workloads and may process requests in parallel to plans, applies, policy checks, etc. You can modify this behavior by enabling or disabling certain workload types via the `-accept` parameter, and selectively setting the `-request-forwarding` flag on certain agent(s) only. For example, you may have a pool of 4 agents, where two are configured to handle only plans and applies, and the other two are configured to handle only request forwarding.

## 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](/terraform/cloud-docs/agents/agent-pools#agent-capacity-usage) 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:
The agent maintains a registration and a liveness indicator within HCP Terraform during the entire course of its runtime. When an agent retires, it must deregister itself from HCP Terraform. 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`, or `SIGQUIT`. It is important to send only one signal. The agent interprets a second signal as forceful termination signal exits immediately.
Expand Down

0 comments on commit 7780919

Please sign in to comment.