Automating ISV product packaging and deployment in AWS Landing Zone

The Amazon Web Services (AWS) Landing Zone solution automates customers’ landing zone deployment and configuration with AWS security and operation best practices. AWS Control Tower extends AWS Landing Zone as a managed landing zone service to further simplify landing zone deployment and management. But after customers set up their landing zone environments through either AWS Landing Zone or AWS Control Tower, they can encounter challenges when deploying additional AWS solutions or Independent Software Vendor (ISV) products, all referred to as add-on products, in their environments.

This blog post is intended for ISV partners who develop products to run in the AWS Cloud and for their customers who want to deploy the ISV products in their AWS Landing Zone environments.

In this post, we provide design and implementation details of a solution that automates add-on product preparation and deployment for AWS Landing Zone-based environments. The solution packages ISV products or any services that are configured by AWS Quick Starts or other AWS CloudFormation templates. It then deploys the packaged add-ons in AWS Landing Zone accounts via AWS Service Catalog and AWS CodePipeline.

For an add-on package example, refer to the AWS Transit Gateway add-on package example in the GitHub Quick Starts sample repository.

Solution overview

The solution’s workflow starts with ISV product templates in either AWS Quick Starts or AWS CloudFormation. A set of packaging functions converts a product template to a set of product add-on configuration and deployment artifacts and stores them in Amazon S3 for customers to consume. The customer then uses AWS Service Catalog in the AWS Organizations account to manage add-on products that are imported from the S3 bucket. The customer deploys the add-ons from AWS Service Catalog to AWS Landing Zone core accounts, such as the Shared Services account, Log Archive account, or Security account.

For AWS Landing Zone service and architecture details, see the AWS Landing Zone website.

overview diagram of packaging products for customer a w s landing zone environment.

Solution design details

The solution consists of two decoupled segments: an automated ISV product packaging and automated ISV product deployment.

diagram showing detailed view of packaging and deployment processes.

Packaging

The solution’s packaging segment resides in the ISV’s AWS environment. Its components are as follows.

The solution master template is an AWS CloudFormation template that starts the automated packaging process.
The add-on packaging component runs AWS Lambda functions orchestrated by AWS Step Functions. It imports the original product CloudFormation templates from either the AWS Quick Starts repository or the vendor’s own product repository. The packaging component then produces two artifacts:
- A new deployment CloudFormation template for AWS Service Catalog to launch the product
- a product add-on .zip package in the AWS Landing Zone add-on structure for AWS CodePipeline to deploy
The product vendor’s S3 bucket stores the artifacts produced by the add-on packaging component.

Deployment

In the customer’s AWS Landing Zone environment, the deployment segment is made up of the following components.

The AWS Service Catalog in the AWS Landing Zone AWS Organizations account enables the customer to centrally manage and deploy ISV product add-ons. The customer creates an ISV product in the AWS Service Catalog by importing the add-on packaging artifacts from the product vendor’s S3 bucket. The customer uses the AWS Service Catalog to deploy an add-on product to a target AWS Landing Zone core account by running the product deployment CloudFormation template.
The AWS Landing Zone add-on deployment function merges the product add-on .zip package that is stored in the product vendor’s S3 bucket with the AWS Landing Zone configuration package, which triggers CodePipeline to deploy the add-on to a target account.
AWS CloudFormation StackSets provides the key mechanism to deploy add-on products from the AWS Landing Zone AWS Organizations account (where the AWS Service Catalog runs) to a target account. Through the StackSets mechanism, the add-on template is executed to deploy the add-on product through the CloudFormation stack in the target account.

Implementation

As we can see from the solution design, the add-on packaging function plays a key role in bridging ISV products and AWS Landing Zone in the customer’s environment. To understand how the automated packaging works, let’s look more closely at the AWS Landing Zone add-on structure used for creating the product package, the product deployment template used by AWS Service Catalog, and the packaging Lambda functions.

Product add-on .zip package

The packaging function automatically generates a separate add-on product package for each add-on product based on the AWS Landing Zone add-on micro-configuration structure.

add-on
  add-on-<product name>
    parameters
      core-accounts
        add-on-<product name>-parameters.json
    templates
      core-accounts
        add-on-<product name>-template.template
    add_on_manifest.yaml
    user-input.yaml

The automatically generated product add-on .zip package contains four files:

add-on-<product name>-parameters.json contains add-on product parameters for the product provisioning.
add-on-<product name>-template.template is the add-on’s product CloudFormation template.
add_on_manifest.yaml describes AWS Landing Zone core account structure with Region name, Organization Unit (OU) name, Account name, product parameter file path, product CloudFormation template file path, and AWS Systems Manager parameters.
user-input.yaml is used by AWS Landing Zone to capture the values of product parameters and manifest parameters that the user types on the AWS Service Catalog console.

Product add-on deployment template for AWS Service Catalog

To enable customers to deploy add-on products from AWS Service Catalog, the add-on packaging function creates an add-on deployment CloudFormation template for each add-on product. AWS Service Catalog then invokes the template. Here is a snippet of the template that shows the structure and required content:

