# Infrastructure as Code

Infrastructure as Code patterns for GoodGo platform including Terraform modules, Kubernetes operators, infrastructure testing, GitOps workflows, and multi-environment management.
> Các patterns Infrastructure as Code cho nền tảng GoodGo bao gồm Terraform modules, Kubernetes operators, infrastructure testing, GitOps workflows, và multi-environment management.

## Tổng Quan

Infrastructure as Code enables managing infrastructure through code, providing version control, reproducibility, and automation.

Infrastructure as Code cho phép quản lý infrastructure qua code, cung cấp version control, reproducibility, và automation.

## Khi Nào Sử Dụng

Use this skill when managing infrastructure, implementing GitOps, or creating reusable modules.

Sử dụng skill này khi quản lý infrastructure, implement GitOps, hoặc tạo các modules tái sử dụng.

## Infrastructure as Code Workflow / Quy Trình Infrastructure as Code

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

Sơ đồ sau minh họa quy trình IaC đầy đủ từ thay đổi code đến triển khai infrastructure.

```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 / Quy Trình GitOps

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

GitOps cho phép đồng bộ tự động Kubernetes manifests từ Git đến 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 / Quy Trình Thực Thi Terraform

The Terraform workflow ensures safe and predictable infrastructure changes.

Quy trình Terraform đảm bảo các thay đổi infrastructure an toàn và có thể dự đoán được.

```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]
```

## Các Patterns Chính

### Terraform Modules / Terraform Modules

Terraform modules enable reusable infrastructure components across environments.

Terraform modules cho phép tái sử dụng các component infrastructure giữa các môi trường.

```hcl
# EN: Reusable module
# VI: Module tái sử dụng
module "postgresql" {
  source = "../../modules/postgresql"
  database_name = "goodgo"
  environment   = "staging"
}
```

### Module Structure / Cấu Trúc Module

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

Sơ đồ sau cho thấy cấu trúc Terraform module điển hình và cách các modules được kết hợp.

```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 với ArgoCD

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

Các công cụ GitOps như ArgoCD và Flux tự động đồng bộ Kubernetes manifests từ Git repositories.

```yaml
# EN: Automated sync from Git
# VI: Đồng bộ tự động từ Git
spec:
  source:
    repoURL: https://github.com/goodgo/platform
    path: deployments/production/kubernetes
  syncPolicy:
    automated:
      prune: true
      selfHeal: true
```

### Multi-Environment Management / Quản Lý Đa Môi Trường

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

Quản lý infrastructure trên nhiều môi trường yêu cầu tách biệt rõ ràng và các patterns nhất quán.

```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 / Kiểm Thử Infrastructure

Always validate infrastructure changes before applying them.

Luôn validate các thay đổi infrastructure trước khi áp dụng.

```bash
# EN: Validate Terraform syntax
# VI: Validate cú pháp Terraform
terraform init
terraform validate

# EN: Preview changes
# VI: Xem trước các thay đổi
terraform plan -out=tfplan

# EN: Review plan before applying
# VI: Xem xét plan trước khi apply
terraform show tfplan
```

## Best Practices / Thực Hành Tốt

1. **Version Control / Kiểm Soát Phiên Bản**: Keep all infrastructure in version control / Giữ tất cả infrastructure trong version control
2. **Modules / Modules**: Create reusable Terraform modules for common components / Tạo các Terraform modules tái sử dụng cho các component phổ biến
3. **Testing / Kiểm Thử**: Test infrastructure changes before applying to production / Kiểm thử các thay đổi infrastructure trước khi áp dụng lên production
4. **GitOps / GitOps**: Use GitOps (ArgoCD/Flux) for Kubernetes deployments / Sử dụng GitOps (ArgoCD/Flux) cho Kubernetes deployments
5. **Environment Isolation / Cô Lập Môi Trường**: Separate environments completely with different state backends / Tách biệt hoàn toàn các môi trường với các state backends khác nhau
6. **State Management / Quản Lý State**: Use remote state backends (S3, GCS) with state locking / Sử dụng remote state backends (S3, GCS) với state locking
7. **Secrets / Bí Mật**: Never commit secrets - use environment variables or secrets managers / Không bao giờ commit secrets - sử dụng environment variables hoặc secrets managers

### Common Mistakes to Avoid / Các Lỗi Thường Gặp Cần Tránh

1. **Committing Secrets / Commit Secrets**: Never hardcode passwords or API keys / Không bao giờ hardcode passwords hoặc API keys
2. **Local State Only / Chỉ Dùng Local State**: Always use remote state backends for team collaboration / Luôn sử dụng remote state backends cho collaboration trong team
3. **No State Locking / Không Lock State**: Enable state locking to prevent concurrent modifications / Bật state locking để ngăn chặn các thay đổi đồng thời
4. **Direct Apply / Apply Trực Tiếp**: Always review `terraform plan` output before applying / Luôn xem xét output của `terraform plan` trước khi apply

## Tài Nguyên

- Skill Source: `.cursor/skills/infrastructure-as-code/SKILL.md`
