10 Best Practices to Help Partners Build AWS Quick Starts for Customers

By Dave May, Partner Solutions Architect, AWS Quick Start

The AWS Quick Starts program helps customers streamline their deployment of key workloads on the Amazon Web Services (AWS) Cloud.

Rather than manually configuring all of the components of a solution, customers can simply deploy a Quick Start, which uses infrastructure as code (IaC) to automate the deployment.

AWS Quick Starts are production architecture accelerators that help customers deploy AWS-native services and products from AWS Partners. These accelerators reduce hundreds of manual procedures into just a few steps, so AWS customers can build production environments quickly and start using them immediately.

AWS Partners use Quick Starts automate the deployment of their products, broaden their customer reach, expedite the deployment of their products (often from weeks to hours), gain access to community feedback, and generate new customer leads.

In this post, I will cover some of the best practices AWS Partners can follow when developing and deploying Quick Starts, along with some common mistakes to avoid.

About AWS Quick Starts

AWS Quick Starts are essentially reference architectures plus automation. The architecture describes how to deploy a key workload on AWS, following our best practices for security and availability. Then, AWS CloudFormation templates automate that deployment so customers can launch them directly into their accounts in an automated fashion, without having to manually configure the product.

Each Quick Start is published with a deployment guide describing the architecture in depth.

The primary components of Quick Starts are CloudFormation templates written in YAML or JSON. These define AWS infrastructure components to be deployed, and are often paired with AWS Lambda functions, Bash or PowerShell scripts, or other assets that automate the deployment of AWS Partner products on top of native AWS services.

How to Work with Us on a Quick Start

AWS Partners can work with us to develop their Quick Start and have it listed on the AWS Quick Start website. There are a wide range of benefits for AWS Partners publishing Quick Starts for AWS customers.

Figure 1 – AWS Partners use Quick Starts to automate deployment of their products and broaden customer reach.

If you are interested in contributing to the Quick Start program, feel free to visit the Quick Start Contributor’s Guide to familiarize yourself with the process. Then, reach out to your Partner Development Manager (PDM) or Partner Solutions Architect (PSA) with an architecture diagram and specifications for your Quick Start.

There are no AWS Partner Network (APN) tier requirements for AWS Partners to publish a Quick Start.

Best Practices

#1. Read the Contributor’s Guide

To prepare AWS Partners to build and document Quick Starts, we created the Quick Start Contributor’s Guide. This contains instructions and examples to help you adapt an existing Quick Start for a custom usage scenario, contribute code to an existing Quick Start (adding features or fixing bugs, for example), or build a net-new Quick Start to automate the deployment of a partner product.

If you create code, architecture diagrams, or documentation without first reading the Contributor’s Guide, you may have to redo or abandon your work.

The Contributor’s Guide also points you to useful tools, including architecture diagram templates and CloudFormation examples, that can help simplify Quick Start development.

#2. Complete the Workshop

AWS Partners should complete the Quick Start Workshop, which walks you through the process of developing and testing a Quick Start. In the workshop, you create a GitHub repository, build a continuous integration and continuous delivery (CI/CD) pipeline, write a CloudFormation template, and test the template.

The workshop covers aspects of working with Quick Start tools that are unfamiliar to many developers. By devoting an hour or so to completing the workshop, you can save hours of work while developing your Quick Start.

When you test the template, you’ll use an open-source tool called TaskCat, which was developed by the AWS Quick Start team. With TaskCat, you specify the parameters for a CloudFormation template in a .json or .yaml file and programmatically launch the template in multiple regions, bypassing the laborious process of manually entering parameters.

After you deploy the template, TaskCat cleans up the deployed assets and produces a report detailing the success or failure of each step of the stack launch.

#3. Reuse Existing Quick Starts as Submodules

Building-AWS-Quick-Starts-1.1 Most Quick Starts are built on top of AWS-native services. For example, they may be deployed into new virtual private clouds (VPCs), or they may use Amazon Aurora databases or require bastion hosts for remote access.

