Design your Quick Start to cover at least two scenarios:
- Building a new virtual private cloud (VPC) that contains the AWS infrastructure for the workload. This scenario enables users to set up a test, demo, or POC environment that doesn’t interfere with their production environment.
- Enabling users to deploy the workload into their existing VPC. This scenario enables quick adoption by users who want to deploy the workload into their existing production environment.
You might also consider additional scenarios that are specific to your architecture on AWS. For an example, see the Active Directory Quick Start.
To implement these scenarios, follow the modularity guidelines in the next section.
To cover your deployment scenarios in a modular fashion, create a master template that deploys one or many nested stacks, depending on the Quick Start. One or more of those nested stacks will deploy the actual workload of the Quick Start, while the others will be referenced as submodules (inside the /submodules/quickstart-repo-name folder for each referenced Quick Start in Git) at a particular commit level in order to ensure that it is repeatable and does not change unexpectedly. The following diagram shows an example of how stacks could be linked together.
For example, to build out the VPC environment for the new VPC scenario, use the VPC Quick Start. (Templates are available in the GitHub repo.) For an example of how to implement a wrapper around the VPC template, see the Active Directory templates.
When you create the nested stack that deploys the workload, make sure that it can be deployed independently by a user who has an existing VPC that meets the criteria of the Quick Start.
The Quick Start team has developed the following templates for deploying the AWS infrastructure for a workload:
- VPC and networking (details; Git repo)
- Linux bastion host (details; Git repo)
- Remote Desktop Gateway (details; Git repo)
To save time, we encourage you to use these templates when setting up the AWS environment for your Quick Start. Using these will also ensure that you’re following AWS best practices for high availability, security, and VPC design, and will help us standardize the AWS platform across Quick Starts.
If you’re developing a Quick Start for a Microsoft workload, you might also want to take a look at the Quick Starts in that category and use those templates to build up the Microsoft environment for your Quick Start. You can find shared scripts for these Quick Starts in the https://github.com/aws-quickstart/quickstart-microsoft-utilities repo.
When referencing existing Quick Starts as nested templates, you should always reference them using Git submodules. This will reduce the impact of one Quick Start changing and affecting others, as well as reducing the amount of duplicate code that has to be maintained. There are a few things to keep in mind when you use submodules as part of a Quick Start:
- When you add a submodule, make sure it points to the master branch and use SSH to authenticate.
Any submodule you add must reside in the submodules/quickstart-repo-name directory of the repository, where quickstart-repo-name is the name of the repository for the Quick Start that you are using as a submodule.
To add a Git submodule, run the following command from your Quick Start root directory:
git submodule add –b master firstname.lastname@example.org:aws-quickstart/<quickstart-repo-name>.git submodules/<quickstart-repo-name>
For example, to add the VPC Quick Start as a submodule, use the command:
git submodule add -b master email@example.com:aws-quickstart/quickstart-aws-vpc.git submodules/quickstart-aws-vpc
To clone a repository that has submodules, use:
git clone <path> -- recursive
To synchronize all submodules in a Quick Start after a
git submodule update --recursive
To update the submodules to the latest version, use:
git submodule update --remote --merge
Do not use the
--recursiveoption in this case, but you can also update an individual module by specifying its name at the end as
AWS Region support
Your Quick Start should be available across the majority of AWS Regions. If you’re relying on specific AWS services, please check the AWS Region table for service availability, and provide alternate deployment scenarios for services that aren’t supported in all regions.
Do not include software bits with your Quick Start. Use one of these options instead:
- Use an AWS Marketplace AMI that contains the bits. You should also use an AMI for the operating system for your Quick Start. For more information, see the Use existing AMIs section.
- If your product isn’t available through an AMI, provide instructions for the user to download the software before deploying the Quick Start, and provide a parameter for specifying the location of the software. For an example of this approach, see the Oracle Quick Start.
- Limit the amount of work done in user data scripts. Try invoking other scripts via cfn-init and make sure to signal the stack when finished.
- Include error checking in your scripts and write your scripts in a pessimistic fashion.
- Signal to AWS CloudFormation when errors occur (and when the work is done for an instance). For more information, see the AWS CloudFormation documentation.
- Do not create any AWS resources out of band (e.g., in scripts) outside the AWS CloudFormation templates. These resources are not tracked and might cause stack removal failures and generate additional costs for the customer.