pangea 0.0.45 → 0.0.47

data/.claude/skills/pangea-infrastructure/SKILL.md

@@ -0,0 +1,300 @@
+---
+name: pangea-infrastructure
+description: Use when managing AWS infrastructure with Pangea. Automation-first infrastructure tool that compiles Ruby DSL to Terraform JSON with template-level state isolation. Covers Route53 DNS, CloudFront, ALB patterns, S3 backend management, cross-template dependencies, and workflow patterns for staging/production deployments. Apply these patterns when creating DNS records, setting up CloudFront distributions, configuring load balancers, managing S3 state backends, or troubleshooting Pangea infrastructure deployments.
+metadata:
+  version: "1.0.0"
+  last_verified: "2025-12-27"
+  research_version: "2025-12-27"
+  domain_keywords:
+    - "amazon-web-services"
+    - "terraform"
+    - "ruby-dsl"
+    - "infrastructure-as-code"
+    - "route53"
+    - "amazon-s3-storage"
+---
+
+# Pangea Infrastructure Standards
+
+## Quick Reference
+
+| Task | Reference |
+|------|-----------|
+| Route53, CloudFront, ALB, Cloudflare Tunnel | [{baseDir}/references/resource-patterns.md](references/resource-patterns.md) |
+| Troubleshooting & Debugging | [{baseDir}/references/troubleshooting.md](references/troubleshooting.md) |
+| Workflow Examples | [{baseDir}/references/workflow-examples.md](references/workflow-examples.md) |
+| Kubernetes Integration (cert-manager, IRSA) | [{baseDir}/references/kubernetes-integration.md](references/kubernetes-integration.md) |
+
+## Pre-Development Checklist
+
+**STOP. Verify before ANY Pangea changes:**
+
+1. **Ruby DSL Syntax**: Using `template :name do` blocks (NOT raw Terraform HCL)
+2. **Config Hash Pattern**: Centralized `config = {}` at top of each template
+3. **Template Isolation**: Each template gets its own workspace and state file
+4. **Pangea CLI Only**: Using `pangea plan/apply/destroy` (NOT terraform/tofu directly)
+5. **Namespace Usage**: Testing in staging/development before production
+6. **Remote State**: Cross-template dependencies use `terraform_remote_state`
+
+**Research existing code in `infrastructure/pangea/{product}/` before creating new templates.**
+
+## Core Concept
+
+Pangea compiles **Ruby DSL to Terraform JSON** with **template-level state isolation**.
+
+**Repository:** `pkgs/tools/ruby/pangea/`
+**Product Infrastructure:** `infrastructure/pangea/{product}/`
+
+**Key Advantages:**
+- Template-Level State Isolation: Each `template :name` gets its own workspace
+- Ruby DSL Power: Better abstraction than HCL for complex logic
+- Automation-First: Auto-approval by default, no manual `terraform init`
+- Multi-Template Files: Logical grouping while maintaining isolation
+
+## Template Structure
+
+```ruby
+# infrastructure/pangea/{product}/{file}.rb
+
+template :template_name do
+  # Centralized configuration - ALL values here
+  config = {
+    region: "us-east-1",
+    domain: "example.com",
+    environment: "production",
+    common_tags: { ManagedBy: "pangea", Environment: "production" }
+  }
+
+  provider :aws do
+    region config[:region]
+  end
+
+  # Resources: resource :type, :name do...end
+  resource :aws_route53_zone, :primary_zone do
+    name config[:domain]
+    tags config[:common_tags]
+  end
+
+  # Data sources: data :type, :name do...end
+  data :aws_route53_zone, :existing do
+    zone_id "Z01234567890"
+  end
+end
+```
+
+**Key Patterns:**
+- Centralized `config` hash at top (NO hardcoded values in resources)
+- Use `.to_json` for policy documents
+- Use `send(:alias)` for Route53 alias blocks (Ruby reserved word)
+
+## Pangea Configuration
+
+**File:** `infrastructure/pangea/pangea.yml`
+
+```yaml
+default_namespace: production
+
+namespaces:
+  development:
+    state:
+      type: local
+      path: "terraform.tfstate"
+
+  staging:
+    state:
+      type: s3
+      bucket: "nxs-{product}-tfstate-use1"
+      key: "pangea/staging/terraform.tfstate"
+      region: "us-east-1"
+      dynamodb_table: "nxs-{product}-tflock-use1"
+      encrypt: true
+
+  production:
+    state:
+      type: s3
+      bucket: "nxs-{product}-tfstate-use1"
+      key: "pangea/production/terraform.tfstate"
+      region: "us-east-1"
+      dynamodb_table: "nxs-{product}-tflock-use1"
+      encrypt: true
+```
+
+## Template-to-Workspace Mapping
+
+Each `template :name` creates a separate workspace:
+
+| Template | Workspace | State File |
+|----------|-----------|------------|
+| `:route53_zones` | `~/.pangea/workspaces/production/route53_zones/` | `s3://{bucket}/pangea/production/route53_zones/terraform.tfstate` |
+| `:dns_records` | `~/.pangea/workspaces/production/dns_records/` | `s3://{bucket}/pangea/production/dns_records/terraform.tfstate` |
+
+**Benefit:** Complete isolation prevents conflicts, reduces blast radius.
+
+## Product Infrastructure Layout
+
+**Directory:** `infrastructure/pangea/{product}/`
+
+```
+infrastructure/pangea/{product}/
+├── {product}_networking.rb      # VPC, subnets, routing
+├── {product}_dns.rb             # Route53 zones and records
+├── {product}_staging_dns.rb     # Staging-specific DNS
+├── {product}_security.rb        # Security groups, certificates
+├── cert_manager_route53.rb      # cert-manager IAM (K8s TLS)
+└── README.md
+```
+
+## CLI Commands
+
+### Nix Run (Preferred)
+
+```bash
+# Apply using nix run handle
+nix run .#apply-novaskyn-staging-dns
+nix run .#apply-{product}-{environment}-{template-type}
+```
+
+If handle doesn't exist, create it in `flake.nix`.
+
+### Direct Pangea CLI
+
+```bash
+cd infrastructure/pangea
+
+# Plan
+pangea plan {product}_dns.rb                           # All templates
+pangea plan {product}_dns.rb --template dns_records    # Specific template
+pangea plan {product}_dns.rb --namespace staging       # Specific namespace
+pangea plan {product}_dns.rb --show-compiled           # Debug: show JSON
+
+# Apply (auto-approves by default)
+pangea apply {product}_dns.rb --template dns_records
+pangea apply {product}_dns.rb --namespace production
+
+# Destroy
+pangea destroy {product}_dns.rb --template dns_records
+```
+
+### Status Checks
+
+```bash
+# View compiled Terraform
+pangea plan {product}_dns.rb --show-compiled
+
+# Check local workspace
+ls ~/.pangea/workspaces/production/dns_records/
+
+# Check S3 state
+aws s3 ls s3://{bucket}/pangea/production/dns_records/
+```
+
+## Resource Naming
+
+**Pattern:** `nxs-{product}-{env}-{resource-type}-{region}-{suffix}`
+
+| Resource | Example |
+|----------|---------|
+| VPC | `nxs-nova-prod-vpc-use1` |
+| ALB | `nxs-nova-prod-use1-api-lb-001` |
+| S3 | `nxs-nova-prod-us-east-1-frontend-static-{hash}` |
+| DynamoDB | `nxs-nova-prod-email-main` |
+
+**Required Tags:**
+```ruby
+tags do
+  Product "{product}"
+  Environment "production|staging|development"
+  ManagedBy "pangea"
+  Component "{component-name}"
+end
+```
+
+## Cross-Template Dependencies
+
+Use `terraform_remote_state` data sources:
+
+```ruby
+template :security_layer do
+  data :terraform_remote_state, :foundation do
+    backend "s3"
+    config do
+      bucket "{bucket-name}"
+      key "pangea/production/foundation_network/terraform.tfstate"
+      region "us-east-1"
+    end
+  end
+
+  resource :aws_security_group, :app do
+    vpc_id "${data.terraform_remote_state.foundation.outputs.vpc_id}"
+  end
+end
+```
+
+## State Management
+
+### S3 Backend Requirements
+
+- S3 bucket with versioning enabled
+- DynamoDB table for state locking
+- IAM permissions for Terraform access
+
+**Naming:**
+- Bucket: `nxs-{product}-tfstate-{region}`
+- Lock Table: `nxs-{product}-tflock-{region}`
+
+### State Organization
+
+```
+s3://{bucket}/pangea/{namespace}/{template_name}/terraform.tfstate
+```
+
+## Anti-Patterns
+
+| DO NOT | INSTEAD |
+|--------|---------|
+| Use Terraform/OpenTofu directly | Use Pangea CLI exclusively |
+| Create monolithic templates | Split by logical layer |
+| Hardcode values in resources | Use `config` hash at top |
+| Skip namespaces | Use staging for testing |
+| Manually edit state files | Use Pangea/Terraform commands |
+| Cross-template refs without remote state | Use `terraform_remote_state` |
+| Block syntax for arrays (`ingress_rule do`) | Parentheses syntax (`ingress([...])`) |
+
+## AWS Zone ID Constants
+
+| Resource | Zone ID |
+|----------|---------|
+| CloudFront | `Z2FDTNDATAQYW2` |
+| US East 1 ALB | `Z35SXDOTRQ7X7K` |
+
+## References
+
+- Pangea tool: `pkgs/tools/ruby/pangea/`
+- NovaSkyn example: `infrastructure/pangea/novaskyn/`
+- Lilitu example: `infrastructure/pangea/lilutu/`
+- Pangea README: `infrastructure/pangea/README.md`
+
+### Detailed Reference Files
+
+- **Resource Patterns:** [{baseDir}/references/resource-patterns.md](references/resource-patterns.md)
+  - Cloudflare Zero Trust Tunnel configuration
+  - Route53 DNS patterns (zones + records)
+  - CloudFront/ALB alias records
+  - Cross-template dependencies
+
+- **Troubleshooting:** [{baseDir}/references/troubleshooting.md](references/troubleshooting.md)
+  - Template compilation errors
+  - State lock issues
+  - Cross-template reference errors
+  - Debugging workflow
+
+- **Workflow Examples:** [{baseDir}/references/workflow-examples.md](references/workflow-examples.md)
+  - Development workflow
+  - Production deployment
+  - Incremental updates
+  - Terraform migration
+
+- **Kubernetes Integration:** [{baseDir}/references/kubernetes-integration.md](references/kubernetes-integration.md)
+  - cert-manager Route53 IAM
+  - External DNS integration
+  - IRSA patterns