Because all Quick Starts reside in public, open-source GitHub repositories, you don’t need to develop code for every resource. You can incorporate existing Quick Starts into new ones as submodules.

When you do this, you take advantage of work that has already been done and avoid having to maintain redundant resources.

Common submodules include quickstart-aws-vpc, quickstart-linux-bastion, quickstart-microsoft-activedirectory, and quickstart-amazon-aurora-mysql.

#4. Use an Integrated Development Environment with Linting

The amount of time Quick Starts take to launch varies significantly, from a few minutes to several hours. With complex Quick Starts, a developer might make a simple mistake and not realize it until a stack fails late in its test deployment, causing unnecessary frustration and wasted time.

While all aspects of Quick Starts—including CloudFormation templates and scripts—can be developed with any text editor, working in an integrated development environment (IDE) can improve the process.

An IDE can catch formatting mistakes in real-time, display aspects of your code in different colors to highlight them, reformat multiple lines of code simultaneously, and incorporate third-party linting tools to ensure your code is developed correctly for particular applications, including CloudFormation.

Cfn-lint is an open-source tool maintained by AWS that analyzes CloudFormation templates and checks for syntactic errors. (The cfn stands for CloudFormation.) We have developed custom cfn-lint rules that are specific to Quick Start guidelines.

By using an IDE with cfn-lint and the custom Quick Start rules installed, developers can catch errors immediately, reducing development and testing time. You can find cfn-lint plugins for popular IDEs on the cfn-lint GitHub page.

#5. Store All Quick Start Assets in the Same Repository

A Quick Start should not include any dependencies on public Amazon Simple Storage Service (Amazon S3) buckets other than the S3 bucket in which the Quick Start itself is hosted.

It can be tempting to place scripts, installation media, or other artifacts in your public S3 bucket, since this allows AWS Partners to maintain control of the assets. However, this dependency can cause the Quick Start to fail to deploy if the S3 bucket’s permissions or structure change.

Store all small files used to deploy the Quick Start (templates, scripts, Lambda functions) in the Quick Start’s GitHub repository. For larger files (.iso or .tar.gz files exceeding a few MB), pass their download paths as parameters in the Quick Start’s CloudFormation templates, enabling customers to enter custom URLs during deployment.

#6. Divide Quick Start Components into Separate Templates

When possible, Quick Starts should be deployed with a parent CloudFormation template deploying individual components as child CloudFormation templates rather than as single, monolithic templates.

For example, take a standard three-tier web application with a load balanced web-server layer, a load balanced application-server layer, and a highly available database layer. This entire stack could be deployed from a single CloudFormation template, but if you divide it into four templates (parent, web layer, application layer, and database layer), you simplify updating and troubleshooting.

Breaking the Quick Start components into separate templates also makes it possible for other Quick Starts to reuse those components. For example, if you use the same web front end for multiple applications, you can reuse the web-layer template.

#7. Observe Conventions for Naming and Storing Files and Directories

All Quick Start files follow the same file structure and naming conventions in the GitHub repository. This consistency makes it possible for any developer to incorporate any existing Quick Start as a submodule without having to worry about inaccurate file names and file paths.

Figure 2 – GitHub repository layout.

Quick Start files are stored in the following directories:

/docs: The contents of the deployment guide
/functions: Lambda functions
- /source: The source code
- /packages: Lambda ZIP files
/scripts: Bash or PowerShell scripts
/submodules: References to other Quick Starts used as submodules
/templates: The CloudFormation templates

Most Quick Starts include a main (parent) template and one or more workload templates. The main template is typically a .yaml file that deploys a VPC, bastion host, and other underlying AWS resources on top of which a partner product is deployed. Workload templates are partner-developed .yaml files that deploy the partner’s product.

Store the main workload templates in the /templates directory, and use the file extension .template.yaml. Name the main template main.template.yaml or <product>-main.template.yaml or <product>-parent.template.yaml. Name the workload templates descriptively: <product>-database.template.yaml or <product>-webserver.template.yaml.

