AWS::SSM::Document Schema differs from deployed / documented Schema, and has room for improvements

[benbridts]

I was taking a look at https://github.com/aws-cloudformation/aws-cloudformation-resource-providers-ssm/blob/master/aws-ssm-document/aws-ssm-document.json to see if I could propose some changes to fix aws-cloudformation/cloudformation-coverage-roadmap#339 (to summarize that issue: It's currently a problem that you can't update the Content of a Document if you have given it a name).

I noticed a few things:

• The current schema is not what's available in CloudFormation https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-ssm-document.html
• The way that VersionName is implemented does not fit with how we as customers would use this resource.

Can we take some time to review the schema in the open, before this gets deployed and almost impossible to remove things from the schema?

---

To speak to the actual problem:

• in the current schema (both deployed and in this repository) Name and Content are createOnly properties
• in the current schema in this repository "VersionName" is an optional, createOnly property
• In general, it's considered a good practice to avoid naming things in CloudFormation. However, SSM documents have some behaviors where the name actually matters. In the linked issue, it's because they will be used by humans, and their names documented in an external system. An example that does not have a workaround is configuring the default Session Manager settings. So we can assume that a lot of customers will want support to update documents "in place"
• It's annoyingly hard to generate random names yourself in a CloudFormation template, so "update this unrelated value" should be avoided if it all possible
• Having separately managed versions, and having auto-updating versions are both behaviors that are currently present in CloudFormation. I can't think of any that has Versions as part of the main resource (maybe API-Gateway somewhere, but that implementation gets a fair bit of comments too).
• Having a replacement (technically a new resource) that is actually a new version of the same document (same Name, different VersionName), is very confusing, Additionally, since the VersionName is not part of the primary identifier this is not allowed by the contract anyway*

Putting that all together: It seems to me that customers would be better served if the resource provider would behave more like the console and create a new version + update the default version when the Content of the document changes (IAM Policies work the same way). Both the current behavior and the behavior in the repo leave some gap between implementation and customer expectations.

• The current one needs two deployments to change the content, but keep the name (1: remove the document, 2: create a new document with the same name)
• The repo behavior (even if it would allow updates without replacements) would require the customer to supply a unique value every time they change something, while their intent to change the document is already expressed by changing the other properties

---

* It's not explicitly disallowed, but from the other requirements it's implied that a primaryIdentifier uniquely identifies a resource, if you create two versions with the same Name the deleteHandler and readHandler will be confused