Automated documentation of AWS CloudFormation template parameters

AWS Quick Starts are automated gold-standard deployments built using AWS CloudFormation that are accompanied by a step-by-step deployment guide. For the guide, we needed a mechanism to automate the documentation of AWS CloudFormation input parameters that are passed to the template at runtime to control the deployment configuration. The templates can contain up to 60 parameters, and documenting these manually can be a laborious exercise.

In this blog post, I give details on the mechanism to document AWS CloudFormation parameters into tables, which provide a handy reference on the parameter tuning categories available. This could be useful to organizations with diverse teams that maintain complex CloudFormation templates, and that are exploring options to document them.

This mechanism uses a Python script that parses the AWS CloudFormation templates in either JSON or YAML formats, and produces an HTML table that you can use in documentation.

I also show you how to package the script as an AWS Lambda function with an Amazon API Gateway endpoint, to provide a convenient serverless solution for generating the template tables.

Generating template parameter tables using Python

CloudFormation templates are written in either JSON or YAML. Python has native support for JSON, and YAML processing can be done by using popular libraries such as PyYAML or ruamel.yaml. Since JSON format is also a valid YAML format, we can use a YAML processing library to process both formats. For details on the anatomy of CloudFormation templates, see the AWS CloudFormation documentation.

A YAML-formatted template fragment looks similar to the following:

---
AWSTemplateFormatVersion: "version date"

Description:
  String

Metadata:
  template metadata

Parameters:
  set of parameters

...

Resources:
  set of resources

...

We can parse the Metadata and Parameter sections to generate a friendly, tabular view of parameter keys and descriptions that state their intent. As an example, you can view the file here:

https://github.com/aws-samples/aws-cloudformation-parameter-table-generator/blob/master/functions/source/table-generator-lambda.py

The script has a test harness as the main method, where you can experiment with four input mechanisms:

• Absolute file path
• File URL
• HTTP(S) URL
• S3 URI

When you run the script, HTML data is output to the console, and you can redirect it to an HTML file for viewing in your preferred browser. For example:

python3 table-generator-lambda.py > test.html

Although running the script is convenient, you’ll notice that there is a lambda_handler method provided in the script. This script can be packaged as an AWS Lambda function and invoked by an Amazon API Gateway endpoint. This gives you a serverless solution for generating CloudFormation parameter tables. Let’s get into that next.

Serverless parameter table generator

Here’s a high-level architecture diagram of the solution.

I’ve created a CloudFormation template that you can use to quickly provision the solution. It requires the following parameters. (Yes, I used the serverless parameter table generator to generate these tables. 🙂 )

Input configuration

AWS Quick Start configuration

Change the following defaults only if you want to customize the deployment from the source.

Once you’ve chosen your IP range for the Allowed CIDR blocks parameter—and, optionally, specified an existing S3 bucket that securely hosts your CloudFormation templates as the Templates bucket parameter—you can deploy the stack.

If you’re using the AWS CloudFormation console, you can provide the template URL on the Create stack page, and then follow the prompts.

Alternatively, you can deploy the stack using the AWS Command Line Interface (CLI). Download the sample parameter input file, and change the input values to match your configuration. Then, run the following command by using the AWS CLI. Replace <region-name> with the region you choose to deploy the stack.

aws cloudformation create-stack --stack-name --region <region-name> cfn-table-generator \
  --template-url https://s3.amazonaws.com/aws-cfn-samples/aws-cloudformation-parameter-table-generator/templates/cfn-doc-generator.yaml \
  --parameters file://params.json \
  --capabilities "CAPABILITY_IAM" "CAPABILITY_AUTO_EXPAND" \
  --disable-rollback

Testing the deployment

Once the deployment is complete, navigate to the Outputs section of your stack in the AWS CloudFormation console. I’ve included the following output to get you started quickly.

To test that the deployment worked, in the CFDocGeneratorApiEndpoint URL, replace the REPLACE_WITH_TEMPLATE_URL token with a public URL—for example, the public URL that you just used earlier to deploy the stack.

https://s3.amazonaws.com/aws-cfn-samples/aws-cloudformation-parameter-table-generator/templates/cfn-doc-generator.yaml

The output of the API Gateway is as follows.

Generating tables for private templates

If you provided a value for the Templates bucket parameter when deploying the stack, the Lambda function role has been granted read access to this bucket. You can replace the token in the output URL with the S3 URI of your template file. For example:

s3://<my-templates-bucket>/<key/of/my-template.yaml>

Troubleshooting

If you run into any errors, check Amazon CloudWatch Logs for the Lambda function.

Conclusion

We on the AWS Quick Starts team use AWS CloudFormation to describe and provision infrastructure resources in a cloud environment, in an automated and secure way.

Manually documenting parameters, especially when you have long, complex templates, can be time consuming. I’ve shown a convenient way of documenting CloudFormation templates by using a serverless solution that eliminates the need to run local scripts. As a result, we get a handy reference to the CloudFormation input parameters in the form of user-friendly parameter tables. This could be equally useful to organizations with diverse teams that maintain complex CloudFormation templates, and are exploring mechanisms to document them.

If you would like to dig deeper into the code, please check out the GitHub repository, and create issues for providing feedback or suggesting enhancements. Open-source code contributions are welcome as pull requests.