diff --git a/content/terraform-docs-agents/v1.22.x/docs/cloud-docs/agents/agent-pools.mdx b/content/terraform-docs-agents/v1.22.x/docs/cloud-docs/agents/agent-pools.mdx index 62e5e06f3..30d34b130 100644 --- a/content/terraform-docs-agents/v1.22.x/docs/cloud-docs/agents/agent-pools.mdx +++ b/content/terraform-docs-agents/v1.22.x/docs/cloud-docs/agents/agent-pools.mdx @@ -4,7 +4,7 @@ description: >- Agent pools are groups of one or more agents. Learn how to manage agent pools and assign them to specific workspaces. --- -# Manage Agent Pools +# Manage agent pools HCP Terraform organizes agents into agent pools. An agent pool represents a group of agents that lets HCP Terraform communicate with isolated, private, or on-premises infrastructure. When you configure a workspace to execute runs using agents, any available agent in that workspace's associated agent pool can complete the run. @@ -19,7 +19,7 @@ Refer to [Permissions](/terraform/cloud-docs/users-teams-organizations/permissio [permissions-citation]: #intentionally-unused---keep-for-maintainers -## Create an Agent Pool +## Create an agent pool To create an agent pool: @@ -36,7 +36,7 @@ To create an agent pool: To connect an agent to this pool, configure and [start an agent using the official Docker image](/terraform/cloud-docs/agents/agents#quick-start). Alternatively, configure and [start an agent using the binary](/terraform/cloud-docs/agents/agents#start-an-agent) then provide then agent with your agent pool's token. -## Scope an Agent Pool to Specific Workspaces +## Scope an agent pool to specific workspaces Scoping an agent pool lets you specify which workspaces can use it. The agent pool is only available from within the chosen workspaces, and it does not appear other workspace's lists of available agent pools. @@ -57,11 +57,11 @@ To scope an agent pool to specific workspaces within the organization: Only the specified workspaces can use the agent pool. -## Configure Workspaces to use the Agent +## Configure workspaces to use the agent Use the following steps to configure a workspace to use an agent pool. -### Step 1: Manage Existing Runs +### Step 1: Manage existing runs Changing a workspace's [execution mode](/terraform/cloud-docs/workspaces/settings#execution-mode) after Terraform completes a plan causes that run to error during apply. To minimize these errors, do the following in the workspace before you change the execution mode: @@ -69,7 +69,7 @@ Changing a workspace's [execution mode](/terraform/cloud-docs/workspaces/setting 1. Wait for the workspace to complete any runs that are no longer in the [pending stage](/terraform/cloud-docs/run/states#1-the-pending-stage). 1. [Lock the workspace](/terraform/cloud-docs/workspaces/settings#locking) to prevent new runs. -### Step 2: Select Agent Pool +### Step 2: Select agent pool To configure the workspace to execute runs using an agent: @@ -79,7 +79,7 @@ To configure the workspace to execute runs using an agent: The workspace begins using the agent for Terraform runs. Runs involving an agent include information about that agent in the run details. HCP Terraform may use different agents for the plan and apply operations, depending on agent availability within the pool. -## Exclude Workspaces from Accessing an Agent Pool +## Exclude workspaces from accessing an agent pool Excluding workspaces from an agent pool prevents the specified workspaces from using it. @@ -99,9 +99,9 @@ To exclude a workspace from an agent pool: Only the specified workspaces will be restricted from accessing the agent pool. -## Scope an Agent Pool to Specific Projects +## Scope an agent pool to specific projects -You can scope an agent pool to specific projects. Only the selected projects will be able to use the agent pool. +You can scope an agent pool to specific projects. Only the selected projects are able to use the agent pool. ~> **Important:** Scoping an agent pool does not remove it from projects that already use it. To remove access, you must first remove the agent pool from the project's settings. @@ -119,7 +119,7 @@ To scope an agent pool to specific projects within the organization: Only the specified projects can use the agent pool. -## Configure Projects to use the Agent +## Configure projects to use the agent To configure the project to execute runs using an agent: @@ -129,7 +129,7 @@ To configure the project to execute runs using an agent: The project begins using the agent for Terraform runs. Any workspace within the project will inherit the execution mode, which will be passed onto the run. Runs involving an agent include information about that agent in the run details. HCP Terraform may use different agents for the plan and apply operations, depending on agent availability within the pool. -## Revoke an Agent Token +## Revoke an agent token You may revoke an issued token from your agents at any time. @@ -143,7 +143,7 @@ Allow active runs in the associated agent pool to finish before revoking a token 1. Click **Yes, delete token** to confirm. -## Delete an Agent Pool +## Delete an agent pool ~> **Important:** You cannot delete an agent pool that is still associated with one or more workspaces. @@ -156,7 +156,7 @@ To delete an agent pool: 1. Click **Yes, delete agent pool** to confirm. -## View Agent Statuses +## View agent statuses To view agent statuses, go to your organization's settings and click **Agents**. The **Agents** page appears, containing a list of agents and their corresponding statuses. An agent can have one of the following statuses: @@ -166,7 +166,7 @@ To view agent statuses, go to your organization's settings and click **Agents**. - **Errored**: The agent encountered an unrecoverable error or has been in an Unknown state for long enough that HCP Terraform considers it errored. This status may indicate that something interrupted the agent process, the process crashed, a permanent network partition exists, or another similar problem. If the agent was in the process of running an operation (such as a plan or apply), the agent marks that operation as errored. If the current agent process recovers, it exits immediately. - **Exited**: The agent exited normally and successfully informed Terraform of it doing so. -## Agent Capacity Usage +## Agent capacity usage Refer to [HCP Terraform pricing](https://www.hashicorp.com/products/terraform/pricing) for more information about HCP Terraform Agents. @@ -178,3 +178,11 @@ Agents may have an **Unknown** status if they terminate without gracefully exiti You can deregister agents that are **Unknown**, **Errored**, or **Exited** through either the **Organization Settings > Agents** page or through the [Agent API](/terraform/cloud-docs/api-docs/agents#delete-an-agent). Deregistered agents no longer appear in the settings page or count against the organization's agent allowance. +## Change the agent pool architecture + +All agents in a pool must have the same architecture, which is determined by the first agent to register. If you need to change the architecture of the agent pool, such as switching from x86 to ARM64, you can complete the following steps: + +1. Spin down all existing agents in the pool so that no agents are registered. +1. Spin up and register an agent of the desired architecture. + +This agent pool will require subsequent registered agents to have the same architecture. diff --git a/content/terraform-docs-agents/v1.22.x/docs/cloud-docs/agents/agents.mdx b/content/terraform-docs-agents/v1.22.x/docs/cloud-docs/agents/agents.mdx index 1542ef29c..e67b1d9bb 100644 --- a/content/terraform-docs-agents/v1.22.x/docs/cloud-docs/agents/agents.mdx +++ b/content/terraform-docs-agents/v1.22.x/docs/cloud-docs/agents/agents.mdx @@ -4,7 +4,7 @@ description: >- Use HCP Terraform agents to manage infrastructure in private networks. Learn how to install, configure, and run agents on your own infrastructure. --- -# Install and Run Agents +# Install and run agents @include 'agents.mdx' @@ -12,11 +12,11 @@ The agent software runs on your own infrastructure. The token you provide when s If you have your Agent pool and token already set up, [start the agent using the official Docker image](/terraform/cloud-docs/agents/agents#run-an-agent-with-docker). -## Operational Considerations +## 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 +### 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, HCP Terraform selects the first available agent within the target pool. @@ -38,7 +38,7 @@ To customize this update behavior, pass the flag `-auto-update` or set the envir | `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. -## Run an Agent with Docker +## Run an agent with Docker To start the agent with the official Docker image and connect it to an HCP Terraform agent pool: @@ -54,7 +54,7 @@ docker run --platform=linux/amd64 -e TFC_AGENT_TOKEN -e TFC_AGENT_NAME hashicorp 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. -## Run an Agent Using the Binary +## Run an agent using the binary To download and install the agent: @@ -75,11 +75,11 @@ export TFC_AGENT_NAME=your-agent-name ``` 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 +## Optional configuration The optional configurations for customizing the agent include building a custom Docker image that grants sudo privileges for software installation, running in single-execution mode to process a single workload before terminating, and enabling request forwarding for secure access to private resources. -### Customize the Agent Docker image +### Customize the agent Docker image The Docker image executes the `tfc-agent` process as the non-root `tfc-agent` user. For some workflows, you may need to build a customized version of the agent Docker image for your internal use. For example, if your workflow needs to install software using `apt-get` during `local-exec` scripts. @@ -100,19 +100,19 @@ USER tfc-agent The above customized Dockerfile lets an agent install additional software using `sudo apt-get`. -### Single-Execution Mode +### 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. -### Request Forwarding +### Request forwarding 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 +## 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. @@ -123,12 +123,64 @@ The agent maintains a registration and a liveness indicator within HCP Terraform 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. +## Address provider compatibility errors + +If a provider does not support your agent’s architecture, the following error appears in the agent’s TRACE logs, the CLI, or the UI: + +```plaintext +Error: Incompatible provider version + +Provider registry.terraform.io// does not have a +package available for your current platform, . + +Provider releases are separate from Terraform CLI releases, so not all +providers are available for all platforms. Other versions of this provider +may have different platforms supported. +``` + +You can call the [Terraform provider registry API](/terraform/internals/provider-registry-protocol#list-available-versions) to confirm the architectures available for a provider. + +Sample request: + +```shell-session +$ curl 'https://registry.terraform.io/v1/providers/hashicorp/random/versions' +``` + +Sample response: + +```json +{ + "versions": [ + { + "version": "2.0.0", + "protocols": ["4.0", "5.1"], + "platforms": [ + {"os": "darwin", "arch": "amd64"}, + {"os": "linux", "arch": "amd64"}, + {"os": "linux", "arch": "arm"}, + {"os": "windows", "arch": "amd64"} + ] + }, + { + "version": "2.0.1", + "protocols": ["5.2"], + "platforms": [ + {"os": "darwin", "arch": "amd64"}, + {"os": "linux", "arch": "amd64"}, + {"os": "linux", "arch": "arm"}, + {"os": "windows", "arch": "amd64"} + ] + } + ] +} +``` + -# CLI Options +# CLI options * `-name `: diff --git a/content/terraform-docs-agents/v1.22.x/docs/cloud-docs/agents/requirements.mdx b/content/terraform-docs-agents/v1.22.x/docs/cloud-docs/agents/requirements.mdx index 0571cfd92..e978908aa 100644 --- a/content/terraform-docs-agents/v1.22.x/docs/cloud-docs/agents/requirements.mdx +++ b/content/terraform-docs-agents/v1.22.x/docs/cloud-docs/agents/requirements.mdx @@ -6,21 +6,33 @@ description: >- # Agent Requirements -~> Important: All agents in an agent pool should have the same operating system and hardware resources available. If the agents are using different resources, run performance can vary significantly between each agent in the pool. - Ensure your system meets the following requirements before installing and configuring HCP Terraform Agents. Refer to [HCP Terraform Agents on Terraform Enterprise](/terraform/enterprise/admin/agents-on-tfe) for additional Terraform Enterprise requirements. -## Supported Operating Systems +## Environment + +You can deploy agents to x86_64 and ARM64 Linux. You can also run the agent in Docker using our official [HCP Terraform Agent Docker container](https://hub.docker.com/r/hashicorp/tfc-agent). + +All agents in an agent pool should have the same operating system. If the agents use different resources, run performance can vary significantly between each agent in the pool. + +The architecture of the agent pool is determined by the first agent that connects to HCP Terraform. For example, when the first agent to register to an empty pool is an ARM64 agent, subsequent agents that register must be ARM64 agents. Attempting to register an ARM64 agent to an existing x86-only agent pool results in an error. + +Refer to [Change the agent pool architecture](/terraform/cloud-docs/agents/agent-pools#change-the-agent-pool-architecture) for instructions on how to switch between architectures. + +## Terraform versions + +You can use the agent with the following versions of Terraform. + +- Terraform 0.12 and newer for agents on x86-64. +- Terraform 0.13.5 and newer for agents on ARM64. -[Agents](https://releases.hashicorp.com/tfc-agent/) currently only support x86_64 bit Linux operating systems. You can also run the agent within Docker using our official [HCP Terraform Agent Docker container](https://hub.docker.com/r/hashicorp/tfc-agent). +Workspaces configured to use Terraform versions older than 0.12 cannot select the agent-based execution mode. -## Supported Terraform Versions -Agents support Terraform versions 0.12 and above. Workspaces configured to use Terraform versions below 0.12 cannot select the agent-based execution mode. +## Hardware -## Hardware Requirements +The host running the agent has varying resource requirements depending on the workspaces the agent serves and the agent's configuration. A host can be a dedicated or shared cloud instance, virtual machine, bare metal server, or a container. You should monitor and adjust memory, CPU, and disk space based on each workspace's usage and performance. -The host running the agent has varying resource requirements depending on the workspaces the agent will serve and the agent's configuration. A host can be a dedicated or shared cloud instance, virtual machine, bare metal server, or a container. You should monitor and adjust memory, CPU, and disk space based on each workspace's usage and performance. +All agents in an agent pool should have the same hardware resources available. If the agents use different resources, run performance can vary significantly between each agent in the pool. Use the following specifications as a reference: @@ -31,7 +43,7 @@ Use the following specifications as a reference: - This provides the agent with enough memory to complete run operations, such as `terraform plan`, `git clone`, and `sentinel apply`. This also supports operations such as uploading and downloading artifacts, constructing temporary execution environments, and parsing configurations. - If you enable request forwarding, we recommend that you add at least 250MB of additional memory. The agent may hold multiple forwarded requests and responses in memory until they are successfully executed and relayed to HCP Terraform. -## Software Requirements +## Software Agents may depend on third-party tooling for certain features and functionality. The tfc-agent itself does not have any direct dependency on any of the following @@ -56,7 +68,7 @@ Terraform's `local-exec` provisioners, an `external` data source, or a tfc-agent * `tar` - Unarchiver for tar archives. * `gzip` - Decompression utility for gzipped archives. -## Networking Requirements +## Networking In order for an agent to function properly, it must be able to make outbound TCP connections to the HCP Terraform application APIs. These requests may require perimeter networking as well as container host networking changes, depending on your environment. Refer to the [HCP Terraform IP Ranges documentation](/terraform/cloud-docs/architectural-details/ip-ranges) for more details on the IP ranges. @@ -68,4 +80,4 @@ Additionally, the agent must also be able to communicate with any services requi | registry.terraform.io | tcp/443, HTTPS | Outbound | Downloading public modules from the Terraform Registry | | releases.hashicorp.com | tcp/443, HTTPS | Outbound | Updating agent components and downloading Terraform binaries | | archivist.terraform.io | tcp/443, HTTPS | Outbound | Blob Storage | -| agents.terraform.io | tcp/7146, TCP | Outbound | Agent RPC interface (currently used for request forwarding only) | +| agents.terraform.io | tcp/7146, TCP | Outbound | Agent RPC interface (currently used for request forwarding only) | \ No newline at end of file