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

---
name: infrastructure-as-code
description: 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:

```mermaid
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:

```mermaid
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:

```mermaid
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:

```hcl
# 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:

```mermaid
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:

```yaml
# 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:

```mermaid
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:

```bash
# 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](https://www.terraform.io/docs)
- [Deployment Kubernetes](./deployment-kubernetes.md)
- Skill Source: `.cursor/skills/infrastructure-as-code/SKILL.md`