Skip to content

Commit 5da29b1

Browse files
rkoron007rkoron007
authored
Merge pull request #399 from hashicorp/sahar/update_agents_for_stacks_ga
Updating the Agents API docs
2 parents 1316a54 + 674c228 commit 5da29b1

File tree

1 file changed

+146
-14
lines changed
  • content/terraform-docs-common/docs/cloud-docs/api-docs

1 file changed

+146
-14
lines changed

‎content/terraform-docs-common/docs/cloud-docs/api-docs/agents.mdx‎

Lines changed: 146 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -38,9 +38,9 @@ description: >-
3838

3939
# Agents and agent pools API reference
4040

41-
An Agent Pool represents a group of Agents, often related to one another by sharing a common network segment or purpose.
42-
A workspace<!-- BEGIN: TFC:only name:stacks-tfe --> or Stack<!-- END: TFC:only name:stacks-tfe --> may be configured to use one of the organization's agent pools to run remote operations with isolated,
43-
private, or on-premises infrastructure.
41+
An Agent Pool represents a group of Agents, often related to one another by sharing a common network segment or purpose. A workspace or Stack may be configured to use one of the organization's agent pools to run remote operations with isolated, private, or on-premises infrastructure.
42+
43+
Terraform Enterprise does not currently support Stacks, so any references to Stacks in the following API endpoints only apply to HCP Terraform.
4444

