AWS::SSM::Document - Name - No replacement Update

[jk2l]

Extended feature request of the new feature released 11hr ago: https://github.com/aws-cloudformation/aws-cloudformation-coverage-roadmap/issues/115

Current behaviour:

• When SSM Document updated, it will trigger a replacement
• If we use hardcode Name, stack update will fail with the message "GoldenAMIAutomationDoc AWS::SSM::Document UPDATE_FAILED CloudFormation cannot update a stack when a custom-named resource requires replacing. Rename GoldenAmiBuidler and update the stack again."

Expected behaviour:

• Originally described in the ticket: a new version created and on the success, it should update the current version to Default.
• For reference can also look into how AWS::SSM::Parameter or AWS::ECS::TaskDefinition is done, it will update and create a new version instead of replacing the document completely.

Currently, I have to create/manage a custom resource just to do this behaviour but maintaining the Custom resource is quite time-consuming for me and I wish I can replace my custom resource to be using native AWS resources only.

The key part of this request is we can have versioning of the AWS SSM Document that we can also reference back into.

As a use case, I have to follow a very strict security audit process (the operation team do not have security clearance to touch production environment. Everything is 100% manage by CloudFormation. or it will need to escalate to system admin that have access which can also costly to do) and the SSM Doc native implementation by CloudFormation is very badly design because it lost the versioning reference which fails auditing process.

Currently, I am using SSM for the following:

• AMI Builder
• System patches
• AWS Inspector
• Some installation and automation

Refrences: https://docs.aws.amazon.com/cli/latest/reference/ssm/update-document.html https://docs.aws.amazon.com/cli/latest/reference/ssm/update-document-default-version.html

[udondan]

The current implementation of AWS::SSM::Documentis mostly useless. If the name of a resource changes when its content changes, it cannot be referenced anywhere, hence cannot be used in any automation. I've seen people in my org deleting an ssm-docs stack and deploying it again, just to keep the document names.

[benbridts]

To add to this aws ssm update-document (in contrast with what the name would indicate), always creates a new version for that document (even when specifying --document-version).

If the SSM team does not plan to support deleting old versions, CloudFromation could mimic this behaviour (and in addition set the default version).

Another approach would to implement something similar as discussed in https://github.com/aws-cloudformation/aws-cloudformation-resource-providers-cloudformation/pull/4 for ResourceProviders.

[udondan]

I don't think deleting document versions is supported by the API. You only can delete the whole document.

Also overriding a version is not possible. As you said, when updating a document, it creates a new version.

[benbridts]

Like you said. It doesn't support delete or update right now. If the SSM team has plans to add delete functionality in the future (like IAM manage policies), it might be an idea to reflect that in the CloudFormation resources too

[jk2l]

delete or not doesn't really matter tbh. look at ECS task definition, you can't delete a version after create. but it works fine with cloudformation fine with the hardcoded name.

using a hardcoded name is quite important for working with multiple environment and team. the name itself shouldn't get change at all so it won't break other team's using my SSM document

the main key thing is to allow hardcoding name that can be referred from anywhere. this is more important if I want to build an SSM document manage that needs to be used by other SSM document.

e.g. I can manage an EBS snapshot SSM with automation tagging. then this document is used by other teams to manage their own EBS snapshot with schedule. if the SSM name keep changing just a simple update, it will break every single script out there when they try to refrence the document name.

I end up spent a week wrote a custom resources name to handle updating version instead of replacement document which should be something support out of the box by Cfn implementation

[udondan]

I just published my custom resource to manage SSM documents. It's made for CDK but I added documentation how to use it in plain old CloudFormation as well - https://github.com/udondan/cdk-ssm-document

[bgardner-noggin]

Agreed. I'm going through this now with AWS::Config::RemediationConfiguration which uses hard coded names

The SSM documentation is lacking and so its a trial and error approach to get them working. A bug in my SSM document requires manual intervention to delete the document and recreate it

[jackdcasey]

In case anyone is also wrestling with this, my organization was planning to use the Document names in IAM to define access. We were able to get a functional workaround using custom tagging, and allowing Cloudformation to generate and apply the name.

For example, we have Documents that define some custom attributes for session access. Here's the IAM defining that:

{
 "Action": [
   "ssm:StartSession"
 ],
 "Resource": [
   "arn:aws:ssm:*:*:document/*"
 ],
 "Condition": {
   "StringEquals": {"ssm:resourceTag/CustomTag": "CustomValue"}
 },
 "Effect": "Allow"
},

Slightly less elegant, but seems to work well for us. Hope this may come in handy for anyone in the same spot!

[kyle-kluever]

It looks like this PR may resolve this issue - https://github.com/aws-cloudformation/aws-cloudformation-resource-providers-ssm/pull/173

The documentation for AWS::SSM::Document has been updated to reflect the UpdateMethod property - https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-ssm-document.html#cfn-ssm-document-updatemethod

[damonmaria]

I can confirm that using updateMethod: 'NewVersion' worked for me with the SSM-SessionManagerRunShell document that used to fail with posted error.

[udondan]

Yep, looking very nice. I just migrated 97 of our documents to the updated AWS::SSM::Document and tested document updates. Looking good. 👍🏼 I'm going to deprecate my custom CDK construct now.

[kyle-kluever]

Yep, looking very nice. I just migrated 97 of our documents to the updated AWS::SSM::Document and tested document updates. Looking good. 👍🏼 I'm going to deprecate my custom CDK construct now.

I just finished converting documents to AWS::SSM::Document this morning and retired the custom resource I wrote for this. 👍

[tdmalone]

Nice! I guess this ticket should be closed and go to Shipped?

[TheDanBlanco]

this appears to be resolved! if it's not the case, please re-open this with more details

[createchange]

Woo - this was such a bane for me a couple of years ago - great to see that it was resolved. Just worked wonderfully for me. Thanks to the team for implementing it.