You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: content/terraform-docs-agents/v1.24.x/docs/cloud-docs/agents/agent-pools.mdx
+43-44Lines changed: 43 additions & 44 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,19 +1,25 @@
1
1
---
2
2
page_title: Manage HCP Terraform agent pools
3
3
description: >-
4
-
Agent pools are groups of one or more agents. Learn how to manage agent pools and assign them to specific workspaces.
4
+
Agent pools are groups of one or more agents. Learn how to manage agent pools and assign them to specific workspaces or Stacks.
5
5
---
6
6
7
7
# Manage agent pools
8
8
9
-
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.
9
+
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 or Stack to execute runs using agents, any available agent in that workspace or Stack's associated agent pool can complete the run.
10
+
11
+
<Note>
12
+
13
+
Terraform Enterprise does not support Stacks. You can only scope agent pools to workspaces and projects in Terraform Enterprise.
14
+
15
+
</Note>
10
16
11
17
## Permissions
12
18
13
19
Managing agent pools requires the following permissions:
14
20
15
-
- You must be a member of the **Owners** team within your organization to manage an organization's agents.
16
-
- You must have **Admin** access to a workspace before you can change its [execution mode](/terraform/cloud-docs/workspaces/settings#execution-mode) to use an agent pool.
21
+
- You must have the [**Manage Agent Pools**](/terraform/cloud-docs/users-teams-organizations/permissions/organization#manage-agent-pools) permission in your organization to manage an organization's agents.
22
+
- You must have **Admin** access to a workspace or Stack before you can change its execution mode to use an agent pool.
17
23
18
24
Refer to [Permissions](/terraform/cloud-docs/users-teams-organizations/permissions) in the HCP Terraform documentation for details.
19
25
@@ -25,7 +31,7 @@ To create an agent pool:
25
31
26
32
1. Go to your organization's settings, click **Agents**, and then click **Create agent pool**.
27
33
28
-
1. Enter an **Agent Pool Name**, and then click **Continue**. HCP Terraform uses this name to distinguish agent pools in a workspace's settings.
34
+
1. Enter an **Agent Pool Name**, and then click **Continue**. HCP Terraform uses this name to distinguish agent pools in a workspace or Stack's settings.
29
35
30
36
1. Enter a token **Description**, and then click **Create Token**.
31
37
@@ -36,26 +42,25 @@ To create an agent pool:
36
42
To connect an agent to this pool, configure and [start an agent using the official Docker image](/terraform/cloud-docs/agents/agents#quick-start).
37
43
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.
38
44
39
-
## Scope an agent pool to specific workspaces
45
+
## Scope an agent pool
40
46
41
-
Scoping an agent pool lets you specify which workspacescan 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.
47
+
Scoping an agent pool lets you specify which workspaces, projects, or Stacks can use it. The agent pool is only available from within the chosen workspaces, projects, or Stacks, and it does not appear in other workspace's, project's, or Stack's lists of available agent pools.
42
48
43
-
~> **Important:** Scoping an agent pool does not remove it from workspacesthat are actively using it. To remove access, you must first remove the agent pool from within the workspace's settings.
49
+
~> **Important:** Scoping an agent pool does not remove it from workspaces, projects, or Stacks that are actively using it. To remove access, you must first remove the agent pool from within the workspace, project, or Stack settings.
44
50
45
-
To scope an agent pool to specific workspaces within the organization:
51
+
To scope an agent pool to specific workspaces, projects, or Stacks within the organization:
46
52
47
53
1. Go to your organization's settings, and then click **Agents**. The **Agents** page appears, with a list of agent pools for the organization.
48
54
49
55
1. Click the name of the pool you want to update.
50
56
51
-
1. Click **Grant access to specific workspaces**. A menu opens where you can search for workspaces within this organization.
57
+
1. Click **Grant access to specific projects, workspaces, and Stacks**. A menu opens where you can search for workspaces, projects, and Stacks within this organization.
52
58
53
-
1. Type in the search field to find available workspacesand select the workspaces that should have access to the agent pool.
59
+
1. Type in the search field to find available workspaces, projects, and Stacks and select the workspaces, projects, and Stacks that should have access to the agent pool.
54
60
55
61
1. Click **Save**.
56
62
57
-
Only the specified workspaces can use the agent pool.
58
-
63
+
Only the specified workspaces, projects, and Stacks can use the agent pool.
59
64
60
65
## Configure workspaces to use the agent
61
66
@@ -79,61 +84,55 @@ To configure the workspace to execute runs using an agent:
79
84
80
85
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.
81
86
82
-
## Exclude workspaces from accessing an agent pool
87
+
## Configure Stacks to use the agent
83
88
84
-
Excluding workspaces from an agent pool prevents the specified workspaces from using it.
89
+
Use the following steps to configure a Stack to use an agent pool.
85
90
86
-
To exclude a workspace from an agent pool:
91
+
### Step 1: Manage existing runs
87
92
88
-
1. Go to your organization's settings, and then click **Agents**. The **Agents** page appears, with a list of agent pools for the organization.
93
+
Changing a Stack's [execution mode](/terraform/cloud-docs/stacks/configure#change-execution-mode) after Terraform completes a plan causes that run to error during apply. To minimize these errors, wait for all in-progress deployment runs to complete before you change the execution mode.
89
94
90
-
1. Click the name of the pool you want to update.
95
+
### Step 2: Select agent pool
91
96
92
-
1. Click **Grant access to specific projects and workspaces**.
97
+
To learn how to configure a Stack to execute runs using an agent, refer to [Configure a Stack](/terraform/cloud-docs/stacks/configure#configure-a-stack-1).
93
98
94
-
1. Click **Add exclusions**. A menu opens where you can search for workspaces within this organization.
99
+
After changing the execution mode, your Stack begins using the agent for deployment 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 runs, depending on agent availability within the pool.
95
100
96
-
1. Type in the search field to find available workspaces and select the workspaces that should be restricted from accessing the agent pool.
101
+
## Configure projects to use the agent
97
102
98
-
1. Click **Save**.
103
+
To configure the project to execute runs using an agent:
99
104
100
-
Only the specified workspaces will be restricted from accessing the agent pool.
105
+
1. Go to the project's **General Settings** page.
106
+
1. Select **Agent** as the [execution mode](/terraform/cloud-docs/workspaces/settings#execution-mode), and select the agent pool this project should use.
107
+
1. Click **Save Settings**.
101
108
102
-
## Scope an agent pool to specific projects
109
+
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.
103
110
104
-
You can scope an agent pool to specific projects. Only the selected projects are able to use the agent pool.
111
+
## Exclude workspaces and Stacks from accessing an agent pool
105
112
106
-
~> **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.
113
+
Excluding workspaces and Stacks from an agent pool prevents the specified workspaces and Stacks from using it.
107
114
108
-
To scope an agent pool to specific projects within the organization:
115
+
To exclude a workspace or Stack from an agent pool:
109
116
110
117
1. Go to your organization's settings, and then click **Agents**. The **Agents** page appears, with a list of agent pools for the organization.
111
118
112
119
1. Click the name of the pool you want to update.
113
120
114
-
1. Click **Grant access to specific projects and workspaces**. A menu opens where you can search for projects within this organization.
115
-
116
-
1. Type in the search field to find available projects and select the projects that should have access to the agent pool.
117
-
118
-
1. Click **Save**.
119
-
120
-
Only the specified projects can use the agent pool.
121
+
1. Click **Grant access to specific projects and workspaces**.
121
122
122
-
## Configure projects to use the agent
123
+
1. Click **Add exclusions**. A menu opens where you can search for workspaces and Stacks within this organization.
123
124
124
-
To configure the project to execute runs using an agent:
125
+
1. Type in the search field to find available workspaces and Stacks and select the workspaces and Stacks that should be restricted from accessing the agent pool.
125
126
126
-
1. Go to the project's **General Settings** page.
127
-
1. Select **Agent** as the [execution mode](/terraform/cloud-docs/workspaces/settings#execution-mode), and select the agent pool this project should use.
128
-
1. Click **Save Settings**.
127
+
1. Click **Save**.
129
128
130
-
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.
129
+
Only the specified workspaces and Stacks are restricted from accessing the agent pool.
131
130
132
131
## Revoke an agent token
133
132
134
133
You may revoke an issued token from your agents at any time.
135
134
136
-
Revoking a token causes the agents using it to exit. You must reinitialize agents with a new token before they can continue servicing workspace jobs.
135
+
Revoking a token causes the agents using it to exit. You must reinitialize agents with a new token before they can continue servicing runs.
137
136
138
137
Allow active runs in the associated agent pool to finish before revoking a token. If you de-authorize an agent while it is still performing a run, the agent does not post updates about that run. We recommend generating a new token first, initializing the agents using it, and then revoking the old token once no agents are using it. Agent tokens display information about the last time an agent used them. You can use this information to help you decide whether a token is safe to revoke.
139
138
@@ -145,12 +144,12 @@ Allow active runs in the associated agent pool to finish before revoking a token
145
144
146
145
## Delete an agent pool
147
146
148
-
~> **Important:** You cannot delete an agent pool that is still associated with one or more workspaces.
147
+
~> **Important:** You cannot delete an agent pool that is still associated with one or more workspaces or Stacks.
149
148
150
149
To delete an agent pool:
151
150
152
-
1. Wait for all associated workspaces to complete all in progress runs.
153
-
1. Remove the agent pool from all associated workspaces.
151
+
1. Wait for all associated workspaces and Stacks to complete all in progress runs.
152
+
1. Remove the agent pool from all associated workspaces and Stacks.
154
153
1. Navigate to your organization's settings, click **Agents**, and then click the name of the agent pool you want to delete.
The above customized Dockerfile lets an agent install additional software using `sudo apt-get`.
102
102
103
103
### Single-execution mode
@@ -130,15 +130,15 @@ If a provider does not support your agent’s architecture, the following error
130
130
```plaintext
131
131
Error: Incompatible provider version
132
132
133
-
Provider registry.terraform.io/<namespace>/<name_version> does not have a
133
+
Provider registry.terraform.io/<namespace>/<name_version> does not have a
134
134
package available for your current platform, <os_architecture>.
135
135
136
-
Provider releases are separate from Terraform CLI releases, so not all
137
-
providers are available for all platforms. Other versions of this provider
136
+
Provider releases are separate from Terraform CLI releases, so not all
137
+
providers are available for all platforms. Other versions of this provider
138
138
may have different platforms supported.
139
139
```
140
140
141
-
You can call the [Terraform provider registry API](/terraform/internals/provider-registry-protocol#list-available-versions) to confirm the architectures available for a provider.
141
+
You can call the [Terraform provider registry API](/terraform/internals/provider-registry-protocol#list-available-versions) to confirm the architectures available for a provider.
Copy file name to clipboardExpand all lines: content/terraform-docs-agents/v1.24.x/docs/cloud-docs/agents/requirements.mdx
+4-4Lines changed: 4 additions & 4 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -28,9 +28,9 @@ You can use the agent with the following versions of Terraform.
28
28
Workspaces configured to use Terraform versions older than 0.12 cannot select the agent-based execution mode.
29
29
30
30
31
-
## Hardware
31
+
## Hardware
32
32
33
-
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.
33
+
The host running the agent has varying resource requirements depending on the workspaces and Stacks 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 and Stack's usage and performance.
34
34
35
35
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.
36
36
@@ -68,7 +68,7 @@ Terraform's `local-exec` provisioners, an `external` data source, or a tfc-agent
68
68
*`tar` - Unarchiver for tar archives.
69
69
*`gzip` - Decompression utility for gzipped archives.
70
70
71
-
## Networking
71
+
## Networking
72
72
73
73
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.
74
74
@@ -80,4 +80,4 @@ Additionally, the agent must also be able to communicate with any services requi
80
80
| registry.terraform.io | tcp/443, HTTPS | Outbound | Downloading public modules from the Terraform Registry |
0 commit comments