Parameters:
  #General Inputs, applies to all add-ons
  SourceBucketName:
    Type: String
    Description: Source S3 bucket name
    Default: 'alz-addon-products'
  SourceKeyName:
    Type: String
    Description: Name of add-on product package zip file in source S3 bucket
    Default: 'alz-addon-products.zip'
  AccountName:
    Description: In which Account do you wish to deploy?
    Type: String
    Default: shared-services
  OUName:
    Description: Which OU does the above Account belong to?
    Type: String
    Default: core
  Region:
    Description: In which Region do you want to deploy this add-on product?
    Type: String
   
  #add-on product specific parameter inputs
  ...... 

Metadata:
  AWS::CloudFormation::Interface:
    ParameterGroups:
    ...... 

Resources:
  LandingZoneAddOnDeploymentLambda:
    Type: AWS::Lambda::Function 
    ......
  LandingZoneAddOnConfigDeployer:
    Type: Custom::AddOnConfigDeployer
    ......

The configuration parameters are populated by the customer when deploying the product through the AWS Service Catalog.

In the Resources section of the template, LandingZoneAddOnDeploymentLambda points to a Lambda function that merges the ISV product add-on package into the AWS Landing Zone configuration package. LandingZoneAddOnConfigDeployer invokes the Lambda function with the ISV add-on package’s S3 bucket location, the AWS Landing Zone S3 bucket location for the merged AWS Landing Zone configuration package, and the product parameter values that the user specifies through the AWS Service Catalog.

Packaging function tasks

The packaging function performs three tasks, which are implemented by three Lambda functions, respectively.

Create the input files. This task validates the deployment CloudFormation template from the package’s S3 bucket, parses the parameters, and generates two files:
- parameter.json is the product input parameter file for AWS Service Catalog to launch the CloudFormation template.
- parameter.yaml file contains the parameters that are required for the user-input.yaml file.
Create the product add-on .zip file. This task creates product add-on .zip file defined by the AWS Landing Zone add-on file structure. It then uploads the product add-on .zip file to the product vendor’s S3 add-on artifacts bucket.
Create the deployment CloudFormation template for the AWS Service Catalog. This task creates a CloudFormation template for the customer to specify and deploy the ISV product add-on in AWS Landing Zone core accounts. It uses the product template file in the add-on product .zip package to generate the product deployment template. It stores the generated template in the product vendor’s S3 add-on artifacts bucket.

The add-on packaging automation process is implemented by three components.

A solution master template starts the packaging process via CloudFormation stack.
A State Machine is employed through AWS Step Functions to orchestrate the add-on packaging execution.
An S3 add-on bucket contains the automatically generated product deployment template and product add-on package.

solution master template to create_input_files.py, create_add_on_zip.py,, create_sc_template.py to s3 bucket with deployment template and add on package.

Instructions for packaging and deployment

How to package your product

As an ISV vendor, you are responsible for preparing and packaging your products for use by AWS Landing Zone customers. With this automated packaging solution, you need only two steps to create a product add-on package.

In the following steps, we use AWS Transit Gateway in place of an ISV product.

Step 1: Create an S3 bucket for storing product add-on artifacts

Step 2: Run the product packaging master template provided by AWS

prerequisites for template packaging.

Specify three parameter values:

AddOnS3Bucket is the S3 bucket where artifacts from product packaging will be stored
ProductName is the name of the product to be packaged
ProductS3Url is the URL of the product’s QuickStart or CloudFormation template

parameters for packaging.

How customers deploy your product

AWS Landing Zone customers are responsible for subscribing to, deploying, and managing ISV product add-ons by using AWS Service Catalog in the AWS Landing Zone AWS Organizations account. To deploy an ISV add-on product, the customer performs three steps.

Step 1: Create the ISV add-on product in the AWS Service Catalog

Create a portfolio for the ISV add-on product.
In the portfolio, add the ISV add-on product that you want to deploy.
The added product is listed.

Step 2: In the Products list, select the add-on that you want to deploy

select the add on product to deploy.

Step 3: Specify add-on parameters

Specify add-on deployment parameters.
Specify and review add-on product parameters.
Deploy the product by choosing LAUNCH.
Inspect the add-on products that were deployed.

Wrapping up

After establishing their AWS Landing Zone environments, customers acquire and deploy ISV products or services in their AWS Landing Zone accounts. In this post, we provided a solution that automates the packaging and deployment of ISV products that are provisioned by AWS Quick Starts or CloudFormation templates. We discussed the solution’s design and implementation, and we included a demonstration. We also provide the implementation code and templates together with an AWS Transit Gateway add-on example in the GitHub repo.

The current packaging implementation supports add-on deployment to AWS Landing Zone core accounts. The implementation can be extended to support add-on deployment to AWS Landing Zone baseline accounts.

We encourage ISV partners to use this solution for automating ISV product packaging and deployment in AWS Landing Zone accounts. We invite you to try the solution and to contact us with any questions at alzqs@amazon.com.