data/.claude/skills/pangea-infrastructure/references/kubernetes-integration.md

@@ -0,0 +1,149 @@
+# Pangea Kubernetes Integration
+
+**Pattern:** Pangea manages AWS resources, Kubernetes uses them via annotations.
+
+## cert-manager Route53 Integration
+
+### Pangea IAM Template
+
+```ruby
+# cert_manager_route53.rb
+template :cert_manager_iam do
+  config = {
+    region: "us-east-1",
+    cluster_name: "orion",
+    oidc_issuer: "oidc.eks.us-east-1.amazonaws.com/id/XXXX"
+  }
+
+  provider :aws do
+    region config[:region]
+  end
+
+  # IAM role for cert-manager DNS-01 challenges
+  resource :aws_iam_role, :cert_manager do
+    name "cert-manager-route53"
+
+    assume_role_policy {
+      Version: "2012-10-17",
+      Statement: [{
+        Effect: "Allow",
+        Principal: {
+          Federated: "arn:aws:iam::ACCOUNT:oidc-provider/#{config[:oidc_issuer]}"
+        },
+        Action: "sts:AssumeRoleWithWebIdentity",
+        Condition: {
+          StringEquals: {
+            "#{config[:oidc_issuer]}:sub": "system:serviceaccount:cert-manager:cert-manager"
+          }
+        }
+      }]
+    }.to_json
+  end
+
+  resource :aws_iam_policy, :route53_access do
+    name "cert-manager-route53-access"
+
+    policy {
+      Version: "2012-10-17",
+      Statement: [{
+        Effect: "Allow",
+        Action: [
+          "route53:GetChange",
+          "route53:ChangeResourceRecordSets",
+          "route53:ListResourceRecordSets"
+        ],
+        Resource: [
+          "arn:aws:route53:::hostedzone/*",
+          "arn:aws:route53:::change/*"
+        ]
+      }, {
+        Effect: "Allow",
+        Action: "route53:ListHostedZonesByName",
+        Resource: "*"
+      }]
+    }.to_json
+  end
+
+  resource :aws_iam_role_policy_attachment, :cert_manager do
+    role "${aws_iam_role.cert_manager.name}"
+    policy_arn "${aws_iam_policy.route53_access.arn}"
+  end
+end
+```
+
+### Kubernetes ClusterIssuer
+
+```yaml
+apiVersion: cert-manager.io/v1
+kind: ClusterIssuer
+metadata:
+  name: letsencrypt-prod
+spec:
+  acme:
+    server: https://acme-v02.api.letsencrypt.org/directory
+    email: admin@example.com
+    privateKeySecretRef:
+      name: letsencrypt-prod-key
+    solvers:
+    - dns01:
+        route53:
+          region: us-east-1
+          # IAM role created by Pangea
+          # Uses IRSA (IAM Roles for Service Accounts)
+```
+
+## External DNS Integration
+
+### Pangea IAM Template
+
+```ruby
+template :external_dns_iam do
+  resource :aws_iam_role, :external_dns do
+    name "external-dns-route53"
+    # Similar IRSA pattern as cert-manager
+  end
+
+  resource :aws_iam_policy, :external_dns do
+    name "external-dns-route53-access"
+
+    policy {
+      Version: "2012-10-17",
+      Statement: [{
+        Effect: "Allow",
+        Action: [
+          "route53:ChangeResourceRecordSets"
+        ],
+        Resource: "arn:aws:route53:::hostedzone/*"
+      }, {
+        Effect: "Allow",
+        Action: [
+          "route53:ListHostedZones",
+          "route53:ListResourceRecordSets"
+        ],
+        Resource: "*"
+      }]
+    }.to_json
+  end
+end
+```
+
+### Kubernetes Deployment
+
+```yaml
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: external-dns
+spec:
+  template:
+    metadata:
+      annotations:
+        # IAM role ARN from Pangea
+        eks.amazonaws.com/role-arn: arn:aws:iam::ACCOUNT:role/external-dns-route53
+```
+
+## Pattern Summary
+
+1. **Pangea creates:** IAM roles, policies, trust relationships
+2. **Kubernetes uses:** IRSA annotations referencing Pangea-managed roles
+3. **Benefit:** Infrastructure as code for both AWS and K8s resources

