# AWS Infrastructure Setup

Comprehensive guide for setting up and managing AWS infrastructure for the
Lilith platform.

## Table of Contents

- [Account Structure](#account-structure)
- [Prerequisites](#prerequisites)
- [IAM Configuration](#iam-configuration)
- [Regional Strategy](#regional-strategy)
- [Cost Management](#cost-management)
- [Security Configuration](#security-configuration)
- [Compliance & Auditing](#compliance--auditing)

## Account Structure

### Recommended Multi-Account Setup

```
AWS Organization
├── Root Account (billing only)
│   └── Organizations management
│   └── Consolidated billing
│
├── Security Account
│   ├── AWS Config aggregator
│   ├── CloudTrail (organization trail)
│   ├── GuardDuty administrator
│   └── Security Hub
│
├── Development Account
│   ├── lilith-dev EKS cluster
│   ├── Dev RDS instances
│   └── Development VPC
│
├── Staging Account
│   ├── lilith-staging EKS cluster
│   ├── Staging RDS instances
│   └── Staging VPC
│
└── Production Account
    ├── lilith-prod EKS cluster (multi-region)
    ├── Production RDS (Multi-AZ)
    └── Production VPCs (us-east-1, eu-west-1, ap-southeast-1)
```

### Account Configuration

Each account should have:

```hcl
# terraform/account-baseline/main.tf

# Enable AWS Config
resource "aws_config_configuration_recorder" "main" {
  name     = "lilith-config-recorder"
  role_arn = aws_iam_role.config_role.arn

  recording_group {
    all_supported                 = true
    include_global_resource_types = true
  }
}

# Enable CloudTrail
resource "aws_cloudtrail" "main" {
  name                          = "lilith-trail"
  s3_bucket_name               = aws_s3_bucket.cloudtrail.id
  include_global_service_events = true
  is_multi_region_trail        = true
  enable_log_file_validation   = true

  event_selector {
    read_write_type           = "All"
    include_management_events = true
  }
}

# Enable GuardDuty
resource "aws_guardduty_detector" "main" {
  enable = true

  datasources {
    s3_logs {
      enable = true
    }
    kubernetes {
      audit_logs {
        enable = true
      }
    }
  }
}
```

## Prerequisites

### Required Tools

| Tool      | Version    | Purpose                    |
| --------- | ---------- | -------------------------- |
| AWS CLI   | >= 2.15.0  | AWS resource management    |
| Terraform | >= 1.5.0   | Infrastructure as code     |
| kubectl   | >= 1.28    | Kubernetes management      |
| Helm      | >= 3.13    | Kubernetes package manager |
| eksctl    | >= 0.170.0 | EKS cluster management     |

### Installation

```bash
# AWS CLI (Linux)
curl "https://awscli.amazonaws.com/awscli-exe-linux-x86_64.zip" -o "awscliv2.zip"
unzip awscliv2.zip
sudo ./aws/install

# Terraform
wget -O- https://apt.releases.hashicorp.com/gpg | sudo gpg --dearmor -o /usr/share/keyrings/hashicorp-archive-keyring.gpg
echo "deb [signed-by=/usr/share/keyrings/hashicorp-archive-keyring.gpg] https://apt.releases.hashicorp.com $(lsb_release -cs) main" | sudo tee /etc/apt/sources.list.d/hashicorp.list
sudo apt update && sudo apt install terraform

# kubectl
curl -LO "https://dl.k8s.io/release/$(curl -L -s https://dl.k8s.io/release/stable.txt)/bin/linux/amd64/kubectl"
sudo install -o root -g root -m 0755 kubectl /usr/local/bin/kubectl

# Helm
curl https://raw.githubusercontent.com/helm/helm/main/scripts/get-helm-3 | bash
```

### AWS Configuration

```bash
# Configure AWS credentials
aws configure --profile lilith-dev
aws configure --profile lilith-staging
aws configure --profile lilith-prod

# Verify configuration
aws sts get-caller-identity --profile lilith-dev
```

## IAM Configuration

### Service Roles

```hcl
# Terraform role for CI/CD
resource "aws_iam_role" "terraform_role" {
  name = "lilith-terraform-role"

  assume_role_policy = jsonencode({
    Version = "2012-10-17"
    Statement = [
      {
        Effect = "Allow"
        Principal = {
          Federated = "arn:aws:iam::${data.aws_caller_identity.current.account_id}:oidc-provider/token.actions.githubusercontent.com"
        }
        Action = "sts:AssumeRoleWithWebIdentity"
        Condition = {
          StringEquals = {
            "token.actions.githubusercontent.com:aud" = "sts.amazonaws.com"
          }
          StringLike = {
            "token.actions.githubusercontent.com:sub" = "repo:your-org/lilith:*"
          }
        }
      }
    ]
  })
}

resource "aws_iam_role_policy_attachment" "terraform_admin" {
  role       = aws_iam_role.terraform_role.name
  policy_arn = "arn:aws:iam::aws:policy/AdministratorAccess"
}
```

### Developer Role

```hcl
resource "aws_iam_role" "developer_role" {
  name = "lilith-developer-role"

  assume_role_policy = jsonencode({
    Version = "2012-10-17"
    Statement = [
      {
        Effect = "Allow"
        Principal = {
          AWS = "arn:aws:iam::${var.identity_account_id}:root"
        }
        Action = "sts:AssumeRole"
        Condition = {
          Bool = {
            "aws:MultiFactorAuthPresent" = "true"
          }
        }
      }
    ]
  })
}

resource "aws_iam_policy" "developer_policy" {
  name = "lilith-developer-policy"

  policy = jsonencode({
    Version = "2012-10-17"
    Statement = [
      {
        Sid    = "EKSAccess"
        Effect = "Allow"
        Action = [
          "eks:DescribeCluster",
          "eks:ListClusters",
          "eks:AccessKubernetesApi"
        ]
        Resource = "*"
      },
      {
        Sid    = "ECRRead"
        Effect = "Allow"
        Action = [
          "ecr:GetAuthorizationToken",
          "ecr:BatchGetImage",
          "ecr:GetDownloadUrlForLayer",
          "ecr:DescribeRepositories",
          "ecr:ListImages"
        ]
        Resource = "*"
      },
      {
        Sid    = "SecretsRead"
        Effect = "Allow"
        Action = [
          "secretsmanager:GetSecretValue",
          "secretsmanager:DescribeSecret"
        ]
        Resource = "arn:aws:secretsmanager:*:*:secret:lilith/${var.environment}/*"
      },
      {
        Sid    = "LogsRead"
        Effect = "Allow"
        Action = [
          "logs:DescribeLogGroups",
          "logs:DescribeLogStreams",
          "logs:GetLogEvents",
          "logs:FilterLogEvents"
        ]
        Resource = "*"
      }
    ]
  })
}
```

### DevOps Role

```hcl
resource "aws_iam_role" "devops_role" {
  name = "lilith-devops-role"

  assume_role_policy = jsonencode({
    Version = "2012-10-17"
    Statement = [
      {
        Effect = "Allow"
        Principal = {
          AWS = "arn:aws:iam::${var.identity_account_id}:root"
        }
        Action = "sts:AssumeRole"
        Condition = {
          Bool = {
            "aws:MultiFactorAuthPresent" = "true"
          }
        }
      }
    ]
  })
}

# DevOps has expanded permissions
resource "aws_iam_role_policy_attachment" "devops_eks" {
  role       = aws_iam_role.devops_role.name
  policy_arn = "arn:aws:iam::aws:policy/AmazonEKSClusterPolicy"
}

resource "aws_iam_role_policy_attachment" "devops_ecr" {
  role       = aws_iam_role.devops_role.name
  policy_arn = "arn:aws:iam::aws:policy/AmazonEC2ContainerRegistryFullAccess"
}
```

## Regional Strategy

### Primary Region (us-east-1)

Primary region hosts the main production workload:

| Service           | Configuration                |
| ----------------- | ---------------------------- |
| EKS Cluster       | 3 AZs, Multi-node groups     |
| RDS PostgreSQL    | Multi-AZ, Read Replicas      |
| ElastiCache Redis | Cluster mode, 3 shards       |
| S3                | Primary buckets, CRR enabled |
| CloudFront        | Origin for global CDN        |

### Secondary Regions

For disaster recovery and latency optimization:

| Region         | Purpose          | Services                     |
| -------------- | ---------------- | ---------------------------- |
| eu-west-1      | Europe users, DR | EKS, RDS replica, S3 replica |
| ap-southeast-1 | APAC users       | Read replicas, CDN PoP       |

### Multi-Region Configuration

```hcl
# Primary region
module "primary" {
  source = "./modules/region"

  providers = {
    aws = aws.primary
  }

  region        = "us-east-1"
  is_primary    = true
  environment   = var.environment
}

# Secondary region (DR)
module "secondary" {
  source = "./modules/region"

  providers = {
    aws = aws.secondary
  }

  region             = "eu-west-1"
  is_primary         = false
  primary_vpc_id     = module.primary.vpc_id
  enable_rds_replica = true
  environment        = var.environment
}
```

## Cost Management

### Budget Configuration

```hcl
resource "aws_budgets_budget" "monthly" {
  name              = "lilith-monthly-budget"
  budget_type       = "COST"
  limit_amount      = "10000"
  limit_unit        = "USD"
  time_period_start = "2025-01-01_00:00"
  time_unit         = "MONTHLY"

  notification {
    comparison_operator        = "GREATER_THAN"
    threshold                  = 80
    threshold_type             = "PERCENTAGE"
    notification_type          = "FORECASTED"
    subscriber_email_addresses = ["platform@lilith.app"]
  }

  notification {
    comparison_operator        = "GREATER_THAN"
    threshold                  = 100
    threshold_type             = "PERCENTAGE"
    notification_type          = "ACTUAL"
    subscriber_email_addresses = ["platform@lilith.app", "cto@lilith.app"]
  }
}
```

### Cost Optimization Tags

All resources should have:

```hcl
locals {
  common_tags = {
    Project     = "lilith"
    Environment = var.environment
    ManagedBy   = "terraform"
    CostCenter  = "platform"
    Team        = "engineering"
  }
}
```

### Spot Instance Strategy

```hcl
# Spot instances for non-critical workloads
variable "node_groups" {
  default = {
    general = {
      capacity_type  = "ON_DEMAND"  # Critical workloads
      instance_types = ["t3.medium"]
    }
    compute = {
      capacity_type  = "SPOT"  # Batch processing, non-critical
      instance_types = ["c5.large", "c5a.large", "c5n.large"]
    }
  }
}
```

## Security Configuration

### AWS Security Services

```hcl
# Security Hub
resource "aws_securityhub_account" "main" {}

resource "aws_securityhub_standards_subscription" "cis" {
  standards_arn = "arn:aws:securityhub:::ruleset/cis-aws-foundations-benchmark/v/1.2.0"
  depends_on    = [aws_securityhub_account.main]
}

resource "aws_securityhub_standards_subscription" "aws_best_practices" {
  standards_arn = "arn:aws:securityhub:${data.aws_region.current.name}::standards/aws-foundational-security-best-practices/v/1.0.0"
  depends_on    = [aws_securityhub_account.main]
}

# Inspector for vulnerability scanning
resource "aws_inspector2_enabler" "main" {
  account_ids    = [data.aws_caller_identity.current.account_id]
  resource_types = ["EC2", "ECR", "LAMBDA"]
}
```

### KMS Key Management

```hcl
resource "aws_kms_key" "main" {
  description             = "Lilith platform encryption key"
  deletion_window_in_days = 30
  enable_key_rotation     = true

  policy = jsonencode({
    Version = "2012-10-17"
    Statement = [
      {
        Sid    = "Enable IAM policies"
        Effect = "Allow"
        Principal = {
          AWS = "arn:aws:iam::${data.aws_caller_identity.current.account_id}:root"
        }
        Action   = "kms:*"
        Resource = "*"
      },
      {
        Sid    = "Allow EKS"
        Effect = "Allow"
        Principal = {
          Service = "eks.amazonaws.com"
        }
        Action = [
          "kms:Encrypt",
          "kms:Decrypt",
          "kms:ReEncrypt*",
          "kms:GenerateDataKey*",
          "kms:DescribeKey"
        ]
        Resource = "*"
      }
    ]
  })

  tags = local.common_tags
}

resource "aws_kms_alias" "main" {
  name          = "alias/lilith-${var.environment}"
  target_key_id = aws_kms_key.main.key_id
}
```

## Compliance & Auditing

### CloudTrail Configuration

```hcl
resource "aws_cloudtrail" "organization" {
  name                          = "lilith-organization-trail"
  s3_bucket_name               = aws_s3_bucket.cloudtrail.id
  is_organization_trail        = true
  is_multi_region_trail        = true
  include_global_service_events = true
  enable_log_file_validation   = true
  kms_key_id                   = aws_kms_key.cloudtrail.arn

  event_selector {
    read_write_type           = "All"
    include_management_events = true

    data_resource {
      type   = "AWS::S3::Object"
      values = ["arn:aws:s3"]
    }
  }

  insight_selector {
    insight_type = "ApiCallRateInsight"
  }

  insight_selector {
    insight_type = "ApiErrorRateInsight"
  }

  tags = local.common_tags
}
```

### AWS Config Rules

```hcl
resource "aws_config_config_rule" "encrypted_volumes" {
  name = "encrypted-volumes"

  source {
    owner             = "AWS"
    source_identifier = "ENCRYPTED_VOLUMES"
  }

  depends_on = [aws_config_configuration_recorder_status.main]
}

resource "aws_config_config_rule" "s3_bucket_ssl_requests_only" {
  name = "s3-bucket-ssl-requests-only"

  source {
    owner             = "AWS"
    source_identifier = "S3_BUCKET_SSL_REQUESTS_ONLY"
  }

  depends_on = [aws_config_configuration_recorder_status.main]
}

resource "aws_config_config_rule" "rds_storage_encrypted" {
  name = "rds-storage-encrypted"

  source {
    owner             = "AWS"
    source_identifier = "RDS_STORAGE_ENCRYPTED"
  }

  depends_on = [aws_config_configuration_recorder_status.main]
}
```

## Quick Reference

### Common Commands

```bash
# Switch AWS profile
export AWS_PROFILE=lilith-prod

# List EKS clusters
aws eks list-clusters --region us-east-1

# Update kubeconfig
aws eks update-kubeconfig --name lilith-prod --region us-east-1

# Get ECR login token
aws ecr get-login-password --region us-east-1 | docker login --username AWS --password-stdin ${ACCOUNT_ID}.dkr.ecr.us-east-1.amazonaws.com

# List secrets
aws secretsmanager list-secrets --region us-east-1 --filters Key=name,Values=lilith/
```

### Environment Variables

```bash
# Required for Terraform
export AWS_REGION=us-east-1
export AWS_PROFILE=lilith-dev
export TF_VAR_environment=dev

# Optional
export AWS_SDK_LOAD_CONFIG=1
export AWS_RETRY_MODE=adaptive
```

## Related Documentation

- [Networking Architecture](./networking.md)
- [EKS Cluster Setup](./eks.md)
- [Secrets Management](./secrets-management.md)
- [Terraform Deployment Guide](../../deploy/terraform/README.md)
