Why AWS Cloudformation schema is defined by AWS region?

[bagajjal]

We are exploring AWS CloudControl API. Based on the AWS documentation page, AWS Cloud Control API is built on top of the AWS Cloud formation. This [link] provides a zip payload with all the AWS cloud formation schema but per region.

We looked in the AWS Cloud formation schema. There are few open questions. We would like to understand the AWS reasoning why things are implemented like the way they are right now.

We would like to understand, 1) why AWS cloudformation schema is defined per AWS region. 2) why there is no Github repository. 3) why there is no versioning?

[bagajjal]

@mircealam, can you please look into this issue.

[mircealam]

for 1) the service is run regionally and there can be variation in the underlying services capabilities (ie a service can have a feature/capability in one region but not in another, this can be steady state or it can be in the case where the resource is rolled out incrementally in all the regions - this translates directly into the capabilities the resources have)

for 2) there is no once central GH repository because schemas are per resource type (and each resource has its own repo - if you describe the type you usually can see where the source code lives). You can download all aggregated schemas from here: https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/resource-type-schemas.html, but keep in mind that ultimately it boils down to what the type is registered with (ie the aggregated schemas or the schemas you see in each of the resource type repos might lag behind)

for 3) for AWS resources types there is no explicit versioning - meaning that any mutations that happen to the schema and to the resource itself must be backwards compatible. You can create your own resource types (and leverage them through CloudFormation afterwards) and in that case there is support for versioning. See: https://docs.aws.amazon.com/cloudformation-cli/latest/userguide/resource-types.html and https://docs.aws.amazon.com/cloudformation-cli/latest/userguide/resource-type-walkthrough.html

[bagajjal]

@mircealam,

Thanks for your reply.

for AWS resources types there is no explicit versioning - meaning that any mutations that happen to the schema and to the resource itself must be backwards compatible.

Does backward compatibility ensure for a given resource type (for example - AWS::S3::AccessPoint) there is no removal of existing properties? It will always be addition of more properties than what we support today?

What is the deprecation process in a given resource type (for example - AWS::S3::AccessPoint) is no longer supported?

One more question, since the AWS CloudControl API doesn't take api-version as input, I'm assuming the AWS CloudControl API always returns the response with latest schema. i.e., AWS CloudControl API response schema has latest schema than the aggregated cloudcontrol schema defined at https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/resource-type-schemas.html?

[mircealam]

Yes. There should be backwards compatibility for AWS resource types.

Based no my experience, service deprecations are very rare. If this would ever occur there would probably be advance notice + a grace period for you to address the deprecation.

Technically, it's the AWS CloudFormation Registry that keeps track of resource types and yes, the schema that is the authoritative response to what the schema for a resource type at a given point in time is (eg https://awscli.amazonaws.com/v2/documentation/api/latest/reference/cloudformation/describe-type.html).

CloudControl API is the way you can invoke the resource CRUDL handlers directly without going through CloudFormation. You can get more context of how all the pieces fit together here: https://aws.amazon.com/blogs/devops/cloudformation-coverage/