data/.claude/skills/pangea-infrastructure/references/resource-patterns.md

@@ -0,0 +1,206 @@
+# Pangea Resource Patterns
+
+Detailed examples for common AWS resource patterns in Pangea Ruby DSL.
+
+## Cloudflare Zero Trust Tunnel Configuration
+
+**Pattern:** Array-based nested attributes require explicit parentheses
+
+When configuring resources with nested array attributes (like `ingress` in `cloudflare_zero_trust_tunnel_cloudflared_config`), use explicit function call syntax with parentheses to ensure Pangea generates an array instead of nested blocks:
+
+```ruby
+# CORRECT: Array syntax with parentheses
+resource :cloudflare_zero_trust_tunnel_cloudflared_config, :tunnel_config do
+  account_id 'account-id'
+  tunnel_id 'tunnel-id'
+
+  config do
+    # Use parentheses to pass array
+    ingress([
+      {
+        hostname: '*.staging.example.com',
+        service: 'http://192.168.50.100:80'
+      },
+      {
+        hostname: 'staging.example.com',
+        service: 'http://192.168.50.100:80'
+      },
+      {
+        service: 'http_status:404'  # Catch-all (required)
+      }
+    ])
+  end
+end
+```
+
+```ruby
+# INCORRECT: Block syntax generates single object instead of array
+config do
+  ingress_rule do
+    hostname '*.staging.example.com'
+    service 'http://192.168.50.100:80'
+  end
+  # This becomes: { ingress_rule: { hostname: ..., service: ... } }
+  # API expects: { ingress: [{ hostname: ..., service: ... }] }
+end
+```
+
+**Generated Terraform JSON (correct):**
+```json
+{
+  "config": {
+    "ingress": [
+      {"hostname": "*.staging.example.com", "service": "http://192.168.50.100:80"},
+      {"hostname": "staging.example.com", "service": "http://192.168.50.100:80"},
+      {"service": "http_status:404"}
+    ]
+  }
+}
+```
+
+**Key Points:**
+- Cloudflare Tunnel `ingress` must be an array of rules
+- Rules are evaluated in order - first match wins
+- Catch-all rule (no hostname) must be last
+- Routes traffic from Cloudflare edge to internal services (e.g., Istio Gateway)
+
+## Route53 DNS Pattern
+
+**Pattern:** Two templates - zones + records
+
+```ruby
+# {product}_dns.rb
+
+template :route53_zones do
+  config = {
+    region: "us-east-1",
+    primary_domain: "{product}.com"
+  }
+
+  provider :aws do
+    region config[:region]
+  end
+
+  resource :aws_route53_zone, :primary do
+    name config[:primary_domain]
+    tags { ManagedBy "pangea" }
+  end
+end
+
+template :dns_records do
+  config = {
+    zone_id: "Z01234567ABCDEFGHIJK",
+    domain: "{product}.com",
+    cloudfront_id: "E1234567890ABC",
+    alb_dns: "lb-123.us-east-1.elb.amazonaws.com",
+    alb_zone_id: "Z35SXDOTRQ7X7K"  # US East 1 constant
+  }
+
+  provider :aws do
+    region "us-east-1"
+  end
+
+  # Root domain -> CloudFront
+  resource :aws_route53_record, :root do
+    zone_id config[:zone_id]
+    name config[:domain]
+    type "A"
+
+    send(:alias) do
+      name "#{config[:cloudfront_id]}.cloudfront.net"
+      zone_id "Z2FDTNDATAQYW2"  # CloudFront constant
+      evaluate_target_health false
+    end
+  end
+
+  # API subdomain -> ALB
+  resource :aws_route53_record, :api do
+    zone_id config[:zone_id]
+    name "api.#{config[:domain]}"
+    type "A"
+
+    send(:alias) do
+      name config[:alb_dns]
+      zone_id config[:alb_zone_id]
+      evaluate_target_health true
+    end
+  end
+end
+```
+
+## Cross-Template Dependencies
+
+**Pattern:** Use remote state data sources
+
+```ruby
+template :security_layer do
+  # Reference foundation_network template's outputs
+  data :terraform_remote_state, :foundation do
+    backend "s3"
+    config do
+      bucket "{bucket-name}"
+      key "pangea/production/foundation_network/terraform.tfstate"
+      region "us-east-1"
+    end
+  end
+
+  # Use VPC ID from foundation
+  resource :aws_security_group, :app do
+    vpc_id "${data.terraform_remote_state.foundation.outputs.vpc_id}"
+  end
+end
+```
+
+## Route53 Hosted Zone
+
+```ruby
+resource :aws_route53_zone, :primary do
+  name "{domain}.com"
+  comment "Primary hosted zone for {product}"
+
+  tags do
+    Name "{product}-com-zone"
+    Environment "production"
+    ManagedBy "pangea"
+  end
+end
+```
+
+## CloudFront Alias Record
+
+```ruby
+resource :aws_route53_record, :root do
+  zone_id "{zone-id}"
+  name "{domain}.com"
+  type "A"
+
+  send(:alias) do
+    name "{distribution-id}.cloudfront.net"
+    zone_id "Z2FDTNDATAQYW2"  # CloudFront constant
+    evaluate_target_health false
+  end
+end
+```
+
+## ALB Alias Record
+
+```ruby
+resource :aws_route53_record, :api do
+  zone_id "{zone-id}"
+  name "api.{domain}.com"
+  type "A"
+
+  send(:alias) do
+    name "{alb-dns-name}"
+    zone_id "{alb-zone-id}"  # Region-specific
+    evaluate_target_health true
+  end
+end
+```
+
+## AWS Zone ID Constants
+
+| Resource | Zone ID |
+|----------|---------|
+| CloudFront | `Z2FDTNDATAQYW2` |
+| US East 1 ALB | `Z35SXDOTRQ7X7K` |