Merge pull request #191 from hashicorp/feature/StackDeploymentRun

Feature full Stack deployment lifecycle resources (groups → runs → steps → states → diagnostics)

Author: isivaselvan

CHANGELOG.md

@@ -1,11 +1,20 @@
 # Unreleased
 
+# Released
+# v1.3.0
+
 ## Enhancements
 
 ### New resources
 * Added `client.stack_deployments` — list the deployments that belong to a stack. `list(stack_id, options=None)` (`GET /stacks/{stack_id}/stack-deployments`) returns an `Iterator[StackDeployment]`, with optional pagination (`page_size`) and `?include=` (`latest_deployment_run`, `latest_deployment_run.stack_configuration`) via `StackDeploymentListOptions`. The `stack` relationship is hydrated as a typed field; the `latest-deployment-run` relation is reachable via the lossless raw accessors (`deployment.related("latest-deployment-run")`). New models: `StackDeployment`, `StackDeploymentListOptions`, `StackDeploymentIncludeOpt`.
+* Added `client.stack_deployment_groups` — list, read, approve, and rerun deployment groups within a stack configuration. `list(stack_configuration_id)` (`GET /stack-configurations/{id}/stack-deployment-groups`), `read(group_id)` (`GET /stack-deployment-groups/{id}`), `read_by_name(stack_configuration_id, name)`, `approve_all_plans(group_id)` (`POST .../approve-all-plans`), `rerun(group_id, options)` (`POST .../rerun?deployments=...`). New models: `StackDeploymentGroup`, `DeploymentGroupStatus`, `StackDeploymentGroupListOptions`, `StackDeploymentGroupRerunOptions`.
+* Added `client.stack_deployment_runs` — list, read, approve, and cancel individual deployment runs within a deployment group. `list(group_id)` (`GET /stack-deployment-groups/{id}/stack-deployment-runs`), `read(run_id)` (`GET /stack-deployment-runs/{id}`), `approve_all_plans(run_id)` (`POST .../approve-all-plans`), `cancel(run_id)` (`POST .../cancel`). New models: `StackDeploymentRun`, `DeploymentRunStatus`, `StackDeploymentRunListOptions`, `StackDeploymentRunReadOptions`, `StackDeploymentRunIncludeOpt`.
+* Added `client.stack_deployment_steps` — list, read, advance, list diagnostics, and download artifacts for individual deployment steps within a deployment run. `list(run_id)` (`GET /stack-deployment-runs/{id}/stack-deployment-steps`), `read(step_id)` (`GET /stack-deployment-steps/{id}`), `advance(step_id)` (`POST .../advance`), `list_diagnostics(step_id)` (`GET .../stack-diagnostics`), `download_artifact(step_id, artifact_type)` (`GET .../artifacts?name=<type>`) returns raw `bytes`. New models: `StackDeploymentStep`, `DeploymentStepStatus`, `StackDeploymentStepArtifactType`, `StackDeploymentStepIncludeOpt`, `StackDeploymentStepListOptions`, `StackDeploymentStepReadOptions`, `StackDiagnostic`, `StackDiagnosticListOptions`.
+* Added `client.stack_states` — list, read, and download descriptions for stack states. `list(stack_id)` (`GET /stacks/{id}/stack-states`), `read(state_id)` (`GET /stack-states/{id}`), `download_description(state_id)` (`GET /stack-states/{id}/description`) returns raw `bytes`. New models: `StackState`, `StackStateListOptions`. New error: `InvalidStackStateIDError`.
+* Added `client.stack_configuration_summaries` — list lightweight stack configuration summaries for a stack. `list(stack_id)` (`GET /stacks/{id}/stack-configuration-summaries`). New models: `StackConfigurationSummary`, `StackConfigurationSummaryListOptions`.
+* Added `client.stack_deployment_group_summaries` — list rolled-up deployment group summaries for a stack configuration. `list(stack_configuration_id)` (`GET /stack-configurations/{id}/stack-deployment-group-summaries`). New models: `StackDeploymentGroupSummary`, `StackDeploymentGroupSummaryListOptions`, `StackDeploymentGroupStatusCounts`.
+* Added `client.stack_diagnostics` — read and acknowledge stack diagnostics. `read(diagnostic_id)` (`GET /stack-diagnostics/{id}`), `acknowledge(diagnostic_id)` (`POST /stack-diagnostics/{id}/acknowledge`). New error: `InvalidStackDiagnosticIDError`.
 
-# Released
 # v1.2.0
 
 ## Enhancements
@@ -81,7 +90,6 @@ drive the SDK without hardcoding resource names or browsing the GitHub repo.
 * Fixed `organizations.read_entitlements` silently dropping most entitlement flags. The parser surfaced only 15 of the ~47 flags the API returns, so flags such as `hyok`, `assessments`, `stacks`, `terraform-actions`, and `change-requests` were discarded. `Entitlements` now exposes those as typed fields and retains every remaining flag (including the integer `*-limit` flags) under `model_extra` via `extra="allow"`. The change is additive — existing typed fields are unchanged.
 
 
-# Released
 # v1.1.0
 
 ## Features

docs/api/index.md

