# Architecture details
<a name="architecture-details"></a>

This section describes the components and AWS services that make up this solution and the architecture details on how these components work together.

## AWS services in this solution
<a name="aws-services-in-this-solution"></a>

For more information about services and features, see the [Included services features and configuration references](https://awslabs.github.io/landing-zone-accelerator-on-aws/latest/user-guide/config/).


| Core AWS services | Supporting AWS services | 
| --- | --- | 
|   [AWS CloudFormation](https://aws.amazon.com/cloudformation/)   |   [AWS Application Load Balancer](https://aws.amazon.com/elasticloadbalancing/application-load-balancer/)   | 
|   [Amazon CloudWatch](https://aws.amazon.com/cloudwatch/)   |   [AWS Autoscaling](https://aws.amazon.com/autoscaling/)   | 
|   [AWS CodeBuild](https://aws.amazon.com/codebuild/)   |   [AWS Backup](https://aws.amazon.com/backup/)   | 
|   [AWS CodeCommit](https://aws.amazon.com/codecommit/)   |   [AWS Budgets](https://aws.amazon.com/aws-cost-management/aws-budgets/)   | 
|   [AWS CodePipeline](https://aws.amazon.com/codepipeline/)   |   [AWS CloudTrail](https://aws.amazon.com/cloudtrail/)   | 
|   [Amazon DynamoDB](https://aws.amazon.com/dynamodb/)   |   [AWS Config](https://aws.amazon.com/config/)   | 
|   [Amazon EventBridge](https://aws.amazon.com/eventbridge/)   |   [AWS Control Tower](https://aws.amazon.com/controltower/)   | 
|   [AWS IAM](https://aws.amazon.com/iam/)   |   [AWS Cost and Usage Report](https://aws.amazon.com/aws-cost-management/aws-cost-and-usage-reporting/)   | 
|   [Amazon Kinesis](https://aws.amazon.com/kinesis/)   |   [AWS EC2](https://aws.amazon.com/ec2/)   | 
|   [AWS KMS](https://aws.amazon.com/kms/)   |   [Amazon Elastic Block Store (Amazon EBS)](https://aws.amazon.com/ebs/)   | 
|   [AWS Lambda](https://aws.amazon.com/lambda/)   |   [Amazon GuardDuty](https://aws.amazon.com/guardduty/)   | 
|   [Amazon S3](https://aws.amazon.com/s3/)   |   [AWS Lambda](https://aws.amazon.com/lambda/)   | 
|   [Amazon SNS](https://aws.amazon.com/sns)   |   [Amazon Macie](https://aws.amazon.com/macie/)   | 
|   [AWS Step Functions](https://aws.amazon.com/step-functions/)   |   [AWS Network Firewall](https://aws.amazon.com/network-firewall/)   | 
|  |   [AWS Network Load Balancer](https://aws.amazon.com/elasticloadbalancing/network-load-balancer/)   | 
|  |   [AWS Organizations](https://aws.amazon.com/organizations/)   | 
|  |   [AWS Resource Access Manager (RAM)](https://aws.amazon.com/ram/)   | 
|  |   [Amazon Route 53](https://aws.amazon.com/route53/)   | 
|  |   [AWS Secrets Manager](https://aws.amazon.com/secrets-manager/)   | 
|  |   [AWS Security Hub](https://aws.amazon.com/security-hub/)   | 
|  |   [Amazon Virtual Private Cloud (Amazon VPC)](https://aws.amazon.com/vpc/)   | 

# Installer pipeline
<a name="awsaccelerator-installer"></a>

This pipeline runs the following stages:

1.  **Source** - The Landing Zone Accelerator on AWS source code from the AWS Solutions [GitHub](https://github.com/awslabs/landing-zone-accelerator-on-aws) repository

1.  **Install** - A CodeBuild project is used to run the Landing Zone Accelerator on AWS pipeline CDK project, resulting in the deployment of the `AWSAccelerator-PipelineStack` 

**Note**  
The Landing Zone Accelerator on AWS Installer and Core pipelines are separate by design. The functionality of the `AWSAccelerator-InstallerStack` has been minimized to purely support deployment of the Core pipeline, `AWSAccelerator-Pipeline`. This will allow you to update your version of the Landing Zone Accelerator on AWS by updating a single parameter through the AWS CloudFormation update stack console. See [Update the solution](update-the-solution.md) for more information.

# Core pipeline
<a name="awsaccelerator-pipeline"></a>

The solution uses CodeBuild as an orchestration engine for each action completed after the **Source** stage in this pipeline. These actions run a CDK application, which deploys CloudFormation stacks across each of the Landing Zone Accelerator on AWS solution-managed AWS accounts and Regions, unless otherwise specified:

1.  **Source** - There are two source actions in this stage:
   +  **Source** - The Landing Zone Accelerator on AWS source code from the AWS Solutions [GitHub](https://github.com/awslabs/landing-zone-accelerator-on-aws) repository.
   +  **Configuration** - The Landing Zone Accelerator on AWS configuration repository, named `aws-accelerator-config`.

1.  **Build** - In this stage, the Landing Zone Accelerator on AWS source code is transpiled, including input and type validation for the configuration files.

1.  **Prepare** - Any AWS accounts that are defined in the configuration are created and/or validated as necessary. If using [AWS Control Tower](https://aws.amazon.com/controltower/), new AWS accounts are generated using the Control Tower Account Factory and enrolled into the proper [AWS Organizations](https://aws.amazon.com/organizations/) Organizational Unit (OU). We highly recommend that you use AWS Control Tower to generate and enroll new OUs. However, if you’re deploying the solution in an AWS Region that isn’t yet supported by AWS Control Tower, any OUs that are defined in the configuration are created and/or validated as necessary.

1.  **Accounts** - Additional account validation occurs across the environment. All accounts in the configuration are checked to verify if they’re part of the AWS Organization. Any configured AWS Organization Service Control Policies (SCPs) are also created and attached to configuration-specified deployment targets in this stage.

1.  **Bootstrap** - AWS CDK bootstrap is run; this initializes the environment for CDK. A solution-specific CDK toolkit CloudFormation template (`AWS Accelerator-CDKToolkit`) is deployed to any AWS accounts and Regions that haven’t been previously bootstrapped. If you want to deploy additional CDK applications, we recommend that you deploy your own CDK bootstrap template to avoid collisions with the Landing Zone Accelerator on AWS usage of CDK.

1.  **Review (optional)** - An optional stage that can be turned on and off using the **EnableApprovalStage** configuration parameter on the `AWSAccelerator-InstallerStack` CloudFormation template. Turning on this option adds this stage to the pipeline, which includes the following actions:
   +  **Diff** - AWS CDK diff is run on the synthesized CloudFormation templates against each target account and Region. The result of the diff can be reviewed in the build logs of the CodeBuild project.
   +  **Approve** - A manual approval action. This is meant as a gate to review and approve/deny the changes represented in the **Diff** action. This action publishes to an SNS topic to notify configured email list(s) of the pending approval.

1.  **Logging** - There are two actions in this stage:
   +  **Key** - The solution deploys two stacks during this stage:
     +  **KeyStack** - Deploys a centralized AWS KMS key to the AWS account designated as the audit account in the configuration. This key is used in subsequent deployments to activate encryption at-rest for applicable resources. The solution also deploys Systems Manager Parameter Store parameters containing the value of the key Amazon Resource Names (ARNs) along with an IAM role that allows cross-account read access for the parameters.
     +  **DependenciesStack** - Deploys resources that are required by the solution in subsequent pipeline stages, such as IAM roles for custom resources.
   +  **Logging** - This solution deploys a centralized logging Amazon S3 bucket, an Amazon Kinesis Data Stream, and Amazon Data Firehose in the AWS account designated as `LogArchive` in the configuration. The solution uses the Kinesis Data Stream as a destination for CloudWatch Logs groups in member accounts so that logs can be streamed to the central logs bucket via Firehose. Optionally, you can specify a dynamic partitioning configuration to map specific CloudWatch Log groups to specific Amazon S3 bucket prefixes.

     The solution creates Amazon S3 buckets for Amazon S3 server access logging in each AWS account and Region activated in the configuration. Optionally, you can activate the Amazon S3 Block Public Access feature at the account level and activate Systems Manager Session Manager logging for each configured account and Region.

     The solution also deploys AWS KMS keys for Amazon S3, [AWS Lambda](https://aws.amazon.com/lambda/), and CloudWatch Logs. These keys deploy in each AWS account and Region activated in the configuration. A solution-deployed Systems Manager automation document named `Accelerator-Put-S3-Encryption` uses the AWS KMS key for Amazon S3 to encrypt any Amazon S3 buckets that were created without encryption. The solution uses the AWS KMS key for Lambda to invoke Lambda environment variable encryption, and it uses the AWS KMS key for CloudWatch Logs to encrypt solution-created CloudWatch Logs groups.

1.  **Organization** - Deployment of AWS Organization-wide resources. These resources are deployed in the Region designated as the organization’s home Region in the organization’s management account. This includes actions such as activating trusted services, creating AWS Organizations tagging and backup policies, creating report definitions for [AWS Cost and Usage Report](https://aws.amazon.com/aws-cost-management/aws-cost-and-usage-reporting/), and [AWS Budgets](https://aws.amazon.com/aws-cost-management/aws-budgets/).

1.  **Security\$1Audit** - Deployment of resource dependencies for centralized security services in the AWS account designated as the audit account in the configuration. This includes S3 buckets and/or configurations for [Amazon Macie](https://aws.amazon.com/macie/), [Amazon GuardDuty](https://aws.amazon.com/guardduty/), [AWS Security Hub](https://aws.amazon.com/security-hub/), and Systems Manager automation documents.

1.  **Deploy** - The following actions are completed in this stage to deploy the remaining architecture as defined in the configuration files. Refer to our [sample configuration](https://github.com/awslabs/landing-zone-accelerator-on-aws/tree/main/reference/sample-configurations) as a reference to get started:
   +  **Network\$1Prepare** - Network resources that subsequent networking stacks must reference are created in this action. This includes AWS Transit Gateway and AWS Resource Access Manager (AWS RAM) shares, if configured.
   +  **Security** - Member account security services are configured.
   +  **Operations** - Users, groups, and roles are deployed. IAM [Security Assertion Markup Language](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_providers_create_saml.html) (SAML) identity provider configuration is also deployed, if configured.
   +  **Network\$1VPCs** - Three stacks are deployed during this stage, each related to VPC networking:
     +  **NetworkVpcStack** - VPCs, subnets, route tables, security groups and other associated resources are deployed. AWS Transit Gateway attachments are created, if configured.
     +  **NetworkVpcEndpointsStack** - VPC endpoints, including Route 53 resolver endpoints and AWS Network Firewall endpoints are deployed.
     +  **NetworkVpcDnsStack** - Route 53 private hosted zones and resolver rules are deployed.
   +  **Security\$1Resources** - Additional member account security services such as AWS Config, CloudWatch metrics, and alarms are deployed.
   +  **Network\$1Associations** - The solution deploys two stacks during this stage, each related to network associations that depend on resources created in the **Network\$1VPCs** stage:
     +  **NetworkAssociationsStack** - Network associations that depend on Amazon VPC resources to be created, such as AWS Transit Gateway VPC associations, are deployed.
     +  **NetworkAssociationsGwlbStack** - Network associations that depend on Gateway Load Balancers to be created, such as Gateway Load Balancer VPC endpoints, are deployed.
   +  **Customizations (optional)** - The solution deploys custom applications, CloudFormation stacks, and CloudFormation stacksets that are configured in the `customizations-config.yaml` file.
   +  **Finalize** - If using the account quarantine feature for new account creation, the quarantine SCP is removed during this action.

# Pipeline artifact Amazon S3 buckets
<a name="pipeline-artifact-amazon-s3-buckets"></a>

Two Amazon S3 buckets are created with the solution by default. These buckets are used to host artifacts for the CodePipeline pipelines. If desired, you can delete artifacts after the pipeline invocations have completed. However, don’t delete the buckets themselves because this breaks the functionality of the pipelines. For more information, refer to [Input and output artifacts](https://docs.aws.amazon.com/codepipeline/latest/userguide/welcome-introducing-artifacts.html) in the *AWS CodePipeline User Guide*.

# Amazon SNS topics
<a name="amazon-sns-topics"></a>

Two Amazon SNS topics are created with the solution by default. One topic is to notify on all `AWSAccelerator-Pipeline` pipeline events. The second notifies only on `AWSAccelerator-Pipeline` pipeline failures. You can choose to subscribe to these topics to increase the observability of your pipeline operations. For more information, refer to [Subscribing to an Amazon SNS topic](https://docs.aws.amazon.com/sns/latest/dg/sns-create-subscribe-endpoint-to-topic.html) in the *Amazon SNS Developer Guide*.

An optional third Amazon SNS topic is created if the **EnableApprovalStage** parameter is set to `Yes` in the **AWSAccelerator-InstallerStack**. You can provide a comma-delimited list of email addresses in the **ApprovalStageNotifyEmailList** parameter to automatically subscribe to this Amazon SNS topic.

# Account creation and drift detection
<a name="account-creation-and-drift-detection"></a>

 **AWS account creation and management workflow with EventBridge, Lambda, DynamoDB, and other services.** 

![\[image4\]](http://docs.aws.amazon.com/solutions/latest/landing-zone-accelerator-on-aws/images/image4.png)


1. The solution deploys [Amazon EventBridge](https://aws.amazon.com/eventbridge/) rules that monitor for AWS Control Tower lifecycle events. These rules invoke AWS Lambda functions that perform different actions based on the lifecycle event. The solution uses the `AttachQuarantineScp` function to attach an AWS Organizations SCP to newly-enrolled accounts, if configured. The solution uses the `ControlTowerOuEvents` function to detect changes made to OUs in the multi-account environment.

1. The Lambda functions have access to [Amazon DynamoDB](https://aws.amazon.com/dynamodb/) tables that contain stateful information about the multi-account environment. The functions use this data to validate changes made to the environment against a known good state.

1. The account creation workflow is invoked by the **Prepare** stage of the `AWSAccelerator-Pipeline` when a new account is added to the `accounts-config.yaml` file. Two [AWS Step Functions](https://aws.amazon.com/step-functions/) state machines handle this workflow: one for AWS Control Tower-based landing zones and the other for AWS Organizations-based landing zones.

1. The state machines have access to DynamoDB tables that contain stateful information about the multi-account environment. This allows the underlying Lambda functions to validate the environment and store the environment’s state in the DynamoDB tables.

1. The state machines initiate the account creation process if a new account is added to the solution configuration. The account creation workflow is dependent on the type of landing zone that the solution has been deployed to. For AWS Control Tower-based landing zones, the solution leverages the [Control Tower Account Factory](https://docs.aws.amazon.com/controltower/latest/userguide/account-factory.html) Service Catalog portfolio to provision a new account. For AWS Organizations-based landing zones, the Organizations API invokes account creation. We provide configuration toggles to differentiate the type of landing zone in the `global-config.yaml` file.

**Note**  
Account creation is an asynchronous process, so the state machine workflow is used to periodically check the status of the Account Factory or Organizations-based account creation. As such, the state machine pauses the pipeline stage progression until the account creation succeeds or fails.

# Centralized logging
<a name="centralized-logging"></a>

 **AWS log archiving architecture with EventBridge, Lambda, Kinesis, and S3 components.** 

![\[image5\]](http://docs.aws.amazon.com/solutions/latest/landing-zone-accelerator-on-aws/images/image5.png)


1. A CloudWatch log group update workflow runs during the **Logging** stage of the pipeline. A CloudFormation custom resource invokes a Lambda function that updates existing log groups to the increase log retention if it’s less than the solution log retention period, CloudWatch AWS KMS key, and subscription filter. The destination for the subscription filter is an Amazon Kinesis Data Stream deployed to the **Log Archive** account. For example, before solution is installed if there are existing log groups `LogGroupA` with 5 years retention and `LogGroupB` with 1 week retention. The solution is deployed with 1 year retention in global-config.yaml under `cloudwatchLogRetentionInDays`. Then `LogGroupA` will be unaffected with the update since 5 years is greater than 1 year but `LogGroupB` retention will change to 1 year. If in a subsequent update or initial update, solution is deployed with 10 years retention in global-config.yaml under `cloudwatchLogRetentionInDays`, then both log groups will change retention to 10 years.

1. An EventBridge rule monitors for new CloudWatch log groups created in core and workload accounts.

1. When new log groups are created, the EventBridge rule invokes a Lambda function that updates the log group with the configured log retention period, CloudWatch AWS KMS key, and subscription filter. The destination for the subscription filter is the Kinesis Data Stream deployed to the **Log Archive** account. Since log replication to s3 is active, any CreateLogGroup API call will get the retention specified in global-config.yaml under `cloudwatchLogRetentionInDays`. So if `cloudwatchLogRetentionInDays` is set to 1 week and new log group is created with 5 year retention then it will change to 1 week. The solution ensures that entire organization’s CloudWatch retention for any new log group is compliant under the value specified in global-config.yaml under `cloudwatchLogRetentionInDays`.

1. Log groups stream their logs to the Kinesis Data Stream. The data stream is encrypted at rest with the replication AWS KMS key.

1. A delivery stream is configured with the Kinesis Data Stream and Firehose, allowing the logs to be transformed and replicated to Amazon S3.

1. The destination of the Firehose delivery stream is the `aws-accelerator-central-logs` Amazon S3 bucket. This bucket is encrypted at rest with the central logging AWS KMS key. In addition, the `aws-accelerator-s3-access-logs` and `aws-accelerator-elb-access-logs` buckets are encrypted at rest with Amazon S3-managed server-side encryption (SSE-S3) because these services don’t support customer-managed AWS KMS keys. Logs delivered to the `aws-accelerator-elb-access-logs` bucket replicate to the central logs bucket with Amazon S3 replication.

# Key management
<a name="key-management"></a>

 **Architecture diagram showing key management for accounts.** 

![\[image6\]](http://docs.aws.amazon.com/solutions/latest/landing-zone-accelerator-on-aws/images/image6.png)


The solution uses AWS KMS keys to provide encryption at rest capabilities for resources deployed by the solution. Some AWS KMS keys are deployed to every account and Region managed by the solution, while others are centralized in a single core account.

## All accounts
<a name="all-accounts"></a>
+  **Amazon CloudWatch key** - used to encrypt CloudWatch Logs groups created by the solution
+  **Amazon S3 key** - used to encrypt Amazon S3 buckets created by the solution
+  **AWS Lambda key** - used to encrypt environment variables for Lambda functions created by the solution
+  **AWS Systems Manager Session Manager key (optional)** - used to encrypt [Session Manager](https://docs.aws.amazon.com/systems-manager/latest/userguide/session-manager.html) sessions if Session Manager logging is activated in the `global-config.yaml` file
+  **Amazon Elastic Block Store (Amazon EBS) key (optional)** - used for default encryption of Amazon EBS volumes if activated in the `security-config.yaml` file

## Management account
<a name="management-account"></a>
+  **Installer key** - created by `AWSAccelerator-InstallerStack` to activate encryption at rest for Installer pipeline dependencies
+  **Management key** - created by `AWSAccelerator-PipelineStack` to activate encryption at rest for Core pipeline dependencies
+  **AWS Backup key (optional)** - used to activate encryption at rest for [AWS Backup](https://aws.amazon.com/backup/) vault if configured in the `organization-config.yaml` file

## LogArchive account
<a name="logarchive-account"></a>
+  **Central logs key** - used to encrypt the `aws-accelerator-central-logs` Amazon S3 bucket
**Note**  
This key is distinct from the per-account/Region key because additional services such as Config, CloudTrail, and log delivery require access. Macie, GuardDuty, and Audit Manager might also require access, if activated.
+  **Log replication key** - used to encrypt a Kinesis Data Stream used as a destination for log replication from CloudWatch Logs to Amazon S3

## Audit account
<a name="audit-account"></a>
+  **Accelerator KMS key** - used by the entire organization to decrypt AWS Systems Manager parameters (SSM parameters) stored centrally in the **Audit** account
+  **Audit S3 key** - used to encrypt authorize-created CloudTrail Amazon S3 buckets and Audit Manager publishing bucket, if configured
+  **Amazon SNS key (optional)** - used to encrypt Amazon SNS topics created to alert on security events, if configured