pos-system/docs/en/skills/infrastructure-as-code.md

name, description

name	description
infrastructure-as-code	Infrastructure as Code patterns for GoodGo platform including Terraform modules, Kubernetes operators, infrastructure testing, GitOps workflows, and multi-environment management.

Infrastructure as Code Patterns

When to Use This Skill

Use this skill when:

• Managing infrastructure with code
• Implementing Terraform modules
• Setting up GitOps workflows
• Creating Kubernetes operators
• Testing infrastructure changes

Infrastructure as Code Workflow

The following diagram illustrates the complete IaC workflow from code changes to infrastructure deployment:

flowchart TD
    A[Developer writes IaC code] --> B[Commit to Git repository]
    B --> C{Code Review}
    C -->|Rejected| D[Fix issues]
    D --> B
    C -->|Approved| E[Merge to branch]
    E --> F[CI/CD Pipeline triggers]
    F --> G{Terraform or<br/>Kubernetes?}
    G -->|Terraform| H[Terraform Workflow]
    G -->|Kubernetes| I[GitOps Workflow]
    H --> J[terraform init]
    J --> K[terraform validate]
    K --> L[terraform plan]
    L --> M{Plan review}
    M -->|Issues found| D
    M -->|Approved| N[terraform apply]
    N --> O[Infrastructure updated]
    I --> P[GitOps tool detects changes]
    P --> Q[Sync to Kubernetes cluster]
    Q --> O
    O --> R[Health checks]
    R --> S{Deployment successful?}
    S -->|No| T[Rollback]
    S -->|Yes| U[Monitor infrastructure]

GitOps Flow

GitOps enables automated synchronization of Kubernetes manifests from Git to clusters:

sequenceDiagram
    participant Dev as Developer
    participant Git as Git Repository
    participant ArgoCD as ArgoCD/Flux
    participant K8s as Kubernetes Cluster
    
    Dev->>Git: Push manifest changes
    Git->>ArgoCD: Detect changes (poll/webhook)
    ArgoCD->>Git: Fetch latest manifests
    ArgoCD->>ArgoCD: Compare desired vs actual state
    alt Drift detected
        ArgoCD->>K8s: Apply changes (sync)
        K8s->>K8s: Update resources
        K8s->>ArgoCD: Status update
    else Auto-heal enabled
        ArgoCD->>K8s: Self-heal (correct drift)
    end
    ArgoCD->>Git: Update sync status

Terraform Execution Flow

The Terraform workflow ensures safe and predictable infrastructure changes:

flowchart LR
    A[terraform init] --> B[Load providers & modules]
    B --> C[terraform validate]
    C --> D{Syntax valid?}
    D -->|No| E[Fix errors]
    E --> C
    D -->|Yes| F[terraform plan]
    F --> G[Read state]
    G --> H[Build dependency graph]
    H --> I[Calculate changes]
    I --> J[Generate plan]
    J --> K{Review plan}
    K -->|Issues| L[Adjust code]
    L --> F
    K -->|Approved| M[terraform apply]
    M --> N[Lock state]
    N --> O[Execute changes]
    O --> P{Success?}
    P -->|No| Q[Rollback]
    P -->|Yes| R[Update state]
    R --> S[Unlock state]
    S --> T[Save state to backend]

Key Patterns

Terraform Modules

Terraform modules enable reusable infrastructure components across environments:

# Reusable module
module "postgresql" {
  source = "../../modules/postgresql"
  database_name = "goodgo"
  environment   = "staging"
}

Module Structure

The following diagram shows the typical Terraform module structure and how modules are composed:

graph TD
    A[Module: postgresql] --> B[variables.tf<br/>Input parameters]
    A --> C[main.tf<br/>Resource definitions]
    A --> D[outputs.tf<br/>Exported values]
    E[Environment: staging] --> F[main.tf]
    F --> G[Module: postgresql]
    F --> H[Module: redis]
    F --> I[Module: kubernetes-cluster]
    G --> J[Output: database_url]
    H --> K[Output: redis_url]
    I --> L[Output: cluster_endpoint]
    F --> M[terraform.tfvars<br/>Environment config]

GitOps with ArgoCD

GitOps tools like ArgoCD and Flux automatically sync Kubernetes manifests from Git repositories:

# Automated sync from Git
spec:
  source:
    repoURL: https://github.com/goodgo/platform
    path: deployments/production/kubernetes
  syncPolicy:
    automated:
      prune: true
      selfHeal: true

Multi-Environment Management

Managing infrastructure across multiple environments requires clear separation and consistent patterns:

graph TB
    subgraph "Git Repository"
        A[infra/terraform]
    end
    subgraph "Modules (Reusable)"
        B[modules/postgresql]
        C[modules/redis]
        D[modules/kubernetes-cluster]
    end
    subgraph "Environments"
        E[environments/staging]
        F[environments/production]
    end
    A --> B
    A --> C
    A --> D
    A --> E
    A --> F
    E --> B
    E --> C
    E --> D
    F --> B
    F --> C
    F --> D
    E --> G[terraform.tfvars<br/>staging config]
    F --> H[terraform.tfvars<br/>production config]
    G --> I[Remote State Backend<br/>staging/terraform.tfstate]
    H --> J[Remote State Backend<br/>production/terraform.tfstate]

Infrastructure Testing

Always validate infrastructure changes before applying them:

# Validate Terraform syntax
terraform init
terraform validate

# Preview changes
terraform plan -out=tfplan

# Review plan before applying
terraform show tfplan

Best Practices

1. Version Control: Keep all infrastructure in version control
2. Modules: Create reusable Terraform modules for common components
3. Testing: Test infrastructure changes before applying to production
4. GitOps: Use GitOps (ArgoCD/Flux) for Kubernetes deployments
5. Environment Isolation: Separate environments completely with different state backends
6. State Management: Use remote state backends (S3, GCS) with state locking
7. Secrets: Never commit secrets - use environment variables or secrets managers

Common Mistakes to Avoid

1. Committing Secrets: Never hardcode passwords or API keys
2. Local State Only: Always use remote state backends for team collaboration
3. No State Locking: Enable state locking to prevent concurrent modifications
4. Direct Apply: Always review terraform plan output before applying

Resources

• Terraform Documentation
• Deployment Kubernetes
• Skill Source: .cursor/skills/infrastructure-as-code/SKILL.md