While CloudFormation initially supported only the JSON file format, YAML has become the preferred file format for Quick Starts. YAML has several advantages over JSON, including shorter files and support for comments that make the templates more readable.

To programmatically convert CloudFormation templates that are written in JSON to YAML, use the cfn-flip tool.

#8. Use the Same Names for Common Parameters

While CloudFormation workload templates have parameters unique to the product being deployed, some Quick Starts have common parameters.

For common parameters, use the same names from one Quick Start to another. For example, most Quick Starts are deployed into multiple AWS Availability Zones and therefore need to define the subnet IDs for each Availability Zone. By using the same parameter names for these CIDR blocks (PrivateSubnet1ID, PrivateSubnet2ID, PublicSubnet1ID), you simplify the process of testing, documenting, and reusing Quick Starts.

Consistent naming of common parameters across the Quick Start catalog also simplifies the use of submodules since developers don’t have to keep track of multiple parameter names when passing parameters between parent and child templates.

If one partner’s Quick Start template were to use the name PrivateSubnet1, while a submodule used the name PrivateSubnet1ID for the same value, developers would have to keep track of two parameter names instead of one. The more nonstandard parameter names partners use, the more the issue is exacerbated.

Here are some other common parameters:

VPCID: ID of the VPC into which the Quick Start is deployed
VPCCIDR: CIDR block of the VPC into which the Quick Start is deployed
PrivateSubnet1ID: ID of the first Availability Zone’s private subnet
PrivateSubnet2ID: ID of the second Availability Zone’s private subnet
PublicSubnet1ID: ID of the first Availability Zone’s public subnet
PublicSubnet2ID: ID of the second Availability Zone’s public subnet
QSS3BucketName: Name of the Amazon S3 bucket hosting the Quick Start assets
QSS3KeyPrefix: Amazon S3 key prefix of the directory in which the Quick Start assets are hosted
KeyPairName: Amazon Elastic Compute Cloud (Amazon EC2) key pair used to access any EC2 instances deployed by the Quick Start

#9. Update the Deployment Guide as the Code Changes

Each Quick Start is published with a deployment guide. Available in HTML or PDF format from each Quick Start’s web page, the deployment guide is a document that provides an overview of the solution and guides customers through the deployment.

The /docs/boilerplate subdirectory in the GitHub repository contains the deployment guide’s generic content, and the /docs/partner_editable subdirectory contains AsciiDoc files with content specific to the particular Quick Start.

The contents of these directories, along with the parameters in the CloudFormation templates, dynamically generate the deployment guide. Prior to publication, the technical writing and legal teams review the deployment guide.

As you change the Quick Start (modify the architecture, add deployment options), update the deployment guide files accordingly to ensure the deployment guide accurately reflects the content of the Quick Start.

#10. Maintain the Quick Start

Once the Quick Start has been launched, the development process is not yet complete. Changes to the product(s) being deployed, changes to the underlying AWS offerings, bugs reported via GitHub and support tickets, and other events require that Quick Starts be continuously maintained.

After your Quick Start has been published, you will need to plan for proactive updates, respond to user queries, and fix reported issues. It’s important to have a well-defined support path or contact person for issues, and to iterate quickly on feedback.

Conclusion

AWS Partners in the AWS Quick Start program can help their customers automate the deployment of their solutions, increasing customer engagements and improving the customer experience.

With more than 170 Quick Starts published at the time of this writing, the AWS Quick Start team has had considerable experience working with a variety of partner products and has identified best practices to follow when developing a Quick Start and common missteps to avoid.

By following the best practices outlined in this post, you can efficiently and effectively develop Quick Starts using the AWS platform. When you’re ready to build your Quick Start, see the steps outlined on our Contributor’s Guide to build a new Quick Start.

To learn more, see the following AWS Quick Start resources:

Contact our team at quickstart@amazon.com, or let me know your thoughts in the comments.