@@ -107,11 +107,29 @@ column.
 | `client.organization_tags` | `OrganizationTags` | `list`, `delete`, `add_workspaces` | [organization_tags.py](../../examples/organization_tags.py) | [Organization tags](https://developer.hashicorp.com/terraform/cloud-docs/api-docs/organization-tags) |
 | `client.comments` | `Comments` | `list`, `read`, `create` | [comment.py](../../examples/comment.py) | [Comments](https://developer.hashicorp.com/terraform/cloud-docs/api-docs/comments) |
 | `client.explorer` | `Explorer` | query and saved-view helpers | [explorer.py](../../examples/explorer.py) | [Explorer](https://developer.hashicorp.com/terraform/cloud-docs/api-docs/explorer) |
-| `client.stacks` | `Stacks` | `list`, `read`, `create`, `update`, `delete`, `force_delete`, VCS fetch | [stack.py](../../examples/stack.py) | [Stacks](https://developer.hashicorp.com/terraform/cloud-docs/api-docs/stacks) |
-| `client.stack_configurations` | `StackConfigurations` | `list`, `read`, `create` | [stack_configuration.py](../../examples/stack_configuration.py) | [Stacks](https://developer.hashicorp.com/terraform/cloud-docs/api-docs/stacks) |
 | `client.github_app_installations` | `GitHubAppInstallations` | `list`, `read` | [github_app_installations.py](../../examples/github_app_installations.py) | [GitHub App installations](https://developer.hashicorp.com/terraform/enterprise/api-docs/github-app-installations) |
 | `client.organization_token_ttl_policies` | `OrganizationTokenTTLPolicies` | `list`, `update`, `reset_to_defaults` | [org_token_ttl.py](../../examples/org_token_ttl.py) | [Org token TTL settings](https://developer.hashicorp.com/terraform/cloud-docs/users-teams-organizations/organizations/settings#api-tokens) |
 
+## Stacks
+
+HCP Terraform Stacks coordinate multi-component, multi-environment Terraform
+deployments. See [stacks.md](stacks.md) for full method details and
+[stack-deployment.md](../scenarios/stack-deployment.md) for an end-to-end
+scenario.
+
+| Client attribute | Resource class | Common methods | Example | Upstream API docs |
+|---|---|---|---|---|
+| `client.stacks` | `Stacks` | `list`, `read`, `create`, `update`, `delete`, `force_delete` | [stack.py](../../examples/stack.py) | [Stacks](https://developer.hashicorp.com/terraform/cloud-docs/api-docs/stacks/stacks) |
+| `client.stack_configurations` | `StackConfigurations` | `list`, `read`, `create` | [stack_configuration.py](../../examples/stack_configuration.py) | [Stack configurations](https://developer.hashicorp.com/terraform/cloud-docs/api-docs/stacks/stack-configurations) |
+| `client.stack_configuration_summaries` | `StackConfigurationSummaries` | `list` | [stack_configuration_summary.py](../../examples/stack_configuration_summary.py) | [Stack configurations](https://developer.hashicorp.com/terraform/cloud-docs/api-docs/stacks/stack-configurations) |
+| `client.stack_deployments` | `StackDeployments` | `list` | [stack_deployment.py](../../examples/stack_deployment.py) | [Stack deployments](https://developer.hashicorp.com/terraform/cloud-docs/api-docs/stacks/stack-deployments) |
+| `client.stack_deployment_groups` | `StackDeploymentGroups` | `list`, `read`, `read_by_name`, `approve_all_plans`, `rerun` | [stack_deployment_group.py](../../examples/stack_deployment_group.py) | [Stack deployment groups](https://developer.hashicorp.com/terraform/cloud-docs/api-docs/stacks/stack-deployment-groups) |
+| `client.stack_deployment_group_summaries` | `StackDeploymentGroupSummaries` | `list` | [stack_deployment_group_summary.py](../../examples/stack_deployment_group_summary.py) | [Stack deployment groups](https://developer.hashicorp.com/terraform/cloud-docs/api-docs/stacks/stack-deployment-groups) |
+| `client.stack_deployment_runs` | `StackDeploymentRuns` | `list`, `read`, `approve_all_plans`, `cancel` | [stack_deployment_run.py](../../examples/stack_deployment_run.py) | [Stack deployment runs](https://developer.hashicorp.com/terraform/cloud-docs/api-docs/stacks/stack-deployment-runs) |
+| `client.stack_deployment_steps` | `StackDeploymentSteps` | `list`, `read`, `advance`, `list_diagnostics`, `download_artifact` | [stack_deployment_step.py](../../examples/stack_deployment_step.py) | [Stack deployment steps](https://developer.hashicorp.com/terraform/cloud-docs/api-docs/stacks/stack-deployment-steps) |
+| `client.stack_states` | `StackStates` | `list`, `read`, `download_description` | [stack_state.py](../../examples/stack_state.py) | [Stack states](https://developer.hashicorp.com/terraform/cloud-docs/api-docs/stacks/stack-states) |
+| `client.stack_diagnostics` | `StackDiagnostics` | `read`, `acknowledge` | [stack_diagnostic.py](../../examples/stack_diagnostic.py) | [Stack diagnostics](https://developer.hashicorp.com/terraform/cloud-docs/api-docs/stacks/stack-diagnostics) |
+
 ## TFE admin (site-admin only)
 
 These endpoints require TFE site-admin permission and return `404` on