Copyright (c) 2020 by Amazon.com, Inc. or its affiliates. Customizations for AWS Control Tower Developer Guide is licensed under the terms of
Apache License Version 2.0 available at https://www.apache.org/licenses/LICENSE-2.0
Customizations for AWS
Control Tower AWS Developer Guide
Lalit Grover
Aijun Peng
January 2020
Last updated: July 2020 (see Revisions)
Amazon Web Services – Customizations for AWS Control Tower Developer Guide July 2020
Page 2 of 19
Contents
Customizations for Solution Deployment ................................................................................ 4
AWS CodePipeline Overview ................................................................................................ 4
AWS CodePipeline Stages ..................................................................................................... 4
Source Stage ....................................................................................................................... 4
Build Stage ......................................................................................................................... 5
(Optional) Manual Approval Stage ................................................................................... 5
Service Control Policy Stage .............................................................................................. 5
AWS CloudFormation Resource Stage .............................................................................. 5
Custom AWS Control Tower Configuration ............................................................................. 5
Configuration Folder Structure............................................................................................. 5
Manifest File Overview ......................................................................................................... 6
Organization Policies ......................................................................................................... 6
AWS CloudFormation Resources ...................................................................................... 6
Manifest File Sections ........................................................................................................... 7
Region ................................................................................................................................ 7
Version ............................................................................................................................... 7
Organizational Policies ...................................................................................................... 7
AWS CloudFormation Resources ...................................................................................... 8
Building Your Own Customizations ........................................................................................ 12
Set Up a Configuration Package for Service Control Policies .............................................. 12
Step 1: Edit the manifest.yaml file .................................................................................... 12
Step 2: Create a folder structure ....................................................................................... 13
Set Up a Configuration Package for AWS CloudFormation StackSets................................14
Step 1: Edit the existing manifest file ..............................................................................14
Step 2: Update the folder structure .................................................................................16
Appendix A: Using ‘alfred’ helper in the CloudFormation parameter files ........................... 18
Document Revisions ................................................................................................................19
Amazon Web Services – Customizations for AWS Control Tower Developer Guide July 2020
Page 3 of 19
About This Guide
This developer guide provides information about customizing and extending the AWS
Control Tower environment. It includes information about the custom configuration package
structure, manifest schema, configuration templates, and pipeline deployment stages.
The guide is intended for IT infrastructure architects, administrators, DevOps professionals,
systems integrators, or independent software vendors who want to customize and extend the
AWS Control Tower environment for their company or customers.
Amazon Web Services – Customizations for AWS Control Tower Developer Guide July 2020
Page 4 of 19
Customizations for Solution Deployment The Customizations for AWS Control Tower solution is deployed and configured by
processing a configuration package through AWS CodePipeline. The following sections
describe this process in detail.
AWS CodePipeline Overview
The configuration package leverages Amazon Simple Storage Service (Amazon S3) and AWS
CodePipeline. The configuration package contains a manifest file, accompanying set of
templates, and other JSON files for describing and implementing a customer’s AWS Control
Tower environment. By default, the _custom-control-tower-configuration.zip
configuration package is loaded in the solution’s custom-control-tower-
configuration-<accountID>-<region> Amazon S3 bucket.
Note: By default, the solution creates an Amazon S3 bucket to store the pipeline source, but you can change the location to an AWS CodeCommit repository. For more information, see the parameters table under Step 1. Launch the Stack in the Customizations for AWS Control Tower Implementation Guide.
The manifest is a text file that describes the service control policies (SCPs) and AWS
CloudFormation resources you can deploy to customize your landing zone. AWS
CodePipeline extracts the manifest file, related templates, and JSON files; performs manifest
file, template, and JSON file validations; and uses sections in the manifest file to execute
specific pipeline stages. Updating the configuration package by customizing the manifest file
and removing the underscore (_) from the configuration package filename automatically
triggers AWS CodePipeline.
Note: The sample configuration package filename begins with an underscore (_) so that AWS CodePipeline is not automatically triggered. When you have completed the customization of the configuration package, you must upload the custom-control-tower-configuration.zip without the underscore (_) in order to trigger the
deployment in AWS CodePipeline.
AWS CodePipeline Stages
The solution pipeline leverages several AWS CodePipeline stages for implementing and
updating your AWS Control Tower environment.
Source Stage
The source stage is the initial stage where your customized configuration package triggers the
pipeline stage. The source for the AWS CodePipeline can be either an Amazon S3 bucket or
AWS CodeCommit repository where the configuration package can be hosted.
Amazon Web Services – Customizations for AWS Control Tower Developer Guide July 2020
Page 5 of 19
Build Stage
The build stage leverages AWS CodeBuild to validate the contents of the configuration
package. These checks include testing the manifest.yaml file syntax and schema, and all
AWS CloudFormation templates included in the package or remotely hosted using
CloudFormation validate-template and cfn_nag. If the manifest file and AWS
CloudFormation templates pass the tests, the pipeline continues to the next stage. If the tests
fail, you can review the CodeBuild logs to identify the issue and edit the configuration source
file as needed.
(Optional) Manual Approval Stage
The manual approval stage is optional and provides additional control over the configuration
pipeline execution by pausing the pipeline until additional approval is provided. You can opt-
in to manual approval by editing the Pipeline Approval Stage template parameter to Yes
when you launch the stack. If enabled, the manual approval step is added to the configuration
pipeline. For more information about manual approval, see Step 1. Launch the Stack in the
Customizations for AWS Control Tower Implementation Guide.
Service Control Policy Stage
The service control policy stage triggers the service control policy state machine to make AWS
Organizations API calls to create service control policies (SCPs). This action is detailed in the
organization_policies section of the manifest file.
AWS CloudFormation Resource Stage
The AWS CloudFormation resource stage triggers the stack set state machine to deploy the
resources specified in the accounts and/or organizational units (OUs) list provided in the
manifest file. The AWS CloudFormation resources are created in the order in which they
appear in the manifest file.
Custom AWS Control Tower Configuration The custom AWS Control Tower configuration is defined by the manifest file, accompanying
set of templates, and other JSON files. The manifest.yaml is a text file that describes your
AWS CloudFormation resources and service control policies (SCPs). These files are packaged
into a folder structure and placed in the Amazon Simple Storage Service (Amazon S3) bucket
as a zip file. If you are using AWS CodeCommit, the files are placed in the repository without
zipping the files.
Configuration Folder Structure
The following code sample shows a custom configuration folder structure. The folder
structure stays the same despite the source storage (Amazon S3 or AWS CodeCommit
Amazon Web Services – Customizations for AWS Control Tower Developer Guide July 2020
Page 6 of 19
repository). However, when using Amazon S3 as the source, all the folders and files should
be compressed into a custom-control-tower-configuration.zip file and only the
zip file should be uploaded to the designated S3 bucket.
- manifest.yaml
- parameters/ [required]
- parameter files for AWS CloudFormation Resources (*.json)
- policies/ [required]
- service control policies files (*.json)
- templates/ [required]
- template files for AWS CloudFormation Resources (*.template)
Manifest File Overview
The following example shows the manifest file structure and its sections:
---
region: <String>
version: 2020-01-01
organization_policies:
set of managed AWS Organization SCPs
cloudformation_resources:
set of AWS CloudFormation resources
...
Organization Policies
The organization_policies section of the manifest file controls the AWS Organizations
SCPs that are applied to the accounts in your organization. This section enables you to specify
which organizational units (OUs) to use when applying SCPs at the OU level.
AWS CloudFormation Resources
The cloudformation_resources section of the manifest defines the AWS
CloudFormation StackSets that automatically deploys in the master account. You can
specify the OUs and accounts and, optionally, their respective regions to be used when
deploying stack instances. The stack instances are deployed at the account level rather than
the OU level. See Building Your Own Customizations for details.
Note: As of the date of this publication, AWS CloudFormation StackSets doesn’t support deployment of stack instances at the OU level.
Amazon Web Services – Customizations for AWS Control Tower Developer Guide July 2020
Page 7 of 19
Manifest File Sections
The manifest file includes the following sections which can be modified for your use case.
Region
Region consists of a text string identifying the default region for AWS Control Tower. This
value must be a valid AWS Region name such as us-east-1, eu-west-1, or ap-
southeast-1. The default region is used to create custom AWS Control Tower resources
such as AWS CloudFormation StackSets, unless a more resource-specific region is specified.
Version
Version identifies the manifest schema version number. The current version is 2020-01-01.
Organizational Policies
The organizational policies section specifies the AWS Organizations SCPs that needs to be
created in each OUs.
Syntax
The organizational policies section consists of the key name organizational_policies.
The following example shows the organizational policies section.
organization_policies: # List of policies
- name: <String>
description: <String>
policy_file: <String>
apply_to_accounts_in_ou: # List of Strings
- <String>
Properties
name
The AWS Organizations SCP name.
Type: String
Required: Yes
Valid Values: a-z, A-Z, 0-9, and an underscore (_). Any other character is automatically
replaced with an underscore (_).
description
The description for the AWS Organizations SCP.
Type: String
Amazon Web Services – Customizations for AWS Control Tower Developer Guide July 2020
Page 8 of 19
Required: Optional
policy_file
The location of policy_file is relative to the manifest file. The policy_file contains the SCP
policy to be applied at the OU level.
Type: String
Required: Yes
apply_to_accounts_in_ou
Identifies the list of OUs to apply at the OU level.
Type: List of OU names
Required: Yes
AWS CloudFormation Resources
The AWS CloudFormation resources are defined and found under the section of the manifest
file using the key name cloudformation_resources. The order of
cloudformation_resources determines the execution order for creating AWS
CloudFormation resources dependencies.
Syntax
The following example shows the cloudformation_resources section.
cloudformation_resources: # List of resources
- name: <String>
template_file: <String>
parameter_file: <String>
deploy_to_account: # List of Strings
- <String>
deploy_to_ou: # list of strings
- <String>
deploy_method: stack_set
ssm_parameters: # List of SSM parameters
- name: <String>
- value: <String>
regions: # list of strings
- <String>
This section consists of the key name cloudformation_resources and uses the following
properties.
Amazon Web Services – Customizations for AWS Control Tower Developer Guide July 2020
Page 9 of 19
Properties
name
The name that is associated with the AWS CloudFormation StackSets. The provided name
is used to provide a more user-friendly name for a stack set.
Type: String
Required: Yes
Valid Values: a-z, A-Z, 0-9, and an underscore (_). Any other character is automatically
replaced with an underscore (_).
template_file
This file can be either the relative location to the manifest file or an Amazon S3 URL that
points to an AWS CloudFormation template for creating AWS CloudFormation resources.
Type: String
Required: Yes
The following example shows the template_file as a relative location to the manifest
file (templates/custom-security.template).
cloudformation_resources:
- name: SecurityRoles
template_file:templates/custom-security.template
The following example shows the template_file as an Amazon S3 URL (s3://<my-
bucket>/templates/custom-security.template).
cloudformation_resources:
- name: SecurityRoles
template_file:s3://<my-bucket>/templates/custom-security.template
Note: If providing an Amazon S3 URL, verify that the bucket policy provides the read access for the AWS Organizations master account deploying the Customization for AWS Control Tower solution.
The following is an example of an S3 bucket policy.
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {"AWS": "arn:aws:iam::xxxxxxxxxxx:root"},
Amazon Web Services – Customizations for AWS Control Tower Developer Guide July 2020
Page 10 of 19
"Action": "s3:GetObject",
"Resource": "arn:aws:s3:::<my-bucket>/*"
}
]
}
The xxxxxxxxxxx is the AWS account ID for the AWS Organizations master account that
is deploying the solution.
parameter_file
This file can be either the relative location to the manifest file or an Amazon S3 URL that
points to an AWS CloudFormation template for defining the input parameters to use
when launching template_file.
Type: String
Required: Optional if the associated AWS CloudFormation template does not have any
input parameters.
The following example shows the parameter_file as a relative location to the manifest
file (parameter/custom-security.json).
cloudformation_resources:
- name: SecurityRoles
parameter_file:parameters/custom-security.json
The following example shows the parameter_file as an Amazon S3 URL (s3://<my-
bucket>/templates/custom-security.json).
cloudformation_resources:
- name: SecurityRoles
parameter_file:s3://<my-bucket>/parameters/custom-security.json
deploy_method
The deployment method for deploying resource(s) into the account. Currently,
deploy_method supports deploying resources using the stack_set option for
deployment through AWS CloudFormation StackSets.
Type: String
Required: Yes
Valid Value: stack_set
Amazon Web Services – Customizations for AWS Control Tower Developer Guide July 2020
Page 11 of 19
deploy_to_account
List of accounts where the AWS CloudFormation resources should be deployed.
Type: Either account name or account number to indicate that this resource should be
deployed into a given account list.
Required: Not required unless the deploy_to_ou key is not present.
deploy_to_ou:
List of OU names where the AWS CloudFormation resources should be deployed. OU
names are an indicator whether the resource should be deployed. The solution retrieves
the account list under each OU name and deploys the resource into a generated combined
account list for all the OUs
Type: List of OU names
Required: Not required unless the deploy_to_account key is not present.
Note: Either deploy_to_account or deploy_to_ou key is required under each AWS CloudFormation resource.
ssm_parameters
Contains the list of SSM parameter key name and value pairs for storing template outputs
in the SSM parameter store for reference by other resources defined earlier in the
manifest file. The following is a sample of the ssm parameters section.
ssm_parameters: # List of SSM parameters
- name: <String>
value: <String>
Type: List of name and value key pairs where the name is an SSM parameter store key
name string and value is the parameter value string.
Required: Optional
Valid Values: Any string or the $[output_<CfnOutput-Logical-ID>] variable
where <CfnOutput-Logical-ID> corresponds to the template output variable. For
more information about the Outputs section in an AWS CloudFormation template, see
Outputs in the AWS CloudFormation User Guide.
Amazon Web Services – Customizations for AWS Control Tower Developer Guide July 2020
Page 12 of 19
For example, the following code snippet will store the template VPCID output variable
into the /org/member/sharedservices/vpc_id SSM parameter key.
ssm_parameters: # List of SSM parameters
- name: /org/member/audit/VPC-ID
value: $[output_VPCID]
Note: The SSM parameter key name may contain a value other than output. For example, if the name is /org/environment-name, the value may production.
regions
List of AWS Regions where the AWS CloudFormation resource should be deployed.
Type: Any AWS commercial region names to indicate that this resource should be
deployed into a given region list. If this key does not exist in the manifest the resources
will be deployed in the home region only.
Required: Optional
Building Your Own Customizations The Customization for AWS Control Tower solution enables you to modify the
manifest.yaml file by adding or updating service control policies (SCPs) and AWS
CloudFormation resources. For resources that need to be deployed, you can add or remove
accounts and/or organizational units (OUs). You can add or modify the templates in the
package folders, create your own folders, and reference the templates or folders in the
manifest.yaml file.
Set Up a Configuration Package for Service Control Policies
This section explains how to create a configuration package for SCPs.
Step 1: Edit the manifest.yaml file
Use the sample manifest.yaml file as your starting point. Enter all necessary
configurations. Add the policy_file and apply_to_accounts_in_ou details.
The following snippet shows the default manifest file.
---
region: us-east-1
version: 2020-01-01
organization_policies: []
Amazon Web Services – Customizations for AWS Control Tower Developer Guide July 2020
Page 13 of 19
The value for region is added automatically during solution deployment and should match
the region where you deployed the solution.
To add a custom SCP in the example-configuration folder in the zip package stored in the
Amazon S3 bucket, open the example-manifest.yaml file and begin editing.
---
region: <your-home-region>
version: 2020-01-01
organization_policies:
- name: test-preventive-guardrails
description: To prevent from deleting or disabling resources in
member accounts
policy_file: policies/preventive-guardrails.json
#Apply to the following OU(s)
apply_to_accounts_in_ou:
- <OU_NAME>
…truncated…
The following snippet is an example of a customized manifest file. You can add more than
one policy in a single change.
---
region: us-east-1
version: 2020-01-01
organization_policies:
- name: block-s3-public-access
description: To S3 buckets to have public access
policy_file: policies/block-s3-public.json
#Apply to the following OU(s)
apply_to_accounts_in_ou:
- Core
- Custom
Step 2: Create a folder structure
The manifest file requires you to include an SCP policy in JSON format to support the
manifest. The manifest references the JSON file. Verify the file paths match what is provided
in the manifest file. A policy JSON file contains the SCPs to be deployed to OUs.
The following snippet shows the folder structure for the sample manifest file.
- manifest.yaml
- policies/
- block-s3-public.json
Amazon Web Services – Customizations for AWS Control Tower Developer Guide July 2020
Page 14 of 19
The following snippet is an example of a block-s3-public.json file.
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "GuardPutAccountPublicAccessBlock",
"Effect": "Deny",
"Action": "s3:PutAccountPublicAccessBlock",
"Resource": "arn:aws:s3:::*"
]
}
Set Up a Configuration Package for AWS CloudFormation StackSets
This section explains how to set up a configuration package for AWS CloudFormation
StackSets.
Step 1: Edit the existing manifest file
In the previously edited manifest file in Step 1, add the new AWS CloudFormation StackSets
information.
The following snippet shows the same sample manifest file that was used previously to set up
a configuration package for SCPs that will be edited to include the
cloudformation_resources details.
---
region: us-east-1
version: 2020-01-01
organization_policies:
- name: block-s3-public-access
description: To S3 buckets to have public access
policy_file: policies/block-s3-public.json
#Apply to the following OU(s)
apply_to_accounts_in_ou:
- Core
- Custom
The following snippet is a sample manifest file depicting the cloudformation_resources
details. The order of cloudformation_resources is used to determine the execution
order for creating cloudformation_resource dependencies. You can edit the following
example manifest file for your business needs.
---
region: <your-home-region>
Amazon Web Services – Customizations for AWS Control Tower Developer Guide July 2020
Page 15 of 19
version: 2020-01-01
…truncated…
cloudformation_resources:
- name: stackset-1
template_file:templates/create-ssm-parameter-keys-1.template
parameter_file:parameters/create-ssm-parameter-keys-1.json
deploy_method: stack_set
deploy_to_account:
- <account-name> # and/or
- <account-number>
ssm_parameters:
- name: /org/member/test-ssm/app-id
value: $[output_ApplicationId]
regions:
- <region-name>
- name: stackset-2
template_file:templates/create-ssm-parameter-keys-2.template
parameter_file:parameters/create-ssm-parameter-keys-2.json
deploy_method: stack_set
deploy_to_ou:
- <OU-name>
deploy_to_account:
- <account-name> # and/or
- <account-number>
regions:
- <region-name>
The following example shows that you can add more than one AWS CloudFormation resource
in the manifest file.
Amazon Web Services – Customizations for AWS Control Tower Developer Guide July 2020
Page 16 of 19
---
region: us-east-1
version: 2020-01-01
organization_policies:
- name: block-s3-public-access
description: To S3 buckets to have public access
policy_file: policies/block-s3-public.json
#Apply to the following OU(s)
apply_to_accounts_in_ou:
- Core
- Custom
cloudformation_resources:
- name: transit-network
template_file:templates/transit-gateway.template
parameter_file:parameters/transit-gateway.json
deploy_method: stack_set
deploy_to_account:
- 111111111111
- 222222222222
deploy_to_ou:
- Custom
ssm_parameters:
- name: /org/network/transit-gateway-id
value: $[output_TransitGatewayID]
regions:
- us-east-1
Step 2: Update the folder structure
To update the folder structure, you must include all supporting CloudFormation template
files and parameter files that are used in the manifest file. Verify that the file paths match
what is provided in the manifest file. A template file contains the AWS resources to be
deployed in OUs and accounts. A parameter file contains the input parameters used in the
template file.
The following is the folder structure for the sample manifest file created in Step 1.
- manifest.yaml
- policies/
- block-s3-public.json
- parameters/
- transit-gateway.json
- templates/
- transit-gateway.template
Amazon Web Services – Customizations for AWS Control Tower Developer Guide July 2020
Page 17 of 19
Note: The organization_policies and cloudformation_resources sections in the
manifest can be created at the same time and then uploaded to the designated source
(Amazon S3 or AWS CodeCommit). This enables you to add multiple customizations to your
environment in a single deployment.
Amazon Web Services – Customizations for AWS Control Tower Developer Guide July 2020
Page 18 of 19
Appendix A: Using alfred helper in the
CloudFormation parameter files The solution provides a mechanism to get the value for an AWS Systems Manager Parameter
Store key defined in the CloudFormation parameter JSON file. This allows you to use values
stored in the Parameter Store without updating the CloudFormation template.
For example, CloudFormation stack 1 creates a VPC and subnets in an Availability Zone. The
VPC ID and subnet ID need to be passed into CloudFormation stack 2 as parameter values.
You can store both of the IDs in the Systems Manager Parameter Store using the
AWS::SSM::Parameter resource in stack 1. As shown below, the alfred helper can get the
values from the parameter store and pass them into the StackSet state machine input.
CloudFormation stack 1 snippet:
VpcIdParameter:
Type: AWS::SSM::Parameter
Properties:
Name: '/stack_1/vpc/id'
Description: Contains the VPC id
Type: String
Value: !Ref MyVpc
SubnetIdParameter:
Type: AWS::SSM::Parameter
Properties:
Name: '/stack_1/subnet/id'
Description: Contains the subnet id
Type: String
Value: !Ref MySubnet
The following example is the parameter file for CloudFormation stack 2 stored in the
customized configuration package.
[
{
"ParameterKey": "VpcId",
"ParameterValue": "$[alfred_ssm_/stack_1/vpc/id']"
},
{
"ParameterKey": "SubnetId",
"ParameterValue": "$[alfred_ssm_/stack_1/subnet/id']"
}
]
Amazon Web Services – Customizations for AWS Control Tower Developer Guide July 2020
Page 19 of 19
Document Revisions
Date Change
January 2020 Initial Release
July 2020 For information about updates and changes for v1.2.0, see the changelog file in
the GitHub repository.
© 2020, Amazon Web Services, Inc. or its affiliates. All rights reserved.
Notices
Customers are responsible for making their own independent assessment of the information in this document.
This document: (a) is for informational purposes only, (b) represents current AWS product offerings and
practices, which are subject to change without notice, and (c) does not create any commitments or assurances
from AWS and its affiliates, suppliers or licensors. AWS products or services are provided “as is” without
warranties, representations, or conditions of any kind, whether express or implied. The responsibilities and
liabilities of AWS to its customers are controlled by AWS agreements, and this document is not part of, nor
does it modify, any agreement between AWS and its customers.
The Customizations for AWS Control Tower solution is licensed under the terms of Apache License Version 2.0
available at https://www.apache.org/licenses/LICENSE-2.0.
Top Related