Merge pull request hashicorp#49 from hashicorp/hs26gill/workspace-sco…

…ped-agent-pool-api added api documentation for allowed workspaces on agent pools page
maniankara · Jun 28, 2022 · 72afa57 · 72afa57
2 parents 7436948 + e99e5f8
commit 72afa57
Show file tree

Hide file tree

Showing 2 changed files with 90 additions and 19 deletions.
diff --git a/website/docs/cloud-docs/api-docs/agents.mdx b/website/docs/cloud-docs/api-docs/agents.mdx
@@ -61,12 +61,13 @@ This endpoint allows you to list agent pools, their agents, and their tokens for
 
 This endpoint supports pagination [with standard URL query parameters](/cloud-docs/api-docs/#query-parameters). Remember to percent-encode `[` as `%5B` and `]` as `%5D` if your tooling doesn't automatically encode URLs.
 
-| Parameter | Description |
-| -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `q` | **Optional.** A search query string. Agent pools are searchable by name. Available in Terraform Enterprise v202207-1 and later. |
-| `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"`). |
-| `page[number]` | **Optional.** If omitted, the endpoint will return the first page. |
-| `page[size]` | **Optional.** If omitted, the endpoint will return 20 agent pools per page. |
+| Parameter | Description |
+|------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `q` | **Optional.** A search query string. Agent pools are searchable by name. Available in Terraform Enterprise v202207-1 and later. |
+| `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"`). |
+| `page[number]` | **Optional.** If omitted, the endpoint will return the first page. |
+| `page[size]` | **Optional.** If omitted, the endpoint will return 20 agent pools per page. |
+| `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](/docs/cloud-docs/agents#scoping-agent-pools-to-specific-workspaces). Available in Terraform Enterprise v202207-1 and later. | |
 
 ### Sample Request
 
@@ -88,7 +89,8 @@ curl \
  "type": "agent-pools",
  "attributes": {
  "name": "example-pool",
- "created-at": "2020-08-05T18:10:26.964Z"
+ "created-at": "2020-08-05T18:10:26.964Z",
+ "organization-scoped": false
  },
  "relationships": {
  "agents": {
@@ -108,6 +110,14 @@ curl \
  "type": "workspaces"
  }
  ]
+ },
+ "allowed-workspaces": {
+ "data": [
+ {
+ "id": "ws-x9taqV23mxrGcDrn",
+ "type": "workspaces"
+ }
+ ]
  }
  },
  "links": {
@@ -267,7 +277,8 @@ curl \
  "type": "agent-pools",
  "attributes": {
  "name": "example-pool",
- "created-at": "2020-08-05T18:10:26.964Z"
+ "created-at": "2020-08-05T18:10:26.964Z",
+ "organization-scoped": false
  },
  "relationships": {
  "agents": {
@@ -287,6 +298,14 @@ curl \
  "type": "workspaces"
  }
  ]
+ },
+ "allowed-workspaces": {
+ "data": [
+ {
+ "id": "ws-x9taqV23mxrGcDrn",
+ "type": "workspaces"
+ }
+ ]
  }
  },
  "links": {
@@ -384,10 +403,13 @@ This POST endpoint requires a JSON object with the following properties as a req
 
 Properties without a default value are required.
 
-| Key path | Type | Default | Description |
-| ---------------------- | ------ | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `data.type` | string | | Must be `"agent-pools"`. |
-| `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. |
+| Key path | Type | Default | Description |
+|---------------------------------------------------|--------|---------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `data.type` | string | | Must be `"agent-pools"`. |
+| `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. |
+| `data.attributes.organization-scoped` | bool | true | The scope of the agent pool. If true, all workspaces in the organization can use the agent pool. Available in Terraform Enterprise v202207-1 and later. |
+| `data.relationships.allowed-workspaces.data.type` | string | | Must be `"workspaces"`. Available in Terraform Enterprise v202207-1 and later. |
+| `data.relationships.allowed-workspaces.data.id` | string | | The ID of the workspace that is allowed to use the agent pool. Refer to [Scoping Agent Pools to Specific Workspaces](/docs/cloud-docs/agents#scoping-agent-pools-to-specific-workspaces). Available in Terraform Enterprise v202207-1 and later. |
 
 ### Sample Payload
 
@@ -396,7 +418,18 @@ Properties without a default value are required.
  "data": {
  "type": "agent-pools",
  "attributes": {
- "name": "my-pool"
+ "name": "my-pool",
+ "organization-scoped": false,
+ },
+ "relationships": {
+ "allowed-workspaces": {
+ "data": [
+ {
+ "id": "ws-x9taqV23mxrGcDrn",
+ "type": "workspaces"
+ }
+ ]
+ }
  }
  }
 }
@@ -422,7 +455,9 @@ curl \
  "type": "agent-pools",
  "attributes": {
  "name": "my-pool",
- "created-at": "2020-10-13T16:32:45.165Z"
+ "created-at": "2020-10-13T16:32:45.165Z",
+ "organization-scoped": false,
+
  },
  "relationships": {
  "agents": {
@@ -437,6 +472,14 @@ curl \
  },
  "workspaces": {
  "data": []
+ },
+ "allowed-workspaces": {
+ "data": [
+ {
+ "id": "ws-x9taqV23mxrGcDrn",
+ "type": "workspaces"
+ }
+ ]
  }
  },
  "links": {
@@ -466,10 +509,13 @@ This PATCH endpoint requires a JSON object with the following properties as a re
 
 Properties without a default value are required.
 
-| Key path | Type | Default | Description |
-| ---------------------- | ------ | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `data.type` | string | | Must be `"agent-pools"`. |
-| `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. |
+| Key path | Type | Default | Description |
+|---------------------------------------------------|--------|------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `data.type` | string | | Must be `"agent-pools"`. |
+| `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. |
+| `data.attributes.organization-scoped` | bool | true | The scope of the agent pool. If true, all workspaces in the organization can use the agent pool. Available in Terraform Enterprise v202207-1 and later. |
+| `data.relationships.allowed-workspaces.data.type` | string | | Must be `"workspaces"`. Available in Terraform Enterprise v202207-1 and later. |
+| `data.relationships.allowed-workspaces.data.id` | string | | The ID of the workspace that is allowed to use the agent pool. Refer to [Scoping Agent Pools to Specific Workspaces](/docs/cloud-docs/agents#scoping-agent-pools-to-specific-workspaces). Available in Terraform Enterprise v202207-1 and later. |
 
 ### Sample Payload
 
@@ -478,7 +524,18 @@ Properties without a default value are required.
  "data": {
  "type": "agent-pools",
  "attributes": {
- "name": "example-pool"
+ "name": "example-pool",
+ "organization-scoped": false,
+ },
+ "relationships": {
+ "allowed-workspaces": {
+ "data": [
+ {
+ "id": "ws-x9taqV23mxrGcDrn",
+ "type": "workspaces"
+ }
+ ]
+ }
  }
  }
 }
@@ -524,6 +581,14 @@ $ curl \
  "type": "workspaces"
  }
  ]
+ },
+ "allowed-workspaces": {
+ "data": [
+ {
+ "id": "ws-x9taqV23mxrGcDrn",
+ "type": "workspaces"
+ }
+ ]
  }
  },
  "links": {

diff --git a/website/docs/cloud-docs/api-docs/changelog.mdx b/website/docs/cloud-docs/api-docs/changelog.mdx
@@ -9,6 +9,12 @@ Keep track of changes to the API for Terraform Cloud and Terraform Enterprise.
 
 ### 2022-06-21
 * Updated [Admin Organizations](/cloud-docs/api-docs/admin/organizations) endpoints with new `workspace-limit` setting. This is available in Terraform Enterprise v202207-1 and later.
+* Updated [List Agent Pools](/cloud-docs/api-docs/agents/#list-agent-pools) to accept a filter parameter `filter[allowed_workspaces][name]` so that agent pools can be filtered by name of an associated workspace. The given workspace must be allowed to use the agent pool. Refer to [Scoping Agent Pools to Specific Workspaces](/docs/cloud-docs/agents#scoping-agent-pools-to-specific-workspaces).
+* Added new `organization-scoped` attribute and `allowed-workspaces` relationship to the request/response body of the below endpoints. This is available in Terraform Enterprise v202207-1 and later.
+ * [Show an Agent Pool](/cloud-docs/api-docs/agents/#show-an-agent-pool)
+ * [Create an Agent Pool](/cloud-docs/api-docs/agents/#create-an-agent-pool)
+ * [Update an Agent Pool](/cloud-docs/api-docs/agents/#update-an-agent-pool)
+
 
 ### 2022-06-17
 * Updated [Creating a Run Task](/cloud-docs/workspaces/settings/run-tasks#creating-a-run-task) section to include the new description information for the run task to be configured.