Deployment options

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 Deployment Scenarios and Architecture.

To implement these scenarios, follow the modularity guidelines in the next section.

Modularity

To cover modularity of your deployment scenarios, create a entrypoint 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. The others will be referenced as submodules (inside the /submodules/quickstart-repo-name folder in GitHub for each referenced Quick Start) at a particular commit level. This ensures that the reference is repeatable and does not change unexpectedly. The following diagram is an example of how stacks can be linked.

Modular infrastructure for Quick Start templates

For example, to build out the VPC environment for the new VPC scenario, use the VPC Quick Start template. For an example of how to implement a wrapper around the VPC template, see the Active Directory templates. Here’s a snippet from the AWS CloudFormation script:

Referencing Git submodules

When you create the nested stack that deploys the workload, ensure that it can be deployed independently from an existing VPC that meets Quick Start criteria.

Infrastructure

The Quick Start team has developed several AWS CloudFormation templates you can use as boilerplates or examples for your own development. These are listed and described in the Templates and examples section of this guide. Using these will save time and ensure that you’re following AWS best practices for high availability, security, and VPC design. It also helps us standardize AWS products and services across Quick Starts.

If you’re developing a Quick Start for a Microsoft workload, search for Microsoft Quick Starts, and use those templates to build your environment. You can also find shared scripts in the Microsoft utilities repository.

Submodules

When referencing existing Quick Starts as nested templates, always reference them using Git submodules. This will reduce the impact of one Quick Start affecting another and reduce the amount of duplicate code that must be maintained. There are a few things to know when using submodules as part of a Quick Start:

  • When you add a submodule, ensure it points to the main branch, and use SSH authentication.
  • 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 submodule’s repository.

    To add a Git submodule, run the following command from your Quick Start root directory:

    git submodule add –b main git@github.com:aws-quickstart/<quickstart-repo-name>.git submodules/<quickstart-repo-name>

    For example, to add the VPC Quick Start as a submodule, use:

    git submodule add -b main git@github.com:aws-quickstart/quickstart-aws-vpc.git submodules/quickstart-aws-vpc

  • To clone a repository that has submodules, use:

    git clone --recursive git@github.com:aws-quickstart/<quickstart-repo-name>.git

  • To synchronize all submodules in a Quick Start after a git pull use:

    git submodule update --recursive

  • To update the submodules to the latest version, use:

    git submodule update --remote --merge

    Do not use the --recursive option in this case. You can, however, update an individual module by specifying its name at the end, as in submodules/<quickstart-repo-name>.

AWS Region support

Your Quick Start should be available across most 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 unsupported services in all Regions.

Note about AWS GovCloud support   Not all Quick Starts officially support the AWS GovCloud (US) Region at this time. We have, however, added conditional code to the AWS CloudFormation templates in preparation for a GovCloud testing framework. The following code examples show how the condition is used.

Condition:


"Conditions": {
   "GovCloudCondition": {
      "Fn::Equals": [
         {
            "Ref": "AWS::Region"
         },
         "us-gov-west-1"
      ]
   }
},

References:


"VPCStack": {
  "Type": "AWS::CloudFormation::Stack",
  "Properties": {
     "TemplateURL": {
        "Fn::Sub": [
           "https://${QSS3BucketName}.${QSS3Region}.amazonaws.com/${QSS3KeyPrefix}submodules/quickstart-aws-vpc/templates/aws-vpc.template",
           {
              "QSS3Region": {
                 "Fn::If": [
                    "GovCloudCondition",
                    "s3-us-gov-west-1",
                    "s3"
                 ]
              }
           }
        ]
     },



"Resource": {
   "Fn::Sub": [
      "arn:${Partition}:s3:::${QSS3BucketName}/${QSS3KeyPrefix}*",
      {
         "Partition": {
            "Fn::If": [
               "GovCloudCondition",
               "aws-us-gov",
               "aws"
            ]
         }
      }
   ]
},


"/tmp/bastion_bootstrap.sh": {
 "source": {
    "Fn::Sub": [
       "https://${QSS3BucketName}.${QSS3Region}.amazonaws.com/${QSS3KeyPrefix}scripts/bastion_bootstrap.sh",
       {
          "QSS3Region": {
             "Fn::If": [
                "GovCloudCondition",
                "s3-us-gov-west-1",
                "s3"
             ]
          }
       }
    ]
 },

Handling downloads

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 how to Use existing AMIs and AMI mappings.
  • If your product isn’t available through an AMI, provide download instructions for the software before deploying the Quick Start, and provide a parameter that specifies the software’s location. For an example of this approach, see the Deployment Steps for the Oracle Quick Start.

Handling product versions

Keep your Quick Start in sync with your product releases:

  • If you expect most of your customers to adopt the latest version of your software release, update your Quick Start to support it. For example, see how the Heptio Quick Start handles frequent Kubernetes updates.
  • If your software has a slow upgrade cycle, consider adding support for multiple versions. If your new version doesn’t require architectural changes, you can offer version selection by using parameters. For example, the SQL Server on the AWS Cloud uses a parameter to support three versions of SQL Server.

Using scripts

  • Limit the amount of work performed by user-data scripts. Try invoking other scripts via cfn-init, and ensure to signal the stack.

Error handling

  • Assume that your script will fail, so format your code logically, and include error checking and ample notes.
  • Signal to AWS CloudFormation when errors occur (and when an instances finish). For more information, see Troubleshooting AWS CloudFormation.
  • Do not create AWS resources (e.g., scripts) outside of AWS CloudFormation templates. Such resources are not tracked and can cause stack removal failures and generate additional customer costs.