Deployment options

Typically, you design a Partner Solution to cover at least two deployment options:

  • New VPC—With this deployment option, customers build a new virtual private cloud (VPC) that contains the AWS infrastructure for the workload. They can then set up a test, demo, or POC an environment that doesn’t interfere with their production environment.
  • Existing VPC—With this deployment option, customers deploy the workload into their existing production environment.

Consider additional scenarios that are specific to your architecture on AWS. For an example of a solution that supports multiple scenarios, refer to Active Directory Domain Services on AWS.

To implement your deployment options, follow the modularity guidelines in the following section.

Modularity

To cover modularity of your deployment scenarios, create an entrypoint template that deploys one or many nested stacks (depending on the Partner Solution). One or more of those nested stacks deploys the workload of the Partner Solution. The others are referenced as submodules (inside the /submodules/quickstart-repo-name folder in GitHub for each referenced Partner Solution) 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 Partner Solution templates

For example, to build out the VPC environment for the new VPC scenario, use the VPC Partner Solution template. For an example of how to implement a wrapper around the VPC template, refer to the Active Directory templates. Here’s a snippet from the AWS CloudFormation script highlighting the linked VPC solution submodule:

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 Partner Solution criteria.

Infrastructure

The Integration & Automation 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 saves time and ensures that you’re following AWS best practices for high availability, security, and VPC design. It also helps us standardize AWS products and services across Partner Solutions.

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

Submodules

When referencing existing Partner Solutions as nested templates, always reference them using Git submodules. This reduces the impact of one Partner Solution 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 Partner Solution:

  • 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 Partner Solution 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 solution 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 Partner Solution 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 Partner Solution should be available across most AWS Regions. If you’re relying on specific AWS services, check the AWS Regional Services List for service availability. Provide alternate deployment scenarios for unsupported services in all Regions.

Handling downloads

Do not store licensed software in your repository for customers to download. Use one of these options to manage your licenses:

  • Use an AWS Marketplace Amazon Machine Image (AMI) that contains the software. You should also use an AMI for the operating system for your Partner Solution. For more information, refer to the Use existing AMIs and AMI mappings section of this guide.
  • If your product isn’t available through an AMI, provide download instructions for the software before deploying the Partner Solution. Provide a parameter that specifies the software’s location.

Handling product versions

Keep your Partner Solution in sync with your product releases:

If you expect most of your customers to adopt the latest version of your software release, update your Partner Solution to support it. 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.

Using scripts

  • Limit the amount of work performed by customer-data scripts. Invoke other scripts using cfn-init, and signal the stack.

Error handling

  • Assume that your script will fail. Format your code logically, and include error checking and ample notes.
  • Signal to AWS CloudFormation when errors occur and when instances finish. For more information, refer to Troubleshooting 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.