How aws/lza-universal-configuration works
This repository is not an application runtime; it is a configuration and documentation package for deploying AWS Landing Zone Accelerator (LZA) Universal Configuration. The architectural boundary is “source configuration in Git” on one side, and “generated LZA deployment inputs that provision AWS organization and network guardrails” on the other.
1. Core purpose
• The repo defines a standardized multi-account AWS foundation.
• It is organized as reusable configuration modules plus operational guidance.
• The resulting artifacts are intended to be consumed by LZA, which then orchestrates AWS service provisioning and policy enforcement.
2. Top-level structure
• docs/ contains the architecture, onboarding, governance, security, networking, logging, and operations guidance.
• modules/ contains the actual deployable configuration inputs.
• replacements/ contains region-specific substitution files.
• scripts/ contains Node.js tooling used to transform/package configuration for release and deployment.
• .gitlab-ci.yml indicates CI/CD automation around packaging or validation.
3. Base governance and organization subsystem
• modules/base/default/ is the foundation layer.
• It includes organization-wide definitions such as:
- account structure (accounts-config.yaml, organization-config.yaml)
- global and security settings (global-config.yaml, security-config.yaml)
- IAM settings and sample policies
- tagging policies
- service control policies and resource control policies
- replacement configuration and VPC endpoint policies
• This layer represents the control-plane boundary for the AWS Organization and account governance.
4. Security and compliance controls
• The base module also bundles security-related implementation assets:
- declarative policies
- SCP/RCP guardrails
- IAM policy examples
- backup plans
- event bus policies
- dynamic log partitioning filters
• These are not application security features; they are preventive and detective controls applied at the organization/account layer.
5. Operational automation artifacts
• The base module contains SSM documents and remediation roles for operational fixes and guardrail enforcement:
- attaching IAM instance profiles
- enabling ELB logging
• This suggests the repo supports not just initial provisioning, but ongoing drift correction and operational remediation.
6. Networking subsystem
• modules/network/ holds the network architecture patterns.
• Two distinct patterns are provided:
- hub-and-spoke/
- shared-vpc/
• Each includes a network-config.yaml and firewall rule definitions.
• This cleanly separates organization/governance from network topology, allowing alternate network models without changing the base controls.
7. Regional specialization
• replacements/replacements-for-aws-govcloud-us.yaml indicates that some settings are parameterized or substituted for specific AWS partitions/regions.
• This shows the repo is designed for portability across environments while keeping a common baseline.
8. Documentation as an architectural layer
• The docs/ tree is structured to match the solution’s major domains:
- overview
- getting started
- management/governance
- security/identity/compliance
- networking
- logging/monitoring
- operations
- region/industry guidance
• The docs are effectively the design contract for how the configuration modules should be interpreted and operated.
9. Tooling and transformation pipeline
• scripts/config-replacer.js, scripts/release-package.js, and related Node.js package files indicate a preprocessing/release stage.
• These scripts likely handle configuration substitution, packaging, and release artifact assembly before LZA consumption.
• This is a build-time concern, not a runtime service.
10. CI/CD boundary
• .gitlab-ci.yml shows the repo is meant to be validated and packaged through GitLab CI.
• The pipeline sits between source config and deployment-ready artifacts, supporting repeatable multi-environment delivery.
11. External platform dependencies that shape the architecture
• The repo is built around AWS Landing Zone Accelerator and commonly integrates with AWS Control Tower.
• The config content explicitly targets AWS services such as CloudTrail, Security Hub, GuardDuty, KMS, Network Firewall, CloudWatch, S3, Kinesis, Firehose, and others.
• These services are central because the configuration modules encode their baseline usage and guardrails.
12. Data flow from source to deployed environment
• Engineers edit YAML/JSON/ASL-style artifacts in modules/ and replacements/.
• Scripts and CI process the inputs into deployable configuration packages.
• LZA consumes those packages to create or update AWS Organizations, accounts, security controls, logging, and network infrastructure.
• The deployed environment then generates operational telemetry and compliance posture that the docs assume operators will manage.
13. Architectural takeaway
• The repository is a layered configuration system:
- governance baseline at the core
- optional network topology modules beside it
- region-specific replacements for portability
- scripts/CI for packaging
- docs for operational and architectural intent
• For an architecture diagram, the main boxes are “Source Config Repo,” “Transformation/Packaging,” “LZA Deployment,” and “AWS Landing Zone resources,” with the repo’s module boundaries split into governance and networking.
Main entry points: default Base Config · network Network Modules · docs Docs · .gitlab-ci.yml GitLab CI
Components 17
Repo
Source configuration, packaging, and documentation in Git
- Docs · Architecture, onboarding, operations, and domain guidance
docs - Base Config · Foundation layer for organization-wide settings and guardrails
modules/base/default - Accounts · Account and organization structure definitions
modules/base/default/accounts-config.yaml - Global Settings · Global and security-wide configuration
modules/base/default/global-config.yaml - IAM Config · IAM settings and policy inputs
modules/base/default/iam-config.yaml - Guardrails · SCPs, RCPs, tagging, declarative, event bus, and endpoint policies
modules/base/default/service-control-policies - Ops Assets · SSM documents and remediation roles for drift correction
modules/base/default/ssm-documents - Network Modules · Alternative landing zone network topologies
modules/network - Hub-Spoke · Centralized network pattern with firewall rules
modules/network/hub-and-spoke/network-config.yaml - Shared VPC · Shared VPC network pattern with firewall rules
modules/network/shared-vpc/network-config.yaml - Replacements · Region and partition substitutions for portability
replacements/replacements-for-aws-govcloud-us.yaml - Scripts · Node.js tooling for substitution and release packaging
scripts - GitLab CI · Validation and packaging automation
.gitlab-ci.yml
External
Downstream deployment platform and AWS landing zone outputs
- LZA Package · Generated configuration consumed by Landing Zone Accelerator
- AWS Org · AWS Organizations, accounts, and governance baseline
- AWS Network · Provisioned network topology and firewall controls
- AWS Controls · Provisioned security, logging, compliance, and remediation services
Connections 20
- Docs → Base Config: describes · Documentation explains the governance and deployment modules
- Docs → Network Modules: describes · Documentation explains network patterns and operations
- Base Config → Accounts: contains · Base module includes organization and account structure
- Base Config → Global Settings: contains · Base module includes global configuration
- Base Config → IAM Config: contains · Base module includes IAM settings
- Base Config → Guardrails: contains · Base module bundles guardrail and policy inputs
- Base Config → Ops Assets: contains · Base module includes operational remediation assets
- Network Modules → Hub-Spoke: has · Network subsystem provides hub-and-spoke pattern
- Network Modules → Shared VPC: has · Network subsystem provides shared VPC pattern
- Replacements → Base Config: specializes · Partition-specific substitutions adjust base config
- Scripts → LZA Package: packages · Scripts transform configuration into deployable inputs
- GitLab CI → Scripts: runs · CI executes packaging and validation tooling
- GitLab CI → LZA Package: produces · Pipeline emits deployment-ready package artifacts
- LZA Package → AWS Org: provisions · LZA applies organization and account governance
- LZA Package → AWS Network: provisions · LZA applies selected network topology and firewall rules
- LZA Package → AWS Controls: provisions · LZA provisions security, logging, and remediation controls
- Guardrails → LZA Package: feeds · Guardrail policies are consumed during deployment
- Hub-Spoke → LZA Package: feeds · Hub-and-spoke network config is consumed during deployment
- Shared VPC → LZA Package: feeds · Shared VPC network config is consumed during deployment
- Ops Assets → AWS Controls: remediates · Operational assets support drift correction in the landing zone