Add comprehensive README and update module documentation

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.