4545
<!-- BEGIN: TFC:only name:pnp-callout -->
4646
@include 'tfc-package-callouts/agents.mdx'
@@ -71,8 +71,9 @@ This endpoint supports pagination [with standard URL query parameters](/terrafor
7171
| `sort` | **Optional.** Allows sorting the returned agents pools. Valid values are `"name"` and `"created-at"`. Prepending a hyphen to the sort parameter will reverse the order (e.g. `"-name"`). |
7272
| `page[number]` | **Optional.** If omitted, the endpoint will return the first page. |
7373
| `page[size]` | **Optional.** If omitted, the endpoint will return 20 agent pools per page. |
74-
| `filter[allowed_workspaces][name]` | **Optional.** Filters agent pools to those associated with the given workspace. The workspace must have permission to use the agent pool. Refer to [Scoping Agent Pools to Specific Workspaces](/terraform/cloud-docs/agents#scope-an-agent-pool). |
75-
| `filter[allowed_projects][name]` | **Optional.** Filters agent pools to those associated with the given project. The project must have permission to use the agent pool. Refer to [Scoping Agent Pools to Specific Projects](/terraform/cloud-docs/agents#scope-an-agent-pool-to-specific-projects). |
74+
| `filter[allowed_workspaces][name]` | **Optional.** Filters agent pools to those associated with the given workspace. The workspace must have permission to use the agent pool. Refer to [Scoping Agent Pools](/terraform/cloud-docs/agents#scope-an-agent-pool). |
75+
| `filter[allowed_stacks][name]` | **Optional.** Filters agent pools to those associated with the given Stack. The Stack must have permission to use the agent pool. Only available in HCP Terraform, refer to [Scope agent pools](/terraform/cloud-docs/agents#scope-an-agent-pool) to learn more. |
76+
| `filter[allowed_projects][name]` | **Optional.** Filters agent pools to those associated with the given project. The project must have permission to use the agent pool. Refer to [Scoping Agent Pools](/terraform/cloud-docs/agents#scope-an-agent-pool). |
7677

7778

7879
### Response fields
@@ -136,6 +137,30 @@ curl \
136137
}
137138
]
138139
},
140+
"stacks": {
141+
"data": [
142+
{
143+
"id": "st-udYJjMCsnxU87uur",
144+
"type": "stacks"
145+
}
146+
]
147+
},
148+
"allowed-stacks": {
149+
"data": [
150+
{
151+
"id": "st-udYJjMCsnxU87uur",
152+
"type": "stacks"
153+
}
154+
]
155+
},
156+
"excluded-stacks": {
157+
"data": [
158+
{
159+
"id": "st-ksVruWHkgjHVB8zM",
160+
"type": "stacks"
161+
}
162+
]
163+
},
139164
"allowed-projects": {
140165
"data": [
141166
{
@@ -190,12 +215,11 @@ curl \
190215

191216
This endpoint supports pagination [with standard URL query parameters](/terraform/cloud-docs/api-docs#query-parameters). Remember to percent-encode `[` as `%5B` and `]` as `%5D` if your tooling doesn't automatically encode URLs.
192217

193-
| Parameter | Description |
194-
| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
195-
| `filter[last-ping-since]` | **Optional.** Accepts a date in ISO8601 format (ex. `2020-08-11T10:41:23Z`). |
196-
| `page[number]` | **Optional.** If omitted, the endpoint will return the first page. |
197-
| `page[size]` | **Optional.** If omitted, the endpoint will return 20 agents per page. |
198-
| `sort` | **Optional.** Allows sorting the returned agents. Valid value is `"created-at"`. Prepending a hyphen to the sort parameter will reverse the order (e.g. `"-created-at"`). |
218+
| Parameter | Description |
219+
| ------------------------- | ---------------------------------------------------------------------------- |
220+
| `filter[last-ping-since]` | **Optional.** Accepts a date in ISO8601 format (ex. `2020-08-11T10:41:23Z`). |
221+
| `page[number]` | **Optional.** If omitted, the endpoint will return the first page. |
222+
| `page[size]` | **Optional.** If omitted, the endpoint will return 20 agents per page. |
199223

200224
### Sample Request
201225

@@ -341,6 +365,30 @@ curl \
341365
}
342366
]
343367
},
368+
"stacks": {
369+
"data": [
370+
{
371+
"id": "st-udYJjMCsnxU87uur",
372+
"type": "stacks"
373+
}
374+
]
375+
},
376+
"allowed-stacks": {
377+
"data": [
378+
{
379+
"id": "st-udYJjMCsnxU87uur",
380+
"type": "stacks"
381+
}
382+
]
383+
},
384+
"excluded-stacks":
385+
"data": [
386+
{
387+
"id": "st-ksVruWHkgjHVB8zM",
388+
"type": "stacks"
389+
}
390+
]
391+
},
344392
"allowed-projects": {
345393
"data": [
346394
{
@@ -453,11 +501,15 @@ Properties without a default value are required.
453501
| `data.attributes.name` | string | | The name of the agent pool, which can only include letters, numbers, `-`, and `_`. This will be used as an identifier and must be unique in the organization. |
454502
| `data.attributes.organization-scoped` | bool | true | The scope of the agent pool. If true, all workspaces in the organization can use the agent pool. |
455503
| `data.relationships.allowed-workspaces.data.type` | string | | Must be `"workspaces"`. |
456-
| `data.relationships.allowed-workspaces.data.id` | string | | The ID of the workspace that has permission to use the agent pool. Refer to [Scoping Agent Pools to Specific Workspaces](/terraform/cloud-docs/agents#scope-an-agent-pool). |
457-
| `data.relationships.allowed-projects.data.type` | string | | Must be `"projects"`. Refer to [Scoping Agent Pools to Specific Projects](/terraform/cloud-docs/agents#scope-an-agent-pool-to-specific-projects). |
504+
| `data.relationships.allowed-workspaces.data.id` | string | | The ID of the workspace that has permission to use the agent pool. Refer to [Scope Agent Pools](/terraform/cloud-docs/agents#scope-an-agent-pool). |
505+
| `data.relationships.allowed-stacks.data.type` | string | | Must be `"stacks"`. Only available in HCP Terraform. |
506+
| `data.relationships.allowed-stacks.data.id` | string | | The ID of the stack that has permission to use the agent pool. Only available in HCP Terraform, refer to [Scope Agent Pools](/terraform/cloud-docs/agents#scope-an-agent-pool) to learn more. |
507+
| `data.relationships.allowed-projects.data.type` | string | | Must be `"projects"`. Refer to [Scope Agent Pools](/terraform/cloud-docs/agents#scope-an-agent-pool). |
458508
| `data.relationships.allowed-projects.data.id` | string | | The ID of the project that has permission to use the agent pool. |
459509
| `data.relationships.excluded-workspaces.data.type` | string | | Must be `"workspaces"`. |
460510
| `data.relationships.excluded-workspaces.data.id` | string | | The ID of the workspace that is excluded from the scope of the agent pool. |
511+
| `data.relationships.excluded-stacks.data.type` | string | | Must be `"stacks"`. Only available in HCP Terraform. |
512+
| `data.relationships.excluded-stacks.data.id` | string | | The ID of the Stack that is excluded from the scope of the agent pool. Only available in HCP Terraform. |
461513

462514
### Sample Payload
463515

@@ -486,6 +538,22 @@ Properties without a default value are required.
486538
}
487539
]
488540
},
541+
"allowed-stacks": {
542+
"data": [
543+
{
544+
"id": "st-udYJjMCsnxU87uur",
545+
"type": "stacks"
546+
}
547+
]
548+
},
549+
"excluded-stacks":
550+
"data": [
551+
{
552+
"id": "st-ksVruWHkgjHVB8zM",
553+
"type": "stacks"
554+
}
555+
]
556+
},
489557
"allowed-projects": {
490558
"data": [
491559
{
@@ -553,6 +621,25 @@ curl \
553621
}
554622
]
555623
},
624+
"stacks": {
625+
"data": []
626+
},
627+
"allowed-stacks": {
628+
"data": [
629+
{
630+
"id": "st-udYJjMCsnxU87uur",
631+
"type": "stacks"
632+
}
633+
]
634+
},
635+
"excluded-stacks":
636+
"data": [
637+
{
638+
"id": "st-ksVruWHkgjHVB8zM",
639+
"type": "stacks"
640+
}
641+
]
642+
},
556643
"allowed-projects": {
557644
"data": [
558645
{
@@ -595,11 +682,15 @@ Properties without a default value are required.
595682
| `data.attributes.name` | string | (previous value) | The name of the agent pool, which can only include letters, numbers, `-`, and `_`. This will be used as an identifier and must be unique in the organization. |
596683
| `data.attributes.organization-scoped` | bool | true | The scope of the agent pool. If true, all workspaces in the organization can use the agent pool. |
597684
| `data.relationships.allowed-workspaces.data.type` | string | | Must be `"workspaces"`. |
598-
| `data.relationships.allowed-workspaces.data.id` | string | | The ID of the workspace that has permission to use the agent pool. Refer to [Scoping Agent Pools to Specific Workspaces](/terraform/cloud-docs/agents#scope-an-agent-pool). |
685+
| `data.relationships.allowed-workspaces.data.id` | string | | The ID of the workspace that has permission to use the agent pool. Refer to [Scoping Agent Pools](/terraform/cloud-docs/agents#scope-an-agent-pool). |
686+
| `data.relationships.allowed-stacks.data.type` | string | | Must be `"stacks"`. Only available in HCP Terraform. |
687+
| `data.relationships.allowed-stacks.data.id` | string | | The ID of the Stack that has permission to use the agent pool. Only available in HCP Terraform, refer to [Scope agent pools](/terraform/cloud-docs/agents#scope-an-agent-pool) to learn more. |
599688
| `data.relationships.allowed-projects.data.type` | string | | Must be `"projects"`. Refer to [Scoping Agent Pools to Specific Projects](/terraform/cloud-docs/agents#scope-an-agent-pool-to-specific-projects). |
600689
| `data.relationships.allowed-projects.data.id` | string | | The ID of the project that has permission to use the agent pool. |
601690
| `data.relationships.excluded-workspaces.data.type` | string | | Must be `"workspaces"`. |
602691
| `data.relationships.excluded-workspaces.data.id` | string | | The ID of the workspace that is excluded from the scope of the agent pool. |
692+
| `data.relationships.excluded-stacks.data.type` | string | | Must be `"stacks"`. Only available in HCP Terraform. |
693+
| `data.relationships.excluded-stacks.data.id` | string | | The ID of the Stack that is excluded from the scope of the agent pool. Only available in HCP Terraform. |
603694

604695
### Sample Payload
605696

@@ -628,6 +719,22 @@ Properties without a default value are required.
628719
}
629720
]
630721
},
722+
"allowed-stacks": {
723+
"data": [
724+
{
725+
"id": "st-udYJjMCsnxU87uur",
726+
"type": "stacks"
727+
}
728+
]
729+
},
730+
"excluded-stacks":
731+
"data": [
732+
{
733+
"id": "st-ksVruWHkgjHVB8zM",
734+
"type": "stacks"
735+
}
736+
]
737+
},
631738
"allowed-projects": {
632739
"data": [
633740
{
@@ -698,6 +805,30 @@ $ curl \
698805
}
699806
]
700807
},
808+
"stacks": {
809+
"data": [
810+
{
811+
"id": "st-udYJjMCsnxU87uur",
812+
"type": "stacks"
813+
}
814+
]
815+
},
816+
"allowed-stacks": {
817+
"data": [
818+
{
819+
"id": "st-udYJjMCsnxU87uur",
820+
"type": "stacks"
821+
}
822+
]
823+
},
824+
"excluded-stacks":
825+
"data": [
826+
{
827+
"id": "st-ksVruWHkgjHVB8zM",
828+
"type": "stacks"
829+
}
830+
]
831+
},
701832
"allowed-projects": {
702833
"data": [
703834
{
@@ -739,3 +870,4 @@ The GET endpoints above can optionally return related resources, if requested wi
739870
| Resource Name | Description |
740871
| -------------- | ------------------------------------------- |
741872
| `workspaces` | The workspaces attached to this agent pool. |
873+
| `stacks` | The Stacks attached to this agent pool. Only available in HCP Terraform. |

0 commit comments

Comments
 (0)