Customizations for AWS Control Tower - Amazon S3€¦ · Amazon Web Services – Customizations for AWS Control Tower Developer Guide July 2020 Page 9 of 19 Properties name The name

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)

https://www.apache.org/licenses/LICENSE-2.0

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


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.


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.

https://docs.aws.amazon.com/solutions/latest/customizations-for-aws-control-tower/deployment.html


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

https://s3.amazonaws.com/solutions-reference/customizations-for-aws-control-tower/latest/customizations-for-aws-control-tower.pdf


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.

https://docs.aws.amazon.com/organizations/latest/userguide/orgs_manage_policies_about-scps.html

https://docs.aws.amazon.com/organizations/latest/userguide/orgs_manage_policies_about-scps.html


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


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.


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).


- 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).



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"},


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).



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).



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


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.


- 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.

https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/outputs-section-structure.html


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.


- 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: []


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


- 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


- name: block-s3-public-access

description: To S3 buckets to have public access

policy_file: policies/block-s3-public.json



- 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


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







- 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>


Page 15 of 19

version: 2020-01-01

…truncated…


- name: stackset-1

template_file:templates/create-ssm-parameter-keys-1.template

parameter_file:parameters/create-ssm-parameter-keys-1.json


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_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.


Page 16 of 19

---

region: us-east-1

version: 2020-01-01







- Core

- Custom


- name: transit-network

template_file:templates/transit-gateway.template

parameter_file:parameters/transit-gateway.json


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


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.


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']"

}

]

https://docs.aws.amazon.com/systems-manager/latest/userguide/systems-manager-parameter-store.html

https://docs.aws.amazon.com/systems-manager/latest/userguide/systems-manager-parameter-store.html

https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-ssm-parameter.html


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.

https://github.com/awslabs/aws-control-tower-customizations/blob/master/CHANGELOG.md

Documents

Customizations for AWS Control Tower - Amazon S3€¦ · Amazon Web Services – Customizations for AWS Control Tower Developer Guide July 2020 Page 9 of 19 Properties name The name