terraform-aws-masteraccount/README.md

# 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.