From 7bee0ce247fc8d304a6c67284d56921a9f38073e Mon Sep 17 00:00:00 2001 From: mrinalirao Date: Wed, 4 Jun 2025 08:20:59 +0530 Subject: [PATCH 1/4] recreate stacks api and configuration api PRs --- .../data/cloud-docs-nav-data.json | 1 + .../docs/cloud-docs/api-docs/stacks.mdx | 946 ++++++++++++++++++ 2 files changed, 947 insertions(+) create mode 100644 content/terraform-docs-common/docs/cloud-docs/api-docs/stacks.mdx diff --git a/content/terraform-docs-common/data/cloud-docs-nav-data.json b/content/terraform-docs-common/data/cloud-docs-nav-data.json index 86b495253..90e4ffbcd 100644 --- a/content/terraform-docs-common/data/cloud-docs-nav-data.json +++ b/content/terraform-docs-common/data/cloud-docs-nav-data.json @@ -173,6 +173,7 @@ "path": "api-docs/state-version-outputs" }, { "title": "Subscriptions", "path": "api-docs/subscriptions" }, + { "title": "Stacks", "path": "api-docs/stacks" }, { "title": "Team Membership", "path": "api-docs/team-members" }, { "title": "Team Tokens", "path": "api-docs/team-tokens" }, { "title": "Teams", "path": "api-docs/teams" }, diff --git a/content/terraform-docs-common/docs/cloud-docs/api-docs/stacks.mdx b/content/terraform-docs-common/docs/cloud-docs/api-docs/stacks.mdx new file mode 100644 index 000000000..52ed12ad2 --- /dev/null +++ b/content/terraform-docs-common/docs/cloud-docs/api-docs/stacks.mdx @@ -0,0 +1,946 @@ + +--- +page_title: Stacks - API Docs - HCP Terraform +description: >- +Use these endpoints to manage and interact with stacks. +tfc_only: true +--- + +[200]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200 + +[201]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/201 + +[202]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/202 + +[204]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/204 + +[400]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400 + +[401]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401 + +[403]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/403 + +[404]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404 + +[409]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/409 + +[412]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/412 + +[422]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/422 + +[429]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429 + +[500]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/500 + +[504]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/504 + +[JSON API document]: /terraform/cloud-docs/api-docs#json-api-documents + +[JSON API error object]: http://jsonapi.org/format/#error-objects + +# Stacks API + +Stacks represent collections of components, replicated across one or more deployments. + +## Overview + +The scope of the API includes the following endpoints: + +| Method | Path | Action | +|----------|-------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------| +| `POST` | `/stacks` | Call this endpoint to [create a stack](#create-a-stack). | +| `GET` | `/organizations/:organization_name/stacks` | Call this endpoint to [list stacks](#list-stacks). | +| `GET` | `/stacks/:stack_id` | Call this endpoint to [show a stack](#show-a-stack). | +| `PATCH` | `/stacks/:stack_id` | Call this endpoint to [update a stack](#update-a-stack). | +| `DELETE` | `/stacks/:stack_id` | Call this endpoint to [delete a stack](#delete-stack). | +| `POST` | `/stacks/:stack_id/stack-configurations` | Call this endpoint to [create a stack configuration](#create-a-stack-configuration). | +| `GET` | `/stacks/:stack_id/stack-configurations` | Call this endpoint to [list stack configurations](#list-stack-configurations). | +| `GET` | `/stack-configurations/:stack_configuration_id` | Call this endpoint to [show a stack configuration](#show-stack-configuration). | +| `GET` | `/stacks/:stack_id/stack-configuration-summaries` | Call this endpoint to [list stack configuration summaries](#list-stack-configuration-summaries). | +| `POST` | `/stacks/:stack_id/fetch-latest-from-vcs` | Call this endpoint to [fetch the latest stack configuration](#fetch-the-latest-stack-configuration). | +| `GET` | `/stack-configurations/:stack_configuration_id/stack-diagnostics` | Call this endpoint to [list stack configuration diagnostics](#list-stack-configuration-diagnostics). | +| `GET` | `/stack-configurations/:stack_configuration_id/upload-url` | Call this endpoint to [fetch stack configuration upload url](#fetch-stack-configuration-upload-url). | +| `GET` | `/stack-configurations/:stack_configuration_id/source-bundle` | Call this endpoint to [fetch stack configuration source bundle](#fetch-stack-configuration-source-bundle). | + +## Create a stack + +This endpoint creates a stack for an organization. + +`POST /stacks` + +-> **Note:** Stack create access is restricted to users who maintain the specified project, the owners team, teams with the "Manage all projects" permission, and the [organization API token](/terraform/cloud-docs/users-teams-organizations/api-tokens#organization-api-tokens). + +### Request Body + +This POST endpoint requires a JSON object with the following properties as a request payload. + +Properties without a default value are required. + +| Key path | Type | Default | Description | +|------------------------------------------------|---------|------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `data.attributes.name` | string | | The name of the stack, which can only include letters, numbers, `-`, and `_`. This will be used as an identifier and must be unique in the project. | +| `data.attributes.description` | string | (nothing) | A description for the stack. | +| `data.attributes.speculative-enabled` | boolean | `false` | Whether this stack allows automatic [speculative plans][]. Setting this to `false` prevents HCP Terraform from running plans on pull requests, which can improve security if the VCS repository is public or includes untrusted contributors. | +| `data.attributes.locked` | boolean | `false` | Whether this stack is locked. A lock prevents HCP Terraform from initiating any new runs that would modify the infrastructure managed by the stack. | +| `data.attributes.lock-reason` | string | (nothing) | Specifies why the stack is locked. | +| `data.attributes.vcs-repo` | object | | Settings for the stack's VCS repository. | +| `data.attributes.vcs-repo.branch` | string | (nothing) | The repository branch used by this stack's configuration. If omitted or submitted as an empty string, this defaults to the repository's default branch (e.g. `main`). | +| `data.attributes.vcs-repo.tags-regex` | string | (previous value) | A regular expression used to match Git tags. HCP Terraform begins preparing a stack configuration when this value is present and a VCS event occurs that contains a matching Git tag for the regular expression. | +| `data.attributes.vcs-repo.identifier` | string | | A reference to your VCS repository in the format :org/:repo where :org and :repo refer to the organization and repository in your VCS provider. | +| `data.attributes.vcs-repo.display-identifier` | string | (nothing) | The display identifier for the stack's VCS repository. For most VCS providers outside of BitBucket Cloud and Azure DevOps, this will match the identifier string. | +| `data.attributes.vcs-repo.repository-http-url` | string | | The HTTP URL for the repository. | +| `data.attributes.service-provider` | string | | The VCS provider being connected with. Valid options are `"github"`, `"github_enterprise"`, `"gitlab_hosted"`, `"gitlab_community_edition"`, `"gitlab_enterprise_edition"`, or `"ado_server"`. | +| `data.attributes.trigger-disabled` | boolean | | When disabled, plan operations won't automatically start. | +| `data.attributes.vcs-repo.oauth-token-id` | string | | The VCS Connection (OAuth Connection + Token) to use. This ID can be obtained from the [oauth-tokens](/terraform/cloud-docs/api-docs/oauth-tokens) endpoint. | +| `data.relationships.project.data.id` | string | | The ID of the project to create the stack in. You must have permission to manage the project, either by organization-level permissions or team admin access to a specific project. | + +| Status | Response | Reason | +|---------|---------------------------|-----------------------------------------------------------------------| +| [201][] | [JSON API document][] | Successfully created a stack. | +| [404][] | [JSON API error object][] | Not found, or the user is unauthorized to perform this action. | +| [422][] | [JSON API error object][] | Malformed request body (e.g., missing attributes, wrong types, etc.). | +| [500][] | [JSON API error object][] | Internal system failure. | + +### Sample Payload + +```json +{ + "data": { + "attributes": { + "vcs-repo": { + "identifier": "my-organization/basic-stack", + "display-identifier": "my-organization/basic-stack", + "oauth-token-id": "ot-hmAyP66qk2AMVdbJ", + "branch": "", + "service-provider": "github", + "repository-http-url": "https://github.com/my-organization/basic-stack", + "trigger-disabled": false + }, + "name": "basic-stack", + "description": "Example stack for documentation", + "locked" : false, + "lock-reason": "", + "speculative-enabled": false + }, + "relationships": { + "project": { + "data": { + "type": "projects", + "id": "prj-jT92VLSFpv8FwKtc" + } + } + } + } +} + +``` + +### Sample Request + +```shell +$ curl\ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request POST \ + --data @payload.json \ + https://app.terraform.io/api/v2/stacks +``` + +### Sample Response + +```json +{ + "data": { + "id": "st-8owEfTCMQShdQ8Lb", + "type": "stacks", + "attributes": { + "name": "basic-stack", + "description": "Example stack for documentation", + "speculative-enabled": false, + "locked": false, + "lock-reason": "", + "linked-stack-connections": { + "upstream-count": 0, + "downstream-count": 0, + "inputs-count": 0, + "outputs-count": 0 + }, + "vcs-repo": { + "branch": "", + "identifier": "my-organization/basic-stack", + "display-identifier": "my-organization/basic-stack", + "oauth-token-id": "ot-hmAyP66qk2AMVdbJ", + "repository-http-url": "https://github.com/my-organization/basic-stack", + "service-provider": "github", + "trigger-disabled": false, + "tags-regex": "" + }, + "created-at": "2025-05-09T21:25:37.504Z", + "updated-at": "2025-05-09T21:25:37.504Z" + }, + "relationships": { + "project": { + "data": { + "id": "prj-AeuWVcVZVFGFgSbk", + "type": "projects" + } + } + }, + "links": { + "self": "/api/v2/stacks/st-8owEfTCMQShdQ8Lb", + "stack-configurations": "/api/v2/stacks/st-8owEfTCMQShdQ8Lb/stack-configurations", + "stack-deployments": "/api/v2/stacks/st-8owEfTCMQShdQ8Lb/stack-deployments" + } + } +} +``` + +## List stacks + +This endpoint lists stacks in the organization. + +`GET /organizations/:organization_name/stacks` + +-> **Note:** Stack read access is restricted to users or teams with read project access and the [organization API token](/terraform/cloud-docs/users-teams-organizations/api-tokens#organization-api-tokens). + +| Parameter | Description | +|----------------------|-----------------------------------------------------| +| `:organization_name` | The name of the organization to list the stacks of. | + +### Query Parameters + +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. + +| Parameter | Description | +|----------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `page[number]` | **Optional.** If omitted, the endpoint will return the first page. | +| `page[size]` | **Optional.** If omitted, the endpoint will return 20 stacks per page. | +| `sort` | **Optional.** Allows sorting the returned stacks. Valid values are "name" and "created-at". Prepending a hyphen to the sort parameter reverses the order. For example, `"-name"` sorts by name in reverse alphabetical order. If omitted, the default sort order is arbitrary but stable. | + +### Sample Request + +```shell +$ curl\ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + https://app.terraform.io/api/v2/organizations/my-organization/stacks +``` + +### Sample Response + +```json +{ + "data": [ + { + "id": "st-LSqektntTNJrAhCt", + "type": "stacks", + "attributes": { + "name": "pet-nulls-stack", + "description": null, + "speculative-enabled": false, + "locked": false, + "lock-reason": "", + "linked-stack-connections": { + "upstream-count": 0, + "downstream-count": 0, + "inputs-count": 0, + "outputs-count": 0 + }, + "vcs-repo": { + "branch": "", + "tags-regex": "", + "identifier": "hashicorp-guides/pet-nulls-stack", + "display-identifier": "hashicorp-guides/pet-nulls-stack", + "oauth-token-id": "ot-t3remoFJPeuLk1Mz", + "repository-http-url": "https://github.com/hashicorp-guides/pet-nulls-stack", + "service-provider": "github", + "trigger-disabled": false + }, + "created-at": "2025-05-09T15:19:42.478Z", + "updated-at": "2025-05-09T22:53:04.324Z" + }, + "links": { + "self": "/api/v2/stacks/st-LSqektntTNJrAhCt", + "stack-configurations": "/api/v2/stacks/st-LSqektntTNJrAhCt/stack-configurations", + "stack-deployments": "/api/v2/stacks/st-LSqektntTNJrAhCt/stack-deployments" + }, + "relationships": { + "project": { + "data": { + "id": "prj-18PG93QyqCMhLhWT", + "type": "projects" + } + } + } + } + ], + "links": { + "self": "https://app.terraform.io/api/v2/organizations/hashicorp/stacks?page%5Bnumber%5D=1&page%5Bsize%5D=20", + "first": "https://app.terraform.io/api/v2/organizations/hashicorp/stacks?page%5Bnumber%5D=1&page%5Bsize%5D=20", + "prev": null, + "next": null, + "last": "https://app.terraform.io/api/v2/organizations/hashicorp/stacks?page%5Bnumber%5D=1&page%5Bsize%5D=20" + }, + "meta": { + "pagination": { + "current-page": 1, + "page-size": 20, + "prev-page": null, + "next-page": null, + "total-pages": 1, + "total-count": 1 + } + } +} +``` + +## Show a Stack +`GET /stacks/:stack_id` + +This endpoint returns details of the specified stack. + +-> **Note:** Stack read access is restricted to users or teams with read project access and the [organization API token](/terraform/cloud-docs/users-teams-organizations/api-tokens#organization-api-tokens). + +| Parameter | Description | +|-------------|---------------| +| `:stack_id` | The stack id. | + +### Sample Request + +```shell +$ curl\ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + https://app.terraform.io/api/v2/stacks/st-LSqektntTNJrAhCt +``` + +### Sample Response +```json +{ + "data": { + "id": "st-LSqektntTNJrAhCt", + "type": "stacks", + "attributes": { + "name": "pns", + "description": "This stack contains the pet-nulls-stack example", + "speculative-enabled": false, + "locked": false, + "lock-reason": "", + "linked-stack-connections": { + "upstream-count": 0, + "downstream-count": 0, + "inputs-count": 0, + "outputs-count": 0 + }, + "vcs-repo": { + "branch": "", + "tags-regex": "", + "identifier": "hashicorp/pet-nulls-stack", + "display-identifier": "hashicorp/pet-nulls-stack", + "oauth-token-id": "ot-t3remoFJPeuLk1Mz", + "repository-http-url": "https://github.com/hashicorp/pet-nulls-stack", + "service-provider": "github", + "trigger-disabled": false + }, + "created-at": "2025-05-09T15:19:42.478Z", + "updated-at": "2025-05-09T21:15:47.727Z" + }, + "relationships": { + "project": { + "data": { + "id": "prj-18PG93QyqCMhLhWT", + "type": "projects" + } + } + }, + "links": { + "self": "/api/v2/stacks/st-LSqektntTNJrAhCt", + "stack-configurations": "/api/v2/stacks/st-LSqektntTNJrAhCt/stack-configurations", + "stack-deployments": "/api/v2/stacks/st-LSqektntTNJrAhCt/stack-deployments" + } + } +} +``` +## Update a Stack + +`PATCH /stacks/:stack_id` + +This endpoint updates the specified Stack. + +| Parameter | Description | +|-------------|---------------| +| `:stack_id` | The stack id. | + +### Request Body +This endpoint requires a JSON object with the following properties as a request payload. + +Properties without a default value are required. + +| Key path | Type | Default | Description | +|------------------------------------------------|---------|------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `data.attributes.name` | string | | The name of the stack, which can only include letters, numbers, `-`, and `_`. This will be used as an identifier and must be unique in the project. | +| `data.attributes.description` | string | (nothing) | A description for the stack. | +| `data.attributes.speculative-enabled` | boolean | `false` | Whether this stack allows automatic [speculative plans][]. Setting this to `false` prevents HCP Terraform from running plans on pull requests, which can improve security if the VCS repository is public or includes untrusted contributors. | +| `data.attributes.locked` | boolean | `false` | Whether this stack is locked. A lock prevents HCP Terraform from initiating any new deployments that would modify the infrastructure managed by the stack. | +| `data.attributes.lock-reason` | string | (nothing) | Specifies why the stack is locked. | +| `data.attributes.vcs-repo` | object | | Settings for the stack's VCS repository. | +| `data.attributes.vcs-repo.branch` | string | (nothing) | The repository branch used by this stack's configuration. If omitted or submitted as an empty string, this defaults to the repository's default branch (e.g. `main`). | +| `data.attributes.vcs-repo.tags-regex` | string | (previous value) | A regular expression used to match Git tags. HCP Terraform begins preparing a stack configuration when this value is present and a VCS event occurs that contains a matching Git tag for the regular expression. | +| `data.attributes.vcs-repo.identifier` | string | | A reference to your VCS repository in the format :org/:repo where :org and :repo refer to the organization and repository in your VCS provider. | +| `data.attributes.vcs-repo.display-identifier` | string | (nothing) | The display identifier for the stack's VCS repository. For most VCS providers outside of BitBucket Cloud and Azure DevOps, this will match the identifier string. | +| `data.attributes.vcs-repo.repository-http-url` | string | | The HTTP URL for the repository. | +| `data.attributes.service-provider` | string | | The VCS provider being connected with. Valid options are `"github"`, `"github_enterprise"`, `"gitlab_hosted"`, `"gitlab_community_edition"`, `"gitlab_enterprise_edition"`, or `"ado_server"`. | +| `data.attributes.trigger-disabled` | boolean | | When disabled, plan operations won't automatically start. | +| `data.attributes.vcs-repo.oauth-token-id` | string | | The VCS Connection (OAuth Connection + Token) to use. This ID can be obtained from the [oauth-tokens](/terraform/cloud-docs/api-docs/oauth-tokens) endpoint. | +| `data.relationships.project.data.id` | string | | The ID of the project to create the stack in. You must have permission to manage the project, either by organization-level permissions or team admin access to a specific project. | + +### Sample Payload +```json +{ + "data": { + "attributes": { + "vcs-repo": { + "identifier": "hashicorp/pet-nulls-stack-local", + "display-identifier": "hashicorp/pet-nulls-stack-local", + "oauth-token-id": "ot-hmAyP66qk2AMVdbJ", + "branch": "", + "service-provider": "github", + "repository-http-url":"https://github.com/hashicorp/pet-nulls-stack-local", + "tags-regex": null, + "trigger-disabled": false + }, + "name": "pet-nulls-stack-local", + "description": "testing patch", + "locked" : false, + "lock-reason": "", + "speculative-enabled": false + } + } +} +``` +### Sample Request + +```shell +$ curl\ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request PATCH \ + https://app.terraform.io/api/v2/stacks/st-EJyw2MktbRjdsg96 +``` + +### Sample Response +```json +{ + "data": { + "id": "st-EJyw2MktbRjdsg96", + "type": "stacks", + "attributes": { + "name": "pet-nulls-stack-local", + "description": "testing patch", + "locked" : false, + "lock-reason": "", + "linked-stack-connections": { + "upstream-count": 0, + "downstream-count": 0, + "inputs-count": 0, + "outputs-count": 0 + }, + "speculative-enabled": false, + "vcs-repo": { + "branch": "", + "tags-regex": null, + "identifier": "hashicorp/pet-nulls-stack-local", + "display-identifier": "hashicorp/pet-nulls-stack-local", + "oauth-token-id": "ot-t3remoFJPeuLk1Mz", + "repository-http-url": "https://github.com/hashicorp/pet-nulls-stack-local", + "service-provider": "github", + "trigger-disabled": false + }, + "created-at": "2025-05-09T16:40:31.255Z", + "updated-at": "2025-05-09T20:24:47.324Z" + }, + "relationships": { + "project": { + "data": { + "id": "prj-18PG93QyqCMhLhWT", + "type": "projects" + } + } + }, + "links": { + "self": "/api/v2/stacks/st-EJyw2MktbRjdsg96", + "stack-configurations": "/api/v2/stacks/st-EJyw2MktbRjdsg96/stack-configurations", + "stack-deployments": "/api/v2/stacks/st-EJyw2MktbRjdsg96/stack-deployments" + } + } +} +``` + +## Delete a Stack + +`DELETE /stacks/:stack_id` + +This endpoint deletes the specified Stack. + +| Parameter | Description | +|-------------|-------------------------------------------------------------------------------------------------------------------------------------------------------| +| `:stack_id` | The ID of the stack to delete. Refer to [List stacks](/terraform/cloud-docs/api-docs#list-stacks) for reference information about finding IDs. | + +| Status | Response | Reason | +|---------|---------------------------|---------------------------------------------------------| +| [204][] | No Content | Successfully deleted the stack | +| [404][] | [JSON API error object][] | Stack not found, or user unauthorized to perform action | + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request DELETE \ + https://app.terraform.io/api/v2/stacks/st-EJyw2MktbRjdsg96 +``` +## Create a stack configuration + +This endpoint creates a stack configuration for the specified stack. + +`POST /stacks/:stack_id/stack-configurations` + +| Parameter | Description | +|-------------|-----------------------------------------------| +| `:stack_id` | The stack id to create the configuration for. | + +### Request Body + +This POST endpoint requires a JSON object with the following properties as a request payload. + +Properties without a default value are required. + +| Key path | Type | Default | Description | +|-----------------------------|---------|---------|------------------------------------------------------------------------------------------------------------------------------------------------| +| `data.attributes.plan-only` | boolean | `false` | Specifies if this is a speculative configuration that HCP Terraform cannot converge past the plan step. | + +| Status | Response | Reason | +|---------|---------------------------|-----------------------------------------------------------------------| +| [200][] | [JSON API document][] | Successfully created a stack configuration. | +| [404][] | [JSON API error object][] | Not found, or the user is unauthorized to perform this action. | +| [422][] | [JSON API error object][] | Malformed request body (e.g., missing attributes, wrong types, etc.). | +| [500][] | [JSON API error object][] | Internal system failure. | + +### Sample Payload + +```json +{ + "data": { + "attributes": { + "plan-only": true + } + } +} + +``` + +### Sample Request + +```shell +$ curl\ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request POST \ + --data @payload.json \ + https://app.terraform.io/api/v2/stacks/st-EJyw2MktbRjdsg96/stack-configurations +``` + +### Sample Response + +```json +{ + "data": { + "id": "st-EJyw2MktbRjdsg96", + "type": "stack-configurations", + "attributes": { + "status": "pending", + "sequence-number": 0, + "plan-only": true, + "preparing-event-stream-url": "https://archivist.terraform.io/v1/object/dmF1bHQ6djE6aFN6WTBJUWJ6N3ViKzFWbmptMkd6SWxocDFJK05FSFJ3MjNSNXRZLzBMS2E1YmgyMWM5eXBYMHpZVXErSG5HTUVJMTZsdHJ5c2tnOWUybDhpaW04eVROdDh1RXNGa1F2VkZqOVZKbGN6MEZhUEVqQmlvVGtwaWhjaHpiZEF3YUtWTmVQZm1TOFY0NnN2dXpVc1V2MlBmOU5BRzMvNDc5RHg0eVA2VFZDRy9PdHY1c3IwWWxwT09sdDRyRnFUSjJDSXhOaWl2UVZKNTdVaW9HOEhrN0ZvM1YyMTZLaVpndzRtSzkyTlYvRWpZTzkyTjU0THg2OWVHQk9nZEptbWhhS3hxVFFIUTR0L1ZwZWZ4SjRCWnJWZitGZ2lmd2tNTmNKTUVBQzdrV2puVWdvUlh2YjBmcGFsdnpUN1VzTkVuM0tDQm1FbXpWVXFGSVRsTlBkMkJ6dWRsYlhJck0vbVBMQ1VlZlhBTWFRZ2h2NjhCdzFFSFQ4bU50eA", + "created-at": "2025-05-09T21:25:37.504Z", + "updated-at": "2025-05-09T21:25:37.504Z" + }, + "relationships": { + "stack": { + "data": { + "id": "st-EJyw2MktbRjdsg96", + "type": "stacks" + } + } + }, + "links": { + "self": "/api/v2/stacks/st-EJyw2MktbRjdsg96", + "stack-diagnostics": "/api/v2/stacks/st-EJyw2MktbRjdsg96/stack-diagnostics", + "stack-deployment-groups": "/api/v2/stacks/st-EJyw2MktbRjdsg96/stack-deployment-groups", + "stack-configuration-summaries": "/api/v2/stacks/st-EJyw2MktbRjdsg96/stack-configuration-summaries" + } + } +} +``` +## List stack configurations + +This endpoint lists configurations for the specified stack. + +`GET /stacks/:stack_id/stack-configurations` + +| Parameter | Description | +|-------------|------------------------------------------| +| `:stack_id` | The stack id to list configurations for. | + +### Query Parameters + +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. + +| Parameter | Description | +|----------------|-----------------------------------------------------------------------------| +| `page[number]` | **Optional.** If omitted, the endpoint will return the first page. | +| `page[size]` | **Optional.** If omitted, the endpoint will return 20 stacks per page. | + +### Sample Request + +```shell +$ curl\ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + https://app.terraform.io/api/v2/stacks/st-EJyw2MktbRjdsg96/stack-configurations +``` + +### Sample Response + +```json +{ + "data": [ + { + "id": "st-EJyw2MktbRjdsg96", + "type": "stack-configurations", + "attributes": { + "status": "pending", + "sequence-number": 0, + "plan-only": true, + "preparing-event-stream-url": "https://archivist.terraform.io/v1/object/dmF1bHQ6djE6aFN6WTBJUWJ6N3ViKzFWbmptMkd6SWxocDFJK05FSFJ3MjNSNXRZLzBMS2E1YmgyMWM5eXBYMHpZVXErSG5HTUVJMTZsdHJ5c2tnOWUybDhpaW04eVROdDh1RXNGa1F2VkZqOVZKbGN6MEZhUEVqQmlvVGtwaWhjaHpiZEF3YUtWTmVQZm1TOFY0NnN2dXpVc1V2MlBmOU5BRzMvNDc5RHg0eVA2VFZDRy9PdHY1c3IwWWxwT09sdDRyRnFUSjJDSXhOaWl2UVZKNTdVaW9HOEhrN0ZvM1YyMTZLaVpndzRtSzkyTlYvRWpZTzkyTjU0THg2OWVHQk9nZEptbWhhS3hxVFFIUTR0L1ZwZWZ4SjRCWnJWZitGZ2lmd2tNTmNKTUVBQzdrV2puVWdvUlh2YjBmcGFsdnpUN1VzTkVuM0tDQm1FbXpWVXFGSVRsTlBkMkJ6dWRsYlhJck0vbVBMQ1VlZlhBTWFRZ2h2NjhCdzFFSFQ4bU50eA", + "created-at": "2025-05-09T21:25:37.504Z", + "updated-at": "2025-05-09T21:25:37.504Z" + }, + "relationships": { + "stack": { + "data": { + "id": "st-EJyw2MktbRjdsg96", + "type": "stacks" + } + } + }, + "links": { + "self": "/api/v2/stacks/st-EJyw2MktbRjdsg96", + "stack-diagnostics": "/api/v2/stacks/st-EJyw2MktbRjdsg96/stack-diagnostics", + "stack-deployment-groups": "/api/v2/stacks/st-EJyw2MktbRjdsg96/stack-deployment-groups", + "stack-configuration-summaries": "/api/v2/stacks/st-EJyw2MktbRjdsg96/stack-configuration-summaries" + } + } + ], + "links": { + "self": "https://app.terraform.io/api/v2/stacks/st-EJyw2MktbRjdsg96/stack-configurations?page%5Bnumber%5D=1&page%5Bsize%5D=20", + "first": "https://app.terraform.io/api/v2/stacks/st-EJyw2MktbRjdsg96/stack-configurations?page%5Bnumber%5D=1&page%5Bsize%5D=20", + "prev": null, + "next": null, + "last": "https://app.terraform.io/api/v2/stacks/st-EJyw2MktbRjdsg96/stack-configurations?page%5Bnumber%5D=1&page%5Bsize%5D=20" + }, + "meta": { + "pagination": { + "current-page": 1, + "page-size": 20, + "prev-page": null, + "next-page": null, + "total-pages": 1, + "total-count": 1 + } + } +} +``` + +## Show Stack Configuration + +`GET /stack-configurations/:stack_configuration_id` + +This endpoint returns details of the specified stack configuration. + +| Parameter | Description | +|---------------------------|-----------------------------| +| `:stack_configuration_id` | The stack configuration id. | + +### Sample Request + +```shell +$ curl\ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + https://app.terraform.io/api/v2/stack-configurations/stc-GEt1cDfuRqLACcL9 +``` + +### Sample Response +```json +{ + "data": { + "id": "stc-GEt1cDfuRqLACcL9", + "type": "stack-configurations", + "attributes": { + "status": "pending", + "sequence-number": 0, + "plan-only": true, + "preparing-event-stream-url": "https://archivist.terraform.io/v1/object/dmF1bHQ6djE6aFN6WTBJUWJ6N3ViKzFWbmptMkd6SWxocDFJK05FSFJ3MjNSNXRZLzBMS2E1YmgyMWM5eXBYMHpZVXErSG5HTUVJMTZsdHJ5c2tnOWUybDhpaW04eVROdDh1RXNGa1F2VkZqOVZKbGN6MEZhUEVqQmlvVGtwaWhjaHpiZEF3YUtWTmVQZm1TOFY0NnN2dXpVc1V2MlBmOU5BRzMvNDc5RHg0eVA2VFZDRy9PdHY1c3IwWWxwT09sdDRyRnFUSjJDSXhOaWl2UVZKNTdVaW9HOEhrN0ZvM1YyMTZLaVpndzRtSzkyTlYvRWpZTzkyTjU0THg2OWVHQk9nZEptbWhhS3hxVFFIUTR0L1ZwZWZ4SjRCWnJWZitGZ2lmd2tNTmNKTUVBQzdrV2puVWdvUlh2YjBmcGFsdnpUN1VzTkVuM0tDQm1FbXpWVXFGSVRsTlBkMkJ6dWRsYlhJck0vbVBMQ1VlZlhBTWFRZ2h2NjhCdzFFSFQ4bU50eA", + "created-at": "2025-05-09T21:25:37.504Z", + "updated-at": "2025-05-09T21:25:37.504Z" + }, + "relationships": { + "stack": { + "data": { + "id": "st-EJyw2MktbRjdsg96", + "type": "stacks" + } + } + }, + "links": { + "self": "/api/v2/stack-configurations/stc-GEt1cDfuRqLACcL9", + "stack-diagnostics": "/api/v2/stack-configurations/stc-GEt1cDfuRqLACcL9/stack-diagnostics", + "stack-deployment-groups": "/api/v2/stack-configurations/stc-GEt1cDfuRqLACcL9/stack-deployment-groups", + "stack-configuration-summaries": "/api/v2/stack-configurations/stc-GEt1cDfuRqLACcL9/stack-configuration-summaries" + } + } +} +``` + +## List stack configuration summaries + +This endpoint lists configuration summaries for the specified stack. + +`GET /stacks/:stack_id/stack-configuration-summaries` + +| Parameter | Description | +|-------------|---------------------------------------------------| +| `:stack_id` | The stack id to list configuration summaries for. | + +### Query Parameters + +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. + +| Parameter | Description | +|----------------|-----------------------------------------------------------------------------| +| `page[number]` | **Optional.** If omitted, the endpoint will return the first page. | +| `page[size]` | **Optional.** If omitted, the endpoint will return 20 stacks per page. | + +### Sample Request + +```shell +$ curl\ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + https://app.terraform.io/api/v2/stacks/st-EJyw2MktbRjdsg96/stack-configuration-summaries +``` + +### Sample Response + +```json +{ + "data": [ + { + "id": "stcs-EJyw2MktbRjdsg96", + "type": "stack-configuration-summaries", + "attributes": { + "status": "pending", + "sequence-number": 0, + "stack-deployment-group-status-summary": { + "pending": 0, + "deploying": 0, + "succeeded": 0, + "failed": 0, + "abandoned": 0 + } + }, + "relationships": { + "stack-configuration": { + "data": { + "id": "stc-GEt1cDfuRqLACcL9", + "type": "stack-configurations" + } + } + } + } + ], + "links": { + "self": "https://app.terraform.io/api/v2/stacks/st-EJyw2MktbRjdsg96/stack-configuration-summaries?page%5Bnumber%5D=1&page%5Bsize%5D=20", + "first": "https://app.terraform.io/api/v2/stacks/st-EJyw2MktbRjdsg96/stack-configuration-summaries?page%5Bnumber%5D=1&page%5Bsize%5D=20", + "prev": null, + "next": null, + "last": "https://app.terraform.io/api/v2/stacks/st-EJyw2MktbRjdsg96/stack-configuration-summaries?page%5Bnumber%5D=1&page%5Bsize%5D=20" + }, + "meta": { + "pagination": { + "current-page": 1, + "page-size": 20, + "prev-page": null, + "next-page": null, + "total-pages": 1, + "total-count": 1 + } + } +} +``` + +## Fetch the latest Stack Configuration + +`POST /stacks/:stack_id/fetch-latest-from-vcs` + +This endpoint fetches the latest configuration from version control system. + +| Parameter | Description | +|-------------|---------------------------------------------------| +| `:stack_id` | The stack id to get the latest configuration for. | + +| Status | Response | Reason | +|---------|---------------------------|-----------------------------------------------------------------------------------| +| [204][] | No Content | Successfully started the process of retrieving the latest configuration from VCS. | +| [404][] | [JSON API error object][] | Stack not found, or user unauthorized to perform action | + +### Sample Request + +```shell +$ curl\ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + https://app.terraform.io/api/v2/stack/st-SihZTyXKfNXUWuUa/fetch-latest-from-vcs +``` + +## List stack configuration diagnostics + +This endpoint lists the diagnostics for the specified stack configuration. + +`GET /stack-configurations/:stack_configuration_id/stack-diagnostics` + + +| Parameter | Description | +|---------------------------|---------------------------------------------------------| +| `:stack_configuration_id` | The stack configuration id to list the diagnostics for. | + +### Query Parameters + +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. + +| Parameter | Description | +|----------------|-----------------------------------------------------------------------------| +| `page[number]` | **Optional.** If omitted, the endpoint will return the first page. | +| `page[size]` | **Optional.** If omitted, the endpoint will return 20 stacks per page. | + +### Sample Request + +```shell +$ curl\ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + https://app.terraform.io/api/v2/stack-configurations/stc-GEt1cDfuRqLACcL9/stack-diagnostics +``` + +### Sample Response + +```json +{ + "data": [ + { + "id": "std-Phi6k5RoZLnuHWke", + "type": "stack-diagnostics", + "attributes": { + "severity": "error", + "summary": "Diagnostics reported", + "detail": "While preparing the configuration, HCP Terraform reported 2 errors.", + "acknowledged": true, + "acknowledged-at": "2025-05-14T04:44:43.893Z", + "created-at": "2025-05-14T04:44:43.893Z" + }, + "links": { + "self": "/api/v2/stack-configurations/stc-GEt1cDfuRqLACcL9/stack-diagnostics" + }, + "relationships": { + "stack-configuration": { + "data": { + "id": "stc-mtLWVPe4DmGCMVn4", + "type": "stack-configurations" + } + }, + "stack-deployment-group": { + "data": { + "id": "sdg-4G2k5J6q3v7x8Y9Z", + "type": "stack-deployment-groups" + } + } + } + } + ], + "links": { + "self": "https://app.terraform.io/api/v2/stack-configurations/stc-GEt1cDfuRqLACcL9/stack-diagnostics?page%5Bnumber%5D=1&page%5Bsize%5D=20", + "first": "https://app.terraform.io/api/v2stack-configurations/stc-GEt1cDfuRqLACcL9/stack-diagnostics?page%5Bnumber%5D=1&page%5Bsize%5D=20", + "prev": null, + "next": null, + "last": "https://app.terraform.io/api/v2stack-configurations/stc-GEt1cDfuRqLACcL9/stack-diagnostics?page%5Bnumber%5D=1&page%5Bsize%5D=20" + }, + "meta": { + "pagination": { + "current-page": 1, + "page-size": 20, + "prev-page": null, + "next-page": null, + "total-pages": 1, + "total-count": 1 + } + } +} +``` + +## Fetch stack configuration upload URL + +`GET /stack-configurations/:stack_configuration_id/upload-url` + +This endpoint fetches the stack configuration upload url. + +| Parameter | Description | +|---------------------------|---------------------------------------------------------| +| `:stack_configuration_id` | The stack configuration id to fetch the upload URL for. | + +### Sample Request + +```shell +$ curl\ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + https://app.terraform.io/api/v2/stack-configurations/stc-SihZTyXKfNXUWuUa/upload-url +``` + +### Sample Response +```json +{ + "data": { + "source-upload-url": "https://github.com/stack-config-uploads" + }, + "links": { + "self": "/api/v2/stack-configurations/stc-SihZTyXKfNXUWuUa/upload-url" + } +} +``` + +## Fetch stack configuration source bundle + +`GET /stack-configurations/:stack_configuration_id/source-bundle` + +This endpoint redirects to the download URL for a stack configuration source bundle. + +| Parameter | Description | +|---------------------------|------------------------------------------------------------| +| `:stack_configuration_id` | The stack configuration id to fetch the source bundle for. | + +| Status | Response | Reason | +|---------|---------------------------|-----------------------------------------------------------------------| +| [302][] | HTTP Redirect | Successfully redirect client to temporary source bundle download URL | +| [404][] | [JSON API error object][] | Stack configuration not found, or user unauthorized to perform action | From f395fe10f930409139db514832c18afa3ca450f1 Mon Sep 17 00:00:00 2001 From: mrinalirao Date: Wed, 11 Jun 2025 07:54:40 +0530 Subject: [PATCH 2/4] docs for stack deployments and stack deployment groups apis --- .../docs/cloud-docs/api-docs/stacks.mdx | 541 +++++++++++++++++- 1 file changed, 512 insertions(+), 29 deletions(-) diff --git a/content/terraform-docs-common/docs/cloud-docs/api-docs/stacks.mdx b/content/terraform-docs-common/docs/cloud-docs/api-docs/stacks.mdx index 52ed12ad2..cfa543b0f 100644 --- a/content/terraform-docs-common/docs/cloud-docs/api-docs/stacks.mdx +++ b/content/terraform-docs-common/docs/cloud-docs/api-docs/stacks.mdx @@ -46,21 +46,29 @@ Stacks represent collections of components, replicated across one or more deploy The scope of the API includes the following endpoints: -| Method | Path | Action | -|----------|-------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------| -| `POST` | `/stacks` | Call this endpoint to [create a stack](#create-a-stack). | -| `GET` | `/organizations/:organization_name/stacks` | Call this endpoint to [list stacks](#list-stacks). | -| `GET` | `/stacks/:stack_id` | Call this endpoint to [show a stack](#show-a-stack). | -| `PATCH` | `/stacks/:stack_id` | Call this endpoint to [update a stack](#update-a-stack). | -| `DELETE` | `/stacks/:stack_id` | Call this endpoint to [delete a stack](#delete-stack). | -| `POST` | `/stacks/:stack_id/stack-configurations` | Call this endpoint to [create a stack configuration](#create-a-stack-configuration). | -| `GET` | `/stacks/:stack_id/stack-configurations` | Call this endpoint to [list stack configurations](#list-stack-configurations). | -| `GET` | `/stack-configurations/:stack_configuration_id` | Call this endpoint to [show a stack configuration](#show-stack-configuration). | -| `GET` | `/stacks/:stack_id/stack-configuration-summaries` | Call this endpoint to [list stack configuration summaries](#list-stack-configuration-summaries). | -| `POST` | `/stacks/:stack_id/fetch-latest-from-vcs` | Call this endpoint to [fetch the latest stack configuration](#fetch-the-latest-stack-configuration). | -| `GET` | `/stack-configurations/:stack_configuration_id/stack-diagnostics` | Call this endpoint to [list stack configuration diagnostics](#list-stack-configuration-diagnostics). | -| `GET` | `/stack-configurations/:stack_configuration_id/upload-url` | Call this endpoint to [fetch stack configuration upload url](#fetch-stack-configuration-upload-url). | -| `GET` | `/stack-configurations/:stack_configuration_id/source-bundle` | Call this endpoint to [fetch stack configuration source bundle](#fetch-stack-configuration-source-bundle). | +| Method | Path | Action | +|----------|------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------| +| `POST` | `/stacks` | Call this endpoint to [create a stack](#create-a-stack). | +| `GET` | `/organizations/:organization_name/stacks` | Call this endpoint to [list stacks](#list-stacks). | +| `GET` | `/stacks/:stack_id` | Call this endpoint to [show a stack](#show-a-stack). | +| `PATCH` | `/stacks/:stack_id` | Call this endpoint to [update a stack](#update-a-stack). | +| `DELETE` | `/stacks/:stack_id` | Call this endpoint to [delete a stack](#delete-stack). | +| `POST` | `/stacks/:stack_id/stack-configurations` | Call this endpoint to [create a stack configuration](#create-a-stack-configuration). | +| `GET` | `/stacks/:stack_id/stack-configurations` | Call this endpoint to [list stack configurations](#list-stack-configurations). | +| `GET` | `/stack-configurations/:stack_configuration_id` | Call this endpoint to [show a stack configuration](#show-stack-configuration). | +| `GET` | `/stacks/:stack_id/stack-configuration-summaries` | Call this endpoint to [list stack configuration summaries](#list-stack-configuration-summaries). | +| `POST` | `/stacks/:stack_id/fetch-latest-from-vcs` | Call this endpoint to [fetch the latest stack configuration](#fetch-the-latest-stack-configuration). | +| `GET` | `/stack-configurations/:stack_configuration_id/stack-diagnostics` | Call this endpoint to [list stack configuration diagnostics](#list-stack-configuration-diagnostics). | +| `GET` | `/stack-configurations/:stack_configuration_id/upload-url` | Call this endpoint to [fetch stack configuration upload url](#fetch-stack-configuration-upload-url). | +| `GET` | `/stack-configurations/:stack_configuration_id/source-bundle` | Call this endpoint to [fetch stack configuration source bundle](#fetch-stack-configuration-source-bundle). | +| `GET` | `/stacks/:stack_id/stack-deployments` | Call this endpoint to [list stack deployments](#list-stack-deployments). | +| `GET` | `/stacks/:stack_id:/stack-deployments/:stack_deployment_name` | Call this endpoint to [show a stack deployment](#show-a-stack-deployment). | +| `GET` | `/stack-configurations/:stack_configuration_id/stack-deployment-groups` | Call this endpoint to [list stack deployment groups](#list-stack-deployment-groups). | +| `GET` | `/stack-configurations/:stack_configuration_id/stack-deployment-groups/:stack_deployment_group_name` | Call this endpoint to [show a stack deployment group by name](#show-a-stack-deployment-group-by-name). | +| `GET` | `/stack-deployment-groups/:stack_deployment_group_id` | Call this endpoint to [show a stack deployment group by id](#show-a-stack-deployment-group-by-id). | +| `POST` | `/stack-deployment-groups/:stack_deployment_group_id/approve-all-plans` | Call this endpoint to [approve a stack deployment group](#approve-a-stack-deployment-group). | +| `POST` | `/stack-deployment-groups/:stack_deployment_group_id/plan` | Call this endpoint to [plan a stack deployment group](#plan-a-stack-deployment-group). | +| `POST` | `/stack-deployment-groups/:stack_deployment_group_id/rerun` | Call this endpoint to [rerun a stack deployment group](#rerun-a-stack-deployment-group). | ## Create a stack @@ -556,7 +564,7 @@ $ curl\ ```json { "data": { - "id": "st-EJyw2MktbRjdsg96", + "id": "stc-EJyw2MktbRjdsg96", "type": "stack-configurations", "attributes": { "status": "pending", @@ -597,10 +605,10 @@ This endpoint lists configurations for the specified stack. 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. -| Parameter | Description | -|----------------|-----------------------------------------------------------------------------| -| `page[number]` | **Optional.** If omitted, the endpoint will return the first page. | -| `page[size]` | **Optional.** If omitted, the endpoint will return 20 stacks per page. | +| Parameter | Description | +|----------------|--------------------------------------------------------------------------------------| +| `page[number]` | **Optional.** If omitted, the endpoint will return the first page. | +| `page[size]` | **Optional.** If omitted, the endpoint will return 20 stack configurations per page. | ### Sample Request @@ -617,7 +625,7 @@ $ curl\ { "data": [ { - "id": "st-EJyw2MktbRjdsg96", + "id": "stc-EJyw2MktbRjdsg96", "type": "stack-configurations", "attributes": { "status": "pending", @@ -728,10 +736,10 @@ This endpoint lists configuration summaries for the specified stack. 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. -| Parameter | Description | -|----------------|-----------------------------------------------------------------------------| -| `page[number]` | **Optional.** If omitted, the endpoint will return the first page. | -| `page[size]` | **Optional.** If omitted, the endpoint will return 20 stacks per page. | +| Parameter | Description | +|----------------|-----------------------------------------------------------------------------------------------| +| `page[number]` | **Optional.** If omitted, the endpoint will return the first page. | +| `page[size]` | **Optional.** If omitted, the endpoint will return 20 stack configuration summaries per page. | ### Sample Request @@ -830,10 +838,10 @@ This endpoint lists the diagnostics for the specified stack configuration. 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. -| Parameter | Description | -|----------------|-----------------------------------------------------------------------------| -| `page[number]` | **Optional.** If omitted, the endpoint will return the first page. | -| `page[size]` | **Optional.** If omitted, the endpoint will return 20 stacks per page. | +| Parameter | Description | +|----------------|-------------------------------------------------------------------------------------------------| +| `page[number]` | **Optional.** If omitted, the endpoint will return the first page. | +| `page[size]` | **Optional.** If omitted, the endpoint will return 20 stack configuration diagnostics per page. | ### Sample Request @@ -944,3 +952,478 @@ This endpoint redirects to the download URL for a stack configuration source bun |---------|---------------------------|-----------------------------------------------------------------------| | [302][] | HTTP Redirect | Successfully redirect client to temporary source bundle download URL | | [404][] | [JSON API error object][] | Stack configuration not found, or user unauthorized to perform action | + + +## List stack deployments + +/* TODO: For reviewer - check if stack-deployment-runs should belong in the links as you need the stack deployment group id to fetch it */ + +This endpoint lists all the deployments under the specified stack. + +`GET /stacks/:stack_id/stack-deployments` + +| Parameter | Description | +|-------------|----------------------------------------------| +| `:stack_id` | The id of the stack to list deployments for. | + +### Query Parameters + +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. + +| Parameter | Description | +|----------------|------------------------------------------------------------------------------------| +| `page[number]` | **Optional.** If omitted, the endpoint will return the first page. | +| `page[size]` | **Optional.** If omitted, the endpoint will return 20 stacks deployments per page. | + +### Sample Request + +```shell +$ curl\ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + https://app.terraform.io/api/v2/stacks/st-LSqektntTNJrAhCt/stack-deployments +``` + +### Sample Response + +```json +{ + "data": [ + { + "id": "st-LSqektntTNJrAhCt-std-complex", + "type": "stack-deployments", + "attributes": { + "name": "complex" + }, + "links": { + "self": "/api/v2/stacks/st-LSqektntTNJrAhCt/stack-deployments", + "stack-deployment-runs": "/api/v2/stacks/st-LSqektntTNJrAhCt/stack-deployment-runs", + "stack-states": "/api/v2/stacks/st-LSqektntTNJrAhCt/stack-states" + }, + "relationships": { + "stack": { + "data": { + "id": "st-LSqektntTNJrAhCt", + "type": "stacks" + } + } + } + } + ], + "links": { + "self": "https://app.terraform.io/api/v2/stacks/st-LSqektntTNJrAhCt/stack-deployments?page%5Bnumber%5D=1&page%5Bsize%5D=20", + "first": "https://app.terraform.io/api/v2/stacks/st-LSqektntTNJrAhCt/stack-deployments?page%5Bnumber%5D=1&page%5Bsize%5D=20", + "prev": null, + "next": null, + "last": "https://app.terraform.io/api/v2/stacks/st-LSqektntTNJrAhCt/stack-deployments?page%5Bnumber%5D=1&page%5Bsize%5D=20" + }, + "meta": { + "pagination": { + "current-page": 1, + "page-size": 20, + "prev-page": null, + "next-page": null, + "total-pages": 1, + "total-count": 1 + } + } +} +``` + +## Show a stack deployment + +/* TODO: For reviewer - check if stack-deployment-runs should belong in the links as you need the stack deployment group id to fetch it */ + +This endpoint shows details about a stack deployment + +`GET /stacks/:stack_id/stack-deployments/:stack_deployment_name` + +| Parameter | Description | +|--------------------|----------------------------| +| `:stack_id` | The id of the stack . | +| `:deployment_name` | The stack deployment name. | + +### Sample Request + +```shell +$ curl\ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + https://app.terraform.io/api/v2/stacks/st-LSqektntTNJrAhCt/stack-deployments/complex +``` + +### Sample Response + +```json +{ + "data": + { + "id": "st-LSqektntTNJrAhCt-std-complex", + "type": "stack-deployments", + "attributes": { + "name": "complex" + }, + "links": { + "self": "/api/v2/stacks/st-LSqektntTNJrAhCt/stack-deployments/complex", + "stack-deployment-runs": "/api/v2/stacks/st-LSqektntTNJrAhCt/stack-deployment-runs", + "stack-states": "/api/v2/stacks/st-LSqektntTNJrAhCt/stack-states" + }, + "relationships": { + "stack": { + "data": { + "id": "st-LSqektntTNJrAhCt", + "type": "stacks" + } + } + } + } +} +``` + +## List stack deployment groups + +This endpoint lists all the deployment groups for the specified stack configuration. + +`GET /stack-configurations/:stack_configuration_id/stack-deployment-groups` + +| Parameter | Description | +|---------------------------|------------------------------------------------------------------| +| `:stack_configuration_id` | The id of the stack configuration to list deployment groups for. | + +### Query Parameters + +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. + +| Parameter | Description | +|----------------|-----------------------------------------------------------------------------------------| +| `page[number]` | **Optional.** If omitted, the endpoint will return the first page. | +| `page[size]` | **Optional.** If omitted, the endpoint will return 20 stack deployment groups per page. | + +### Sample Request + +```shell +$ curl\ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + https://app.terraform.io/api/v2/stack-configurations/stc-EJyw2MktbRjdsg96/stack-deployment-groups +``` + +### Sample Response + +```json +{ + "data": [ + { + "id": "sdg-LSqektntTNJrAhCt", + "type": "stack-deployment-groups", + "attributes": { + "name": "canary", + "status": "pending", + "completion-details": { + "description": "" + }, + "config": { + "failure-tolerance-count": 0, + "eager-plan": "on", + "auto-approve-checks": [ + "deployment_auto_approve.no_deletes" + ] + }, + "runtime-state": { + "current-failure-count": 0, + "total-failure-count": 0 + }, + "created-at": "2025-05-19T00:21:17.882Z", + "updated-at": "2025-05-19T00:21:17.882Z" + }, + "links": { + "self": "/api/v2/stack-configurations/stc-EJyw2MktbRjdsg96/stack-deployment-groups", + "stack-deployment-runs": "/api/v2/stack-deployment-groups/sdg-LSqektntTNJrAhCt/stack-deployment-runs", + "stack-deployment-group-summaries": "/api/v2/stack-configurations/stc-EJyw2MktbRjdsg96/stack-deployment-group-summaries" + }, + "relationships": { + "stack-configuration": { + "data": { + "id": "stc-EJyw2MktbRjdsg96", + "type": "stack-configurations" + } + }, + "state-locked-by": { + "data": [ + { + "id": "sdg-LSqektntTNJrAhCt", + "type": "stack-deployment-groups" + } + ] + }, + "active-stack-approval": { + "data": [ + { + "id": "sa-LMqektntTNJrAhCt", + "type": "stack-approvals" + } + ] + } + } + } + ], + "links": { + "self": "https://app.terraform.io/api/v2/stack-configurations/stc-EJyw2MktbRjdsg96/stack-deployment-groups?page%5Bnumber%5D=1&page%5Bsize%5D=20", + "first": "https://app.terraform.io/api/v2/stack-configurations/stc-EJyw2MktbRjdsg96/stack-deployment-groups?page%5Bnumber%5D=1&page%5Bsize%5D=20", + "prev": null, + "next": null, + "last": "https://app.terraform.io/api/v2/stack-configurations/stc-EJyw2MktbRjdsg96/stack-deployment-groups?page%5Bnumber%5D=1&page%5Bsize%5D=20" + }, + "meta": { + "pagination": { + "current-page": 1, + "page-size": 20, + "prev-page": null, + "next-page": null, + "total-pages": 1, + "total-count": 1 + } + } +} +``` + +## Show a stack deployment group by name + +This endpoint gets details about a stack deployment group by name + +`GET /stack-configurations/:stack_configuration_id/stack-deployment-groups/:stack_deployment_group_name` + +| Parameter | Description | +|--------------------------------|-----------------------------------------------------------------------| +| `:stack_configuration_id` | The id of the stack configuration to fetch the deployment groups for. | +| `:stack_deployment_group_name` | The name of the stack deployment group. | + +### Sample Request + +```shell +$ curl\ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + https://app.terraform.io/api/v2/stack-configurations/stc-EJyw2MktbRjdsg96/stack-deployment-groups/canary +``` + +### Sample Response + +```json +{ + "data": + { + "id": "sdg-LSqektntTNJrAhCt", + "type": "stack-deployment-groups", + "attributes": { + "name": "canary", + "status": "pending", + "completion-details": { + "description": "" + }, + "config": { + "failure-tolerance-count": 0, + "eager-plan": "on", + "auto-approve-checks": [ + "deployment_auto_approve.no_deletes" + ] + }, + "runtime-state": { + "current-failure-count": 0, + "total-failure-count": 0 + }, + "created-at": "2025-05-19T00:21:17.882Z", + "updated-at": "2025-05-19T00:21:17.882Z" + }, + "links": { + "self": "/api/v2/stack-configurations/stc-EJyw2MktbRjdsg96/stack-deployment-groups", + "stack-deployment-runs": "/api/v2/stack-deployment-groups/sdg-LSqektntTNJrAhCt/stack-deployment-runs", + "stack-deployment-group-summaries": "/api/v2/stack-configurations/stc-EJyw2MktbRjdsg96/stack-deployment-group-summaries" + }, + "relationships": { + "stack-configuration": { + "data": { + "id": "stc-EJyw2MktbRjdsg96", + "type": "stack-configurations" + } + }, + "state-locked-by": { + "data": [ + { + "id": "sdg-LSqektntTNJrAhCt", + "type": "stack-deployment-groups" + } + ] + }, + "active-stack-approval": { + "data": [ + { + "id": "sa-LMqektntTNJrAhCt", + "type": "stack-approvals" + } + ] + } + } + } +} +``` + +## Show a stack deployment group by id + +This endpoint gets details about a stack deployment group by Id + +`GET /stack-deployment-groups/:stack_deployment_group_id` + +| Parameter | Description | +|------------------------------|------------------------------------------------| +| `:stack_deployment_group_id` | The id of the stack deployment group to fetch. | + +### Sample Request + +```shell +$ curl\ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + https://app.terraform.io/api/v2/stack-deployment-groups/sdg-LSqektntTNJrAhCt +``` + +### Sample Response + +```json +{ + "data": + { + "id": "sdg-LSqektntTNJrAhCt", + "type": "stack-deployment-groups", + "attributes": { + "name": "canary", + "status": "pending", + "completion-details": { + "description": "" + }, + "config": { + "failure-tolerance-count": 0, + "eager-plan": "on", + "auto-approve-checks": [ + "deployment_auto_approve.no_deletes" + ] + }, + "runtime-state": { + "current-failure-count": 0, + "total-failure-count": 0 + }, + "created-at": "2025-05-19T00:21:17.882Z", + "updated-at": "2025-05-19T00:21:17.882Z" + }, + "links": { + "self": "/api/v2/stack-configurations/stc-EJyw2MktbRjdsg96/stack-deployment-groups", + "stack-deployment-runs": "/api/v2/stack-deployment-groups/sdg-LSqektntTNJrAhCt/stack-deployment-runs", + "stack-deployment-group-summaries": "/api/v2/stack-configurations/stc-EJyw2MktbRjdsg96/stack-deployment-group-summaries" + }, + "relationships": { + "stack-configuration": { + "data": { + "id": "stc-EJyw2MktbRjdsg96", + "type": "stack-configurations" + } + }, + "state-locked-by": { + "data": [ + { + "id": "sdg-LSqektntTNJrAhCt", + "type": "stack-deployment-groups" + } + ] + }, + "active-stack-approval": { + "data": [ + { + "id": "sa-LMqektntTNJrAhCt", + "type": "stack-approvals" + } + ] + } + } + } +} +``` + +## Approve a stack deployment group + +This endpoint approves a stack deployment group. + +`POST /stack-deployment-groups/:stack_deployment_group_id/approve-all-plans` + +| Parameter | Description | +|------------------------------|-------------------------------------------| +| `:stack_deployment_group_id` | The stack deployment group id to approve. | + +| Status | Response | Reason | +|---------|---------------------------|--------------------------------------------------------------------------| +| [204][] | No Content | Successfully approved all plans recieved for Stack Deployment Group. | +| [404][] | [JSON API error object][] | Stack Deployment Group not found, or user unauthorized to perform action | + +### Sample Request + +```shell +$ curl\ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + https://app.terraform.io/api/v2/stack-deployment-groups/stg-LSqektntTNJrAhCt/approve-all-plans +``` + +## Plan a stack deployment group + +This endpoint triggers a plan for a stack deployment group that has eager plan disabled. + +`POST /stack-deployment-groups/:stack_deployment_group_id/approve-all-plans` + +| Parameter | Description | +|------------------------------|------------------------------------------------------| +| `:stack_deployment_group_id` | The stack deployment group id to trigger a plan for. | + +| Status | Response | Reason | +|---------|---------------------------|--------------------------------------------------------------------------| +| [204][] | No Content | Successfully recieved plan for Stack Deployment Group. | +| [404][] | [JSON API error object][] | Stack Deployment Group not found, or user unauthorized to perform action | + +### Sample Request + +```shell +$ curl\ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + https://app.terraform.io/api/v2/stack-deployment-groups/stg-LSqektntTNJrAhCt/plan +``` + +## Rerun a stack deployment group + +This endpoint reruns a stack deployment group that has ended up in a failed state. + +`POST /stack-deployment-groups/:stack_deployment_group_id/rerun` + +| Parameter | Description | +|------------------------------|-----------------------------------------| +| `:stack_deployment_group_id` | The stack deployment group id to rerun. | + +### Query Parameters + +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. + +| Parameter | Description | +|------------------------|------------------------------------------------------------------------------| +| `stack_deployment_ids` | **Required.** Accepts an array of Stack deployment IDs that we wish to rerun | + +| Status | Response | Reason | +|---------|---------------------------|--------------------------------------------------------------------------| +| [204][] | No Content | Successfully recieved plan for Stack Deployment Group. | +| [404][] | [JSON API error object][] | Stack Deployment Group not found, or user unauthorized to perform action | + +### Sample Request + +```shell +$ curl\ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + https://app.terraform.io/api/v2/stack-deployment-groups/stg-LSqektntTNJrAhCt/rerun +``` \ No newline at end of file From eac6667014d8f92a8e83c2739197c0c76e5bcf66 Mon Sep 17 00:00:00 2001 From: mrinalirao Date: Wed, 11 Jun 2025 12:00:56 +0530 Subject: [PATCH 3/4] docs for stack deployment runs and steps apis --- .../docs/cloud-docs/api-docs/stacks.mdx | 542 +++++++++++++++++- 1 file changed, 541 insertions(+), 1 deletion(-) diff --git a/content/terraform-docs-common/docs/cloud-docs/api-docs/stacks.mdx b/content/terraform-docs-common/docs/cloud-docs/api-docs/stacks.mdx index cfa543b0f..0137e85a8 100644 --- a/content/terraform-docs-common/docs/cloud-docs/api-docs/stacks.mdx +++ b/content/terraform-docs-common/docs/cloud-docs/api-docs/stacks.mdx @@ -69,6 +69,15 @@ The scope of the API includes the following endpoints: | `POST` | `/stack-deployment-groups/:stack_deployment_group_id/approve-all-plans` | Call this endpoint to [approve a stack deployment group](#approve-a-stack-deployment-group). | | `POST` | `/stack-deployment-groups/:stack_deployment_group_id/plan` | Call this endpoint to [plan a stack deployment group](#plan-a-stack-deployment-group). | | `POST` | `/stack-deployment-groups/:stack_deployment_group_id/rerun` | Call this endpoint to [rerun a stack deployment group](#rerun-a-stack-deployment-group). | +| `GET` | `/stack-deployment-groups/:stack_deployment_group_id/stack-deployment-runs` | Call this endpoint to [list stack deployment runs](#list-stack-deployment-runs). | +| `GET` | `/stack-deployment-runs/:stack_deployment_run_id` | Call this endpoint to [show a stack deployment run](#show-a-stack-deployment-run). | +| `POST` | `/stack-deployment-runs/:stack_deployment_run_id/approve-all-plans` | Call this endpoint to [approve a stack deployment run](#approve-a-stack-deployment-run). | +| `POST` | `/stack-deployment-runs/:stack_deployment_run_id/cancel` | Call this endpoint to [cancel a stack deployment run](#cancel-a-stack-deployment-run). | +| `GET` | `/stack-deployment-runs/:stack_deployment_run_id/stack-deployment-steps` | Call this endpoint to [list stack deployment steps](#list-stack-deployment-steps). | +| `GET` | `/stack-deployment-steps/:stack_deployment_step_id` | Call this endpoint to [show a stack deployment step](#show-a-stack-deployment-step). | +| `GET` | `/stack-deployment-steps/:stack_deployment_step_id/stack-diagnostics` | Call this endpoint to [list stack deployment step diagnostics](#list-stack-deployment-step-diagnostics). | +| `POST` | `/stack-deployment-steps/:stack_deployment_step_id/advance` | Call this endpoint to [advance a stack deployment step](#advance-a-stack-deployment-step). | +| `POST` | `/stack-deployment-steps/:stack_deployment_step_id/fail` | Call this endpoint to [fail a stack deployment step](#fail-a-stack-deployment-step). | ## Create a stack @@ -1426,4 +1435,535 @@ $ curl\ --header "Authorization: Bearer $TOKEN" \ --header "Content-Type: application/vnd.api+json" \ https://app.terraform.io/api/v2/stack-deployment-groups/stg-LSqektntTNJrAhCt/rerun -``` \ No newline at end of file +``` + +## List stack deployment runs + +This endpoint lists stack deployment runs for a stack deployment group. + +`GET /stack-deployment-groups/:stack_deployment_group_id/stack-deployment-runs` + +| Parameter | Description | +|------------------------------|----------------------------------------------------------------------------------------| +| `:stack_deployment_group_id` | The id of the stack deployment group for which stack deployment runs are being listed. | + +### Query Parameters + +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. + +| Parameter | Description | +|----------------|---------------------------------------------------------------------------------------| +| `page[number]` | **Optional.** If omitted, the endpoint will return the first page. | +| `page[size]` | **Optional.** If omitted, the endpoint will return 20 stack deployment runs per page. | + +### Sample Request + +```shell +$ curl\ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + https://app.terraform.io/api/v2/stack-deployment-groups/stg-RSqektntTNJrAhCm/stack-deployment-runs +``` + +### Sample Response + +```json +{ + "data": [ + { + "id": "sdr-LSqektntTNJrAhCt", + "type": "stack-deployment-runs", + "attributes": { + "mode": "normal", + "status": "pending", + "runtime-state": { + "current-failure-count": 0, + "total-failure-count": 0 + }, + "completion-details": { + "description": "" + }, + "created-at": "2025-06-11T15:19:42.478Z", + "updated-at": "2025-06-11T22:53:04.324Z" + }, + "links": { + "self": "/stack-deployment-groups/stg-RSqektntTNJrAhCm/stack-deployment-runs", + "stack-states": "/api/v2/stacks/st-ZqqektntTNJrAhCm/stack-states", + "stack-deployments": "/api/v2/stacks/st-ZqqektntTNJrAhCt/stack-deployments", + "stack-deployment-steps": "/stack-deployment-runs/sdr-LSqektntTNJrAhCt/stack-deployment-steps" + }, + "relationships": { + "stack-deployment-group": { + "data": { + "id": "stg-RSqektntTNJrAhCm", + "type": "stack-deployment-groups" + } + }, + "destroy-stack-configuration": { + "data": { + "id": "stc-EJyw2MktbRjdsg96", + "type": "stack-configurations" + } + }, + "latest-stack-state": { + "data": { + "id": "sts-pA6dJk7G7r7icTE8", + "type": "stack-states" + } + }, + "stack-approval": { + "data": { + "id": "sta-qB6dJk7G7r7icTE8", + "type": "stack-approvals" + } + } + } + } + ], + "links": { + "self": "https://app.terraform.io/api/v2/stack-deployment-groups/stg-RSqektntTNJrAhCm/stack-deployment-runs?page%5Bnumber%5D=1&page%5Bsize%5D=20", + "first": "https://app.terraform.io/api/v2/stack-deployment-groups/stg-RSqektntTNJrAhCm/stack-deployment-runs?page%5Bnumber%5D=1&page%5Bsize%5D=20", + "prev": null, + "next": null, + "last": "https://app.terraform.io/api/v2/stack-deployment-groups/stg-RSqektntTNJrAhCm/stack-deployment-runs?page%5Bnumber%5D=1&page%5Bsize%5D=20" + }, + "meta": { + "pagination": { + "current-page": 1, + "page-size": 20, + "prev-page": null, + "next-page": null, + "total-pages": 1, + "total-count": 1 + } + } +} +``` + +## Show a stack deployment run + +This endpoint gets details about a stack deployment run. + +`GET /stack-deployment-runs/:stack_deployment_run_id` + +| Parameter | Description | +|----------------------------|---------------------------------------------| +| `:stack_deployment_run_id` | The id of the stack deployment run to show. | + + +### Sample Request + +```shell +$ curl\ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + https://app.terraform.io/api/v2/stack-deployment-runs/sdr-LSqektntTNJrAhCt +``` + +### Sample Response + +```json +{ + "data": { + "id": "sdr-LSqektntTNJrAhCt", + "type": "stack-deployment-runs", + "attributes": { + "mode": "normal", + "status": "pending", + "runtime-state": { + "current-failure-count": 0, + "total-failure-count": 0 + }, + "completion-details": { + "description": "" + }, + "created-at": "2025-06-11T15:19:42.478Z", + "updated-at": "2025-06-11T22:53:04.324Z" + }, + "links": { + "self": "/stack-deployment-groups/stg-RSqektntTNJrAhCm/stack-deployment-runs", + "stack-states": "/api/v2/stacks/st-ZqqektntTNJrAhCm/stack-states", + "stack-deployments": "/api/v2/stacks/st-ZqqektntTNJrAhCt/stack-deployments", + "stack-deployment-steps": "/stack-deployment-runs/sdr-LSqektntTNJrAhCt/stack-deployment-steps" + }, + "relationships": { + "stack-deployment-group": { + "data": { + "id": "stg-RSqektntTNJrAhCm", + "type": "stack-deployment-groups" + } + }, + "destroy-stack-configuration": { + "data": { + "id": "stc-EJyw2MktbRjdsg96", + "type": "stack-configurations" + } + }, + "latest-stack-state": { + "data": { + "id": "sts-pA6dJk7G7r7icTE8", + "type": "stack-states" + } + }, + "stack-approval": { + "data": { + "id": "sta-qB6dJk7G7r7icTE8", + "type": "stack-approvals" + } + } + } + } +} +``` + +## Approve a stack deployment run + +This endpoint approves a stack deployment run. + +`POST /stack-deployment-runs/:stack_deployment_run_id/approve-all-plans` + +| Parameter | Description | +|----------------------------|-----------------------------------------| +| `:stack_deployment_run_id` | The stack deployment run id to approve. | + +### Query Parameters + + +| Parameter | Description | +|-------------|-----------------------------------------------------------| +| `all_plans` | **Optional.** Approve all potential future plans as well. | + + +| Status | Response | Reason | +|---------|---------------------------|------------------------------------------------------------------------| +| [204][] | No Content | Successfully approved all plans recieved for Stack Deployment Run. | +| [404][] | [JSON API error object][] | Stack Deployment Run not found, or user unauthorized to perform action | + +### Sample Request + +```shell +$ curl\ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + https://app.terraform.io/api/v2/stack-deployment-runs/sdr-LSqektntTNJrAhCt/approve-all-plans +``` + +## Cancel a stack deployment run + +This endpoint cancels a stack deployment run. + +`POST /stack-deployment-runs/:stack_deployment_run_id/approve-all-plans` + +| Parameter | Description | +|----------------------------|----------------------------------------| +| `:stack_deployment_run_id` | The stack deployment run id to cancel. | + +### Query Parameters + +| Parameter | Description | +|-----------|---------------------------------------------------------------------------| +| `force` | **Optional.** Whether or not to forcably cancel the stack deployment run. | + + +| Status | Response | Reason | +|---------|---------------------------|------------------------------------------------------------------------| +| [204][] | No Content | Successfully receieved cancel for the Stack Deployment Run. | +| [404][] | [JSON API error object][] | Stack Deployment Run not found, or user unauthorized to perform action | + +### Sample Request + +```shell +$ curl\ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + https://app.terraform.io/api/v2/stack-deployment-runs/sdr-LSqektntTNJrAhCt/cancel +``` + +## List stack deployment steps + +/*TODO: For reviewer - check if the plan-description, apply-description and structured-logs links look ok or need to be fixed */ + +This endpoint lists stack deployment steps for a stack deployment run. + +`GET /stack-deployment-runs/:stack_deployment_run_id/stack-deployment-steps` + +| Parameter | Description | +|----------------------------|---------------------------------------------------------------------------------------| +| `:stack_deployment_run_id` | The id of the stack deployment run for which stack deployment steps are being listed. | + +### Query Parameters + +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. + +| Parameter | Description | +|----------------|---------------------------------------------------------------------------------------------| +| `page[number]` | **Optional.** If omitted, the endpoint will return the first page. | +| `page[size]` | **Optional.** If omitted, the endpoint will return 20 stack deployment steps runs per page. | + +### Sample Request + +```shell +$ curl\ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + https://app.terraform.io/api/v2/stack-deployment-runs/str-RSqektntTNJrAhCm/stack-deployment-steps +``` + +### Sample Response + +```json +{ + "data": [ + { + "id": "sds-LSqektntTNJrAhCt", + "type": "stack-deployment-steps", + "attributes": { + "title": "Plan step", + "type": "plan", + "requires-state-lock": true, + "status": "blocked", + "completion-details": { + "description": "" + }, + "outputs": {}, + "auto-fail-at": "2025-06-11T05:33:36.673Z", + "created-at": "2025-06-11T15:19:42.478Z", + "updated-at": "2025-06-11T22:53:04.324Z" + }, + "links": { + "self": "/stack-deployment-runs/str-RSqektntTNJrAhCm/stack-deployment-steps", + "stack-diagnostics": "/api/v2/stacks/st-EJyw2MktbRjdsg96/stack-diagnostics", + "plan-description": "/api/v2/stacks/st-EJyw2MktbRjdsg96/plan-description", + "apply-description": "/api/v2/stacks/st-EJyw2MktbRjdsg96/apply-description", + "structured-logs": "/api/v2/stacks/st-EJyw2MktbRjdsg96/logs" + }, + "relationships": { + "stack-deployment-run": { + "data": { + "id": "sdr-RSqektntTNJrAhCm", + "type": "stack-deployment-runs" + } + }, + "stack-approval": { + "data": { + "id": "sta-qB6dJk7G7r7icTE8", + "type": "stack-approvals" + } + } + } + } + ], + "links": { + "self": "https://app.terraform.io/api/v2/stack-deployment-runs/str-RSqektntTNJrAhCm/stack-deployment-steps?page%5Bnumber%5D=1&page%5Bsize%5D=20", + "first": "https://app.terraform.io/api/v2/stack-deployment-runs/str-RSqektntTNJrAhCm/stack-deployment-steps?page%5Bnumber%5D=1&page%5Bsize%5D=20", + "prev": null, + "next": null, + "last": "https://app.terraform.io/api/v2/stack-deployment-runs/str-RSqektntTNJrAhCm/stack-deployment-steps?page%5Bnumber%5D=1&page%5Bsize%5D=20" + }, + "meta": { + "pagination": { + "current-page": 1, + "page-size": 20, + "prev-page": null, + "next-page": null, + "total-pages": 1, + "total-count": 1 + } + } +} +``` + +## Show a stack deployment step + +This endpoint gets details about a stack deployment step. + +`GET /stack-deployment-steps/:stack_deployment_step_id` + +| Parameter | Description | +|-----------------------------|----------------------------------------------| +| `:stack_deployment_step_id` | The id of the stack deployment step to show. | + +### Sample Request + +```shell +$ curl\ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + https://app.terraform.io/api/v2/stack-deployment-steps/sds-LSqektntTNJrAhCt +``` + +### Sample Response + +```json +{ + "data": { + "id": "sds-LSqektntTNJrAhCt", + "type": "stack-deployment-steps", + "attributes": { + "title": "Plan step", + "type": "plan", + "requires-state-lock": true, + "status": "blocked", + "completion-details": { + "description": "" + }, + "outputs": {}, + "auto-fail-at": "2025-06-11T05:33:36.673Z", + "created-at": "2025-06-11T15:19:42.478Z", + "updated-at": "2025-06-11T22:53:04.324Z" + }, + "links": { + "self": "/stack-deployment-runs/str-RSqektntTNJrAhCm/stack-deployment-steps", + "stack-diagnostics": "/api/v2/stacks/st-EJyw2MktbRjdsg96/stack-diagnostics", + "plan-description": "/api/v2/stacks/st-EJyw2MktbRjdsg96/plan-description", + "apply-description": "/api/v2/stacks/st-EJyw2MktbRjdsg96/apply-description", + "structured-logs": "/api/v2/stacks/st-EJyw2MktbRjdsg96/logs" + }, + "relationships": { + "stack-deployment-run": { + "data": { + "id": "sdr-RSqektntTNJrAhCm", + "type": "stack-deployment-runs" + } + }, + "stack-approval": { + "data": { + "id": "sta-qB6dJk7G7r7icTE8", + "type": "stack-approvals" + } + } + } + } +} +``` + +## List stack deployment step diagnostics + +This endpoint lists stack deployment step diagnostics for a stack deployment step. + +`GET /stack-deployment-steps/:stack_deployment_step_id/stack-diagnostics` + +| Parameter | Description | +|-----------------------------|----------------------------------------------------------------------------------------------| +| `:stack_deployment_step_id` | The id of the stack deployment step for which stack deployment diagnostics are being listed. | + +### Query Parameters + +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. + +| Parameter | Description | +|----------------|---------------------------------------------------------------------------------------------------| +| `page[number]` | **Optional.** If omitted, the endpoint will return the first page. | +| `page[size]` | **Optional.** If omitted, the endpoint will return 20 stack deployment step diagnostics per page. | + +### Sample Request + +```shell +$ curl\ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + https://app.terraform.io/api/v2/stack-deployment-steps/sds-LSqektntTNJrAhCt/stack-diagnostics +``` + +### Sample Response + +```json +{ + "data": [ + { + "id": "stf-PrqektntTNJrAhCm", + "type": "stack-diagnostics", + "attributes": { + "severity": "warning", + "summary": "Diagnostics reported", + "detail": "While preparing the configuration, HCP Terraform reported 2 warnings.", + "acknowledged": true, + "acknowledged-at": "2025-06-11T06:13:01.082Z", + "created-at": "2025-06-11T06:13:01.082Z" + }, + "links": { + "self": "/stack-deployment-steps/sds-LSqektntTNJrAhCt/stack-diagnostics" + }, + "relationships": { + "stack-configuration": { + "data": { + "id": "stc-RSqektntTNJrAhCm", + "type": "stack-configurations" + } + }, + "stack-deployment-step": { + "data": { + "id": "sds-qB6dJk7G7r7icTE8", + "type": "stack-deployment-steps" + } + } + } + } + ], + "links": { + "self": "https://app.terraform.io/api/v2/stack-deployment-steps/sds-LSqektntTNJrAhCt/stack-diagnostics?page%5Bnumber%5D=1&page%5Bsize%5D=20", + "first": "https://app.terraform.io/api/v2/stack-deployment-steps/sds-LSqektntTNJrAhCt/stack-diagnostics?page%5Bnumber%5D=1&page%5Bsize%5D=20", + "prev": null, + "next": null, + "last": "https://app.terraform.io/api/v2/stack-deployment-steps/sds-LSqektntTNJrAhCt/stack-diagnostics?page%5Bnumber%5D=1&page%5Bsize%5D=20" + }, + "meta": { + "pagination": { + "current-page": 1, + "page-size": 20, + "prev-page": null, + "next-page": null, + "total-pages": 1, + "total-count": 1 + } + } +} +``` + +## Advance a stack deployment step + +This endpoint advances a stack deployment step. + +`POST /stack-deployment-steps/:stack_deployment_step_id/advance` + +| Parameter | Description | +|-----------------------------|------------------------------------------| +| `:stack_deployment_step_id` | The stack deployment step id to advance. | + +| Status | Response | Reason | +|---------|---------------------------|-------------------------------------------------------------------------| +| [204][] | No Content | Successfully recieved advance for Stack Deployment Step. | +| [404][] | [JSON API error object][] | Stack Deployment Step not found, or user unauthorized to perform action | + +### Sample Request + +```shell +$ curl\ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + https://app.terraform.io/api/v2/stack-deployment-steps/sds-LSqektntTNJrAhCt/advance +``` + +## Fail a stack deployment step + +This endpoint fails a stack deployment step. + +`POST /stack-deployment-steps/:stack_deployment_step_id/fail` + +| Parameter | Description | +|-----------------------------|---------------------------------------| +| `:stack_deployment_step_id` | The stack deployment step id to fail. | + +| Status | Response | Reason | +|---------|---------------------------|-------------------------------------------------------------------------| +| [204][] | No Content | Successfully recieved fail for the Stack Deployment Step. | +| [404][] | [JSON API error object][] | Stack Deployment Step not found, or user unauthorized to perform action | + +### Sample Request + +```shell +$ curl\ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + https://app.terraform.io/api/v2/stack-deployment-steps/sds-LSqektntTNJrAhCt/fail +``` From 2e9753804ce7b377294bbeb86bf9d428802a5e23 Mon Sep 17 00:00:00 2001 From: mrinalirao Date: Mon, 16 Jun 2025 11:06:18 +0530 Subject: [PATCH 4/4] add stack states and approval api --- .../docs/cloud-docs/api-docs/stacks.mdx | 258 +++++++++++++++++- 1 file changed, 252 insertions(+), 6 deletions(-) diff --git a/content/terraform-docs-common/docs/cloud-docs/api-docs/stacks.mdx b/content/terraform-docs-common/docs/cloud-docs/api-docs/stacks.mdx index 0137e85a8..2cbebbdbb 100644 --- a/content/terraform-docs-common/docs/cloud-docs/api-docs/stacks.mdx +++ b/content/terraform-docs-common/docs/cloud-docs/api-docs/stacks.mdx @@ -78,6 +78,10 @@ The scope of the API includes the following endpoints: | `GET` | `/stack-deployment-steps/:stack_deployment_step_id/stack-diagnostics` | Call this endpoint to [list stack deployment step diagnostics](#list-stack-deployment-step-diagnostics). | | `POST` | `/stack-deployment-steps/:stack_deployment_step_id/advance` | Call this endpoint to [advance a stack deployment step](#advance-a-stack-deployment-step). | | `POST` | `/stack-deployment-steps/:stack_deployment_step_id/fail` | Call this endpoint to [fail a stack deployment step](#fail-a-stack-deployment-step). | +| `GET` | `/stack-approvals/:stack_approval_id` | Call this endpoint to [show a stack approval](#show-a-stack-approval). | +| `GET` | `/stacks/:stack_id/stack-states` | Call this endpoint to [list stack states](#list-stack-states). | +| `GET` | `/stack-states/:stack_state_id` | Call this endpoint to [show a stack state](#show-a-stack-state). | +| `GET` | `/stack-states/:stack_state_id/description` | Call this endpoint to [show a stack state description](#show-a-stack-state-description). | ## Create a stack @@ -1490,7 +1494,7 @@ $ curl\ "self": "/stack-deployment-groups/stg-RSqektntTNJrAhCm/stack-deployment-runs", "stack-states": "/api/v2/stacks/st-ZqqektntTNJrAhCm/stack-states", "stack-deployments": "/api/v2/stacks/st-ZqqektntTNJrAhCt/stack-deployments", - "stack-deployment-steps": "/stack-deployment-runs/sdr-LSqektntTNJrAhCt/stack-deployment-steps" + "stack-deployment-steps": "/api/v2/stack-deployment-runs/sdr-LSqektntTNJrAhCt/stack-deployment-steps" }, "relationships": { "stack-deployment-group": { @@ -1581,10 +1585,10 @@ $ curl\ "updated-at": "2025-06-11T22:53:04.324Z" }, "links": { - "self": "/stack-deployment-groups/stg-RSqektntTNJrAhCm/stack-deployment-runs", + "self": "/api/v2/stack-deployment-groups/stg-RSqektntTNJrAhCm/stack-deployment-runs", "stack-states": "/api/v2/stacks/st-ZqqektntTNJrAhCm/stack-states", "stack-deployments": "/api/v2/stacks/st-ZqqektntTNJrAhCt/stack-deployments", - "stack-deployment-steps": "/stack-deployment-runs/sdr-LSqektntTNJrAhCt/stack-deployment-steps" + "stack-deployment-steps": "/api/v2/stack-deployment-runs/sdr-LSqektntTNJrAhCt/stack-deployment-steps" }, "relationships": { "stack-deployment-group": { @@ -1731,7 +1735,7 @@ $ curl\ "updated-at": "2025-06-11T22:53:04.324Z" }, "links": { - "self": "/stack-deployment-runs/str-RSqektntTNJrAhCm/stack-deployment-steps", + "self": "/api/v2/stack-deployment-runs/str-RSqektntTNJrAhCm/stack-deployment-steps", "stack-diagnostics": "/api/v2/stacks/st-EJyw2MktbRjdsg96/stack-diagnostics", "plan-description": "/api/v2/stacks/st-EJyw2MktbRjdsg96/plan-description", "apply-description": "/api/v2/stacks/st-EJyw2MktbRjdsg96/apply-description", @@ -1813,7 +1817,7 @@ $ curl\ "updated-at": "2025-06-11T22:53:04.324Z" }, "links": { - "self": "/stack-deployment-runs/str-RSqektntTNJrAhCm/stack-deployment-steps", + "self": "/api/v2/stack-deployment-runs/str-RSqektntTNJrAhCm/stack-deployment-steps", "stack-diagnostics": "/api/v2/stacks/st-EJyw2MktbRjdsg96/stack-diagnostics", "plan-description": "/api/v2/stacks/st-EJyw2MktbRjdsg96/plan-description", "apply-description": "/api/v2/stacks/st-EJyw2MktbRjdsg96/apply-description", @@ -1882,7 +1886,7 @@ $ curl\ "created-at": "2025-06-11T06:13:01.082Z" }, "links": { - "self": "/stack-deployment-steps/sds-LSqektntTNJrAhCt/stack-diagnostics" + "self": "/api/v2/stack-deployment-steps/sds-LSqektntTNJrAhCt/stack-diagnostics" }, "relationships": { "stack-configuration": { @@ -1967,3 +1971,245 @@ $ curl\ --header "Content-Type: application/vnd.api+json" \ https://app.terraform.io/api/v2/stack-deployment-steps/sds-LSqektntTNJrAhCt/fail ``` + +## Show a stack approval + +This endpoint gets details about a stack approval. + +`GET /stack-approvals/:stack_approval_id` + +| Parameter | Description | +|----------------------|---------------------------------------| +| `:stack_approval_id` | The id of the stack approval to show. | + +### Sample Request + +```shell +$ curl\ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + https://app.terraform.io/api/v2/stack-approvals/sta-LSqektntTNJrAhCt +``` + +### Sample Response + +```json +{ + "data": { + "id": "sta-LSqektntTNJrAhCt", + "type": "stack-approvals", + "attributes": { + "reason": "Infrastructure changes", + "created-at": "2025-06-11T15:19:42.478Z", + }, + "links": { + "self": "/api/v2/stack-approvals/sta-LSqektntTNJrAhCt" + }, + "relationships": { + "stack-deployment-run": { + "data": { + "id": "sdr-RSqektntTNJrAhCm", + "type": "stack-deployment-runs" + } + }, + "stack-approval": { + "data": { + "id": "sta-qB6dJk7G7r7icTE8", + "type": "stack-approvals" + } + } + } + } +} +``` + +## List stack states + +/*TODO: For reviewer - check if the examples for address, component-address, instance-correlator and component-correlator make sense */ + +This endpoint lists states for a stack. + +`GET /stacks/:stack_id/stack-states` + +| Parameter | Description | +|-------------|------------------------------------------------------------| +| `:stack_id` | The id of the stack for which the states are being listed. | + +### Query Parameters + +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. + +| Parameter | Description | +|----------------|------------------------------------------------------------------------------| +| `page[number]` | **Optional.** If omitted, the endpoint will return the first page. | +| `page[size]` | **Optional.** If omitted, the endpoint will return 20 stack states per page. | + +### Sample Request + +```shell +$ curl\ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + https://app.terraform.io/api/v2/stacks/st-VrqRktntTNJrAhBz/stack-states +``` + +### Sample Response + +```json +{ + "data": [ + { + "id": "sts-PrqektntTNJrAhCm", + "type": "stack-states", + "attributes": { + "generation": 0, + "deployment-name": "staging", + "status": "created", + "components": [ + { + "name": "webserver", + "address": "192.168.1.1", + "component-address": "ec2-3-91-22-35.compute-1.amazonaws.com", + "instance-correlator": "instance-12345", + "component-correlator": "component-67890", + "resource-instance-count": 3 + } + ], + "is-current": true, + "resource-instance-count": 3 + }, + "links": { + "self": "/api/v2/stacks/st-VrqRktntTNJrAhBz/stack-states", + "description": "/api/v2/stacks/st-VrqRktntTNJrAhBz/description", + "stack-deployment": "/api/v2/stacks/st-VrqRktntTNJrAhBz/stack-deployments" + }, + "relationships": { + "stack": { + "data": { + "id": "st-VrqRktntTNJrAhBz", + "type": "stacks" + } + }, + "stack-deployment-run": { + "data": { + "id": "sdr-qB6dJk7G7r7icTE8", + "type": "stack-deployment-runs " + } + } + } + } + ], + "links": { + "self": "https://app.terraform.io/api/v2/stacks/st-VrqRktntTNJrAhBz/stack-states?page%5Bnumber%5D=1&page%5Bsize%5D=20", + "first": "https://app.terraform.io/api/v2/stacks/st-VrqRktntTNJrAhBz/stack-states?page%5Bnumber%5D=1&page%5Bsize%5D=20", + "prev": null, + "next": null, + "last": "https://app.terraform.io/api/v2/stacks/st-VrqRktntTNJrAhBz/stack-states?page%5Bnumber%5D=1&page%5Bsize%5D=20" + }, + "meta": { + "pagination": { + "current-page": 1, + "page-size": 20, + "prev-page": null, + "next-page": null, + "total-pages": 1, + "total-count": 1 + } + } +} +``` + +## Show a stack state + +/*TODO: For reviewer - check if the examples for address, component-address, instance-correlator and component-correlator make sense */ + +This endpoint gets details about a stack state. + +`GET /stack_states/:stack_state_id` + +| Parameter | Description | +|-------------------|-----------------------------------------------| +| `:stack_state_id` | The id of the stack state to get details for. | + +### Sample Request + +```shell +$ curl\ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + https://app.terraform.io/api/v2/stack-states/sts-PrqektntTNJrAhCm +``` + +### Sample Response + +```json +{ + "data": { + "id": "sts-PrqektntTNJrAhCm", + "type": "stack-states", + "attributes": { + "generation": 0, + "deployment-name": "staging", + "status": "created", + "components": [ + { + "name": "webserver", + "address": "192.168.1.1", + "component-address": "ec2-3-91-22-35.compute-1.amazonaws.com", + "instance-correlator": "instance-12345", + "component-correlator": "component-67890", + "resource-instance-count": 3 + } + ], + "is-current": true, + "resource-instance-count": 3 + }, + "links": { + "self": "/api/v2/stack-states/sts-PrqektntTNJrAhCm", + "description": "/api/v2/stack-states/sts-PrqektntTNJrAhCm/description", + "stack-deployment": "/api/v2/stacks/st-VrqRktntTNJrAhBz/stack-deployments" + }, + "relationships": { + "stack": { + "data": { + "id": "st-VrqRktntTNJrAhBz", + "type": "stacks" + } + }, + "stack-deployment-run": { + "data": { + "id": "sdr-qB6dJk7G7r7icTE8", + "type": "stack-deployment-runs " + } + } + } + } +} +``` + +## Show a stack state description + +This endpoint redirects to a download url for a stack state description. + +`GET /stack-states/:stack_state_id/description` + +| Parameter | Description | +|-------------------|-------------------------------------------------------------------| +| `:stack_state_id` | The id of the stack state to get the stack state description for. | + + +| Status | Response | Reason | +|---------|---------------------------|--------------------------------------------------------------------| +| [204][] | No Content | Responds with empty success when state has not yet been uploaded. | +| [302][] | [JSON API error object][] | Redirect client to temporary stack state description download URL. | +| [404][] | [JSON API error object][] | Stack state not found, or user unauthorized to perform action. | + + +### Sample Request + +```shell +$ curl\ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + https://app.terraform.io/api/v2/stack-states/sts-LSqektntTNJrAhCt/description +``` \ No newline at end of file