# Get started with AWS Control Tower using APIs
This getting started procedure is intended for AWS Control Tower administrators. This procedure requires some prerequisites and includes two main steps.
In this procedure, you will use APIs from AWS Control Tower and other AWS services to configure and launch a landing zone. These APIs allow you to create a AWS Control Tower environment programatically, either [through the CloudFormation console](lz-apis-cfn.md), or through the AWS CLI.
Before you launch your AWS Control Tower landing zone, perform these prerequisite tasks:
+ Determine the most appropriate home Region. For more information, see [Administrative tips for landing zone setup](tips-for-admin-setup.md).
+ Review [Prerequisite: Automated pre-launch checks for your management account](getting-started-prereqs.md) to learn about the automated pre-launch checks that make sure your management account is ready for changes that establish your landing zone.
**Topics**
+ [Expectations for landing zone configuration with APIs](getting-started-expectations-api.md)
+ [Step 1: Configure your landing zone](lz-api-prereques.md)
+ [Step 2: Launch your landing zone using the AWS Control Tower APIs](lz-api-launch.md)
+ [Identify your landing zone](lz-api-list.md)
+ [Update your landing zone](lz-api-update.md)
+ [Reset the landing zone to resolve drift](lz-api-reset.md)
+ [View the details of your landing zone manifest file](lz-manifest-file.md)
+ [View the status of your landing zone operations](lz-api-examples-short.md)
+ [Examples: Set up an AWS Control Tower landing zone with APIs only](walkthrough-api-setup.md)
+ [Landing zone schemas](landing-zone-schemas.md)
+ [Launch a landing zone using CloudFormation](lz-apis-cfn.md)
# Expectations for landing zone configuration with APIs
The process of setting up your AWS Control Tower landing zone has multiple steps. Certain aspects of your AWS Control Tower landing zone are configurable. Other choices cannot be changed after setup.
**Key items to configure during setup**
+ You can select your Foundational OU names during setup, and you also can change OU names after you've set up your landing zone. By default, the Foundational OUs are named **Security** and **Sandbox**. For more information, see [Guidelines to set up a well-architected environment](aws-multi-account-landing-zone.md#guidelines-for-multi-account-setup).
+ During setup, you can select customized names for the shared accounts that AWS Control Tower creates, called **log archive** and **audit** by default, but you cannot change these names after setup. (This is a one-time selection.)
+ During setup with APIs, you *must* specify existing AWS accounts for AWS Control Tower to use as audit and log archive accounts. To specify existing AWS accounts, if those accounts have existing AWS Config resources, you must delete or modify the existing AWS Config resources before you can enroll the accounts into AWS Control Tower. (This is a one-time selection.)
+ If you are setting up for the first time, or if you're upgrading to landing zone version 3.0, you can choose whether to allow AWS Control Tower to set up an organization-level AWS CloudTrail trail for your organization, or you can opt out of trails that are managed by AWS Control Tower and manage your own CloudTrail trails. You can opt into or opt out of organization-level trails that are managed by AWS Control Tower any time you update your landing zone.
+ You can optionally set a customized retention policy for your Amazon S3 log bucket and log access bucket, when you set up or update your landing zone.
**Configuration choices that cannot be undone**
+ You cannot change your home Region after you've set up your landing zone.
+ If you're provisioning accounts with VPCs, VPC CIDRs can't be changed after they are created.
The next sections give the setup prerequisites and steps in detail, with explanations and caveats. For additional code examples, see [Examples: Set up an AWS Control Tower landing zone with APIs only](walkthrough-api-setup.md).
# Step 1: Configure your landing zone
The process of setting up your AWS Control Tower landing zone has multiple steps. Certain aspects of your AWS Control Tower landing zone are configurable, but other choices cannot be changed after setup. To learn more about these important considerations prior to launching your landing zone, review [Expectations for landing zone configuration](getting-started-configure.md).
Before using the AWS Control Tower landing zone APIs, you must first call APIs from other AWS services to configure your landing zone prior to launch. The process includes three main steps:
1. creating a new AWS Organizations organization,
1. setting up your service integration accounts,
1. and creating an IAM role or IAM Identity Center user with the required permissions to call the landing zone APIs.
## Step 1. Create the organization that will contain your landing zone:
Call the AWS Organizations `CreateOrganization` API and enable all features to create the **Foundational OU**. AWS Control Tower also recommends creating a designated **Security OU**. This Security OU should contain all of your service integration accounts. These would be the **log archive** account and the **audit** account for previous Landing Zone versions.
```
aws organizations create-organization --feature-set ALL
```
AWS Control Tower can set up one or more **Additional OUs**. We recommend that you provision at least one Additional OU in your landing zone, besides the Security OU. If this Additional OU is intended for development projects, we recommend that you name it the **Sandbox OU**, as given in the [AWS multi-account strategy for your AWS Control Tower landing zone](aws-multi-account-landing-zone.md).
## Step 2. Provision service integration accounts if needed:
To set up your landing zone, AWS Control Tower allows customers to configure AWS service integrations. Each of these service integrations may require one or more service integration central accounts. If you are using landing zone APIs to set up AWS Control Tower for the first time, you must provide the central integration account for each enabled AWS service integration. You can use existing AWS accounts or provision these accounts through the AWS Control Tower console or AWS Organizations APIs. **Ensure these service integration accounts are in the designated Security OU that is at the root level in your organization.**
1. Call the AWS Organizations `CreateAccount` API to create the **Log archive** account and **Audit** account in the **Security OU**.
```
aws organizations create-account --email mylog@example.com --account-name "Logging Account"
aws organizations create-account --email mysecurity@example.com --account-name "Security Account"
```
(Optional) Check the status of the `CreateAccount` operation using the AWS Organizations `DescribeAccount` API.
1. Move the provisioned service integration accounts into the designated **Security OU**
```
aws organizations move-account --account-id 0123456789012 --source-parent-id r-examplerootid111 --destination-parent-id ou-examplerootid111-security
```
## Step 3. Create the required service roles
Create the following IAM service roles in the `/service-role/` IAM path that enable AWS Control Tower to perform the API calls required to set up your landing zone:
+ [https://docs.aws.amazon.com//controltower/latest/userguide/access-control-managing-permissions.html#AWSControlTowerAdmin](https://docs.aws.amazon.com//controltower/latest/userguide/access-control-managing-permissions.html#AWSControlTowerAdmin)
+ [https://docs.aws.amazon.com//controltower/latest/userguide/access-control-managing-permissions.html#AWSControlTowerCloudTrailRole](https://docs.aws.amazon.com//controltower/latest/userguide/access-control-managing-permissions.html#AWSControlTowerCloudTrailRole)
+ [https://docs.aws.amazon.com//controltower/latest/userguide/access-control-managing-permissions.html#AWSControlTowerStackSetRole](https://docs.aws.amazon.com//controltower/latest/userguide/access-control-managing-permissions.html#AWSControlTowerStackSetRole)
+ [https://docs.aws.amazon.com//controltower/latest/userguide/roles-how.html#config-role-for-organizations](https://docs.aws.amazon.com//controltower/latest/userguide/roles-how.html#config-role-for-organizations)
For more information about these roles and their policies, see [Using identity-based policies (IAM policies) for AWS Control Tower](access-control-managing-permissions.md).
### To create an IAM role:
Create an IAM role with the necessary permissions to call all landing zone APIs. Alternatively, you can create an IAM Identity Center user and assign the necessary permissions.
```
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"backup:UpdateGlobalSettings",
"controltower:CreateLandingZone",
"controltower:UpdateLandingZone",
"controltower:ResetLandingZone",
"controltower:DeleteLandingZone",
"controltower:GetLandingZoneOperation",
"controltower:GetLandingZone",
"controltower:ListLandingZones",
"controltower:ListLandingZoneOperations",
"controltower:ListTagsForResource",
"controltower:TagResource",
"controltower:UntagResource",
"servicecatalog:*",
"organizations:*",
"organizations:RegisterDelegatedAdministrator",
"organizations:EnableAWSServiceAccess",
"organizations:DeregisterDelegatedAdministrator",
"organizations:ListDelegatedAdministrators",
"sso:*",
"sso-directory:*",
"logs:*",
"cloudformation:*",
"kms:*",
"iam:GetRole",
"iam:CreateRole",
"iam:GetSAMLProvider",
"iam:CreateSAMLProvider",
"iam:CreateServiceLinkedRole",
"iam:ListRolePolicies",
"iam:PutRolePolicy",
"iam:ListAttachedRolePolicies",
"iam:AttachRolePolicy",
"iam:DeleteRole",
"iam:DeleteRolePolicy",
"iam:DetachRolePolicy"
],
"Resource": "*"
}
]
}
```
**Note**
When upgrading to landing zone version 4.0 with AWS Config integration enabled, customers need to have `organizations:ListDelegatedAdministrators` permissions.
# Step 2: Launch your landing zone using the AWS Control Tower APIs
You can use AWS Control Tower APIs to launch your landing zone. This section describes how to create the required *landing zone manifest file* and use it with the `CreateLandingZone` API operation.
## Creating the manifest file
The manifest file is a JSON document that specifies your landing zone configuration. With landing zone version 4.0, many components are now optional, allowing for a more flexible deployment.
### Manifest Structure
Below is the complete structure of the manifest file with all available configurations:
```
{
"accessManagement": {
"enabled": true // Required - Controls IAM Identity Center integration
},
"backup": {
"enabled": true, // Required - Controls AWS Backup integration
"configurations": {
"backupAdmin": {
"accountId": "111122223333" // Backup administrator account
},
"centralBackup": {
"accountId": "111122224444" // Central backup account
},
"kmsKeyArn": "arn:aws:kms:region:account-id:key/key-id"
}
},
"centralizedLogging": {
"accountId": "111122225555", // Log archive account
"enabled": true, // Required - Controls centralized logging
"configurations": {
"accessLoggingBucket": {
"retentionDays": 365 // Minimum value: 1
},
"loggingBucket": {
"retentionDays": 365 // Minimum value: 1
},
"kmsKeyArn": "arn:aws:kms:region:account-id:key/key-id"
}
},
"config": {
"accountId": "111122226666", // Config aggregator account
"enabled": true, // Required - Controls AWS Config integration
"configurations": {
"accessLoggingBucket": {
"retentionDays": 365 // Minimum value: 1
},
"loggingBucket": {
"retentionDays": 365 // Minimum value: 1
},
"kmsKeyArn": "arn:aws:kms:region:account-id:key/key-id"
}
},
"governedRegions": [ // Optional - List of regions to govern
"us-east-1",
"us-west-2"
],
"securityRoles": {
"enabled": true, // Required - Controls security roles creation
"accountId": ""111122226666" // Security/Audit account
}
}
```
### Important Notes
+ All `enabled` flags are required in the manifest.
+ If you disable AWS Config integration (`"config.enabled": false`), you must also disable the following integrations:
+ Security Roles (`"securityRoles.enabled": false`)
+ Access Management (`"accessManagement.enabled": false`)
+ Backup (`"backup.enabled": false`)
+ Account IDs must be valid 12-digit AWS account IDs.
+ KMS key ARNs must be valid AWS KMS key ARNs.
+ Retention days must be at least 1.
## Using the CreateLandingZone API
To create your landing zone using the API:
```
aws controltower create-landing-zone --landing-zone-version 4.0 --manifest file://manifest.json
```
The API will return a landing zone operation ID that you can use to track the progress of your landing zone creation. Sample response:
```
{
"arn": "arn:aws:controltower:us-west-2:123456789012:landingzone/1A2B3C4D5E6F7G8H",
"operationIdentifier": "55XXXXXX-e2XX-41XX-a7XX-446XXXXXXXXX"
}
```
You can monitor the operation status using `GetLandingZoneOperation` API which returns a **status** of `SUCCEEDED`, `FAILED`, or `IN_PROGRESS`:
```
aws controltower get-landing-zone-operation --operation-identifier "55XXXXXX-eXXX-4XXX-aXXX-44XXXXXXXXXX"
```
## What's Changed in landing zone version 4.0
Important changes to the manifest structure and requirements:
+ Organization Structure
+ `organizationStructure` definition has been removed from the manifest
+ Customers can now define their own organizational structure
+ Only requirement: Service integration accounts must be in the same OU directly under root
+ Enabled Flags
+ All service integration configurations have an `enabled` flag which is now a required field.
+ Customers need to always provide a boolean value. No default values are provided.
+ Customers need to explicitly enable/disable each service integration configuration in the manifest:
+ `accessManagement`
+ `backup`
+ `centralizedLogging`
+ `config`
+ `securityRoles`
+ Security Roles
+ Security Roles integration is now optional
+ New `enabled` flag introduced to manage `securityRoles` deployment
+ When disabled, related security features will not be implemented
+ AWS Config Integration
+ New AWS Config service integration section added to manifest as `config` with the following fields:
+ `enabled`: Required boolean flag to manage AWS Config integration deployment
+ `accountId`: AWS account ID for AWS Config aggregator
+ configurations:
+ `accessLoggingBucket.retentionDays`: Retention period for access logs
+ `loggingBucket.retentionDays`: Retention period for AWS Config logs
+ `kmsKeyArn`: KMS key for encryption
# Identify your landing zone
Calling `ListLandingZones` can help you determine if your account is already set up with AWS Control Tower. This API returns one landing zone identifier (ARN) across any **commercial** region, regardless of the landing zone's home region. Landing zone ARNs are regionally unique.
```
aws controltower list-landing-zones --region us-east-1
```
For [opt-in regions](https://docs.aws.amazon.com/controltower/latest/userguide/opt-in-region-considerations.html), the `ListLandingZones` API only returns the landing zone identifier *if you call the API in the same region as the API's home region*. For example, if your landing zone is set up in af-south-1 and you call `ListLandingZones` *in af-south-1*, the API returns the landing zone identifier. If your landing zone is set up in af-south-1 and you call `ListLandingZones` *in ap-east-1*, the API **does not** return the landing zone identifier.
**Output**:
```
{
"landingZones" [
"arn": "arn:aws:controltower:us-west-2:123456789123:landingzone/1A2B3C4D5E6F7G8H"
]
}
```
# Update your landing zone
When a new landing zone version is available, or to make other updates to your landing zone configuration, you can call the `UpdateLandingZone` API and reference an updated landing zone manifest file. This API returns an `OperationIdentifier`, which you can then use when calling the `GetLandingZoneOperation` API to check the update operation's status.
**To update the landing zone**
1. Call the AWS Control Tower `UpdateLandingZone` API and refer to the updated **landing zone version** or your **updated landing zone manifest file**.
```
aws controltower update-landing-zone --landing-zone-version 3.3 --landing-zone-identifier "arn:aws:controltower:us-west-2:123456789123:landingzone/1A2B3C4D5E6F7G8H" --manifest file://LandingZoneManifest.json
```
**Example LandingZoneManifest.json** file, with Regions and centralized logging:
```
{
"governedRegions": ["us-west-2","us-west-1"],
"organizationStructure": {
"security": {
"name": "Security"
},
"sandbox": {
"name": "Sandbox"
}
},
"centralizedLogging": {
"accountId": "LOG ARCHIVE ACCOUNT ID",
"configurations": {
"loggingBucket": {
"retentionDays":2555
},
"accessLoggingBucket": {
"retentionDays": 2555
},
"kmsKeyArn": "arn:aws:kms:us-west-1:123456789123:key/e84XXXXX-6bXX-49XX-9eXX-ecfXXXXXXXXX"
},
"enabled": true
},
"securityRoles": {
"accountId": "SECURITY ACCOUNT ID"
},
"accessManagement": {
"enabled": true
}
}
```
**Output**:
```
{
"operationIdentifier": "55XXXXXX-e2XX-41XX-a7XX-446XXXXXXXXX"
}
```
**Optionally Re-register OU to update accounts**
For registered AWS Control Tower OUs with fewer than 1000 accounts, you can use the AWS Control Tower console access the **OU page** in the dashboard and select **Re-register OU** to update the accounts in that OU.
# Reset the landing zone to resolve drift
When you create your landing zone, the landing zone and all the organizational units (OUs), accounts, and resources are compliant with the governance rules enforced by your chosen controls. As you and your organization members use the landing zone, changes in this compliance status may occur. These changes are called *drift*.
To identify if your landing zone is in drift, you can call the `GetLandingZone` API. This API returns the landing zone's **drift status** of `DRIFTED` or `IN_SYNC`.
To resolve drift within your landing zone you can use the `ResetLandingZone` API to reset the landing zone back to its original configuration. For example, AWS Control Tower enables IAM Identity Center by default to help you manage your AWS accounts-- but if you configure your original landing zone parameters with IAM Identity Center disabled, calling `ResetLandingZone` maintains that disabled IAM Identity Center configuration.
You can only use the `ResetLandingZone` API if you are using the latest available landing zone version. You can call the `GetLandingZone` API and compare your landing zone version with the **latest available version**. If necessary, you can [Update your landing zone](lz-api-update.md) so your landing zone uses the latest available version. In these examples, we are using version 3.3 as the latest version.
1. Call the `GetLandingZone` API. If the API returns a **drift status** of `DRIFTED`, your landing zone is in drift.
1. Call the `ResetLandingZone` API to reset your landing zone to its original configuration.
```
aws controltower reset-landing-zone --landing-zone-identifier "arn:aws:controltower:us-west-2:123456789123:landingzone/1A2B3C4D5E6F7G8H"
```
**Output**:
```
{
"operationIdentifier": "55XXXXXX-e2XX-41XX-a7XX-446XXXXXXXXX"
}
```
**Note**
Resetting the landing zone does not update the landing zone version. Review [Update your landing zone](lz-api-update.md) for details about updating the landing zone version.
# View the details of your landing zone manifest file
The AWS Control Tower landing zone manifest file is a text file that describes your AWS Control Tower resources. The following sections show detailed definitions of entries in the landing zone manifest file.
To see a full landing zone schema example, see [Landing zone schemas](https://docs.aws.amazon.com//controltower/latest/userguide/landing-zone-schemas.html).
**governedRegions** – Regions to place under governance
+ **Type:** List of strings
+ **Required:** No
+ **Example:**
```
"governedRegions": ["us-west-2","us-west-1"]
```
**organizationStructure** – Select the names of security and sandbox OUs to be created in your organization
+ **Type:** Object
+ **Required:** Yes
+ **Properties:**
+ **Example:**
+ `security` - an object with one required property, `name`, which takes a `String`
+ `sandbox` - an object with one required property, `name`, which takes a `String`
```
"organizationStructure": {
"security": {
"name": "CORE"
},
"sandbox": {
"name": "Sandbox"
}
}
```
**centralizedLogging** – Configuration for AWS CloudTrail
+ **Type:** Object
+ **Required:** Yes
+ **Properties:**
+ *accountId* - a `String` the represents the AWS account into which the logging resource should be deployed
+ *configurations* - an `Object` with three properties
+ `loggingBucket` - an object with one property, `retentionDays`, which takes a `Number`
+ `accessLoggingBucket` - an object with one property, `retentionDays`, which takes a `Number`
+ `kmsKeyArn` - an optional `String`
+ *enabled* - an optional `Boolean`
+ **Example:**
```
"centralizedLogging": {
"accountId": "222222222222",
"configurations": {
"loggingBucket": {
"retentionDays": 60
},
"accessLoggingBucket": {
"retentionDays": 60
},
"kmsKeyArn": "arn:aws:kms:us-west-1:123456789123:key/e84XXXXX-6bXX-49XX-9eXX-ecfXXXXXXXXX"
},
"enabled": true
}
```
**securityRoles** – Choose where to deploy the logging resource
+ **Type:** Object
+ **Required:** Yes
+ **Properties:** *accountId* - a `String` that represents the AWS account into which the logging resource should be deployed
+ **Example:**
```
"securityRoles": {
"accountId": "333333333333"
}
```
**accessManagement** – Choose whthether to enable access management
+ **Type:** Object
+ **Required:** No
+ **Properties:** *enabled* - a Boolean
+ **Example:**
```
"accessManagement": {
"enabled": true
}
```
**backup** – Configuration for AWS Backup with AWS Control Tower
+ **Type:** Object
+ **Required:** No
+ **Properties:**
+ *configurations* - an `Object` with three properties
+ `centralBackup` - an object with one property, `accountId`, which takes a `String`
+ `backupAdmin` - an object with one property, `accountId`, which takes a `String`
+ `kmsKeyArn` - an optional `String`
+ *enabled* - a `Boolean`
+ **Example:**
```
"backup": {
"configurations": {
"centralBackup": {
"accountId": "CENTRAL BACKUP ACCOUNT ID"
},
"backupAdmin": {
"accountId": "BACKUP MANAGER ACCOUNT ID"
},
"kmsKeyArn": "arn:aws:kms:us-west-1:123456789123:key/e84XXXXX-6bXX-49XX-9eXX-ecfXXXXXXXXX"
},
"enabled": true
}
```
# View the status of your landing zone operations
The `ListLandingZoneOperations` API allows you to view the status of AWS Control Tower operations that perform actions on your landing zone.
For more information about this API operation, see [ListLandingZoneOperations](https://docs.aws.amazon.com//controltower/latest/APIReference/API_ListLandingZoneOperations.html).
## ListLandingZoneOperations
**Example input and output for `ListLandingZoneOperations`**.
This example shows how to call the API with no parameters.
```
aws controltower --region us-east-1 list-landing-zone-operations
{
"landingZoneOperations": [
{
"operationIdentifier": "873fe98d-1ecc-4154-b593-86e4a95ebfXX",
"operationType": "CREATE",
"status": "FAILED"
},
{
"operationIdentifier": "0016d43d-a307-4ad8-a2a2-b427b8eb1cXX",
"operationType": "DELETE",
"status": "SUCCEEDED"
},
{
"operationIdentifier": "002b8b5a-6bb7-4c40-89cd-5822a73d13XX",
"operationType": "CREATE",
"status": "SUCCEEDED"
},
{
"operationIdentifier": "008886a0-f7a2-4df3-90e8-6e9f936507XX",
"operationType": "CREATE",
"status": "FAILED"
}
]
}
```
This example shows how to call the API and specify the maximum number of results.
```
aws controltower --region us-east-1 list-landing-zone-operations --max-results 1
{
"landingZoneOperations": [
{
"operationIdentifier": "873fe98d-1ecc-4154-b593-86e4a95ebfXX",
"operationType": "CREATE",
"status": "FAILED"
}
],
"nextToken": "AAMAATFMzwP0QysYY8npWgstfcHGQBj-XCC18ISyd9mkQmzLR7ZFMket4F0aWv8tUTtnsTWOnfblUp_Q9U-nX9_6lEsLHs0RlhceDKskHr0_3fm8KdPTa6ofxMt5SPw8WF7-Jsvw2rJVvhj4DHDipo-y1HVK_eZ__Z3-OzInm403cIHxhbjGPgqCX6FeKr8lwgTDKOejkLYZ9w7J5aqPAKLfVP8KKNda5g0VfMj1wdl4J2nwnHI-UuCTIZ5nUEgXgUHaFq6Ma1pLDfGefZQJn5HmDhhgd5yvqzSRH1BtrHpdV_N1EVP8u3JJr3eWQHe9jNB02lihD4Mdcbm3SJg1tWWw2bxp0cgClepI-1Dxt3FAZ5XMVjDxHQHxdKkrazHunMgBFvwfzauC3Ah0WqJg9dkEP22l5HI9qZ7LtDbYZEb5hCskVmjxFsbbwia_OrL2X8ZDeHZStJkxbC3CPIjFMQuldBlzF6L19GSpHE7XIMlTBzzwWtg92sGlpz0An1Smh12jZDe__u2rx8NSkAT97B0bKtmI2TKjutOx7NYUxOhc5qio8dAJbcMgDkf1m5BjK9R7GKdrVv5EDY5Q6uE8gxM2wGnUr_NkpGqR1aEjLIRfZYKN9so_x4vZZPhwtp1NIv256mIGvMYzNivLZ4FE9RPJFh7rSNwFvWnRSVwFLDkOoqXZV9OUYsXdn3W3FMqBzbG6g2KvMXKrKdbrnJHxGgyNYSbS3ogkQYGeuz-VXRwTUIBInrit4HslNtPE8-IC1gxCjGoYPGtuWBPumK-pUPE="
}
```
This example shows how to call the API and obtain a paginated result with `nextToken`.
```
aws controltower --region us-east-1 list-landing-zone-operations --next-token AAMAATFMzwP0QysYY8npWgstfcHGQBj-XCC18ISyd9mkQmzLR7ZFMket4F0aWv8tUTtnsTWOnfblUp_Q9U-nX9_6lEsLHs0RlhceDKskHr0_3fm8KdPTa6ofxMt5SPw8WF7-Jsvw2rJVvhj4DHDipo-y1HVK_eZ__Z3-OzInm403cIHxhbjGPgqCX6FeKr8lwgTDKOejkLYZ9w7J5aqPAKLfVP8KKNda5g0VfMj1wdl4J2nwnHI-UuCTIZ5nUEgXgUHaFq6Ma1pLDfGefZQJn5HmDhhgd5yvqzSRH1BtrHpdV_N1EVP8u3JJr3eWQHe9jNB02lihD4Mdcbm3SJg1tWWw2bxp0cgClepI-1Dxt3FAZ5XMVjDxHQHxdKkrazHunMgBFvwfzauC3Ah0WqJg9dkEP22l5HI9qZ7LtDbYZEb5hCskVmjxFsbbwia_OrL2X8ZDeHZStJkxbC3CPIjFMQuldBlzF6L19GSpHE7XIMlTBzzwWtg92sGlpz0An1Smh12jZDe__u2rx8NSkAT97B0bKtmI2TKjutOx7NYUxOhc5qio8dAJbcMgDkf1m5BjK9R7GKdrVv5EDY5Q6uE8gxM2wGnUr_NkpGqR1aEjLIRfZYKN9so_x4vZZPhwtp1NIv256mIGvMYzNivLZ4FE9RPJFh7rSNwFvWnRSVwFLDkOoqXZV9OUYsXdn3W3FMqBzbG6g2KvMXKrKdbrnJHxGgyNYSbS3ogkQYGeuz-VXRwTUIBInrit4HslNtPE8-IC1gxCjGoYPGtuWBPumK-pUPE=
{
"landingZoneOperations": [
{
"operationIdentifier": "0016d43d-a307-4ad8-a2a2-b427b8eb1cXX",
"operationType": "DELETE",
"status": "SUCCEEDED"
},
{
"operationIdentifier": "002b8b5a-6bb7-4c40-89cd-5822a73d13XX",
"operationType": "CREATE",
"status": "SUCCEEDED"
},
{
"operationIdentifier": "008886a0-f7a2-4df3-90e8-6e9f936507XX",
"operationType": "CREATE",
"status": "FAILED"
}
]
}
```
This example shows how to call the API with a filter.
```
aws controltower --region us-east-1 list-landing-zone-operations --filter '{"types":["CREATE"],"statuses":["FAILED"]}'
{
"landingZoneOperations": [
{
"operationIdentifier": "873fe98d-1ecc-4154-b593-86e4a95ebfXX",
"operationType": "CREATE",
"status": "FAILED"
},
{
"operationIdentifier": "008886a0-f7a2-4df3-90e8-6e9f936507XX",
"operationType": "CREATE",
"status": "FAILED"
}
]
}
```
# Examples: Set up an AWS Control Tower landing zone with APIs only
This walkthrough of examples is a companion document. For explanations, caveats, and more information, see [Getting started with AWS Control Tower using APIs](https://docs.aws.amazon.com//controltower/latest/userguide/getting-started-apis.html).
**Prerequisites**
Before creating an AWS Control Tower landing zone, you must create an organization, two shared accounts, and some IAM roles. This walkthrough tutorial includes these steps, with example CLI commands and output.
**Step 1. Create the organization and two required accounts.**
```
aws organizations create-organization --feature-set ALL
aws organizations create-account --email example+log@example.com --account-name "Log archive account"
aws organizations create-account --email example+aud@example.com --account-name "Audit account"
```
**Step 2. Create the required IAM roles.**
`AWSControlTowerAdmin`
```
cat <controltower_trust.json
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"Service": "controltower.amazonaws.com"
},
"Action": "sts:AssumeRole"
}
]
}
EOF
aws iam create-role --role-name AWSControlTowerAdmin --path /service-role/ --assume-role-policy-document file://controltower_trust.json
cat <ct_admin_role_policy.json
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "ec2:DescribeAvailabilityZones",
"Resource": "*"
}
]
}
EOF
aws iam put-role-policy --role-name AWSControlTowerAdmin --policy-name AWSControlTowerAdminPolicy --policy-document file://ct_admin_role_policy.json
aws iam attach-role-policy --role-name AWSControlTowerAdmin --policy-arn arn:aws:iam::aws:policy/service-role/AWSControlTowerServiceRolePolicy
```
`AWSControlTowerCloudTrailRole`
```
cat <cloudtrail_trust.json
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"Service": "cloudtrail.amazonaws.com"
},
"Action": "sts:AssumeRole"
}
]
}
EOF
aws iam create-role --role-name AWSControlTowerCloudTrailRole --path /service-role/ --assume-role-policy-document file://cloudtrail_trust.json
cat <cloudtrail_role_policy.json
{
"Version": "2012-10-17",
"Statement": [
{
"Action": "logs:CreateLogStream",
"Resource": "arn:aws:logs:*:*:log-group:aws-controltower/CloudTrailLogs:*",
"Effect": "Allow"
},
{
"Action": "logs:PutLogEvents",
"Resource": "arn:aws:logs:*:*:log-group:aws-controltower/CloudTrailLogs:*",
"Effect": "Allow"
}
]
}
EOF
aws iam put-role-policy --role-name AWSControlTowerCloudTrailRole --policy-name AWSControlTowerCloudTrailRolePolicy --policy-document file://cloudtrail_role_policy.json
```
`AWSControlTowerStackSetRole`
```
cat <cloudformation_trust.json
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"Service": "cloudformation.amazonaws.com"
},
"Action": "sts:AssumeRole"
}
]
}
EOF
aws iam create-role --role-name AWSControlTowerStackSetRole --path /service-role/ --assume-role-policy-document file://cloudformation_trust.json
cat <stackset_role_policy.json
{
"Version": "2012-10-17",
"Statement": [
{
"Action": [
"sts:AssumeRole"
],
"Resource": [
"arn:aws:iam::*:role/AWSControlTowerExecution"
],
"Effect": "Allow"
}
]
}
EOF
aws iam put-role-policy --role-name AWSControlTowerStackSetRole --policy-name AWSControlTowerStackSetRolePolicy --policy-document file://stackset_role_policy.json
```
`AWSControlTowerConfigAggregatorRoleForOrganizations`
```
cat <config_trust.json
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"Service": "config.amazonaws.com"
},
"Action": "sts:AssumeRole"
}
]
}
EOF
aws iam create-role --role-name AWSControlTowerConfigAggregatorRoleForOrganizations --path /service-role/ --assume-role-policy-document file://config_trust.json
aws iam attach-role-policy --role-name AWSControlTowerConfigAggregatorRoleForOrganizations --policy-arn arn:aws:iam::aws:policy/service-role/AWSConfigRoleForOrganizations
```
**Step 3. Get account IDs and generate the landing zone manifest file.**
The first two commands in the following example store the account IDs for the accounts you created in **Step 1** into variables. These variables then help generate the landing zone manifest file.
```
sec_account_id=$(aws organizations list-accounts | jq -r '.Accounts[] | select(.Name == "Audit account") | .Id')
log_account_id=$(aws organizations list-accounts | jq -r '.Accounts[] | select(.Name == "Log archive account") | .Id')
cat <landing_zone_manifest.json
{
"governedRegions": ["us-west-1", "us-west-2"],
"organizationStructure": {
"security": {
"name": "Security"
},
"sandbox": {
"name": "Sandbox"
}
},
"centralizedLogging": {
"accountId": "$log_account_id",
"configurations": {
"loggingBucket": {
"retentionDays": 60
},
"accessLoggingBucket": {
"retentionDays": 60
}
},
"enabled": true
},
"securityRoles": {
"accountId": "$sec_account_id"
},
"accessManagement": {
"enabled": true
}
}
EOF
```
**Step 4. Create the landing zone with the latest version.**
You must set up the landing zone with the manifest file and the latest version. This example shows version 3.3.
```
aws --region us-west-1 controltower create-landing-zone --manifest file://landing_zone_manifest.json --landing-zone-version 3.3
```
The output will contain an **arn** and an **operationIdentifier**, as shown in the example that follows.
```
{
"arn": "arn:aws:controltower:us-west-1:0123456789012:landingzone/4B3H0ULNUOL2AXXX",
"operationIdentifier": "16bb47f7-b7a2-4d90-bc71-7df4ca1201xx"
}
```
**Step 5. (Optional) Track the status of your landing zone creation operation, by setting up a loop.**
To track status, use the **operationIdentifier** from the previous `create-landing-zone` command's output.
```
aws --region us-west-1 controltower get-landing-zone-operation --operation-identifier 16bb47f7-b7a2-4d90-bc71-7df4ca1201xx
```
Sample status output:
```
{
"operationDetails": {
"operationType": "CREATE",
"startTime": "2024-02-28T21:49:31Z",
"status": "IN_PROGRESS"
}
}
```
You can use the following example script to help you set up a loop, which reports the operation's status over and over, like a log file. Then you don't need to keep entering the command.
```
while true; do echo "$(date) $(aws --region us-west-1 controltower get-landing-zone-operation --operation-identifier 16bb47f7-b7a2-4d90-bc71-7df4ca1201xx | jq -r .operationDetails.status)"; sleep 15; done
```
**To show detailed information about your landing zone**
*Step 1. Find the ARN of the landing zone*
```
aws --region us-west-1 controltower list-landing-zones
```
Output will include the identifier of the landing zone, as shown in the following example of output.
```
{
"landingZones": [
{
"arn": "arn:aws:controltower:us-west-1:123456789012:landingzone/4B3H0ULNUOL2AXXX"
}
]
}
```
*Step 2. Get the information*
```
aws --region us-west-1 controltower get-landing-zone --landing-zone-identifier arn:aws:controltower:us-west-1:123456789012:landingzone/4B3H0ULNUOL2AXXX
```
Here's an example of the kind of output you may see:
```
{
"landingZone": {
"arn": "arn:aws:controltower:us-west-1:123456789012:landingzone/4B3H0ULNUOL2AXXX",
"driftStatus": {
"status": "IN_SYNC"
},
"latestAvailableVersion": "3.3",
"manifest": {
"accessManagement": {
"enabled": true
},
"securityRoles": {
"accountId": "9750XXXX4444"
},
"governedRegions": [
"us-west-1",
"us-west-2"
],
"organizationStructure": {
"sandbox": {
"name": "Sandbox"
},
"security": {
"name": "Security"
}
},
"centralizedLogging": {
"accountId": "012345678901",
"configurations": {
"loggingBucket": {
"retentionDays": 60
},
"accessLoggingBucket": {
"retentionDays": 60
}
},
"enabled": true
}
},
"status": "ACTIVE",
"version": "3.3"
}
}
```
**Step 6. (Optional) Call the `ListLandingZoneOperations` API to view the status of any operations that change your landing zone.**
To track the status of any landing zone operation, you can call the [ListLandingZoneOperations](lz-api-examples-short.md#list-lz-operations-api-examples) API.
# Landing zone schemas
A landing zone is an AWS resource, which is created by means of schemas. Each AWS Control Tower landing zone version has a unique schema.
The schemas for AWS Control Tower landing zones, version 3.1 and newer, are published in this reference section, to assist you in choosing a compatible version.
**Note**
A known issue regarding *unneccessary access logging* is present in landing zone version 3.0. The issue is addressed in landing zone version 3.1. For more information about the changes, see [AWS Control Tower landing zone version 3.1](2023-all.md#lz-3-1).
## Landing zone 4.0 schema
```
{
"type": "object",
"required": [],
"properties": {
"accessManagement": {
"$ref": "#/definitions/AccessManagement"
},
"backup": {
"$ref": "#/definitions/Backup"
},
"centralizedLogging": {
"$ref": "#/definitions/CentralizedLogging"
},
"governedRegions": {
"type": "array",
"items": {
"type": "string",
"maxLength": 24,
"minLength": 1,
"pattern": "^[a-z]{2}-[a-z\\-]*-[0-9]{1}$",
"additionalProperties": false
},
"additionalProperties": false
},
"securityRoles": {
"$ref": "#/definitions/SecurityRoles"
},
"config": {
"$ref": "#/definitions/Config"
}
},
"additionalProperties": false,
"definitions": {
"AccessManagement": {
"type": "object",
"required": [
"enabled"
],
"properties": {
"enabled": {
"type": "boolean",
"additionalProperties": false
}
},
"additionalProperties": false
},
"Backup": {
"type": "object",
"required": [
"enabled"
],
"properties": {
"configurations": {
"$ref": "#/definitions/BackupConfigurations"
},
"enabled": {
"type": "boolean",
"additionalProperties": false
}
},
"additionalProperties": false,
"if": {
"properties": {
"enabled": {
"const": true
}
}
},
"then": {
"required": [
"configurations"
]
}
},
"BackupAdminConfigurations": {
"type": "object",
"required": [
"accountId"
],
"properties": {
"accountId": {
"type": "string",
"maxLength": 12,
"minLength": 12,
"pattern": "^\\d{12}$",
"additionalProperties": false
}
},
"additionalProperties": false
},
"BackupConfigurations": {
"type": "object",
"required": [
"backupAdmin",
"centralBackup",
"kmsKeyArn"
],
"properties": {
"backupAdmin": {
"$ref": "#/definitions/BackupAdminConfigurations"
},
"centralBackup": {
"$ref": "#/definitions/CentralBackupConfigurations"
},
"kmsKeyArn": {
"type": "string",
"maxLength": 2048,
"minLength": 1,
"additionalProperties": false
}
},
"additionalProperties": false
},
"CentralBackupConfigurations": {
"type": "object",
"required": [
"accountId"
],
"properties": {
"accountId": {
"type": "string",
"maxLength": 12,
"minLength": 12,
"pattern": "^\\d{12}$",
"additionalProperties": false
}
},
"additionalProperties": false
},
"CentralizedLogging": {
"type": "object",
"required": [
"enabled"
],
"properties": {
"accountId": {
"type": "string",
"maxLength": 12,
"minLength": 12,
"pattern": "^\\d{12}$",
"additionalProperties": false
},
"configurations": {
"$ref": "#/definitions/LoggingConfigurations"
},
"enabled": {
"type": "boolean",
"additionalProperties": false
}
},
"additionalProperties": false,
"if": {
"properties": {
"enabled": {
"const": true
}
}
},
"then": {
"required": [
"accountId"
]
}
},
"LoggingConfigurations": {
"type": "object",
"properties": {
"accessLoggingBucket": {
"$ref": "#/definitions/S3BucketConfiguration"
},
"kmsKeyArn": {
"type": "string",
"maxLength": 2048,
"minLength": 1,
"additionalProperties": false
},
"loggingBucket": {
"$ref": "#/definitions/S3BucketConfiguration"
}
},
"additionalProperties": false
},
"S3BucketConfiguration": {
"type": "object",
"properties": {
"retentionDays": {
"type": "number",
"minimum": 1,
"additionalProperties": false
}
},
"additionalProperties": false
},
"SecurityRoles": {
"type": "object",
"required": [
"enabled"
],
"properties": {
"accountId": {
"type": "string",
"maxLength": 12,
"minLength": 12,
"pattern": "^\\d{12}$",
"additionalProperties": false
},
"enabled": {
"type": "boolean",
"additionalProperties": false
}
},
"additionalProperties": false,
"if": {
"properties": {
"enabled": {
"const": true
}
}
},
"then": {
"required": [
"accountId"
]
}
},
"Config": {
"type": "object",
"required": [
"enabled"
],
"properties": {
"accountId": {
"type": "string",
"maxLength": 12,
"minLength": 12,
"pattern": "^\\d{12}$",
"additionalProperties": false
},
"configurations": {
"$ref": "#/definitions/ConfigConfiguration"
},
"enabled": {
"type": "boolean",
"additionalProperties": false
}
},
"additionalProperties": false,
"if": {
"properties": {
"enabled": {
"const": true
}
}
},
"then": {
"required": [
"accountId"
]
}
},
"ConfigConfiguration": {
"type": "object",
"required": [],
"properties": {
"loggingBucket": {
"$ref": "#/definitions/S3BucketConfiguration"
},
"accessLoggingBucket": {
"$ref": "#/definitions/S3BucketConfiguration"
},
"kmsKeyArn": {
"type": "string",
"maxLength": 2048,
"minLength": 1,
"additionalProperties": false
}
}
}
}
}
```
## Landing zone 3.3 schema
```
{
"type": "object",
"required": [
"centralizedLogging",
"organizationStructure",
"securityRoles"
],
"properties": {
"accessManagement": {
"$ref": "#/definitions/AccessManagement"
},
"backup": {
"$ref": "#/definitions/Backup"
},
"centralizedLogging": {
"$ref": "#/definitions/CentralizedLogging"
},
"governedRegions": {
"type": "array",
"items": {
"type": "string",
"maxLength": 24,
"minLength": 1,
"pattern": "^[a-z]{2}-[a-z\\-]*-[0-9]{1}$",
"additionalProperties": false
},
"additionalProperties": false
},
"organizationStructure": {
"$ref": "#/definitions/OrganizationStructure"
},
"securityRoles": {
"$ref": "#/definitions/SecurityRoles"
}
},
"additionalProperties": false,
"definitions": {
"AccessManagement": {
"type": "object",
"required": [
"enabled"
],
"properties": {
"enabled": {
"type": "boolean",
"additionalProperties": false,
"default": true
}
},
"additionalProperties": false
},
"Backup": {
"type": "object",
"properties": {
"configurations": {
"$ref": "#/definitions/BackupConfigurations"
},
"enabled": {
"type": "boolean",
"additionalProperties": false,
"default": false
}
},
"additionalProperties": false,
"if": {
"properties": {
"enabled": {
"const": true
}
}
},
"then": {
"required": [
"configurations"
]
}
},
"BackupAdminConfigurations": {
"type": "object",
"required": [
"accountId"
],
"properties": {
"accountId": {
"type": "string",
"maxLength": 12,
"minLength": 12,
"pattern": "^\\d{12}$",
"additionalProperties": false
}
},
"additionalProperties": false
},
"BackupConfigurations": {
"type": "object",
"required": [
"backupAdmin",
"centralBackup",
"kmsKeyArn"
],
"properties": {
"backupAdmin": {
"$ref": "#/definitions/BackupAdminConfigurations"
},
"centralBackup": {
"$ref": "#/definitions/CentralBackupConfigurations"
},
"kmsKeyArn": {
"type": "string",
"maxLength": 2048,
"minLength": 1,
"additionalProperties": false
}
},
"additionalProperties": false
},
"CentralBackupConfigurations": {
"type": "object",
"required": [
"accountId"
],
"properties": {
"accountId": {
"type": "string",
"maxLength": 12,
"minLength": 12,
"pattern": "^\\d{12}$",
"additionalProperties": false
}
},
"additionalProperties": false
},
"CentralizedLogging": {
"type": "object",
"required": [
"accountId"
],
"properties": {
"accountId": {
"type": "string",
"maxLength": 12,
"minLength": 12,
"pattern": "^\\d{12}$",
"additionalProperties": false
},
"configurations": {
"$ref": "#/definitions/LoggingConfigurations"
},
"enabled": {
"type": "boolean",
"additionalProperties": false,
"default": true
}
},
"additionalProperties": false
},
"LoggingConfigurations": {
"type": "object",
"properties": {
"accessLoggingBucket": {
"$ref": "#/definitions/S3BucketConfiguration"
},
"kmsKeyArn": {
"type": "string",
"maxLength": 2048,
"minLength": 1,
"additionalProperties": false
},
"loggingBucket": {
"$ref": "#/definitions/S3BucketConfiguration"
}
},
"additionalProperties": false
},
"OrganizationalUnit": {
"type": "object",
"required": [
"name"
],
"properties": {
"name": {
"type": "string",
"maxLength": 120,
"minLength": 1,
"pattern": "^[\\s\\S]*$",
"additionalProperties": false
}
},
"additionalProperties": false
},
"OrganizationStructure": {
"type": "object",
"required": [
"security"
],
"properties": {
"sandbox": {
"$ref": "#/definitions/OrganizationalUnit"
},
"security": {
"$ref": "#/definitions/OrganizationalUnit"
}
},
"additionalProperties": false
},
"S3BucketConfiguration": {
"type": "object",
"properties": {
"retentionDays": {
"type": "number",
"minimum": 1,
"additionalProperties": false
}
},
"additionalProperties": false
},
"SecurityRoles": {
"type": "object",
"required": [
"accountId"
],
"properties": {
"accountId": {
"type": "string",
"maxLength": 12,
"minLength": 12,
"pattern": "^\\d{12}$",
"additionalProperties": false
}
},
"additionalProperties": false
}
}
}
```
## Landing zone 3.2 schema
```
{
"type": "object",
"required": [
"centralizedLogging",
"organizationStructure",
"securityRoles"
],
"properties": {
"accessManagement": {
"$ref": "#/definitions/AccessManagement"
},
"backup": {
"$ref": "#/definitions/Backup"
},
"centralizedLogging": {
"$ref": "#/definitions/CentralizedLogging"
},
"governedRegions": {
"type": "array",
"items": {
"type": "string",
"maxLength": 24,
"minLength": 1,
"pattern": "^[a-z]{2}-[a-z\\-]*-[0-9]{1}$",
"additionalProperties": false
},
"additionalProperties": false
},
"organizationStructure": {
"$ref": "#/definitions/OrganizationStructure"
},
"securityRoles": {
"$ref": "#/definitions/SecurityRoles"
}
},
"additionalProperties": false,
"definitions": {
"AccessManagement": {
"type": "object",
"required": [
"enabled"
],
"properties": {
"enabled": {
"type": "boolean",
"additionalProperties": false,
"default": true
}
},
"additionalProperties": false
},
"Backup": {
"type": "object",
"properties": {
"configurations": {
"$ref": "#/definitions/BackupConfigurations"
},
"enabled": {
"type": "boolean",
"additionalProperties": false,
"default": false
}
},
"additionalProperties": false,
"if": {
"properties": {
"enabled": {
"const": true
}
}
},
"then": {
"required": [
"configurations"
]
}
},
"BackupAdminConfigurations": {
"type": "object",
"required": [
"accountId"
],
"properties": {
"accountId": {
"type": "string",
"maxLength": 12,
"minLength": 12,
"pattern": "^\\d{12}$",
"additionalProperties": false
}
},
"additionalProperties": false
},
"BackupConfigurations": {
"type": "object",
"required": [
"backupAdmin",
"centralBackup",
"kmsKeyArn"
],
"properties": {
"backupAdmin": {
"$ref": "#/definitions/BackupAdminConfigurations"
},
"centralBackup": {
"$ref": "#/definitions/CentralBackupConfigurations"
},
"kmsKeyArn": {
"type": "string",
"maxLength": 2048,
"minLength": 1,
"additionalProperties": false
}
},
"additionalProperties": false
},
"CentralBackupConfigurations": {
"type": "object",
"required": [
"accountId"
],
"properties": {
"accountId": {
"type": "string",
"maxLength": 12,
"minLength": 12,
"pattern": "^\\d{12}$",
"additionalProperties": false
}
},
"additionalProperties": false
},
"CentralizedLogging": {
"type": "object",
"required": [
"accountId"
],
"properties": {
"accountId": {
"type": "string",
"maxLength": 12,
"minLength": 12,
"pattern": "^\\d{12}$",
"additionalProperties": false
},
"configurations": {
"$ref": "#/definitions/LoggingConfigurations"
},
"enabled": {
"type": "boolean",
"additionalProperties": false,
"default": true
}
},
"additionalProperties": false
},
"LoggingConfigurations": {
"type": "object",
"properties": {
"accessLoggingBucket": {
"$ref": "#/definitions/S3BucketConfiguration"
},
"kmsKeyArn": {
"type": "string",
"maxLength": 2048,
"minLength": 1,
"additionalProperties": false
},
"loggingBucket": {
"$ref": "#/definitions/S3BucketConfiguration"
}
},
"additionalProperties": false
},
"OrganizationalUnit": {
"type": "object",
"required": [
"name"
],
"properties": {
"name": {
"type": "string",
"maxLength": 120,
"minLength": 1,
"pattern": "^[\\s\\S]*$",
"additionalProperties": false
}
},
"additionalProperties": false
},
"OrganizationStructure": {
"type": "object",
"required": [
"security"
],
"properties": {
"sandbox": {
"$ref": "#/definitions/OrganizationalUnit"
},
"security": {
"$ref": "#/definitions/OrganizationalUnit"
}
},
"additionalProperties": false
},
"S3BucketConfiguration": {
"type": "object",
"properties": {
"retentionDays": {
"type": "number",
"minimum": 1,
"additionalProperties": false
}
},
"additionalProperties": false
},
"SecurityRoles": {
"type": "object",
"required": [
"accountId"
],
"properties": {
"accountId": {
"type": "string",
"maxLength": 12,
"minLength": 12,
"pattern": "^\\d{12}$",
"additionalProperties": false
}
},
"additionalProperties": false
}
}
}
```
## Landing zone 3.1 schema
```
{
"type": "object",
"required": [
"centralizedLogging",
"organizationStructure",
"securityRoles"
],
"properties": {
"accessManagement": {
"$ref": "#/definitions/AccessManagement"
},
"backup": {
"$ref": "#/definitions/Backup"
},
"centralizedLogging": {
"$ref": "#/definitions/CentralizedLogging"
},
"governedRegions": {
"type": "array",
"items": {
"type": "string",
"maxLength": 24,
"minLength": 1,
"pattern": "^[a-z]{2}-[a-z\\-]*-[0-9]{1}$",
"additionalProperties": false
},
"additionalProperties": false
},
"organizationStructure": {
"$ref": "#/definitions/OrganizationStructure"
},
"securityRoles": {
"$ref": "#/definitions/SecurityRoles"
}
},
"additionalProperties": false,
"definitions": {
"AccessManagement": {
"type": "object",
"required": [
"enabled"
],
"properties": {
"enabled": {
"type": "boolean",
"additionalProperties": false,
"default": true
}
},
"additionalProperties": false
},
"Backup": {
"type": "object",
"properties": {
"configurations": {
"$ref": "#/definitions/BackupConfigurations"
},
"enabled": {
"type": "boolean",
"additionalProperties": false,
"default": false
}
},
"additionalProperties": false,
"if": {
"properties": {
"enabled": {
"const": true
}
}
},
"then": {
"required": [
"configurations"
]
}
},
"BackupAdminConfigurations": {
"type": "object",
"required": [
"accountId"
],
"properties": {
"accountId": {
"type": "string",
"maxLength": 12,
"minLength": 12,
"pattern": "^\\d{12}$",
"additionalProperties": false
}
},
"additionalProperties": false
},
"BackupConfigurations": {
"type": "object",
"required": [
"backupAdmin",
"centralBackup",
"kmsKeyArn"
],
"properties": {
"backupAdmin": {
"$ref": "#/definitions/BackupAdminConfigurations"
},
"centralBackup": {
"$ref": "#/definitions/CentralBackupConfigurations"
},
"kmsKeyArn": {
"type": "string",
"maxLength": 2048,
"minLength": 1,
"additionalProperties": false
}
},
"additionalProperties": false
},
"CentralBackupConfigurations": {
"type": "object",
"required": [
"accountId"
],
"properties": {
"accountId": {
"type": "string",
"maxLength": 12,
"minLength": 12,
"pattern": "^\\d{12}$",
"additionalProperties": false
}
},
"additionalProperties": false
},
"CentralizedLogging": {
"type": "object",
"required": [
"accountId"
],
"properties": {
"accountId": {
"type": "string",
"maxLength": 12,
"minLength": 12,
"pattern": "^\\d{12}$",
"additionalProperties": false
},
"configurations": {
"$ref": "#/definitions/LoggingConfigurations"
},
"enabled": {
"type": "boolean",
"additionalProperties": false,
"default": true
}
},
"additionalProperties": false
},
"LoggingConfigurations": {
"type": "object",
"properties": {
"accessLoggingBucket": {
"$ref": "#/definitions/S3BucketConfiguration"
},
"kmsKeyArn": {
"type": "string",
"maxLength": 2048,
"minLength": 1,
"additionalProperties": false
},
"loggingBucket": {
"$ref": "#/definitions/S3BucketConfiguration"
}
},
"additionalProperties": false
},
"OrganizationalUnit": {
"type": "object",
"required": [
"name"
],
"properties": {
"name": {
"type": "string",
"maxLength": 120,
"minLength": 1,
"pattern": "^[\\s\\S]*$",
"additionalProperties": false
}
},
"additionalProperties": false
},
"OrganizationStructure": {
"type": "object",
"required": [
"security"
],
"properties": {
"sandbox": {
"$ref": "#/definitions/OrganizationalUnit"
},
"security": {
"$ref": "#/definitions/OrganizationalUnit"
}
},
"additionalProperties": false
},
"S3BucketConfiguration": {
"type": "object",
"properties": {
"retentionDays": {
"type": "number",
"minimum": 1,
"additionalProperties": false
}
},
"additionalProperties": false
},
"SecurityRoles": {
"type": "object",
"required": [
"accountId"
],
"properties": {
"accountId": {
"type": "string",
"maxLength": 12,
"minLength": 12,
"pattern": "^\\d{12}$",
"additionalProperties": false
}
},
"additionalProperties": false
}
}
}
```
# Launch a landing zone using CloudFormation
You can configure and launch a landing zone with CloudFormation either through the CloudFormation console, or through the AWS CLI. This section provides instructions and examples to launch a landing zone using APIs through CloudFormation.
**Topics**
+ [Prerequisites for launching a landing zone using CloudFormation](lz-apis-cfn-setup.md)
+ [Create a new landing zone using CloudFormation](lz-apis-cfn-launch.md)
+ [Manage an existing landing zone using CloudFormation](lz-apis-cfn-launch-existing.md)
# Prerequisites for launching a landing zone using CloudFormation
1. From the AWS CLI, use the AWS Organizations `CreateOrganization` API to create an organization and enable all features.
For more detailed instructions, review [Step 1: Configure your landing zone](lz-api-prereques.md).
1. From the CloudFormation console or using the AWS CLI, deploy a CloudFormation template that creates the following resources in the management account:
+ Log Archive account (sometimes called the "Logging" account)
+ Audit account (sometimes called the "Security" account)
+ The **AWSControlTowerAdmin**, **AWSControlTowerCloudTrailRole**, **AWSControlTowerConfigAggregatorRoleForOrganizations**, and **AWSControlTowerStackSetRole** service roles.
For information about how AWS Control Tower uses these roles to perform landing zone API calls, see [Step 1: Configure your landing zone](lz-api-prereques.md).
```
Parameters:
LoggingAccountEmail:
Type: String
Description: The email Id for centralized logging account
LoggingAccountName:
Type: String
Description: Name for centralized logging account
SecurityAccountEmail:
Type: String
Description: The email Id for security roles account
SecurityAccountName:
Type: String
Description: Name for security roles account
Resources:
MyOrganization:
Type: 'AWS::Organizations::Organization'
Properties:
FeatureSet: ALL
LoggingAccount:
Type: 'AWS::Organizations::Account'
Properties:
AccountName: !Ref LoggingAccountName
Email: !Ref LoggingAccountEmail
SecurityAccount:
Type: 'AWS::Organizations::Account'
Properties:
AccountName: !Ref SecurityAccountName
Email: !Ref SecurityAccountEmail
AWSControlTowerAdmin:
Type: 'AWS::IAM::Role'
Properties:
RoleName: AWSControlTowerAdmin
AssumeRolePolicyDocument:
Version: 2012-10-17
Statement:
- Effect: Allow
Principal:
Service: controltower.amazonaws.com
Action: 'sts:AssumeRole'
Path: '/service-role/'
ManagedPolicyArns:
- !Sub >-
arn:${AWS::Partition}:iam::aws:policy/service-role/AWSControlTowerServiceRolePolicy
AWSControlTowerAdminPolicy:
Type: 'AWS::IAM::Policy'
Properties:
PolicyName: AWSControlTowerAdminPolicy
PolicyDocument:
Version: 2012-10-17
Statement:
- Effect: Allow
Action: 'ec2:DescribeAvailabilityZones'
Resource: '*'
Roles:
- !Ref AWSControlTowerAdmin
AWSControlTowerCloudTrailRole:
Type: 'AWS::IAM::Role'
Properties:
RoleName: AWSControlTowerCloudTrailRole
AssumeRolePolicyDocument:
Version: 2012-10-17
Statement:
- Effect: Allow
Principal:
Service: cloudtrail.amazonaws.com
Action: 'sts:AssumeRole'
Path: '/service-role/'
AWSControlTowerCloudTrailRolePolicy:
Type: 'AWS::IAM::Policy'
Properties:
PolicyName: AWSControlTowerCloudTrailRolePolicy
PolicyDocument:
Version: 2012-10-17
Statement:
- Action:
- 'logs:CreateLogStream'
- 'logs:PutLogEvents'
Resource: !Sub >-
arn:${AWS::Partition}:logs:*:*:log-group:aws-controltower/CloudTrailLogs:*
Effect: Allow
Roles:
- !Ref AWSControlTowerCloudTrailRole
AWSControlTowerConfigAggregatorRoleForOrganizations:
Type: 'AWS::IAM::Role'
Properties:
RoleName: AWSControlTowerConfigAggregatorRoleForOrganizations
AssumeRolePolicyDocument:
Version: 2012-10-17
Statement:
- Effect: Allow
Principal:
Service: config.amazonaws.com
Action: 'sts:AssumeRole'
Path: '/service-role/'
ManagedPolicyArns:
- !Sub arn:${AWS::Partition}:iam::aws:policy/service-role/AWSConfigRoleForOrganizations
AWSControlTowerStackSetRole:
Type: 'AWS::IAM::Role'
Properties:
RoleName: AWSControlTowerStackSetRole
AssumeRolePolicyDocument:
Version: 2012-10-17
Statement:
- Effect: Allow
Principal:
Service: cloudformation.amazonaws.com
Action: 'sts:AssumeRole'
Path: '/service-role/'
AWSControlTowerStackSetRolePolicy:
Type: 'AWS::IAM::Policy'
Properties:
PolicyName: AWSControlTowerStackSetRolePolicy
PolicyDocument:
Version: 2012-10-17
Statement:
- Action: 'sts:AssumeRole'
Resource: !Sub 'arn:${AWS::Partition}:iam::*:role/AWSControlTowerExecution'
Effect: Allow
Roles:
- !Ref AWSControlTowerStackSetRole
Outputs:
LogAccountId:
Value:
Fn::GetAtt: LoggingAccount.AccountId
Export:
Name: LogAccountId
SecurityAccountId:
Value:
Fn::GetAtt: SecurityAccount.AccountId
Export:
Name: SecurityAccountId
```
# Create a new landing zone using CloudFormation
From the CloudFormation console or using the AWS CLI, deploy the following CloudFormation template to create a landing zone.
```
Parameters:
Version:
Type: String
Description: The version number of Landing Zone
GovernedRegions:
Type: Array
Description: List of governed regions
SecurityOuName:
Type: String
Description: The security Organizational Unit name
SandboxOuName:
Type: String
Description: The sandbox Organizational Unit name
CentralizedLoggingAccountId:
Type: String
Description: The AWS account ID for centralized logging
SecurityAccountId:
Type: String
Description: The AWS account ID for security roles
LoggingBucketRetentionPeriod:
Type: Number
Description: Retention period for centralized logging bucket
AccessLoggingBucketRetentionPeriod:
Type: Number
Description: Retention period for access logging bucket
KMSKey:
Type: String
Description: KMS key ARN used by CloudTrail and Config service to encrypt data in logging bucket
Resources:
MyLandingZone:
Type: 'AWS::ControlTower::LandingZone'
Properties:
Version:
Ref: Version
Tags:
- Key: "keyname1"
Value: "value1"
- Key: "keyname2"
Value: "value2"
Manifest:
governedRegions:
Ref: GovernedRegions
organizationStructure:
security:
name:
Ref: SecurityOuName
sandbox:
name:
Ref: SandboxOuName
centralizedLogging:
accountId:
Ref: CentralizedLoggingAccountId
configurations:
loggingBucket:
retentionDays:
Ref: LoggingBucketRetentionPeriod
accessLoggingBucket:
retentionDays:
Ref: AccessLoggingBucketRetentionPeriod
kmsKeyArn:
Ref: KMSKey
enabled: true
securityRoles:
accountId:
Ref: SecurityAccountId
accessManagement:
enabled: true
```
# Manage an existing landing zone using CloudFormation
You can use CloudFormation to manage a landing zone that you have already launched by importing the landing zone in a new or existing CloudFormation stack. Review [ Bringing existing resources into CloudFormation management](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/resource-import.html) for details and instructions.
To [detect and resolve drift within a landing zone](https://docs.aws.amazon.com/controltower/latest/userguide/drift.html), you can use the AWS Control Tower console, the AWS CLI, or the [`ResetLandingZone` API](lz-api-reset.md).