---
id: devops-kubernetes-basics
title: Kubernetes — Deployment / Service / Ingress
category: Coding
status: draft
source_trust_level: B
verification_status: conceptual
created_at: 2026-05-09
updated_at: 2026-05-09
tags: [devops, kubernetes, k8s, vibe-coding]
tech_stack: { language: "YAML / kubectl", applicable_to: ["DevOps"] }
applied_in: []
aliases: [Deployment, Service, Ingress, ConfigMap, Secret, HPA, probes]
---

# Kubernetes Basics

> Container orchestrator. **Pod = 컨테이너 그룹, Deployment = pod replica 관리, Service = 안정 endpoint, Ingress = 외부 노출**. Probes / resources / HPA 가 production hygiene.

## 📖 핵심 개념
- Namespace: 논리 분리.
- Pod: 1+ 컨테이너 단위, 같은 IP.
- ReplicaSet: pod 수 유지. (Deployment 가 사용)
- Deployment: rolling update.
- Service: stable IP / DNS, load balance.
- Ingress: HTTP path / host routing.

## 💻 코드 패턴

### Deployment
```yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: api
  namespace: prod
spec:
  replicas: 3
  selector: { matchLabels: { app: api } }
  strategy:
    type: RollingUpdate
    rollingUpdate: { maxUnavailable: 0, maxSurge: 1 }
  template:
    metadata: { labels: { app: api } }
    spec:
      containers:
      - name: api
        image: ghcr.io/myco/api:1.2.3
        ports: [{ containerPort: 8080 }]
        env:
        - { name: NODE_ENV, value: production }
        - { name: DB_URL, valueFrom: { secretKeyRef: { name: db, key: url } } }
        resources:
          requests: { cpu: 100m, memory: 256Mi }
          limits:   { cpu: 500m, memory: 512Mi }
        readinessProbe:
          httpGet: { path: /healthz, port: 8080 }
          initialDelaySeconds: 5
          periodSeconds: 5
        livenessProbe:
          httpGet: { path: /livez, port: 8080 }
          initialDelaySeconds: 30
          periodSeconds: 10
        startupProbe:
          httpGet: { path: /healthz, port: 8080 }
          failureThreshold: 30
          periodSeconds: 2
```

### Service
```yaml
apiVersion: v1
kind: Service
metadata: { name: api, namespace: prod }
spec:
  type: ClusterIP
  selector: { app: api }
  ports: [{ port: 80, targetPort: 8080 }]
```

### Ingress
```yaml
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: api
  namespace: prod
  annotations:
    cert-manager.io/cluster-issuer: letsencrypt
spec:
  ingressClassName: nginx
  tls:
  - hosts: [api.myco.com]
    secretName: api-tls
  rules:
  - host: api.myco.com
    http:
      paths:
      - path: /
        pathType: Prefix
        backend: { service: { name: api, port: { number: 80 } } }
```

### ConfigMap & Secret
```yaml
apiVersion: v1
kind: ConfigMap
metadata: { name: app-config }
data:
  LOG_LEVEL: info
  FEATURE_X: "true"
---
apiVersion: v1
kind: Secret
metadata: { name: db }
type: Opaque
stringData:
  url: postgres://app:pw@db:5432/app
```

### HPA (autoscale)
```yaml
apiVersion: autoscaling/v2
kind: HorizontalPodAutoscaler
metadata: { name: api }
spec:
  scaleTargetRef: { apiVersion: apps/v1, kind: Deployment, name: api }
  minReplicas: 2
  maxReplicas: 20
  metrics:
  - type: Resource
    resource: { name: cpu, target: { type: Utilization, averageUtilization: 70 } }
```

### PDB (graceful disruption)
```yaml
apiVersion: policy/v1
kind: PodDisruptionBudget
metadata: { name: api }
spec:
  minAvailable: 2
  selector: { matchLabels: { app: api } }
```

### kubectl 자주 쓰는
```bash
kubectl get pods -n prod
kubectl logs -f deployment/api -n prod
kubectl describe pod <pod> -n prod
kubectl exec -it <pod> -n prod -- sh
kubectl rollout restart deployment/api -n prod
kubectl rollout undo deployment/api -n prod
kubectl top pods -n prod
kubectl port-forward svc/api 8080:80 -n prod
```

### Helm chart 구조
```
charts/api/
  Chart.yaml
  values.yaml          # 기본값
  values-prod.yaml     # 환경별 override
  templates/
    deployment.yaml
    service.yaml
    ingress.yaml
```

## 🤔 의사결정 기준
| 상황 | 도구 |
|---|---|
| 단순 배포 | raw YAML + kustomize |
| Reusable / 환경 다양 | Helm chart |
| 다중 환경 GitOps | Argo CD / Flux |
| 복잡한 cron | Job / CronJob |
| Stateful (DB) | StatefulSet (또는 DB 매니지드) |
| Sidecars (proxy, log) | initContainer / sidecar |

## ❌ 안티패턴
- **Liveness만, Readiness 없음**: warmup 안 끝났는데 트래픽.
- **Resources 없음**: 한 pod 가 노드 장악 / OOM.
- **Limit = Request**: throttling 심해짐. limit 좀 여유.
- **Latest tag**: 재현 불가. semver tag.
- **Secret YAML 에 평문**: SOPS / Sealed Secrets / External Secrets.
- **Replicas 1 + PDB minAvailable 1**: 노드 drain 못 함.
- **maxUnavailable 1 + replicas 2**: 50% 다운. 0/1 권장.
- **HPA 없음 prod**: 트래픽 spike 죽음.

## 🤖 LLM 활용 힌트
- Probes 3종 + resources + HPA + PDB 항상.
- Helm + Argo CD GitOps.
- ConfigMap 비밀X, Secret 평문X (SOPS).

## 🔗 관련 문서
- [[DevOps_Terraform_Patterns]]
- [[Backend_Cron_Patterns]]