I was asked recently, “Can I store AWS LZA config files on GitHub?” The answer is ‘yes’ and I’ll endeavor to show you how on this post.
What is the AWS Landing Zone Accelerator?
The AWS Landing Zone Accelerator (LZA) is a solution designed to help organizations deploy a secure, compliant, and scalable AWS cloud foundation. Using the LZA provides centralized governance and management that aligns with AWS best practices and many global compliance frameworks, making the LZA a solution suitable for highly-regulated workloads.
The LZA integrates with other AWS services to enhance security, compliance, and operational efficiency. For example, the LZA leverages AWS CloudFormation and CodePipeline to deploy the necessary infrastructure and services. It may also use KMS for encryption, Control Tower to deploy a multi-region, multi-account AWS organization, Macie for sensitive data detection, and Security Hub and GuardDuty to detect and resolve security events.
What are the LZA Config Files?
The LZA uses the settings defined in several YAML configuration files as blueprints to setup and manage an AWS environment.
- accounts-config.yaml – manages the AWS accounts within an organization
- global-config.yaml – manages global properties that can be inherited across an organization
- iam-config.yaml – manages IAM resources (roles and policies)
- network-config.yaml – manages network resources (VPCs, TGWs, etc.). Honestly, I’ve never seen an extensive use of this file as clients tend to deploy everything beyond the organization level resources using Terraform for example. The most common setting I see enabled in this file is disabling the default VPC.
- organization-config.yaml – manages OUs, SCPs, backup and tagging policies
- security-config.yaml – manages AWS security services such as GuardDuty, Security Hub, Macie, and Config rules
Here’s a simple example of an accounts-config.yaml:
mandatoryAccounts:
- name: Management
description: >-
The management (primary) account. Do not change the name field for this
mandatory account. Note, the account name key does not need to match the
AWS account name.
email: aws.mgmt@virtualbonzo.com
organizationalUnit: Root
warm: false
- name: LogArchive
description: >-
The log archive account. Do not change the name field for this mandatory
account. Note, the account name key does not need to match the AWS account
name.
email: aws.log@virtualbonzo.com
organizationalUnit: Security
warm: false
- name: Audit
description: >-
The security audit account (also referred to as the audit account). Do not
change the name field for this mandatory account. Note, the account name
key does not need to match the AWS account name.
email: aws.audit@virtualbonzo.com
organizationalUnit: Security
warm: false
workloadAccounts:
- name: SharedServices
description: >-
The AWS Shared Services account
email: aws.sharedservices@virtualbonzo.com
organizationalUnit: Infrastructure
warm: false
- name: Network
description: >-
The AWS Network account
email: aws.network@virtualbonzo.com
organizationalUnit: Infrastructure
warm: falseBy default, the AWS LZA stores configuration files in an Amazon S3 bucket (in a single file named aws-accelerator-config.zip). For some environments, this approach may be suitable. Alternatively, the LZA configuration files can be stored in a version control system such as GitHub. Storing configuration files on GitHub offers advantages in terms of version control, collaboration, and auditing configuration changes compared to using an S3 bucket.
Prior to deploying the LZA solution, I suggest customizing the configuration files to align with your specific cloud foundation requirements and pushing them to a version control system. After the initial LZA deployment, use this same process for ongoing management of the AWS environment.
What do I push to the GitHub Repo?
This will be a quick section but I just wanted to point something out that got me the first time I tried to deploy the LZA using a GitHub repo. I mentioned earlier that if one simply deploys the LZA, an S3 bucket containing the file aws-accelerator-config.zip will be created. This zip file contains the LZA configuration files.
Not knowing any better, I had assumed that I needed to archive my customized YAML files as aws-accelerator-config.zip, and push them to the GitHub repo….this is totally wrong. As shown below, you will need to push the customized YAML files, as well as any relevant policy folders, to the repo.
Creating a CodePipeline “codeconnection”
Now that we have our LZA config files in a GitHub repo, we need to perform some work within AWS CodePipeline to make those files accessible to the AWSAccelerator-Pipeline. I’m going to show the steps that would be done through the GUI to visualize the process.
- Login to what will become the organizations Management account and open the CodePipeline service dashboard. Click Settings | Connections | Create connection.
- On the Create a connection page, select GitHub as the provider, enter a connection name, and then click Connect to GitHub
- On the Connect to GitHub page, you have an option. If App Installation is left blank, you will need to provide GitHub user credentials when the pipeline executes. If you would prefer not to do that, you can create a GitHub App that would connect to the repo as a bot, by clicking Install a new app. In this example, I’m going to create a GitHub App because they use short-lived tokens, can be configured with limited permissions, and they operate independently of user accounts, not requiring manual authentication for each pipeline run, making them ideal for automated workflows.
- After you click Install a new app, an Install & Authorize AWS Connector for GitHub window should appear. By default, this app will be authorized for all repositories. However, you should select Only select repositories and choose the repo containing the LZA configuration files. Click Install and Authorize.
- When returned to the Connect to GitHub page, there should be an 8-digit number representing the GitHub app within the App Installation option. Click Connect.
- On the main connection page, copy the ARN of the connection.
Deploying the LZA
I’m not going to go through the entire LZA process on this post, I just want to show you how to use the customized YAML files on GitHub when deploying the LZA using its CloudFormation template. To understand the LZA process more completely, review the LZA Deployment Guide.
Now, after you launch the LZA CFT, on the Specify stack details page, you’ll see the Config Repository Configuration settings. These are the options you must set to use the GitHub hosted LZA configuration files:
- Configuration Repository Location – codeconnection
- Use Existing Config Repository – Yes
- Existing Config Repository Name – match the GitHub repo name. In this case, my repo was called aws-lza, yours will likely be different.
- Existing Config Repository Branch Name – match the GitHub branch name you wish to use. In this case, I used the main branch but yours could be different
- Existing Config Repository Owner – match the owner ID or namespace of the LZA configuration repository. In this case, I used my balld0909 GitHub account to create a private GitHub repo to store the config files. Your repo owner will most certainly be different.
- Existing Config Repository CodeConnection ARN – paste the ARN of the codeconnection copied earlier
When the LZA kicks off, it begins a journey that includes the deployment of 20+ CloudFormation stacks. I believe its the 4th stack that creates the LZA pipeline. Once that stack launches, open the CodePipeline dashboard and click AWSAccelerator-Pipeline. You should see a “Source” box. If the Configuration option has a green check next to GitHub app, you should be good to go! I imagine there is a cooler way to verify it….
Wrap-up
Hopefully, by following these steps you will be able to store and manage your LZA configuration files using a version control system. This blog used GitHub but you can also use Bitbucket and GitLab…the steps should be very similar. Integrating a version control system with the LZA takes advantage of version control, collaboration, and auditing features, ensuring efficient management of the AWS environment.
If you are looking to dig deeper into the LZA, Adam has written a couple posts that you may find interesting as well. Check them out!
