aws-cloudformation / aws-cloudformation/cloudformation-coverage-roadmap

[AWS::SSM::Document] UpdateMethod: NewVersion reports UPDATE_COMPLETE but never promotes the new version to Default

Open
#2,539 0 comments 0 reactions 0 assignees View on GitHub
Dominant language
No language data
Stars
1.1k
Forks
62
PR merge metrics
No merged PRs in 30d

Description

### Resource
AWS::SSM::Document

### Issue Description
When `UpdateMethod` is set to `NewVersion` and an existing document's `Content` is updated, CloudFormation creates a new document version but does not promote it to the document's default version (the equivalent of calling `ssm:UpdateDocumentDefaultVersion`). CloudFormation still reports `UPDATE_COMPLETE`, with the correct new `Content` recorded in the stack event's `ResourceProperties`, so there is no indication anything went wrong. Any consumer that reads the document via its **default** version (for example the Session Manager "Preferences" console page, which reads the well-known `SSM-SessionManagerRunShell` document) keeps seeing the old content indefinitely.

Per the [documented behavior](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-ssm-document.html#cfn-ssm-document-updatemethod):

> When you specify NewVersion, the default version of the document is changed to the newly created version.

This did not happen across three consecutive stack updates in our account, all reporting success.

### Expected Behavior
After a stack update with `UpdateMethod: NewVersion` reaches `UPDATE_COMPLETE`, `DefaultVersion` (from `aws ssm describe-document`) should equal `LatestVersion`, and the new `Content` should be live and visible to any consumer reading the default version.

### Observed Behavior
`LatestVersion` increments correctly on each deploy, but `DefaultVersion` stays stuck at its old value — with no error, warning, or drift signal anywhere in CloudFormation. This is likely compounded by #1957 (`AWS::SSM::Document` does not support drift detection despite the documentation saying it does), since that means CloudFormation has no mechanism to ever notice or surface that the promotion step didn't happen.

### Reproduction

1. Deploy a `Session`-type document with `UpdateMethod: NewVersion` (we have not confirmed whether this reproduces for other `DocumentType` values):

```yaml
Resources:
Document:
Type: AWS::SSM::Document
Properties:
Name: SSM-SessionManagerRunShell
DocumentType: Session
UpdateMethod: NewVersion
Content:
schemaVersion: "1.0"
description: Document to hold regional settings for Session Manager
sessionType: Standard_Stream
inputs:
idleSessionTimeout: "20"
cloudWatchEncryptionEnabled: true
cloudWatchStreamingEnabled: true
s3EncryptionEnabled: true
runAsEnabled: false
```

2. Confirm `aws ssm describe-document --name SSM-SessionManagerRunShell` shows `DocumentVersion`, `DefaultVersion`, and `LatestVersion` all `"1"`.
3. Change `idleSessionTimeout` to `"60"` and redeploy the stack.
4. `aws cloudformation describe-stack-events` shows the `AWS::SSM::Document` resource reaching `UPDATE_COMPLETE`, with `ResourceProperties.Content.inputs.idleSessionTimeout` correctly `"60"` in the event.
5. `aws ssm describe-document --name SSM-SessionManagerRunShell` still shows `DefaultVersion: "1"`, `LatestVersion: "2"` — a new version was created but never promoted, and the live idle timeout is unchanged.
6. Manually running `aws ssm update-document-default-version --name SSM-SessionManagerRunShell --document-version 2` immediately fixes it — the setting takes effect and is visible in the Session Manager Preferences console right away. This confirms the underlying SSM API works correctly and the gap is specifically in what the CloudFormation resource handler does (or fails to do) on update.

### Workaround
After every content-changing deploy of a document using `UpdateMethod: NewVersion`, we now have to manually check whether `LatestVersion == DefaultVersion` and call `update-document-default-version` if not, since CloudFormation gives no indication the promotion step was skipped.

### Other Details
Possibly related to #1957 — the same underlying visibility gap (no drift detection for this resource type) likely prevents CloudFormation from ever detecting or reporting this failure mode after the fact.

Contributor guide

Open the contributing guide

Research direction

Start by reproducing the AWS::SSM::Document update from the YAML example, then run aws cloudformation describe-stack-events and aws ssm describe-document to compare LatestVersion with DefaultVersion. The issue is resolved when an update using UpdateMethod: NewVersion leaves DefaultVersion equal to LatestVersion and the changed content is visible to consumers of the default version.

Written by the indexing model from the issue text.

Assessment

Tech stack
aws
Domain
cloud, infrastructure
Issue type
Bug
Difficulty
4/5
Estimated time
3-5 days
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
48/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.