Stack Update
StackUpdateService handles CloudFormation ChangeSet creation, review, and execution for root stack updates. All operations are human-gated and audited.
Base path: /stack-update
POST /stack-update/GetUpdateOptions
Section titled “POST /stack-update/GetUpdateOptions”GetUpdateOptions returns the current stack template version and available upgrade paths within the current distTag, plus any active (pending) changeset.
Request (GetUpdateOptionsRequest)
No fields.
Response (GetUpdateOptionsResponse)
| Field | Type | Description |
|---|---|---|
current_version | string | Current template version deployed in the stack. |
current_dist_tag | string | Current distTag (e.g., “stable”, “edge”). |
next_minor | UpdateOption? | Next available minor version bump within the current major version and distTag. Absent if already on the latest minor. |
next_major | UpdateOption? | Next available major version bump within the current distTag. Absence means no newer major version exists. Presence always implies breaking change. |
active_change_set | ActiveChangeSet? | Active (pending, not yet executed) changeset if one exists and is still valid. Absent if no changeset is currently pending. |
stack_name | string | Root stack name (from the stack ARN). Always present. Generic identity field — the client derives console links from stack_name + region. |
region | string | AWS region the root stack lives in (from the stack ARN). Always present. |
POST /stack-update/CreateChangeSet
Section titled “POST /stack-update/CreateChangeSet”CreateChangeSet initiates a new changeset for the selected target version, superseding any prior pending changeset. Non-idempotent.
Request (CreateChangeSetRequest)
| Field | Type | Description |
|---|---|---|
target_template_version | string? | Target template version. If omitted, defaults to next_minor from GetUpdateOptions. To target next_major, explicitly pass next_major.version. Must match semver pattern if provided. |
Response (CreateChangeSetResponse)
| Field | Type | Description |
|---|---|---|
change_set_id | string | CloudFormation ChangeSet ID. |
change_set_arn | string | CloudFormation ChangeSet ARN. |
POST /stack-update/DescribeChangeSet
Section titled “POST /stack-update/DescribeChangeSet”DescribeChangeSet retrieves the changeset status and resource-level detail. Serves both as a creation-status poll endpoint and a detail-fetch endpoint.
Request (DescribeChangeSetRequest)
| Field | Type | Description |
|---|---|---|
change_set_id | string | CloudFormation ChangeSet ID (from CreateChangeSetResponse or active_change_set). |
Response (DescribeChangeSetResponse)
| Field | Type | Description |
|---|---|---|
status | ChangeSetStatus | Changeset creation status (or execution status if already executed). |
status_reason | string | CFN StatusReason on CREATE_FAILED or EXECUTE_FAILED; sanitized for client display. |
console_url | string | Fully-formed AWS Console URL for this changeset. |
previous_template | string | Raw CloudFormation template body (JSON) before this changeset’s changes. Also used by the frontend to parse aws:cdk:path for the CDK-metadata tree view. |
proposed_template | string | Raw CloudFormation template body (JSON) after this changeset’s changes. |
resource_changes | ResourceChange[] | Resource-level changes from this changeset. Pre-sorted with IAM-related resources first, everything else in template order. |
POST /stack-update/ExecuteChangeSet
Section titled “POST /stack-update/ExecuteChangeSet”ExecuteChangeSet applies the changeset to the root stack after passing all gates (lock, typed confirmation, IAM re-verification, executability check).
Request (ExecuteChangeSetRequest)
| Field | Type | Description |
|---|---|---|
change_set_id | string | CloudFormation ChangeSet ID (from CreateChangeSetResponse). |
iam_review_ack | bool | Hard confirmation that the admin has reviewed any IAM changes. Required if any resource_changes[].is_iam_related is true; can be false only if no IAM changes exist. |
Response (ExecuteChangeSetResponse)
No fields.
POST /stack-update/GetChangeSetExecutionStatus
Section titled “POST /stack-update/GetChangeSetExecutionStatus”GetChangeSetExecutionStatus polls the stack update status after ExecuteChangeSet.
Request (GetChangeSetExecutionStatusRequest)
| Field | Type | Description |
|---|---|---|
change_set_id | string | CloudFormation ChangeSet ID. |
Response (GetChangeSetExecutionStatusResponse)
| Field | Type | Description |
|---|---|---|
status | StackStatus | Current stack update status. |
last_event_at | string | RFC3339 timestamp of the most recent event (from CFN StackEvents). |
last_event_message | string | Event summary (e.g., “Stack UPDATE_COMPLETE_CLEANUP_IN_PROGRESS”). |
POST /stack-update/ListUpdateHistory
Section titled “POST /stack-update/ListUpdateHistory”ListUpdateHistory returns paginated audit trail of past update executions.
Request (ListUpdateHistoryRequest)
| Field | Type | Description |
|---|---|---|
page_size | int32? | Maximum results per page (default 50, max 100). |
page_token | string? | Pagination token from previous response. |
Response (ListUpdateHistoryResponse)
| Field | Type | Description |
|---|---|---|
entries | UpdateHistoryEntry[] | |
next_page_token | string | Token for next page; empty if no more results. |