Infrastructure as Code 툴킷

# Infrastructure as Code 툴킷 — 사용 가이드

## 기능 개요

Infrastructure as Code 툴킷은 세 가지 스킬을 연결하여 완전한 클라우드 배포 라이프사이클을 다룹니다: Terraform 으로 인프라를 프로비저닝하고, Helm 으로 애플리케이션을 패키징하며, Kubernetes 에 배포합니다. AI 어시스턴트에서 벗어나지 않고 제로부터 프로덕션 환경 실행까지 진행할 수 있습니다.

---

## 전체 워크플로우 예시

**시나리오:** Node.js API 를 AWS EKS 에 배포합니다.

**1 단계 — 클라우드 인프라 프로비저닝** (`wshobson-terraform-module-library`)
```
Create a Terraform module for AWS EKS cluster:
- Region: us-east-1
- Node group: 3x t3.medium
- VPC with private subnets
- Enable cluster autoscaler

Run: terraform init → terraform plan → terraform apply
```
출력: EKS 클러스터, 노드 그룹, 네트워킹이 설정된 Terraform 모듈 파일 (`main.tf`, `variables.tf`, `outputs.tf`). 플랜에는 약 12 개의 리소스 생성이 표시됩니다. 적용 시 클러스터가 약 15 분 내에 프로비저닝됩니다.

**2 단계 — 애플리케이션 패키징** (`wshobson-helm-chart-scaffolding`)
```
Create a Helm chart for my-node-api:
- Image: my-registry/node-api:v1.2.0
- Replicas: 2
- Port: 3000
- Health check: /health
- ConfigMap for environment variables
- HorizontalPodAutoscaler: 2-10 replicas at 70% CPU
```
출력: `Chart.yaml`, `values.yaml`, `templates/deployment.yaml`, `templates/service.yaml`, `templates/hpa.yaml`, `templates/configmap.yaml` 로 구성된 완전한 Helm 차트. 배포 전 린트를 위한 `validate-chart.sh` 스크립트가 포함됩니다.

**3 단계 — Kubernetes 에 배포** (`wshobson-k8s-manifest-generator`)
```
Generate K8s manifests to deploy my-node-api to the EKS cluster:
- Namespace: production
- Deployment: 2 replicas, resource limits 256Mi/500m
- Service: ClusterIP on port 80
- ConfigMap: LOG_LEVEL=info, NODE_ENV=production
- Secret: DATABASE_URL from Secrets Manager
```
출력: `kubectl apply -f` 에 사용할 수 있는 `deployment.yaml`, `service.yaml`, `configmap.yaml`, `secret.yaml`.

---

## 범위 및 경계

**이 툴킷에 필요한 것:**
- 로컬 CLI 도구 설치 필요: `terraform` (>=1.0), `helm` (>=3.0), 클러스터에 설정된 `kubectl`
- Terraform 적용을 위한 클라우드 자격 증명 설정 (AWS CLI, GCP auth 등)
- 기존 Kubernetes 클러스터 또는 1 단계에서 프로비저닝된 클러스터

**이 툴킷이 제공하지 않는 것:**
- `terraform apply` 또는 `kubectl apply` 를 직접 실행하지 않습니다 — 파일을 생성하면 사용자가 명령을 실행합니다
- 완전한 CI/CD 파이프라인 (GitHub Actions, ArgoCD, FluxCD) 을 대체하지 않습니다 — 자동화된 배포에는 해당 도구를 사용하세요
- 클러스터 업그레이드, 인증서 회전, 또는 비밀 회전을 관리하지 않습니다
- 독점 플랫폼 (Heroku, Railway, Render) 과 함께 작동하지 않습니다 — 표준 K8s/Terraform 을 대상으로 합니다

---

## 장애 복구

**Terraform: 제공자가 구성되지 않음**
오류: `No valid credential sources found`. 해결: `terraform init` 전에 `aws configure` (또는 클라우드에 해당하는 명령) 를 실행하세요. `terraform plan` 으로 확인하면 — 리소스에 영향을 주기 전에 인증 오류가 표시됩니다.

**Terraform: 권한 거부**
오류: 적용 중 `AccessDenied`. IAM 역할/서비스 계정에 필요한 권한이 없습니다. 오류에서 특정 작업 (예: `eks:CreateCluster`) 을 확인하세요. IAM 정책에 누락된 권한을 추가한 후 `terraform apply` 를 다시 실행하면 — Terraform 은 나머지 리소스만 생성합니다.

**Helm: 차트 유효성 검사 실패**
`helm lint ./my-chart` 를 실행하여 구체적인 오류를 확인하세요. 일반적인 원인: `values.yaml` 에 필수 값 누락, 템플릿의 유효하지 않은 YAML 들여쓰기. 보고된 줄을 수정한 후 배포 전에 다시 린트하세요.

**Helm: 릴리스가 이미 존재함**
오류: `cannot re-use a name that is still in use`. `helm install` 대신 `helm upgrade my-release ./my-chart` 를 사용하거나, `--create-namespace --replace` 플래그를 추가하세요.

**kubectl: 클러스터 연결 불가**
오류: `Unable to connect to the server`. 해결: `kubectl config get-contexts` 를 실행하여 올바른 클러스터가 선택되었는지 확인하세요. EKS 의 경우: `aws eks update-kubeconfig --name <cluster-name> --region <region>` 으로 자격 증명을 갱신하세요.

**배포 후 Pod CrashLoopBackOff**
`kubectl logs <pod-name> -n production` 을 실행하여 애플리케이션 오류를 확인하세요._manifest 의 모든 ConfigMap 키와 Secret 참조가 애플리케이션의 예상과 일치하는지 확인하세요._ 매니페스트를 수정하고 다시 적용하세요.