Rewrite the build command to use registry schemas instead of spec files

aws-cloudformation / rain

A development workflow tool for working with AWS CloudFormation.

Apache License 2.0

771 stars 69 forks source link

Rewrite the build command to use registry schemas instead of spec files #262

Closed ericzbeard closed 7 months ago

ericzbeard commented 7 months ago

This is a breaking change to the way the build command works. Instead of using a locally stored copy of the spec file, we now download the current schema from the registry in your account/region. In some ways this will be more accurate, since the registry schemas are more expressive and represent the source of truth going forward. But registry coverage is not yet 100%, so some resources will not build correctly. I added a patching mechanism so that we can improve the output when the schemas are lacking.

SAM templates used to be generated based on parsing documentation files, which are no longer maintained, so we switched to parsing a simplified SAM schema from the goformation project and converting it into the registry schema format.

ericzbeard commented 7 months ago

@hariprakash-j, @khmoryz, @null93, @iainelder Please let me know what you think of this when you have time. I'm honestly not even sure how many people use the build command. This will require a major version bump to be safe. I'd like to expand this command in the future so that it will output hand-crafted templates that follow best practices and pass compliance checks by default, maybe with a --recommended flag.

khmoryz commented 7 months ago

Hi @ericzbeard

I think your improvement is great. Template correctness is more important than coverage.

I use rain build as usual. However, I don't remember all of the aws resource types, so I often do a fuzzy search on google.com and copy the templates from docs.aws.amazon.com.

I think major version upgrade is not a problem, because I don't think rain build is used in automation.

As for the --recommended flag, it is great. But, I have concerns about continuing maintenance.

null93 commented 7 months ago

I cannot speak too much on this because I don't use the build command. I just refer to the docs. I can see it being more useful to me if it had more detailed information like the docs do.

If this PR makes the output more accurate, I think that is great!

iainelder commented 6 months ago

Just catching up now after an extended break from GitHub.

I don't use the rain build command. Like @null93 , I read the docs and type the templates by hand in VS Code.

Can I use the feature to write correct templates more quickly?

ericzbeard commented 6 months ago

Can I use the feature to write correct templates more quickly?

Yes, and I just added a new feature to the build command to emit fully functional, tested templates for certain use cases. It's not released yet so you would need to install from @main. So there are now 3 modes for build:

Default mode with a resource type like AWS::S3::Bucket, which spits out all properties with placeholders like STRING for values.
LLM Prompt mode, for example, rain build -p 'A vpc with 2 subnets'
Recommendations, fully tested templates. rain build -r

iainelder commented 6 months ago

Sounds awesome!

For a VS Code user, what does the workflow look like?

I'm thinking:

Run rain build ResourceType in a terminal and copy the output
Paste the output into my template editor tab
Edit the output to change the placeholders and delete optional properties where the default is fine.

A way to use the template generation from inside VS Code would be awesome too. Maybe out of scope for this repo, but another repo with an extension for VS Code could handle it.