From e02821d3d8fe974aa414b4948197685daac880a6 Mon Sep 17 00:00:00 2001 From: Patrick de Ruiter Date: Sat, 1 Nov 2025 10:19:32 +0100 Subject: [PATCH] Add comprehensive README and update module documentation --- .gitignore | 0 README.md | 312 +++++++++++++++++++++++++++++++++++++++++++++++- backend.tf | 0 landing-zone.tf | 0 main.tf | 0 outputs.tf | 0 provider.tf | 0 variables.tf | 0 versions.tf | 0 9 files changed, 311 insertions(+), 1 deletion(-) mode change 100644 => 100755 .gitignore mode change 100644 => 100755 README.md mode change 100644 => 100755 backend.tf mode change 100644 => 100755 landing-zone.tf mode change 100644 => 100755 main.tf mode change 100644 => 100755 outputs.tf mode change 100644 => 100755 provider.tf mode change 100644 => 100755 variables.tf mode change 100644 => 100755 versions.tf diff --git a/.gitignore b/.gitignore old mode 100644 new mode 100755 diff --git a/README.md b/README.md old mode 100644 new mode 100755 index c414d3a..4ffaa1c --- a/README.md +++ b/README.md @@ -1 +1,311 @@ -# terraform-aws-master +# Terraform AWS Master Account Module + +## Overview + +This Terraform module provisions an AWS Landing Zone using the MitocGroup AWS Landing Zone module. It provides a foundation for multi-account AWS environments with best practices for security, compliance, and operational efficiency. + +## Features + +- AWS Landing Zone deployment via MitocGroup module +- Multi-account environment configuration +- Landing Zone components configuration +- AWS provider configuration management +- Terraform backend configuration support +- Organization-wide governance + +## Resources Created + +The module leverages the MitocGroup Landing Zone module which creates: +- AWS Organizations structure +- Core accounts (log archive, audit, security) +- AWS Config for compliance +- AWS CloudTrail for audit logging +- AWS Service Catalog +- AWS SSO configuration (optional) +- VPC configurations +- Baseline security controls + +## Usage + +### Basic Example + +```hcl +module "master_account" { + source = "git@github.com:webuildyourcloud/terraform-aws-masteraccount.git" + + # Organization Settings + organization = "mycompany" + environment = "production" + region = "us-east-1" + + # Availability Zones + availability-zone-names = ["us-east-1a", "us-east-1b", "us-east-1c"] + + # Landing Zone Providers Configuration + landing_zone_providers = { + default = { + region = "us-east-1" + } + master = { + region = "us-east-1" + alias = "master" + } + } + + # Landing Zone Components + landing_zone_components = { + landing_zone_pipeline_s3_bucket = "enabled" + landing_zone_vpc = "enabled" + landing_zone_vpc_flow_logs = "enabled" + landing_zone_config = "enabled" + landing_zone_cloudtrail = "enabled" + landing_zone_organization = "enabled" + } + + # Terraform Configuration + terraform_config = true +} +``` + +### Advanced Example with Custom Components + +```hcl +module "master_account" { + source = "git@github.com:webuildyourcloud/terraform-aws-masteraccount.git" + + organization = "enterprise" + environment = "prod" + region = "eu-west-1" + + availability-zone-names = [ + "eu-west-1a", + "eu-west-1b", + "eu-west-1c" + ] + + landing_zone_providers = { + default = { + region = "eu-west-1" + profile = "default" + } + master = { + region = "eu-west-1" + alias = "master" + profile = "master" + } + logging = { + region = "eu-west-1" + alias = "logging" + profile = "logging" + } + security = { + region = "eu-west-1" + alias = "security" + profile = "security" + } + } + + landing_zone_components = { + # Core Infrastructure + landing_zone_pipeline_s3_bucket = "enabled" + landing_zone_vpc = "enabled" + landing_zone_vpc_flow_logs = "enabled" + landing_zone_subnet = "enabled" + + # Security & Compliance + landing_zone_config = "enabled" + landing_zone_cloudtrail = "enabled" + landing_zone_guardduty = "enabled" + landing_zone_security_hub = "enabled" + + # Governance + landing_zone_organization = "enabled" + landing_zone_service_catalog = "enabled" + + # Monitoring + landing_zone_cloudwatch = "enabled" + } + + terraform_config = true +} +``` + +## Variables + +| Name | Description | Type | Default | Required | +|------|-------------|------|---------|----------| +| organization | Organization Name | `string` | n/a | yes | +| environment | Environment Name | `string` | n/a | yes | +| region | Default Region to set | `string` | n/a | yes | +| availability-zone-names | List of Availability zone names | `list(string)` | n/a | yes | +| landing_zone_providers | List of AWS providers for Landing Zone | `map(map(string))` | n/a | yes | +| landing_zone_components | List of AWS Landing Zone components to deploy | `map(string)` | n/a | yes | +| terraform_config | Generate terraform config file | `bool` | `true` | no | + +## Outputs + +The module outputs are determined by the MitocGroup Landing Zone module based on the enabled components. Common outputs include: +- Organization ID +- Account IDs for each created account +- VPC IDs and configurations +- CloudTrail configuration +- S3 bucket names + +## Requirements + +| Name | Version | +|------|---------| +| terraform | >= 0.13 | +| aws | Latest | + +## Dependencies + +- [MitocGroup/landing-zone/aws](https://registry.terraform.io/modules/MitocGroup/landing-zone/aws) version 0.2.5 + +## Landing Zone Components + +The following components can be enabled/disabled via `landing_zone_components`: + +### Core Infrastructure +- `landing_zone_pipeline_s3_bucket` - S3 bucket for pipeline artifacts +- `landing_zone_vpc` - VPC configuration +- `landing_zone_vpc_flow_logs` - VPC Flow Logs +- `landing_zone_subnet` - Subnet configuration + +### Security & Compliance +- `landing_zone_config` - AWS Config for compliance +- `landing_zone_cloudtrail` - CloudTrail for audit logging +- `landing_zone_guardduty` - GuardDuty threat detection +- `landing_zone_security_hub` - Security Hub +- `landing_zone_access_analyzer` - IAM Access Analyzer + +### Governance +- `landing_zone_organization` - AWS Organizations +- `landing_zone_service_catalog` - Service Catalog +- `landing_zone_sso` - AWS SSO configuration + +### Monitoring +- `landing_zone_cloudwatch` - CloudWatch configuration +- `landing_zone_sns` - SNS topics for notifications + +## Provider Configuration + +The `landing_zone_providers` map configures multiple AWS providers for different accounts: + +```hcl +landing_zone_providers = { + default = { + region = "us-east-1" + profile = "default" + } + master = { + region = "us-east-1" + alias = "master" + profile = "master-account" + } + logging = { + region = "us-east-1" + alias = "logging" + profile = "logging-account" + } +} +``` + +## Important Notes + +1. **Master Account**: This module should only be run in the AWS master/management account +2. **Organization Creation**: Running this will create an AWS Organization if one doesn't exist +3. **Destructive Changes**: Be cautious with changes as they may affect the entire organization +4. **Initial Setup**: First-time deployment can take 30-60 minutes +5. **Prerequisites**: Ensure appropriate IAM permissions and email addresses for account creation +6. **Cost**: Landing Zone components incur charges (CloudTrail, Config, VPC, etc.) +7. **State Management**: Use remote state backend for production deployments + +## Best Practices + +1. **Separate State**: Use a dedicated S3 backend for Landing Zone state +2. **Version Control**: Track all Landing Zone configuration changes in Git +3. **Email Addresses**: Prepare unique email addresses for each AWS account +4. **Access Control**: Implement strict IAM policies for Landing Zone management +5. **Change Management**: Use a formal change control process for Landing Zone modifications +6. **Documentation**: Maintain documentation of your Landing Zone architecture +7. **Testing**: Test Landing Zone changes in a non-production environment first +8. **Monitoring**: Set up CloudWatch alarms for Landing Zone resources + +## Multi-Account Strategy + +The Landing Zone typically creates: + +### Core Accounts +1. **Master/Management Account**: Organization root +2. **Log Archive Account**: Centralized logging +3. **Audit Account**: Security and compliance +4. **Shared Services Account**: Common resources + +### Workload Accounts +- Development +- Staging +- Production +- Sandbox + +## Security Considerations + +1. **Root Account**: Secure the master account root credentials +2. **MFA**: Enable MFA on all privileged accounts +3. **SCPs**: Implement Service Control Policies for governance +4. **CloudTrail**: Ensure CloudTrail is enabled across all accounts +5. **Config**: Use AWS Config for compliance monitoring +6. **GuardDuty**: Enable GuardDuty in all regions and accounts +7. **Access**: Use AWS SSO or IAM Identity Center for user access +8. **Encryption**: Enable encryption for all data at rest and in transit + +## Compliance + +Landing Zone helps achieve compliance with: +- CIS AWS Foundations Benchmark +- NIST 800-53 +- PCI DSS +- HIPAA +- SOC 2 +- ISO 27001 + +## Troubleshooting + +### Organization already exists +- If an organization already exists, import it into Terraform state +- Or disable the organization component + +### Email address already in use +- Each AWS account requires a unique email address +- Use email aliasing (e.g., aws+dev@company.com) + +### Insufficient permissions +- Ensure the IAM principal has permissions to: + - Create and manage AWS Organizations + - Create AWS accounts + - Deploy CloudFormation StackSets + - Create IAM roles and policies + +### Component conflicts +- Some components may conflict with existing resources +- Review and disable conflicting components + +## Migration Considerations + +When migrating to Landing Zone: +1. Inventory existing accounts and resources +2. Plan account structure and hierarchy +3. Map existing accounts to Landing Zone structure +4. Import existing resources into Terraform state +5. Gradually enable Landing Zone components +6. Validate compliance and security controls + +## Support + +For issues with the underlying Landing Zone module: +- [MitocGroup Landing Zone GitHub](https://github.com/MitocGroup/terraform-aws-landing-zone) +- [AWS Landing Zone Documentation](https://aws.amazon.com/solutions/implementations/aws-landing-zone/) + +## License + +This module is provided as-is for use within your organization. diff --git a/backend.tf b/backend.tf old mode 100644 new mode 100755 diff --git a/landing-zone.tf b/landing-zone.tf old mode 100644 new mode 100755 diff --git a/main.tf b/main.tf old mode 100644 new mode 100755 diff --git a/outputs.tf b/outputs.tf old mode 100644 new mode 100755 diff --git a/provider.tf b/provider.tf old mode 100644 new mode 100755 diff --git a/variables.tf b/variables.tf old mode 100644 new mode 100755 diff --git a/versions.tf b/versions.tf old mode 100644 new mode 100755