Many of us use AWS Systems Manager (SSM) documents to help automate various tasks. As we author documents and move them toward deployment, we’ll likely enforce certain standards and best practices. The AWS CloudFormation team released a general-purpose tool called AWS CloudFormation Guard that we can use to help enforce these best practices. In this post, we will review a simple use case that demonstrates how you can leverage AWS CloudFormation Guard (cfn-guard) when developing and deploying your SSM documents.
As an organization, you may want to enforce various rules on your SSM documents. Depending on the document type, you may want to require a description, require parameters, enforce specific runtimes, and more. This is where cfn-guard can help. Cfn-guard is a general-purpose tool developed by the CloudFormation team for expressing policy-as-code that can be enforced against structured hierarchical data, such as JSON or YAML. Furthermore, AWS has started leveraging cfn-guard themselves to enforce certain standards when publishing SSM documents. Let’s see what we can do with a use case.
Use case example
Annie is an architect responsible for SSM documents. They want to enforce some simple best practices for everyone who authors SSM documents at their company. The rules they want to enforce are outlined as follows and are organized by the SSM document type.
Automation document requirements
schemaVersionmust be 0.3
assumeRolemust be defined
mainSteps.descriptionmust be defined
- Only allow
python3.8as the runtime for
Command document requirements
schemaVersionmust be 2.2
mainSteps.inputs.timeoutSecondsmust be defined
Generic document requirements
- The document’s
descriptionmust be defined
- Parameter validation must be defined using either
- Each parameter’s
descriptionmust be defined
To do this, they define a set of cfn-guard rules and add a step in the pipeline to validate any SSM documents using the defined rules. As the pipeline executes the rules against the SSM documents, the pipeline will be halted if it finds a violation based on the rules.
To get started, Annie downloads and sets up cfn-guard locally, and begins to author and test the following set of rules:
The following file content matches the automation document requirements above.
The following file content matches the command document requirements above.
The following file content matches the generic document requirements above.
These files are added to the repo so that validations can be run on SSM documents using the defined cfn-guard rules. Furthermore, tests are added to invoke the cfn-guard CLI for any documents, applying the appropriate set of .guard files.
For instance, let’s assume an SSM document is missing the assumeRole property. When cfn-guard is invoked, it will detect the missing property as an error before the document is created within their AWS account.
We looked at how an organization can use cfn-guard in their processes to enforce standards and best practices for SSM documents. In our example use case, we created three rules that we can either invoke manually or as part of a pipeline to validate that SSM documents meet the defined standards.
To get started using cfn-guard, see the GitHub repo for installation instructions and detailed documentation on how to write your own policies to enforce standards in your SSM documents.