김신건의 로그 - 위키 / kubernetes

[K8s] HPA / VPA / KEDA: 자동 확장

koa (김신건) — Thu, 16 Jul 2026 00:00:00 GMT

정의

Pod 를 자동으로 확장/축소하는 K8s 메커니즘. 세 가지 레벨:

레벨	도구	무엇을 확장
Pod 수	HPA / KEDA	동일 spec pod 추가/삭제
Pod 크기	VPA	CPU/Memory request/limit 조절
Node 수	Cluster Autoscaler / Karpenter	node 추가/삭제

3가지 스케일링

flowchart TB
    Q[스케일링 종류]
    Q --> HPA["HPA<br/>Pod 수 증감"]
    Q --> VPA["VPA<br/>Pod 리소스 증감"]
    Q --> CA["Cluster Autoscaler / Karpenter<br/>Node 수 증감"]

HPA (Horizontal Pod Autoscaler)

CPU / Memory / custom metric 기반 pod 수 조정.

apiVersion: autoscaling/v2
kind: HorizontalPodAutoscaler
metadata: { name: web }
spec:
  scaleTargetRef:
    apiVersion: apps/v1
    kind: Deployment
    name: web
  minReplicas: 3
  maxReplicas: 50
  metrics:
    - type: Resource
      resource:
        name: cpu
        target: { type: Utilization, averageUtilization: 70 }
    - type: Pods
      pods:
        metric: { name: http_requests_per_second }
        target: { type: AverageValue, averageValue: "1000" }
  behavior:
    scaleUp:
      stabilizationWindowSeconds: 0
      policies:
        - type: Percent
          value: 100
          periodSeconds: 15
    scaleDown:
      stabilizationWindowSeconds: 300
      policies:
        - type: Percent
          value: 10
          periodSeconds: 60

HPA 알고리즘

desired = ceil(currentReplicas × (currentMetric / targetMetric))

예: 현재 4 pod, CPU 80%, 목표 50%:

desired = ceil(4 × (80/50)) = 7 pod

HPA 제어 루프

sequenceDiagram
    participant MS as metrics-server
    participant HPA as HPA controller
    participant D as Deployment

    loop 15초마다
        HPA->>MS: 현재 CPU/메모리 조회
        MS-->>HPA: 평균 CPU 80%
        HPA->>HPA: desired = ceil(4 * 80/50) = 7
        HPA->>D: replicas: 7
        D->>D: pod 3개 추가
    end

stabilizationWindowSeconds: scale down 은 기본 300초 대기 후 결정
scaleDown.policies: 한 번에 10% 씩, 60초 간격으로 축소

Custom Metrics: Prometheus Adapter

HPA 에서 커스텀 메트릭을 사용하려면 Prometheus Adapter 로 메트릭을 K8s Custom Metrics API 에 노출:

# prometheus-adapter ConfigMap (간략)
rules:
  - seriesQuery: 'http_requests_total{namespace!="",pod!=""}'
    resources:
      overrides:
        namespace: { resource: "namespace" }
        pod: { resource: "pod" }
    name:
      matches: "^(.*)_total$"
      as: "${1}_per_second"
    metricsQuery: 'rate(<<.Series>>{<<.LabelMatchers>>}[2m])'

이후 HPA spec 에서:

metrics:
  - type: Pods
    pods:
      metric: { name: http_requests_per_second }
      target: { type: AverageValue, averageValue: "1000" }

VPA (Vertical Pod Autoscaler)

apiVersion: autoscaling.k8s.io/v1
kind: VerticalPodAutoscaler
metadata: { name: web }
spec:
  targetRef:
    apiVersion: apps/v1
    kind: Deployment
    name: web
  updatePolicy:
    updateMode: "Auto"   # Off / Initial / Recreate / Auto
  resourcePolicy:
    containerPolicies:
      - containerName: '*'
        minAllowed: { cpu: 50m, memory: 64Mi }
        maxAllowed: { cpu: 2, memory: 2Gi }

[!CAUTION] VPA + HPA on CPU 동시 사용 금지. 둘이 같은 메트릭으로 다툼. HPA 는 custom metric, VPA 는 resource → 분리 가능.

VPA 모드 비교

updateMode	동작	재시작
`Off`	권고값만 계산, 실제 변경 없음	없음
`Initial`	pod 생성 시 한 번만 적용	없음
`Recreate`	변경 필요 시 pod 삭제 후 재생성	있음
`Auto`	현재는 Recreate 와 동일 (인플레이스 업데이트 개발 중)	있음

VPA Off 모드는 초기 resource request 추천 용도로 자주 활용.

KEDA (Kubernetes Event-Driven Autoscaling)

flowchart LR
    Trigger["외부 트리거<br/>Kafka lag, SQS depth, ..."] --> KEDA
    KEDA --> HPA[표준 HPA 생성]
    HPA --> Deploy[Deployment scale]

apiVersion: keda.sh/v1alpha1
kind: ScaledObject
metadata: { name: kafka-consumer }
spec:
  scaleTargetRef:
    name: consumer
  minReplicaCount: 0
  maxReplicaCount: 30
  triggers:
    - type: kafka
      metadata:
        bootstrapServers: kafka:9092
        topic: events
        consumerGroup: my-group
        lagThreshold: '1000'

[!IMPORTANT] KEDA 가 2026 시점 표준. 50+ scaler (Kafka, SQS, Prometheus, Redis, DB query, …) 지원. scale-to-zero 가능.

KEDA: Prometheus 기반 스케일링

triggers:
  - type: prometheus
    metadata:
      serverAddress: http://prometheus:9090
      metricName: http_requests_total
      query: sum(rate(http_requests_total{job="web"}[2m]))
      threshold: '1000'

Prometheus 가 있는 클러스터에서 임의의 PromQL 로 스케일링 가능. metrics-server + Prometheus Adapter 없이 KEDA 만으로도 커스텀 메트릭 HPA 구현 가능.

Cluster Autoscaler / Karpenter

flowchart LR
    HPA --> NeedMore[새 pod 들이 Pending]
    NeedMore --> CA[Cluster Autoscaler]
    CA -->|"EC2 / GCE"| AddNode[새 node 추가]
    AddNode --> Schedule[pending pod 스케줄]

-	Cluster Autoscaler	Karpenter
종류	표준 K8s 도구	AWS 발 (이제 CNCF)
Node 선택	미리 정의된 node group	동적 instance type 선택
속도	분 단위	수십 초
비용 최적화	제한적	우수 (spot, right-sizing)
클라우드	다양	AWS, Azure

HPA vs KEDA 선택 기준

상황	추천
CPU/Memory 기반 스케일링만 필요	HPA 단독
Kafka lag, SQS depth, Prometheus metric	KEDA
scale-to-zero 필요	KEDA
50+ 종류의 외부 트리거	KEDA
기존 HPA + 일부 custom metric	HPA + Prometheus Adapter

흔한 함정

[!WARNING]

stabilization window 너무 짧음 = 빈번한 scale up/down → 비용 + 안정성 문제.

HPA + VPA 동시 (같은 메트릭) = 충돌. 분리 또는 VPA off mode + 수동.

metrics-server 미설치 = HPA 작동 안 함. cluster 부팅 시 자동 설치 확인.

resource request 없음 = HPA CPU 기준 무의미. requests 필수.

minReplicas: 0 + 갑작스러운 트래픽 = cold-start latency. KEDA minReplicaCount: 1 권장.

[K8s] Job / CronJob: 일회성 + 스케줄 작업

koa (김신건) — Thu, 16 Jul 2026 00:00:00 GMT

정의

컨트롤러	의미
Job	완료까지 실행하는 일회성 작업
CronJob	스케줄 (cron) 에 따라 Job 생성

Deployment 와 다른 점: 완료를 목표로 함. pod 가 종료되어도 재시작 안 함.

Job

apiVersion: batch/v1
kind: Job
metadata: { name: migrate }
spec:
  backoffLimit: 3                # 실패 시 재시도 한도
  activeDeadlineSeconds: 600     # 10분 초과 시 강제 종료
  ttlSecondsAfterFinished: 3600  # 완료 후 1시간 뒤 정리
  template:
    spec:
      restartPolicy: OnFailure
      containers:
        - name: migrate
          image: app:v2
          command: ['python', 'manage.py', 'migrate']

흐름

stateDiagram-v2
    [*] --> Active: Job 생성
    Active --> Succeeded: completions 달성
    Active --> Failed: backoffLimit 초과
    Succeeded --> Cleaned: TTL 후 자동 삭제
    Failed --> Cleaned: TTL 후

Job 생명주기 상세

sequenceDiagram
    autonumber
    participant K as K8s API
    participant J as Job controller
    participant P as Pod

    K->>J: Job 생성
    J->>P: Pod 시작
    P->>P: 작업 실행
    alt 성공
        P-->>J: exit 0
        J->>K: Succeeded
    else 실패 (backoffLimit 이내)
        P-->>J: exit 1
        J->>P: 재시도 Pod 생성
    else backoffLimit 초과
        J->>K: Failed
    end

병렬 실행 (parallelism / completions)

spec:
  completions: 10       # 총 10개 완료 필요
  parallelism: 3        # 동시 3개 실행

패턴	의미
`completions=1, parallelism=1`	단일 작업 (기본)
`completions=N, parallelism=N`	N개 병렬
`completions=N, parallelism=M < N`	동시 M, 총 N
`completions=null, parallelism=M`	무한 (작업 큐 패턴)

activeDeadlineSeconds

spec:
  activeDeadlineSeconds: 300    # 5분 초과 시 강제 종료
  backoffLimit: 2

backoffLimit = 실패 재시도 한도 (pod 수준)
activeDeadlineSeconds = 전체 Job 의 최대 실행 시간 (시간 초과 시 Failed)
둘 다 지정 시 먼저 도달하는 조건 에 따라 종료

Job Suspend (1.24+)

실행 중인 Job 을 일시 정지 후 재개 가능:

# 일시 정지
kubectl patch job migrate -p '{"spec":{"suspend":true}}'
# 재개
kubectl patch job migrate -p '{"spec":{"suspend":false}}'

정지 시 활성 pod 는 삭제, 완료된 pod 는 유지
CronJob 에도 적용: spec.suspend: true 로 스케줄 중단

Failure Policy (1.26+)

특정 종료 코드를 성공 또는 영구 실패 로 처리:

spec:
  podFailurePolicy:
    rules:
      - action: FailJob           # 즉시 전체 Job 실패
        onExitCodes:
          operator: In
          values: [42]            # 비즈니스 오류 코드
      - action: Ignore            # 무시 (재시도 카운트 안 함)
        onPodConditions:
          - type: DisruptionTarget  # node eviction 은 재시도

작업 큐 패턴

flowchart LR
    Queue[("Job Queue<br/>Redis / SQS")] --> P1[Pod 1]
    Queue --> P2[Pod 2]
    Queue --> P3[Pod 3]
    P1 --> Output[("처리 완료")]
    P2 --> Output
    P3 --> Output

각 pod 가 큐에서 work 가져와 처리 후 종료. completions 없이 queue 가 빌 때까지.

Indexed Job (1.24+)

spec:
  completions: 10
  parallelism: 3
  completionMode: Indexed
  template:
    spec:
      containers:
        - name: worker
          image: app:v1
          env:
            - name: JOB_COMPLETION_INDEX
              valueFrom:
                fieldRef:
                  fieldPath: metadata.annotations['batch.kubernetes.io/job-completion-index']

각 pod 가 고유 인덱스 (0..N-1). 파티션된 작업 분배.

CronJob

apiVersion: batch/v1
kind: CronJob
metadata: { name: nightly-backup }
spec:
  schedule: "0 2 * * *"           # 매일 2시
  timeZone: "Asia/Seoul"           # K8s 1.27+
  successfulJobsHistoryLimit: 3
  failedJobsHistoryLimit: 1
  concurrencyPolicy: Forbid       # 이전 job 끝나기 전 새 job 안 만듦
  startingDeadlineSeconds: 300    # 5분 안에 시작 못 하면 skip
  jobTemplate:
    spec:
      template:
        spec:
          restartPolicy: OnFailure
          containers:
            - name: backup
              image: db-backup:v1

concurrencyPolicy

정책	의미
`Allow` (기본)	동시 실행 허용
`Forbid`	이전 job 끝나기 전 새 job skip
`Replace`	이전 job 중단 + 새 job

CronJob 누락 스케줄 처리

K8s 컨트롤러가 오프라인이었다가 복구 되거나 startingDeadlineSeconds 기간 내 에 놓친 스케줄이 많을 때:

startingDeadlineSeconds 미설정: 마지막 스케줄 시간부터 현재까지 놓친 횟수를 계산, 100회 초과 시 CronJob 비활성화
startingDeadlineSeconds: 300: 최근 5분 이내 놓친 횟수만 계산

[!WARNING] startingDeadlineSeconds 를 설정하지 않으면 컨트롤러 장기 다운 후 복구 시 CronJob 이 영구 비활성화 될 수 있다.

Cron 식

┌──── 분 (0-59)
│ ┌── 시 (0-23)
│ │ ┌── 일 (1-31)
│ │ │ ┌── 월 (1-12)
│ │ │ │ ┌── 요일 (0-6, 0=Sun)
│ │ │ │ │
0 2 * * *     매일 2시
*/15 * * * *  15분마다
0 9 * * 1-5   평일 9시
0 0 1 * *     매월 1일 자정
@hourly       매시 (alias)

Job vs Deployment 선택 기준

상황	선택
DB 마이그레이션, 배치 처리	Job
스케줄 리포트, 백업	CronJob
상시 실행 API 서버	Deployment
큐 소비 + 무한 대기	Deployment
큐 소비 + 작업 완료 후 종료	Job (parallelism)

흔한 함정

[!WARNING]

restartPolicy: Always = Job 의 의미 깨짐. OnFailure 또는 Never.

ttlSecondsAfterFinished 없음 = 완료된 Job 누적. cluster cluttered.

CronJob 의 시간대 = K8s 1.27+ 까지 UTC 만. timeZone 명시 권장.

concurrencyPolicy: Allow + 무거운 작업 = job 들이 겹쳐 시스템 부하. Forbid 안전.

JOB 실패 알림 부재 = silent fail. Prometheus + Alertmanager 로 failed Job 알림.

activeDeadlineSeconds 미설정 + 무한 루프 = Job 이 영구 실행, 클러스터 자원 점유.

[K8s] StatefulSet: 순서 보장, 고유 ID, 영속 스토리지

koa (김신건) — Thu, 16 Jul 2026 00:00:00 GMT

정의

StatefulSet = 상태 있는 워크로드를 위한 컨트롤러. Deployment 와의 차이:

항목	Deployment	StatefulSet
Pod 이름	random hash (`web-7d9c-xpqr`)	순서 (`db-0, db-1, db-2`)
Pod 식별	변경됨	고정 (sticky identity)
시작 순서	parallel	순차 (0 → 1 → 2)
종료 순서	parallel	역순 (N-1 → 0)
스토리지	공유 또는 ephemeral	pod 별 PVC
Headless Service	옵션	필수

사용처

flowchart TD
    Yes[StatefulSet 적합]
    Yes --> Y1["DB (PostgreSQL, MySQL replica)"]
    Yes --> Y2["Kafka, Zookeeper"]
    Yes --> Y3[Elasticsearch]
    Yes --> Y4[etcd]
    Yes --> Y5[Cassandra]
    No[Deployment 가 충분]
    No --> N1[Stateless API]
    No --> N2[Web frontend]
    No --> N3[Worker]

YAML

apiVersion: v1
kind: Service
metadata: { name: db-headless }
spec:
  clusterIP: None        # Headless 필수
  selector: { app: db }
  ports: [{ port: 5432, targetPort: 5432 }]
---
apiVersion: apps/v1
kind: StatefulSet
metadata: { name: db }
spec:
  serviceName: db-headless
  replicas: 3
  selector: { matchLabels: { app: db } }
  template:
    metadata: { labels: { app: db } }
    spec:
      containers:
        - name: postgres
          image: postgres:17
          ports: [{ containerPort: 5432 }]
          readinessProbe:
            exec:
              command: [pg_isready, -U, postgres]
            initialDelaySeconds: 5
            periodSeconds: 5
          volumeMounts:
            - name: data
              mountPath: /var/lib/postgresql/data
  volumeClaimTemplates:
    - metadata: { name: data }
      spec:
        accessModes: [ReadWriteOnce]
        storageClassName: fast-ssd
        resources: { requests: { storage: 100Gi } }

Pod 이름과 DNS

pod 0: db-0   → db-0.db-headless.default.svc.cluster.local
pod 1: db-1   → db-1.db-headless.default.svc.cluster.local
pod 2: db-2   → db-2.db-headless.default.svc.cluster.local

각 pod 가 고유 DNS 이름. peer 끼리 서로 직접 통신 (replication 등).

Peer Discovery 패턴

StatefulSet + Headless Service 조합이 peer discovery 의 핵심:

flowchart LR
    db0["db-0 (Primary)"]
    db1["db-1 (Replica 1)"]
    db2["db-2 (Replica 2)"]
    db0 -->|"WAL 스트리밍"| db1
    db0 -->|"WAL 스트리밍"| db2
    db1 -.->|"db-0.db-headless 연결"| db0
    db2 -.->|"db-0.db-headless 연결"| db0

Replica 가 Primary 에 연결: postgresql://db-0.db-headless:5432
pod 재시작 후에도 같은 DNS 유지
애플리케이션이 Primary 주소를 안정적으로 참조 가능

시작 / 종료 순서

sequenceDiagram
    autonumber
    Note over STS: Create / Scale up
    STS->>Pod0: start (ready 대기)
    Pod0-->>STS: ready
    STS->>Pod1: start (ready 대기)
    Pod1-->>STS: ready
    STS->>Pod2: start (ready 대기)
    Note over STS: Delete / Scale down (역순)
    STS->>Pod2: terminate
    STS->>Pod1: terminate
    STS->>Pod0: terminate

[!IMPORTANT] Master-replica DB 처럼 순서가 중요 한 경우 핵심. podManagementPolicy: Parallel 로 순차 종속성 제거 가능 (Kafka 같이 peer 끼리 sync).

initContainers로 초기화

Replica pod 가 시작 전 Primary 에서 데이터를 받아야 할 때:

initContainers:
  - name: init-replica
    image: postgres:17
    command:
      - bash
      - -c
      - |
        # db-0 (Primary) 은 초기화 스킵
        [ "$(hostname)" = "db-0" ] && exit 0
        # Primary 에서 base backup 취득
        pg_basebackup -h db-0.db-headless \
          -U replicator -D /var/lib/postgresql/data \
          -Xs -R
    volumeMounts:
      - name: data
        mountPath: /var/lib/postgresql/data

db-0 (Primary) 은 initContainer 를 스킵
db-1, db-2 는 기동 전 Primary 에서 base backup 취득
데이터가 있는 상태 에서 Replica 시작 보장

PVC per Pod (영속 스토리지)

flowchart LR
    STS[StatefulSet] --> P0[db-0]
    STS --> P1[db-1]
    STS --> P2[db-2]
    P0 --> PVC0[("data-db-0")]
    P1 --> PVC1[("data-db-1")]
    P2 --> PVC2[("data-db-2")]

pod 재생성 후에도 같은 PVC 재연결
pod 삭제 해도 PVC 보존 (직접 삭제 필요)

PVC 생명주기 관리

작업	동작
Pod 재시작	PVC 자동 재연결
Scale down	PVC 보존 (삭제 안 됨)
StatefulSet 삭제	PVC 보존 (수동 삭제 필요)
PVC 용량 확장	`StorageClass allowVolumeExpansion: true` 필요

# K8s 1.27+: StatefulSet 삭제/축소 시 PVC 정책 설정
spec:
  persistentVolumeClaimRetentionPolicy:
    whenDeleted: Delete    # StatefulSet 삭제 시 PVC 도 삭제
    whenScaled: Retain     # Scale down 시 PVC 유지

Update 전략

전략	의미
`RollingUpdate` (기본)	순차 업데이트 (N-1 → 0)
`OnDelete`	수동 삭제 시 만 새 spec
`partition: N`	인덱스 ≥ N 만 업데이트 (canary)

Canary Update (partition 활용)

spec:
  updateStrategy:
    type: RollingUpdate
    rollingUpdate:
      partition: 2    # db-2 만 먼저 업데이트

sequenceDiagram
    autonumber
    Note over STS: partition=2 설정
    STS->>db2: 새 이미지로 업데이트
    db2-->>STS: 정상 확인
    Note over STS: partition=1 로 변경
    STS->>db1: 새 이미지로 업데이트
    db1-->>STS: 정상 확인
    Note over STS: partition=0 으로 변경
    STS->>db0: 새 이미지로 업데이트

문제 발생 시: image 를 이전 버전으로 되돌리면 이미 업데이트된 pod 도 재시작 시 롤백.

운영 패턴: Operator

flowchart LR
    Op["Operator (controller)"] -->|관리| STS[StatefulSet]
    Op -->|backup| Backup[("S3 backup")]
    Op -->|failover| Promote["Replica to Primary"]
    Op -->|scale| Add[새 replica 추가]

DB 운영의 표준 (PostgreSQL Operator, Kafka Strimzi, ElasticSearch ECK)
StatefulSet 만으로 부족한 애플리케이션 특화 로직 자동화

대상	대표 Operator
PostgreSQL	CNPG (CloudNativePG), Zalando postgres-operator
Kafka	Strimzi
Elasticsearch	ECK (Elastic Cloud on K8s)
Redis	Redis Operator

Primary 장애 복구 흐름

Operator 없이 수동 failover 시:

sequenceDiagram
    autonumber
    Note over db0: Primary 다운
    db1->>db1: pg_promote 실행
    db2->>db1: 복제 재연결 (db-0 → db-1)
    Note over Admin: db-0 PVC 데이터 초기화
    Admin->>db0: pod 재시작
    db0->>db1: base backup 취득 후 Replica 합류

[!IMPORTANT] Operator (예: CNPG, Zalando) 를 사용하면 이 모든 흐름이 자동화. 수동 StatefulSet 만으로 DB HA 구현은 권장하지 않음.

흔한 함정

[!WARNING]

Headless Service 없음 = pod DNS 안 잡힘 → peer discovery 실패.

partition 활용 안 함 = canary 불가. 모든 pod 한 번에 업데이트.

PVC delete 정책 = StatefulSet 삭제 시 PVC 보존 (기본). 의도적으로 삭제 안 하면 영구 storage cost.

DB 의 순서 의존성 + parallel 정책 잘못 = 데이터 손상.

initContainer 없이 Replica 시작 = 빈 PVC 로 Replica 가 기동, 데이터 없는 상태.

Operator 없이 DB HA 구현 = failover, backup, scale 을 손으로. Operator 사용 권장.

[K8s] ConfigMap & Secret: 설정과 비밀의 분리

koa (김신건) — Wed, 15 Jul 2026 00:00:00 GMT

정의

ConfigMap 과 Secret 은 컨테이너 이미지에서 설정/비밀 값을 분리하기 위한 Kubernetes 리소스.

항목	ConfigMap	Secret
데이터	평문 (UTF-8)	base64 인코딩
크기 제한	1 MiB	1 MiB
용도	비민감 설정	비밀 (비밀번호, 토큰, 인증서)
etcd 저장	평문	평문 (EncryptionConfiguration 설정 시 암호화)
RBAC 권고	일반	엄격한 제한 권고
기본 마운트	일반 volume	`tmpfs` (in-memory)

[!IMPORTANT] Secret = base64 는 암호화가 아니다. echo "password" | base64 한 줄로 복호화됨. 진짜 보안은 etcd encryption at rest + RBAC + 외부 시크릿 관리(ESO, Vault) 로 달성.

ConfigMap

ConfigMap 생성

apiVersion: v1
kind: ConfigMap
metadata:
  name: app-config
  namespace: production
data:
  # 단순 키-값
  log_level: "info"
  db_host: "db.production.svc.cluster.local"
  max_connections: "100"

  # 여러 줄 (파일 내용)
  feature_flags: |
    new_ui: true
    beta_search: false
    dark_mode: true

  # nginx.conf 파일 통째로
  nginx.conf: |
    worker_processes auto;
    events { worker_connections 1024; }
    http {
      server {
        listen 80;
        location / { proxy_pass http://backend:8080; }
      }
    }

CLI 생성

# 파일에서
kubectl create configmap nginx-config --from-file=nginx.conf

# 리터럴에서
kubectl create configmap app-env \
  --from-literal=log_level=info \
  --from-literal=db_host=db.prod

# 여러 파일 디렉토리에서
kubectl create configmap configs --from-file=./configs/

Secret

Secret 생성 (YAML)

apiVersion: v1
kind: Secret
metadata:
  name: db-creds
  namespace: production
type: Opaque
data:
  # base64 인코딩 값 (echo -n "value" | base64)
  username: a29h                # base64("koa")
  password: cGFzc3dvcmQ=        # base64("password")

# stringData: 평문으로 작성 (쿠버네티스가 자동 base64)
stringData:
  api_key: "sk-prod-xxxxxxx"    # 평문 OK (stringData 필드)

Secret 타입

`type`	용도
`Opaque` (기본)	임의 비밀 데이터
`kubernetes.io/dockerconfigjson`	프라이빗 레지스트리 인증
`kubernetes.io/tls`	TLS 인증서 (`tls.crt`, `tls.key`)
`kubernetes.io/service-account-token`	서비스 어카운트 토큰
`kubernetes.io/ssh-auth`	SSH 인증 키

# 프라이빗 레지스트리 secret
kubectl create secret docker-registry regcred \
  --docker-server=registry.example.com \
  --docker-username=admin \
  --docker-password=secret \
  --docker-email=admin@example.com

# TLS secret
kubectl create secret tls tls-secret \
  --cert=server.crt \
  --key=server.key

Pod 에서 사용

1. 환경 변수 (개별)

spec:
  containers:
    - name: app
      image: app:v1
      env:
        - name: LOG_LEVEL
          valueFrom:
            configMapKeyRef:
              name: app-config
              key: log_level
        - name: DB_PASSWORD
          valueFrom:
            secretKeyRef:
              name: db-creds
              key: password
        - name: DB_HOST
          valueFrom:
            configMapKeyRef:
              name: app-config
              key: db_host

2. 환경 변수 (전체 import)

spec:
  containers:
    - name: app
      envFrom:
        - configMapRef:
            name: app-config     # ConfigMap 의 모든 키가 env 로
        - secretRef:
            name: db-creds       # Secret 의 모든 키가 env 로

3. Volume mount (파일로 마운트)

spec:
  containers:
    - name: app
      volumeMounts:
        - name: config-vol
          mountPath: /etc/config
          readOnly: true
        - name: secret-vol
          mountPath: /etc/secrets
          readOnly: true
        - name: nginx-conf
          mountPath: /etc/nginx/nginx.conf
          subPath: nginx.conf      # 특정 키만 단일 파일로
  volumes:
    - name: config-vol
      configMap:
        name: app-config
        items:                    # 특정 키만 선택 (선택적)
          - key: feature_flags
            path: feature_flags.yaml
    - name: secret-vol
      secret:
        secretName: db-creds
        defaultMode: 0400         # read-only (소유자만)
    - name: nginx-conf
      configMap:
        name: app-config

env vs volume mount 비교

flowchart LR
    subgraph "환경 변수 방식"
        CM1["ConfigMap"] -->|"envFrom / valueFrom"| ENV["Pod 환경 변수\n(start 시 로드)"]
        ENV --> App1["앱"]
        App1 -->|"변경 시"| Restart["Pod 재시작 필요"]
    end
    subgraph "Volume Mount 방식"
        CM2["ConfigMap"] -->|"volume mount"| File["파일 시스템\n(/etc/config)"]
        File --> App2["앱"]
        App2 -->|"변경 시"| Auto["자동 반영\n(수십 초 후)"]
    end

항목	환경 변수	Volume Mount
로드 시점	Pod 시작 시	실행 중 갱신 가능
ConfigMap 변경 반영	Pod 재시작 필요	자동 반영 (kubelet sync)
접근 방식	`os.getenv()`	파일 읽기
대용량 데이터	비권장	적합
민감 데이터	프로세스 환경에 노출	파일 권한으로 제어

[!TIP] 설정 Hot Reload 가 필요하면 Volume Mount 를 사용하고, 앱이 파일 변경을 감지(inotify)하도록 구현. 환경 변수는 Pod 재시작 없이 변경 불가.

Immutable ConfigMap / Secret

쿠버네티스 1.21+ 에서 immutable: true 지원.

apiVersion: v1
kind: ConfigMap
metadata:
  name: app-config-v1
immutable: true    # 이 ConfigMap 은 변경 불가
data:
  version: "1.0.0"
  config: "..."

장점:

etcd 의 변경 감시(watch) 부하 제거 (수천 개 ConfigMap 이 있는 클러스터에서 유의미)
실수로 설정 변경 방지
변경이 필요하면 새 이름으로 새 ConfigMap 생성 후 Pod 업데이트 (GitOps 친화적)

# immutable ConfigMap 변경 시도 (실패)
kubectl patch configmap app-config-v1 --patch '{"data":{"new_key":"value"}}'
# Error: configmap "app-config-v1" is immutable

Secret 관리: git 에 평문 절대 금지

flowchart TD
    Q{"Secret 관리 방식"}
    Q --> S1["Sealed Secrets\n(Bitnami)"]
    Q --> S2["External Secrets Operator\n(ESO)"]
    Q --> S3["SOPS + age/KMS"]
    Q --> S4["Vault Agent / CSI Driver"]
    S1 -->|"GitOps 친화"| GitOps["git에 암호화 commit 가능"]
    S2 -->|"클라우드 통합"| Cloud["AWS/GCP/Azure 시크릿 동기화"]
    S3 -->|"파일 단위 암호화"| Git2["git에 SOPS 파일 commit"]
    S4 -->|"중앙집중식"| Vault["HashiCorp Vault 연동"]

1. Sealed Secrets (Bitnami)

클러스터의 공개키로 Secret 을 암호화. 복호화는 클러스터 안에서만 가능.

# Sealed Secrets 컨트롤러 설치
helm install sealed-secrets \
  oci://registry-1.docker.io/bitnamicharts/sealed-secrets \
  -n kube-system

# 클러스터 공개키 가져오기
kubeseal --fetch-cert > pub-cert.pem

# Secret 생성 (임시)
kubectl create secret generic db-creds \
  --from-literal=password=MySecret123 \
  --dry-run=client -o yaml > secret.yaml

# SealedSecret 으로 암호화
kubeseal --cert pub-cert.pem -f secret.yaml -w sealed-secret.yaml

# git 에 안전하게 커밋
git add sealed-secret.yaml && git commit -m "add sealed db-creds"

SealedSecret 을 git 에 올리면 ArgoCD/Flux 가 자동으로 클러스터에 복호화 적용.

2. External Secrets Operator (ESO)

클라우드 시크릿 관리 서비스(AWS Secrets Manager, GCP Secret Manager, Vault 등)와 K8s Secret 을 동기화.

# ClusterSecretStore: 시크릿 소스 설정
apiVersion: external-secrets.io/v1beta1
kind: ClusterSecretStore
metadata:
  name: aws-secrets-manager
spec:
  provider:
    aws:
      service: SecretsManager
      region: ap-northeast-2
      auth:
        jwt:
          serviceAccountRef:
            name: external-secrets-sa
            namespace: external-secrets

---
# ExternalSecret: 동기화 규칙
apiVersion: external-secrets.io/v1beta1
kind: ExternalSecret
metadata:
  name: db-creds
  namespace: production
spec:
  refreshInterval: 1h                # 1시간마다 동기화
  secretStoreRef:
    name: aws-secrets-manager
    kind: ClusterSecretStore
  target:
    name: db-creds                   # 생성할 K8s Secret 이름
    creationPolicy: Owner
  data:
    - secretKey: password            # K8s Secret 의 키
      remoteRef:
        key: prod/myapp/db           # AWS Secrets Manager 경로
        property: password           # JSON 필드
    - secretKey: username
      remoteRef:
        key: prod/myapp/db
        property: username

3. SOPS (Secrets OPerationS)

파일 자체를 암호화해서 git 에 커밋. age 또는 AWS KMS 키로 복호화.

# Secret YAML 암호화 (age 키 사용)
sops -e -i secrets/db-creds.yaml
# 복호화 후 적용 (CI/CD)
sops -d secrets/db-creds.yaml | kubectl apply -f -

4. 관리 방식 비교

방식	GitOps 친화성	클라우드 의존	학습 비용	시크릿 로테이션
Sealed Secrets	높음	없음	낮음	수동 재암호화
ESO	중간	높음	중간	자동 (refreshInterval)
SOPS	높음	KMS 선택적	중간	수동
Vault Agent	낮음	없음	높음	자동

etcd Encryption at Rest

Secret 이 etcd 에 암호화 저장되도록 kube-apiserver 옵션 설정:

# kube-apiserver flag
--encryption-provider-config=/etc/kubernetes/encryption-config.yaml

# 기존 Secret 재암호화 (적용 후)
kubectl get secrets --all-namespaces -o json | kubectl replace -f -

흔한 함정

[!WARNING]

base64 = 암호화 오해: base64 는 인코딩. echo "dGVzdA==" | base64 -d 한 줄이면 복호화. 실제 보안은 etcd encryption + RBAC.

Secret 을 git 에 평문 커밋: 한 번 노출된 비밀은 히스토리에 남음. git filter-repo 로 지워야. Sealed Secrets/ESO/SOPS 사용.

env var 갱신 안 됨: ConfigMap 변경 후 환경변수로 주입된 Pod 는 재시작 필요. Volume Mount 로 hot-reload 구현.

너무 큰 ConfigMap (1MiB+): 거절됨. 큰 데이터(ML 모델, 바이너리)는 PVC, S3 mount, init container 로 처리.

etcd encryption 미설정: 클러스터 관리자가 etcd 직접 접근 시 모든 Secret 평문 노출. 프로덕션에서는 반드시 설정.

Secret RBAC 미설정: default ServiceAccount 에 Secret 읽기 권한 부여되면 모든 Pod 가 Secret 접근 가능. 최소 권한 원칙 적용.

immutable 사용 시 변경 방법 혼동: immutable ConfigMap 수정 불가. 새 이름(v2, hash suffix)으로 생성 후 Pod 롤링 업데이트.

[K8s] DaemonSet: 모든 노드에 한 pod

koa (김신건) — Wed, 15 Jul 2026 00:00:00 GMT

정의

DaemonSet 은 클러스터의 각 노드에 정확히 1개의 Pod 을 보장하는 워크로드 리소스. 노드가 추가되면 자동으로 Pod 가 배포되고, 노드가 제거되면 자동으로 정리된다.

Deployment 가 “N 개의 replicas” 를 어딘가에 배치한다면, DaemonSet 은 “모든 노드마다 1개” 를 보장한다.

언제 쓰이나

카테고리	예시
로그 수집	fluent-bit, fluentd, vector, filebeat
메트릭 수집	node-exporter, datadog-agent, dynatrace-oneagent
네트워크 플러그인	calico-node, cilium, kube-proxy, flannel
스토리지 드라이버	csi-driver-nfs, longhorn-manager
보안/감사	falco, sysdig-agent, aqua-enforcer
GPU 드라이버	nvidia-device-plugin, amd-gpu-plugin

동작 원리

flowchart TB
    DS["DaemonSet (컨트롤러)"] --> Check{"새 노드 감지?"}
    Check -->|"Yes"| Schedule["해당 노드에 Pod 스케줄"]
    Check -->|"No"| Watch["노드 이벤트 감시 중"]
    Schedule --> P1["Node 1: Pod (fluent-bit)"]
    Schedule --> P2["Node 2: Pod (fluent-bit)"]
    Schedule --> P3["Node 3: Pod (fluent-bit)"]
    P1 & P2 & P3 --> Log["로그/메트릭 수집"]
    NodeDel["노드 삭제"] --> Clean["Pod 자동 정리"]

DaemonSet 컨트롤러는 kube-controller-manager 안에 내장. 클러스터 이벤트를 감시하며 노드와 Pod 수를 일치시킨다.

기본 YAML: fluent-bit 로그 수집

apiVersion: apps/v1
kind: DaemonSet
metadata:
  name: fluent-bit
  namespace: logging
  labels:
    app: fluent-bit
spec:
  selector:
    matchLabels:
      app: fluent-bit
  template:
    metadata:
      labels:
        app: fluent-bit
    spec:
      serviceAccountName: fluent-bit
      tolerations:
        - operator: Exists          # 모든 taint 무시: master/control-plane 포함
      hostNetwork: false
      containers:
        - name: fluent-bit
          image: fluent/fluent-bit:3.0
          resources:
            requests:
              cpu: 50m
              memory: 50Mi
            limits:
              cpu: 200m
              memory: 200Mi
          volumeMounts:
            - name: varlog
              mountPath: /var/log
              readOnly: true
            - name: containers
              mountPath: /var/lib/docker/containers
              readOnly: true
            - name: config
              mountPath: /fluent-bit/etc/
      volumes:
        - name: varlog
          hostPath:
            path: /var/log
        - name: containers
          hostPath:
            path: /var/lib/docker/containers
        - name: config
          configMap:
            name: fluent-bit-config

node-exporter: Prometheus 메트릭 수집

apiVersion: apps/v1
kind: DaemonSet
metadata:
  name: node-exporter
  namespace: monitoring
spec:
  selector:
    matchLabels:
      app: node-exporter
  template:
    metadata:
      labels:
        app: node-exporter
    spec:
      tolerations:
        - effect: NoSchedule
          operator: Exists
      hostPID: true              # 노드 프로세스 정보 접근
      hostIPC: true
      hostNetwork: true          # 노드 네트워크 스택 직접 접근
      containers:
        - name: node-exporter
          image: prom/node-exporter:v1.8.0
          ports:
            - containerPort: 9100
              hostPort: 9100     # 노드 포트 직접 바인딩
          args:
            - "--path.procfs=/host/proc"
            - "--path.sysfs=/host/sys"
            - "--path.rootfs=/host/root"
            - "--collector.filesystem.mount-points-exclude=^/(sys|proc|dev)($|/)"
          volumeMounts:
            - name: proc
              mountPath: /host/proc
              readOnly: true
            - name: sys
              mountPath: /host/sys
              readOnly: true
            - name: root
              mountPath: /host/root
              mountPropagation: HostToContainer
              readOnly: true
      volumes:
        - name: proc
          hostPath: { path: /proc }
        - name: sys
          hostPath: { path: /sys }
        - name: root
          hostPath: { path: / }

Tolerations: 특정 노드 포함/제외

DaemonSet 은 기본적으로 node.kubernetes.io/unschedulable 등 일부 taint 를 자동으로 tolerate 한다. 하지만 사용자 정의 taint 는 명시해야 한다.

spec:
  template:
    spec:
      tolerations:
        # 모든 taint 무시 (master 포함, 권장 설정)
        - operator: Exists

        # 특정 taint 만 허용
        - key: "node-role.kubernetes.io/control-plane"
          effect: NoSchedule
          operator: Exists

        # GPU 노드 포함
        - key: "nvidia.com/gpu"
          effect: NoSchedule
          operator: Exists

        # 특정 팀 노드만 (Equal)
        - key: "team"
          value: "infra"
          effect: NoSchedule
          operator: Equal

Node Selector: 특정 노드만 대상

GPU 드라이버, ARM 전용 에이전트 등 특정 노드만 필요할 때:

spec:
  template:
    spec:
      nodeSelector:
        kubernetes.io/os: linux
        accelerator: nvidia-tesla-v100

      # 더 유연한 nodeAffinity
      affinity:
        nodeAffinity:
          requiredDuringSchedulingIgnoredDuringExecution:
            nodeSelectorTerms:
              - matchExpressions:
                  - key: node-type
                    operator: In
                    values: ["gpu", "high-memory"]

노드 토폴로지 예시

flowchart TB
    DS_Log["DaemonSet: fluent-bit\n(모든 노드)"]
    DS_GPU["DaemonSet: nvidia-plugin\n(GPU 노드만)"]

    subgraph "노드 풀"
        Node1["Worker Node 1\n(CPU)"]
        Node2["Worker Node 2\n(CPU)"]
        Node3["Worker Node 3\n(GPU)"]
        Node4["Master Node"]
    end

    DS_Log --> Node1 & Node2 & Node3
    DS_Log -->|"toleration: control-plane"| Node4
    DS_GPU -->|"nodeSelector: gpu=true"| Node3

UpdateStrategy: 안전한 업데이트

DaemonSet 업데이트 전략을 설정하지 않으면 기본은 RollingUpdate.

spec:
  updateStrategy:
    type: RollingUpdate
    rollingUpdate:
      maxUnavailable: 1    # 동시에 최대 1개 노드에서 재시작

  # 또는 OnDelete: kubectl delete pod 시만 업데이트
  # updateStrategy:
  #   type: OnDelete

전략	동작	사용 시점
`RollingUpdate` (기본)	순차적으로 pod 교체, maxUnavailable 제어	일반적인 업데이트
`OnDelete`	pod 수동 삭제 시에만 새 버전 시작	노드별 제어가 필요할 때

[!IMPORTANT] maxUnavailable: 1 로 설정하면 한 번에 1개 노드에서만 재시작. 로그/메트릭 수집 공백을 최소화. 클러스터가 100+ 노드면 maxUnavailable: 10% 처럼 비율로 지정 가능.

고급 패턴

init container 로 노드 초기화

spec:
  template:
    spec:
      initContainers:
        - name: install-cni
          image: calico/cni:v3.27.0
          command: ["/install-cni.sh"]
          securityContext:
            privileged: true
          volumeMounts:
            - name: cni-bin
              mountPath: /host/opt/cni/bin
      containers:
        - name: calico-node
          # ...

환경변수로 노드 정보 주입

spec:
  template:
    spec:
      containers:
        - name: agent
          env:
            - name: NODE_NAME
              valueFrom:
                fieldRef:
                  fieldPath: spec.nodeName
            - name: NODE_IP
              valueFrom:
                fieldRef:
                  fieldPath: status.hostIP
            - name: POD_IP
              valueFrom:
                fieldRef:
                  fieldPath: status.podIP

이렇게 하면 에이전트가 자신이 어떤 노드에서 실행 중인지 알 수 있다.

Deployment 와 비교

flowchart LR
    subgraph "Deployment (replicas=3)"
        D["Deployment"] --> P_D1["Pod"] & P_D2["Pod"] & P_D3["Pod"]
        P_D1 --> N1["Node A"]
        P_D2 --> N2["Node B"]
        P_D3 --> N2
    end
    subgraph "DaemonSet (모든 노드)"
        DS["DaemonSet"] --> P_S1["Pod"] & P_S2["Pod"] & P_S3["Pod"]
        P_S1 --> N3["Node A"]
        P_S2 --> N4["Node B"]
        P_S3 --> N5["Node C"]
    end

항목	Deployment	DaemonSet
Pod 수	지정한 replicas 수	노드 수와 동일
스케줄 결정	kube-scheduler	DaemonSet 컨트롤러 직접
주 용도	앱 서비스	인프라 에이전트
노드 신규 추가	재스케줄 없음	자동 배포
HPA 연동	가능	없음 (노드 수가 replica)

흔한 함정

[!WARNING]

Tolerations 누락 = control-plane 노드나 taint 있는 워커 노드에 Pod 가 배치 안 됨. 로그/메트릭 공백 발생. operator: Exists 로 전체 허용하거나 명시적 taint 나열.

Resource limit 너무 작음 = 트래픽 많은 노드에서 OOM 발생. 노드 크기 비례로 limit 설정. memory: 200Mi 이상 권장.

hostNetwork 부주의 = 노드 포트 직접 바인딩 → 포트 충돌 위험. 반드시 hostPort 고정 또는 Headless Service 사용.

maxUnavailable 기본값 = 기본 maxUnavailable=1. 100개 노드면 업데이트에 수십 분 소요. 비율 지정으로 조정 가능.

네임스페이스 간 로그 접근 = fluent-bit 이 /var/log/containers 접근 시 모든 네임스페이스 로그가 노출. RBAC + network policy 로 수집 대상 제한.

DaemonSet 으로 앱 배포 = 서비스 Pod 를 DaemonSet 으로 배포 금지. 노드 증설마다 자동 복제됨. Deployment 사용.

[K8s] Deployment: ReplicaSet, rolling update, rollback

koa (김신건) — Wed, 15 Jul 2026 00:00:00 GMT

정의

Deployment = stateless 워크로드를 위한 컨트롤러. 내부적으로 ReplicaSet 관리 + rolling update / rollback.

사용 시나리오

상황	Deployment 역할
Stateless API / Web 배포	replica 수 보장 + rolling update
이미지 버전 업그레이드	무중단 rolling update
배포 실패 시 복구	revision history 로 rollback
점진적 배포	maxSurge / maxUnavailable 조절

계층

flowchart TB
    Dep[Deployment] --> RS[ReplicaSet]
    RS --> P1[Pod 1]
    RS --> P2[Pod 2]
    RS --> P3[Pod 3]
    Note["사용자는 Deployment 만 관리.<br/>ReplicaSet 은 자동."]

객체	책임
Deployment	원하는 상태 + rollout 전략
ReplicaSet	replica 수 보장
Pod	실제 워크로드

YAML

apiVersion: apps/v1
kind: Deployment
metadata:
  name: web
spec:
  replicas: 3
  selector:
    matchLabels: { app: web }
  strategy:
    type: RollingUpdate
    rollingUpdate:
      maxUnavailable: 1
      maxSurge: 1
  minReadySeconds: 10           # 새 pod ready 후 추가 10초 대기
  progressDeadlineSeconds: 300  # 5분 내 완료 안 되면 Failed
  revisionHistoryLimit: 10
  template:
    metadata:
      labels: { app: web }
    spec:
      containers:
        - name: nginx
          image: nginx:1.27
          ports:
            - containerPort: 80
          readinessProbe:
            httpGet: { path: /, port: 80 }
            initialDelaySeconds: 5
            periodSeconds: 5
          resources:
            requests:
              cpu: 100m
              memory: 128Mi
            limits:
              cpu: 500m
              memory: 512Mi

Rolling Update

sequenceDiagram
    autonumber
    participant D as Deployment
    participant Old as ReplicaSet v1 (3 pods)
    participant New as ReplicaSet v2 (0 pods)

    D->>New: scale up 1 (maxSurge)
    Note over Old,New: 4 pods 동안 운영
    New->>D: pod ready
    D->>Old: scale down 1 (maxUnavailable)
    Note over Old,New: 3 pods
    D->>New: scale up 1
    Note over Old,New: 4 pods
    Note over D: 반복...
    Note over Old: 모두 0
    Note over New: 모두 3

옵션	의미	기본
`maxUnavailable`	동시에 불가용 될 수 있는 pod 수 (또는 %)	25%
`maxSurge`	동시에 추가 될 수 있는 pod 수	25%

[!TIP] 짧은 maxUnavailable + 짧은 maxSurge = 안전 + 느림. zero-downtime + readiness probe 필수.

Recreate Strategy

strategy:
  type: Recreate

옛 pod 모두 종료 → 새 pod 시작.
다운타임 발생.
DB schema 마이그레이션 같이 두 버전 동시 운영 불가 한 경우.

배포 상태 흐름

flowchart LR
    Prog["Progressing<br/>(롤아웃 중)"]
    Done["Complete<br/>(모든 pod ready)"]
    Fail["Failed<br/>(deadline 초과)"]

    Prog -->|"모든 replica ready"| Done
    Prog -->|"progressDeadlineSeconds 초과"| Fail
    Fail -->|"rollback"| Prog

progressDeadlineSeconds 기본 600초. 이 시간 내 진행 없으면 Failed 마킹.
minReadySeconds = 새 pod 가 ready 된 후 추가 대기 시간. 실제 트래픽 안정화 확인용.

ConfigMap / Secret 주입

spec:
  containers:
    - name: app
      image: myapp:1.0
      env:
        - name: DB_HOST
          valueFrom:
            configMapKeyRef:
              name: app-config
              key: db_host
        - name: DB_PASSWORD
          valueFrom:
            secretKeyRef:
              name: app-secret
              key: db_password
      envFrom:
        - configMapRef:
            name: app-config    # ConfigMap 의 모든 key → env

ConfigMap/Secret 변경 시 pod 재시작 필요 (envFrom). 실시간 반영은 volumeMount + 파일 감시 패턴.

Rollout 명령

kubectl rollout status deployment/web        # 진행 상황
kubectl rollout history deployment/web        # 이전 버전 목록
kubectl rollout undo deployment/web           # 이전 버전으로 롤백
kubectl rollout undo deployment/web --to-revision=3
kubectl rollout restart deployment/web        # 모든 pod 재시작 (rolling)
kubectl rollout pause deployment/web          # rollout 일시 정지 (canary 용)
kubectl rollout resume deployment/web

Canary / Blue-Green (Deployment 만으로는 부족)

Deployment 의 기본 rolling 은 부분 canary. 진짜 canary / blue-green 은:

Istio / Linkerd: traffic 분배 5%, 20%, 50%, 100%
Argo Rollouts: 정식 canary / blue-green
Flagger: progressive delivery 자동화

자세한 건 [[Zero Downtime Deployment]] 참고.

Revision History

spec:
  revisionHistoryLimit: 10   # 기본 10. 옛 ReplicaSet 보관 수

kubectl get rs   # 옛 ReplicaSet 들이 있음 (replica=0)

헬스 체크 3종

spec:
  containers:
    - name: app
      livenessProbe:        # 실패 시 pod 재시작
        httpGet: { path: /healthz, port: 8080 }
        initialDelaySeconds: 15
        failureThreshold: 3
      readinessProbe:       # 실패 시 Service 에서 제외
        httpGet: { path: /ready, port: 8080 }
        periodSeconds: 5
      startupProbe:         # 느린 앱 초기화 대기 (1.18+)
        httpGet: { path: /healthz, port: 8080 }
        failureThreshold: 30
        periodSeconds: 10   # 최대 300초 대기

프로브	실패 시 동작	용도
`livenessProbe`	pod 재시작	데드락 / 무한루프 감지
`readinessProbe`	Service 엔드포인트 제거	트래픽 차단 (배포 중)
`startupProbe`	초기화 완료 전 다른 프로브 비활성	느린 앱 초기화

[!TIP] startupProbe 없이 livenessProbe 만 쓰면 느린 앱이 초기화 중 재시작 루프 에 빠짐.

PodDisruptionBudget

노드 드레인 / 클러스터 업그레이드 시 pod 가용성 최소 보장.

apiVersion: policy/v1
kind: PodDisruptionBudget
metadata:
  name: web-pdb
spec:
  minAvailable: 2          # 최소 2개 항상 유지
  # maxUnavailable: 1      # 또는 최대 1개까지 중단 허용
  selector:
    matchLabels: { app: web }

[!TIP] PDB 없으면 kubectl drain 이 모든 pod 를 동시에 퇴거 할 수 있음. 3개 replica + minAvailable: 2 조합이 안전.

흔한 함정

[!WARNING]

readinessProbe 없음 = rolling update 가 준비 안 된 pod 도 ready 로 인식 → 503 폭증.

maxSurge=0 = 새 pod 만들기 전에 옛 pod 죽임 → 일시 capacity 부족.

이미지 tag latest = kubectl rollout restart 안 하면 새 이미지 안 받음. 항상 명시 tag (sha).

Resource limits 없이 = 한 pod 가 node 자원 독점 → 다른 pod throttle.

minReadySeconds 미설정 = 새 pod 가 ready 직후 바로 old 삭제 → 실제 트래픽 오류 가능.

[K8s] NetworkPolicy: pod 간 네트워크 차단

koa (김신건) — Wed, 15 Jul 2026 00:00:00 GMT

정의

NetworkPolicy = pod 간 허용된 트래픽만 통과. 없으면 모든 pod ↔ pod 가 허용 (기본 open).

[!IMPORTANT] NetworkPolicy 는 CNI 플러그인이 구현. Calico, Cilium, Weave 가 지원. Flannel 단독은 미지원.

사용 시나리오

상황	NetworkPolicy 역할
Zero-Trust 마이크로서비스	서비스 간 허가된 경로만 개방
PCI-DSS / HIPAA 규정 준수	민감 데이터 namespace 격리
멀티 테넌트 클러스터	테넌트 간 트래픽 완전 격리
DB 보호	frontend 가 db 직접 접근 금지
외부 API 제한	특정 pod 만 외부 인터넷 egress 허용

트래픽 흐름 시각화

flowchart LR
    NET["외부 인터넷"]
    FE["frontend pod"]
    API["api pod"]
    DB["db pod"]

    NET -.->|"차단"| API
    NET -.->|"차단"| DB
    FE -->|"허용 (8080)"| API
    FE -.->|"차단"| DB
    API -->|"허용 (5432)"| DB

NetworkPolicy 는 L3/L4 방화벽. 각 pod 에 ingress/egress 규칙이 독립 적용.

Default Deny

apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
metadata: { name: default-deny }
spec:
  podSelector: {}        # 모든 pod
  policyTypes: [Ingress, Egress]
  # ingress / egress 비어있음 → 전부 차단

모든 namespace 에 default deny + 필요한 규칙만 명시 허용 이 Zero-Trust 정통.

Ingress 허용 예시

kind: NetworkPolicy
metadata: { name: allow-frontend-to-api }
spec:
  podSelector:
    matchLabels: { app: api }
  policyTypes: [Ingress]
  ingress:
    - from:
        - podSelector:
            matchLabels: { app: frontend }
      ports:
        - protocol: TCP
          port: 8080

api pod 는 frontend pod 의 8080 트래픽만 허용.

Egress 허용 예시

kind: NetworkPolicy
metadata: { name: allow-egress-to-db }
spec:
  podSelector:
    matchLabels: { app: api }
  policyTypes: [Egress]
  egress:
    - to:
        - podSelector:
            matchLabels: { app: db }
      ports:
        - protocol: TCP
          port: 5432
    - to:                    # DNS 허용 (필수)
        - namespaceSelector:
            matchLabels: { kubernetes.io/metadata.name: kube-system }
          podSelector:
            matchLabels: { k8s-app: kube-dns }
      ports:
        - protocol: UDP
          port: 53

[!CAUTION] Egress default-deny 시 DNS (kube-dns) 허용 잊지 말 것. 안 그러면 모든 외부 호출이 DNS resolution 실패.

AND / OR 조건 이해

from / to 배열에서 같은 항목 내 두 selector 나열 = AND (교집합). 다른 항목 으로 나열 = OR (합집합).

# AND: prod namespace 의 frontend pod 만 허용
ingress:
  - from:
      - namespaceSelector:           # 같은 항목
          matchLabels: { env: prod }
        podSelector:                 # AND 조건
          matchLabels: { app: frontend }

# OR: prod namespace 전체 OR frontend pod (namespace 무관)
ingress:
  - from:
      - namespaceSelector:           # 항목 1
          matchLabels: { env: prod }
      - podSelector:                 # 항목 2 → OR
          matchLabels: { app: frontend }

[!WARNING] AND / OR 구별이 가장 흔한 NetworkPolicy 실수. YAML 들여쓰기 위치가 전부.

Namespace 격리

metadata: { name: allow-from-same-namespace }
spec:
  podSelector: {}
  policyTypes: [Ingress]
  ingress:
    - from:
        - namespaceSelector:
            matchLabels:
              kubernetes.io/metadata.name: same-namespace

IP Block (외부 IP 허용)

spec:
  egress:
    - to:
        - ipBlock:
            cidr: 0.0.0.0/0
            except:
              - 10.0.0.0/8        # 내부 IP 제외
              - 172.16.0.0/12
              - 192.168.0.0/16

CNI 플러그인 비교

CNI	NetworkPolicy 지원	추가 기능
Calico	완전 지원	GlobalNetworkPolicy, eBPF 옵션
Cilium	완전 지원	L7 HTTP/gRPC, eBPF, Hubble 관측
Weave	지원	단순, 기능 제한
Flannel	미지원	별도 Calico overlay 필요
AWS VPC CNI	지원	EKS 기본, Security Group for Pods

Calico/Cilium 이 프로덕션 표준. CNI 없이 NetworkPolicy 적용 시 YAML 만 저장되고 실제 차단 없음.

프로덕션 패턴: 3-tier 격리

flowchart TD
    FE["frontend (tier=frontend)"]
    API["api (tier=api)"]
    DB["db (tier=db)"]

    FE -->|"8080"| API
    API -->|"5432"| DB
    FE -.->|"차단"| DB

# 1. 모든 트래픽 기본 차단
apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
metadata:
  name: default-deny-all
  namespace: production
spec:
  podSelector: {}
  policyTypes: [Ingress, Egress]
---
# 2. frontend → api (8080)
apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
metadata:
  name: allow-fe-to-api
  namespace: production
spec:
  podSelector: { matchLabels: { tier: api } }
  policyTypes: [Ingress]
  ingress:
    - from:
        - podSelector: { matchLabels: { tier: frontend } }
      ports:
        - { protocol: TCP, port: 8080 }
---
# 3. api → db (5432)
apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
metadata:
  name: allow-api-to-db
  namespace: production
spec:
  podSelector: { matchLabels: { tier: db } }
  policyTypes: [Ingress]
  ingress:
    - from:
        - podSelector: { matchLabels: { tier: api } }
      ports:
        - { protocol: TCP, port: 5432 }
---
# 4. api egress: db + DNS 만
apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
metadata:
  name: api-egress-allow
  namespace: production
spec:
  podSelector: { matchLabels: { tier: api } }
  policyTypes: [Egress]
  egress:
    - to:
        - podSelector: { matchLabels: { tier: db } }
      ports:
        - { protocol: TCP, port: 5432 }
    - to:
        - namespaceSelector:
            matchLabels: { kubernetes.io/metadata.name: kube-system }
          podSelector: { matchLabels: { k8s-app: kube-dns } }
      ports:
        - { protocol: UDP, port: 53 }

Cilium 의 확장 (L7 NetworkPolicy)

apiVersion: cilium.io/v2
kind: CiliumNetworkPolicy
metadata: { name: api-l7 }
spec:
  endpointSelector: { matchLabels: { app: api } }
  ingress:
    - fromEndpoints: [{ matchLabels: { app: frontend } }]
      toPorts:
        - ports: [{ port: "80", protocol: TCP }]
          rules:
            http:
              - method: GET
                path: "/api/.*"
              - method: POST
                path: "/api/orders"

L7 (HTTP method / path) 까지. Service Mesh 가 아니어도 L7 보안.

Policy 검증 / 디버깅

# 현재 namespace 의 NetworkPolicy 목록
kubectl get networkpolicy -n production

# 특정 policy 상세 보기
kubectl describe networkpolicy default-deny-all -n production

# pod 의 label 확인 (selector 매칭용)
kubectl get pod frontend-xyz -n production --show-labels

# Cilium: 엔드포인트 정책 상태
kubectl exec -n kube-system cilium-xxx -- cilium endpoint list
kubectl exec -n kube-system cilium-xxx -- cilium policy get

[!TIP] Cilium Hubble UI: 실시간 트래픽 흐름 + 차단 이유 시각화. 디버깅 시 가장 강력한 도구.

흔한 함정

[!WARNING]

CNI 가 NetworkPolicy 미지원 = YAML 만 적용되고 실제 동작 안 함. Calico/Cilium 확인.

Egress default-deny + DNS 차단 = 모든 외부 호출 실패. DNS 항상 허용.

policyTypes 누락 = Egress 없으면 egress 규칙 무시.

namespaceSelector 의 label = 1.21+ 부터 자동 kubernetes.io/metadata.name. 옛 버전은 namespace 에 직접 label.

AND/OR 혼동 = 같은 from 항목 내 두 selector = AND. 다른 항목 = OR.

[K8s] RBAC: Role, ClusterRole, ServiceAccount, RoleBinding

koa (김신건) — Wed, 15 Jul 2026 00:00:00 GMT

정의

RBAC (Role-Based Access Control) = K8s 의 권한 부여 모델. 주체 + 권한 + 바인딩.

사용 시나리오

상황	RBAC 역할
CI/CD 파이프라인	SA 에 최소 권한만 부여, 배포 자동화
멀티팀 클러스터	팀별 namespace 관리 권한 격리
Operator / Controller	CRD read/write 권한만 허용
감사 준비	누가 어떤 자원에 접근하는지 추적

API 요청 처리 흐름

flowchart LR
    Req["API 요청<br/>(kubectl / pod)"]
    Auth["Authentication<br/>(인증: 누구?)"]
    Authz["Authorization<br/>(인가: 허용?)"]
    Adm["Admission Control"]
    ETCD["etcd 저장"]

    Req --> Auth --> Authz --> Adm --> ETCD

RBAC 는 Authorization 단계 에서만 작동. Authentication 은 별도 플러그인 (X.509, OIDC 등).

4 객체

flowchart LR
    User[User / Group<br/>또는 ServiceAccount] -->|RoleBinding| Role
    User -->|ClusterRoleBinding| CRole[ClusterRole]
    Role -->|"namespace 안"| API[API resources]
    CRole -->|"cluster 전체"| API

객체	범위
`Role`	단일 namespace
`ClusterRole`	전체 cluster
`RoleBinding`	같은 namespace 안 user → Role
`ClusterRoleBinding`	cluster 전체 user → ClusterRole

ServiceAccount

apiVersion: v1
kind: ServiceAccount
metadata:
  name: app-sa
  namespace: default

Pod 가 K8s API 호출 할 때의 identity.
기본은 default SA. 명시 권장.
모든 SA 는 토큰 자동 마운트 (/var/run/secrets/kubernetes.io/serviceaccount/token).

# Pod 에 SA 연결
spec:
  serviceAccountName: app-sa
  automountServiceAccountToken: false  # API 호출 안 하면 false 권장

Role 예시

apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
  name: pod-reader
  namespace: default
rules:
  - apiGroups: [""]
    resources: [pods, pods/log]
    verbs: [get, list, watch]
  - apiGroups: [apps]
    resources: [deployments]
    verbs: [get, list]

verb	의미
`get`	단일
`list`	목록
`watch`	변경 stream
`create`	생성
`update`	갱신
`patch`	부분 갱신
`delete`	삭제
`deletecollection`	일괄 삭제

RoleBinding

apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
  name: app-pod-reader
  namespace: default
subjects:
  - kind: ServiceAccount
    name: app-sa
    namespace: default
roleRef:
  kind: Role
  name: pod-reader
  apiGroup: rbac.authorization.k8s.io

ClusterRole + ClusterRoleBinding

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata: { name: namespace-admin }
rules:
  - apiGroups: ["*"]
    resources: ["*"]
    verbs: ["*"]
---
kind: ClusterRoleBinding
metadata: { name: alice-cluster-admin }
subjects:
  - kind: User
    name: alice
roleRef:
  kind: ClusterRole
  name: namespace-admin

최소 권한 패턴

flowchart TD
    Goal["최소 권한 원칙"]
    Goal --> P1["필요한 verb 만<br/>(get, list 등)"]
    Goal --> P2["필요한 resource 만<br/>(pods 지정)"]
    Goal --> P3["필요한 namespace 만<br/>(Role 우선)"]
    Goal --> P4["별도 SA 사용<br/>(default SA 금지)"]

CI/CD SA 예시: 배포만 하는 SA 에 최소 권한 부여:

apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
  name: deployer
  namespace: production
rules:
  - apiGroups: [apps]
    resources: [deployments]
    verbs: [get, list, patch, update]
  - apiGroups: [""]
    resources: [pods]
    verbs: [get, list]

검사 / 디버깅

# 내가 무엇을 할 수 있나?
kubectl auth can-i get pods
kubectl auth can-i list secrets --as alice

# 특정 SA 권한
kubectl auth can-i get pods --as=system:serviceaccount:default:app-sa

# 누가 어떤 권한?
kubectl get rolebinding,clusterrolebinding -A | grep alice

# SA 의 모든 RoleBinding 조회
kubectl get rolebindings -A -o json | \
  jq '.items[] | select(.subjects[]?.name=="app-sa")'

Aggregated ClusterRole

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: monitoring
  labels:
    rbac.authorization.k8s.io/aggregate-to-monitoring: "true"
rules: [...]

다른 ClusterRole 이 자동 결합. 운영 도구의 plugin 권한 추가 패턴.

Workload Identity (IRSA / GKE WI)

클라우드 SA 를 K8s SA 와 연동해 AWS/GCP 권한 획득. 토큰 직접 관리 불필요.

flowchart LR
    Pod["pod (SA: app-sa)"]
    STS["AWS STS<br/>(token 교환)"]
    OIDC["K8s OIDC Provider"]
    IAM["AWS IAM Role"]
    S3["AWS S3"]

    Pod -->|"SA token"| STS
    STS -->|"OIDC 검증"| OIDC
    STS -->|"Role 확인"| IAM
    STS -->|"임시 credential"| Pod
    Pod -->|"임시 credential"| S3

AWS IRSA (EKS):

# ServiceAccount 에 IAM Role ARN 어노테이션
apiVersion: v1
kind: ServiceAccount
metadata:
  name: app-sa
  namespace: default
  annotations:
    eks.amazonaws.com/role-arn: arn:aws:iam::123456789012:role/app-role

[!TIP] GKE Workload Identity, Azure Workload Identity 도 동일 패턴. 인스턴스 프로파일 없이 pod 단위 IAM 제어 가능.

흔한 함정

[!WARNING]

verbs: ["*"] 남발 = 권한 최소화 원칙 위배. 필요한 verb 만.

default SA 사용 = 모든 pod 가 같은 권한. 명시 SA + 최소 Role.

apiGroups: ["*"] 와 resources: ["*"] = 모든 자원 접근. cluster-admin과 다를 바 없음.

RoleBinding namespace 잘못 = Role 은 같은 namespace 만. 다른 namespace 면 무효.

token 직접 사용 = 만료 짧음 (1시간 기본, 1.24+). projected SA token 으로 자동 갱신.

[Kubernetes] Admission Controllers

koa (김신건) — Tue, 07 Jul 2026 00:00:00 GMT

정의

Admission Controller 는 kube-apiserver 가 인증/인가 후, etcd 저장 전에 요청을 가로채 검증 (validate) 하거나 수정 (mutate) 하는 계층입니다. 클러스터 정책 강제, 기본값 주입, 보안 검사의 핵심 지점입니다.

요청 흐름

flowchart LR
  U[사용자/kubectl] --> API[kube-apiserver]
  API --> Auth[인증<br/>Authentication]
  Auth --> Authz[인가<br/>Authorization RBAC]
  Authz --> Mut[Mutating<br/>Admission]
  Mut --> Val[Validating<br/>Admission]
  Val --> Persist[(etcd 저장)]
  Persist --> API

순서:

인증
인가 (RBAC)
Mutating admission: 요청 body 수정 (기본값, sidecar 주입, 라벨 추가)
Validating admission: 검증만 (수정 없음)
etcd 저장

Mutating 이 먼저인 이유: Validating 이 최종 상태를 검사할 수 있도록.

내장 Admission Controller

kube-apiserver flag --enable-admission-plugins 로 활성화. 관용 (v1.29+ 기본):

NamespaceLifecycle: 삭제 중인 namespace 에 리소스 생성 방지
LimitRanger: LimitRange 정책 적용
ServiceAccount: Pod 에 default SA 삽입, secret token mount
DefaultStorageClass: PVC 에 default StorageClass 자동 할당
DefaultTolerationSeconds: NotReady/unreachable taint 에 300s toleration
MutatingAdmissionWebhook: 동적 mutating hook
ValidatingAdmissionWebhook: 동적 validating hook
ResourceQuota: ResourceQuota 정책 적용
PodSecurity: [[k8s-pod|Pod]] 보안 표준 (privileged/baseline/restricted)
NodeRestriction: kubelet 이 자기 노드/pod 만 수정 가능
PriorityClass

Pod Security Admission (PSA)

v1.25 부터 stable. 3 profile:

privileged: 무제한 (system pods)
baseline: 알려진 privilege escalation 방지
restricted: 강력한 보안 (nonroot, seccomp, capabilities 제한)

Namespace 라벨로 지정:

apiVersion: v1
kind: Namespace
metadata:
  name: prod
  labels:
    pod-security.kubernetes.io/enforce: restricted
    pod-security.kubernetes.io/enforce-version: latest
    pod-security.kubernetes.io/audit: restricted
    pod-security.kubernetes.io/warn: restricted

세 모드:

enforce: 위반 시 거부
audit: 감사 로그만
warn: 사용자에게 warning

PodSecurityPolicy (PSP) 는 v1.25 에서 제거되었습니다. PSA + Kyverno / Gatekeeper 로 대체.

Dynamic Admission Webhook

CRD 나 커스텀 정책은 webhook 으로. 사용자가 배포한 HTTP 서버가 admission review 를 처리.

ValidatingWebhookConfiguration

apiVersion: admissionregistration.k8s.io/v1
kind: ValidatingWebhookConfiguration
metadata:
  name: my-policy
webhooks:
  - name: validate.example.com
    clientConfig:
      service:
        namespace: policy
        name: validator
        path: /validate
      caBundle: <base64 CA>
    rules:
      - apiGroups: ["apps"]
        apiVersions: ["v1"]
        operations: ["CREATE", "UPDATE"]
        resources: ["deployments"]
        scope: Namespaced
    admissionReviewVersions: ["v1"]
    sideEffects: None
    failurePolicy: Fail          # 또는 Ignore
    timeoutSeconds: 5
    namespaceSelector:
      matchLabels:
        policy-enforced: "true"

Webhook 은 다음과 같은 요청/응답:

// Request
{
  "kind": "AdmissionReview",
  "apiVersion": "admission.k8s.io/v1",
  "request": {
    "uid": "abc123",
    "kind": {"group": "apps", "version": "v1", "kind": "Deployment"},
    "operation": "CREATE",
    "object": {...}
  }
}

// Response
{
  "kind": "AdmissionReview",
  "apiVersion": "admission.k8s.io/v1",
  "response": {
    "uid": "abc123",
    "allowed": false,
    "status": {
      "message": "must set resources.limits"
    }
  }
}

MutatingWebhookConfiguration

응답에 JSON Patch 로 수정:

{
  "response": {
    "allowed": true,
    "patchType": "JSONPatch",
    "patch": "<base64 [{'op':'add','path':'/spec/foo','value':'bar'}]>"
  }
}

대표 사용 사례:

Sidecar 자동 주입 (Istio, Linkerd, Fluent Bit operator)
이미지 이름 registry prefix 추가
라벨/annotation 자동 삽입

ValidatingAdmissionPolicy (K8s 1.30 GA)

Webhook 없이 CEL (Common Expression Language) 로 policy:

apiVersion: admissionregistration.k8s.io/v1
kind: ValidatingAdmissionPolicy
metadata:
  name: require-image-registry
spec:
  failurePolicy: Fail
  matchConstraints:
    resourceRules:
      - apiGroups:   ["apps"]
        apiVersions: ["v1"]
        operations:  ["CREATE", "UPDATE"]
        resources:   ["deployments"]
  validations:
    - expression: |
        object.spec.template.spec.containers.all(c,
          c.image.startsWith("registry.example.com/"))
      message: "images must come from registry.example.com"
---
apiVersion: admissionregistration.k8s.io/v1
kind: ValidatingAdmissionPolicyBinding
metadata:
  name: require-image-registry-binding
spec:
  policyName: require-image-registry
  validationActions: [Deny]
  matchResources:
    namespaceSelector:
      matchLabels:
        policy-enforced: "true"

장점:

웹훅 서버 배포 불필요 (성능/가용성 이점)
YAML 만으로 정책 표현
서버 죽어도 정책 유효 (webhook 은 서버 죽으면 정책 무력)

단점:

CEL 만 사용 (복잡한 로직 제한)
Mutating 지원 X (Mutating은 v1.32+ alpha)

OPA Gatekeeper

CNCF 프로젝트. Rego 언어로 정책 정의.

apiVersion: constraints.gatekeeper.sh/v1beta1
kind: K8sRequiredLabels
metadata:
  name: ns-must-have-owner
spec:
  match:
    kinds:
      - apiGroups: [""]
        kinds: [Namespace]
  parameters:
    labels: [owner]

Constraint Template (Rego):

package k8srequiredlabels

violation[{"msg": msg}] {
  required := input.parameters.labels
  provided := input.review.object.metadata.labels
  missing := required[_]
  not provided[missing]
  msg := sprintf("missing label: %v", [missing])
}

강점: 표현력 강력, 정책 라이브러리 방대 약점: Rego 학습 곡선, Gatekeeper 자체 리소스 부담

Kyverno

Kubernetes-native (YAML 만). Rego 안 배워도 됨.

apiVersion: kyverno.io/v1
kind: ClusterPolicy
metadata:
  name: require-labels
spec:
  validationFailureAction: Enforce
  rules:
    - name: check-owner-label
      match:
        any:
          - resources:
              kinds: [Namespace]
      validate:
        message: "namespace must have label 'owner'"
        pattern:
          metadata:
            labels:
              owner: "?*"

Mutating, generating, verifying (이미지 서명) 도 지원. Sigstore 통합.

정책 도구 선택

도구	정책 언어	장점	언제
PSA	내장	무설정, K8s 표준	Pod 보안 표준만
ValidatingAdmissionPolicy	CEL	웹훅 불필요, 성능	Simple validation
OPA Gatekeeper	Rego	표현력 최상	복잡한 정책, 다양한 리소스
Kyverno	YAML	학습 부담 낮음	K8s 팀 친숙 언어

관용: 소규모 클러스터 = PSA + Kyverno. 대규모 = Gatekeeper.

실전 정책 예시

1. `latest` 이미지 금지

Kyverno:

apiVersion: kyverno.io/v1
kind: ClusterPolicy
metadata:
  name: disallow-latest-tag
spec:
  validationFailureAction: Enforce
  rules:
    - name: check-image-tag
      match:
        any:
          - resources:
              kinds: [Pod]
      validate:
        message: "image tag 'latest' is prohibited"
        pattern:
          spec:
            containers:
              - image: "!*:latest"

2. 리소스 요청 필수

Gatekeeper Constraint Template:

package k8srequiredresources

violation[{"msg": msg}] {
  container := input.review.object.spec.containers[_]
  not container.resources.requests.cpu
  msg := sprintf("container %v missing cpu request", [container.name])
}

3. 특정 registry 만

ValidatingAdmissionPolicy (CEL):

validations:
  - expression: |
      object.spec.template.spec.containers.all(c,
        c.image.startsWith("ghcr.io/") || c.image.startsWith("registry.example.com/"))
    message: "only ghcr.io and registry.example.com allowed"

4. 이미지 서명 검증

Kyverno + Sigstore:

apiVersion: kyverno.io/v1
kind: ClusterPolicy
metadata:
  name: verify-image-signature
spec:
  rules:
    - name: verify-cosign
      match:
        any:
          - resources:
              kinds: [Pod]
      verifyImages:
        - imageReferences:
            - "ghcr.io/*"
          attestors:
            - entries:
                - keys:
                    publicKeys: |
                      -----BEGIN PUBLIC KEY-----
                      ...

Webhook 배포 시 주의

1. Circular dependency

Webhook 이 자기 자신을 관리하는 리소스에 의존하면 chicken-and-egg. namespaceSelector 로 kube-system 제외.

2. Failure Policy

Fail: 웹훅 실패 시 요청 거부 (엄격)
Ignore: 웹훅 실패 시 통과 (관대)

Fail 로 두었다가 웹훅 서버 죽으면 클러스터 마비. Bootstrap 리소스는 반드시 예외 처리.

3. Timeout

기본 30초, 최대 30초. Timeout 은 API 지연 유발. 짧게 (수 초) + 빠른 응답.

4. TLS

Webhook 은 반드시 TLS. caBundle 로 CA 신뢰. cert-manager 활용 관용.

함정

[!WARNING] failurePolicy: Fail + 웹훅 서버 죽음 = 모든 요청 실패. Bootstrap 순서 및 예외 처리 필수.

[!CAUTION] Mutating 순서 불확정. 여러 mutating webhook 이 있으면 서로의 결과에 의존 X.

[!WARNING] PodSecurityPolicy (PSP) 는 v1.25 에서 제거. 아직도 사용 중이면 즉시 마이그레이션 (PSA + Kyverno).

[!IMPORTANT] 정책은 dry-run 부터. 프로덕션 클러스터에 enforce 걸기 전에 audit / warn 모드로 관찰.

[!CAUTION] Cluster-scoped policy 는 실수 위험 큼. Namespace 스코프 우선 검토.

[Kubernetes] Architecture (Control Plane + Node)

koa (김신건) — Tue, 07 Jul 2026 00:00:00 GMT

정의

Kubernetes Architecture 는 Control Plane (제어) 과 Worker Node (실행) 두 계층으로 구성됩니다. Control Plane 은 원하는 상태를 결정하고, Node 는 그 결정을 실제로 실행합니다. 모든 통신은 kube-apiserver 를 통해 이루어집니다.

전체 구조

flowchart TB
  subgraph "Control Plane"
    API[kube-apiserver]
    ETCD[(etcd)]
    SCH[kube-scheduler]
    CM[kube-controller-manager]
    CCM[cloud-controller-manager]
    API <--> ETCD
    API <--> SCH
    API <--> CM
    API <--> CCM
  end

  subgraph "Node 1"
    K1[kubelet]
    P1[kube-proxy]
    R1[Container Runtime]
    K1 --> R1
    R1 --> Pods1[Pods]
  end

  subgraph "Node 2"
    K2[kubelet]
    P2[kube-proxy]
    R2[Container Runtime]
    K2 --> R2
    R2 --> Pods2[Pods]
  end

  API --> K1
  API --> K2
  API --> P1
  API --> P2

  U[사용자 / kubectl / CI] --> API

Control Plane 컴포넌트

kube-apiserver

모든 요청의 진입점. RESTful API, gRPC (일부).
인증 (Authentication) -> 인가 (Authorization: [[k8s-rbac|RBAC]]) -> [[k8s-admission-controllers|Admission Controllers]] -> etcd 저장 순.
stateless 라서 여러 replica 로 HA 가능 (LB 앞).
클러스터 안의 다른 모든 컴포넌트 (kubelet, controller, scheduler) 는 apiserver 를 통해서만 상태 읽기/쓰기.

API Group / Version:

/api/v1: core (Pod, Service, ConfigMap, …)
/apis/apps/v1: apps (Deployment, StatefulSet, …)
/apis/networking.k8s.io/v1: (Ingress, NetworkPolicy)
/apis/rbac.authorization.k8s.io/v1
CRD 는 /apis/{group}/{version} 형태로 추가

etcd

분산 key-value store. Raft 합의 알고리즘.
클러스터의 모든 상태 (Pod spec, ConfigMap 값, 이벤트 등) 저장.
홀수 개 (3, 5, 7) 노드 권장 (Raft quorum).
백업 필수. etcdctl snapshot save 로 정기 백업.
성능 요구: SSD, 저지연 네트워크. 큰 클러스터에서 etcd 병목이 흔한 문제.

# 백업
ETCDCTL_API=3 etcdctl snapshot save backup.db \
  --endpoints=https://127.0.0.1:2379 \
  --cacert=/etc/kubernetes/pki/etcd/ca.crt \
  --cert=/etc/kubernetes/pki/etcd/server.crt \
  --key=/etc/kubernetes/pki/etcd/server.key

kube-scheduler

새 Pod 을 어느 노드에 배치할지 결정.
2단계 알고리즘:
1. Filtering (predicates): 노드 CPU/메모리 여유, taint 매치, PVC affinity, 리소스 제한 등을 기준으로 후보 노드 필터.
2. Scoring (priorities): 남은 노드에 점수 매기고 최고점 선택 (least-requested, image locality, [[k8s-scheduling|topology spread]] 등).
사용자 정의 스케줄러 (schedulerName) 로 확장 가능.
Extensions: Scheduling Framework (필터/스코어 플러그인).

kube-controller-manager

여러 controller loop 을 하나의 프로세스로 실행.
각 controller 는 “원하는 상태 vs 실제 상태” 를 지속 조정.

주요 controller:

Deployment Controller: ReplicaSet 생성/롤링 업데이트
ReplicaSet Controller: Pod 생성/삭제해 replica 유지
Node Controller: 노드 상태 감지, unresponsive node 처리
Service Account Controller: default SA 생성
Endpoint Controller: Service <-> Pod 매핑 갱신
Namespace Controller: 삭제된 namespace 리소스 정리

cloud-controller-manager

클라우드 API 와의 다리. AWS, GCP, Azure 등.
관리형 클러스터 (EKS/GKE/AKS) 는 클라우드가 관리.

주요 controller:

Node Controller: 클라우드 API 로 노드 lifecycle 관리
Route Controller: 클라우드 VPC 라우팅
Service Controller (LB): type: LoadBalancer Service -> 클라우드 LB 프로비저닝
Volume Controller: 클라우드 볼륨 attach/detach

Node 컴포넌트

kubelet

노드의 primary agent. Pod spec (파일 또는 API 로) 을 받아 컨테이너 실행 상태 유지.
CRI (Container Runtime Interface) 로 runtime 과 통신.
Probes (liveness, readiness, startup) 를 주기적으로 실행.
Node 상태 (heartbeat, capacity) 를 apiserver 에 보고.
정적 Pod (static Pod): /etc/kubernetes/manifests/ 의 YAML 을 apiserver 없이 직접 실행 (kube-apiserver, etcd 자체가 이 방식).

kube-proxy

Service 네트워킹 담당.
3가지 모드:
1. iptables (기본): iptables 규칙으로 서비스 IP -> Pod IP DNAT
2. IPVS: 리눅스 커널 IPVS (성능 우수, 큰 클러스터)
3. nftables (신규, 실험적)
eBPF 기반 Cilium 은 kube-proxy 완전 대체 가능 (kubeProxyReplacement).

Container Runtime (CRI)

CRI 호환 runtime:

containerd (기본, CNCF): 경량, 빠름
CRI-O: OCI 표준 지향, OpenShift 기본
Kata Containers: VM 격리 (보안 강화)

Docker 는 v1.24 이후 CRI 지원 종료 (dockershim 제거). Docker 이미지는 여전히 호환 (OCI 표준).

CNI (Container Network Interface)

Pod 네트워킹. k8s network model:

모든 Pod 은 고유 IP
Pod ↔ Pod NAT 없이 통신
Node ↔ Pod NAT 없이 통신

주요 CNI:

Calico: BGP 기반, NetworkPolicy 강력, 대규모 클러스터
Cilium: eBPF 기반, Service Mesh + observability 통합
Flannel: 단순, 개발/소규모
Weave: 오래됨, 사용 감소
AWS VPC CNI: EKS 기본, Pod 이 VPC IP 획득
Azure CNI, GCP CNI: 각 클라우드 특화

kube-apiserver 를 통한 상호작용 흐름

예: Pod 생성:

1. 사용자: kubectl apply -f pod.yaml
2. kubectl -> kube-apiserver (auth, admission)
3. kube-apiserver -> etcd (Pod object 저장)
4. kube-scheduler (watch): 새 unscheduled Pod 발견
5. kube-scheduler: 노드 선택 -> Pod.spec.nodeName 갱신
6. kubelet (해당 노드, watch): 새 Pod 발견
7. kubelet -> CRI -> containerd: 이미지 pull + 컨테이너 실행
8. kubelet -> CNI: Pod 네트워크 설정 (IP 할당)
9. kubelet: 상태 -> kube-apiserver -> etcd

모든 컴포넌트가 watch 로 apiserver 를 구독. Push 아님 pull.

High Availability

Control Plane HA

kube-apiserver: 여러 replica + LB (nginx, HAProxy, 클라우드 LB)
etcd: 홀수 (3, 5) 노드, 분산 배치
kube-scheduler / controller-manager: 여러 replica, leader election (한 번에 하나만 active)

관리형 vs 자체 HA

관리형 (EKS/GKE/AKS): 클라우드가 Control Plane HA 자동
자체 운영: kubeadm HA 설정, HAProxy + keepalived

노드 HA

여러 AZ 에 분산 (VPC 여러 subnet)
[[k8s-scheduling|Topology Spread Constraints]] 로 AZ 균형
PodDisruptionBudget 으로 한 번에 죽는 Pod 상한

확장

CRD ([[k8s-crd-operators|Custom Resource Definition]]): 새 리소스 타입 추가
API Aggregation Layer: 다른 API 서버를 kube-apiserver 뒤에 추가
Admission Webhook: Mutating / Validating hook
Scheduler Framework: 커스텀 스케줄링 로직
CSI (Storage), CNI (Network), CRI (Runtime), CPI (Cloud), CCM

함정

[!WARNING] etcd 성능 저하 = 전체 클러스터 저하. SSD, 저지연 네트워크 필수. 크기 상한 8 GB 권장.

[!CAUTION] 모든 kubelet 이 apiserver 에 watch 유지. 큰 클러스터 (수천 노드) 는 apiserver 확장이 병목.

[!WARNING] cloud-controller-manager 없이 type: LoadBalancer 는 pending. 관리형이 아니면 MetalLB 등 대체.

[!IMPORTANT] CNI 플러그인 교체는 복잡. 초기 선택이 장기 결정. Calico / Cilium 이 안전한 선택.

[!CAUTION] kube-proxy iptables 규칙은 O(n) 조회. 서비스 수천 개면 IPVS 나 eBPF 로 이전.

[Kubernetes] CRDs & Operators

koa (김신건) — Tue, 07 Jul 2026 00:00:00 GMT

정의

Custom Resource Definition (CRD) 는 Kubernetes API 에 새 리소스 타입 을 추가하는 기능입니다. apiVersion + kind 를 정의하면 kubectl / apiserver 가 마치 내장 리소스처럼 취급합니다.

Operator 는 CRD + 그 리소스를 관리하는 컨트롤러 의 조합입니다. 사람 운영자가 하는 작업 (설치, 백업, 업그레이드, 스케일링) 을 코드로 자동화합니다. CoreOS 가 2016년 제안한 패턴.

왜 필요한가

CRD 없이의 한계

내장 리소스 (Pod, Deployment, Service) 만으로는 복잡한 앱 (DB, Kafka, ML pipeline) 관리에 부족.

DB primary 승격 절차: 여러 리소스 조합 + 순서 있는 조정
Backup / Restore: 시간 기반 이벤트 처리
Version upgrade: 데이터 마이그레이션 포함 단계별

이를 사람이 runbook 으로 관리하는 대신 선언적 리소스 + 자동 컨트롤러 로.

예: Postgres Operator

내장 리소스만으로 Postgres HA 클러스터 배포:

StatefulSet 3개 (primary + replica)
ConfigMap 여러 개
Service (primary, replica 각각)
PVC
Backup CronJob
…

Operator 는 이것을 하나의 CR 로 압축:

apiVersion: acid.zalan.do/v1
kind: postgresql
metadata:
  name: prod-db
spec:
  numberOfInstances: 3
  postgresql:
    version: "16"
  volume:
    size: 100Gi
  backup:
    schedule: "0 3 * * *"

Operator 가 모든 내부 리소스 자동 관리.

CRD 정의

apiVersion: apiextensions.k8s.io/v1
kind: CustomResourceDefinition
metadata:
  name: myapps.example.com
spec:
  group: example.com
  versions:
    - name: v1alpha1
      served: true
      storage: true
      schema:
        openAPIV3Schema:
          type: object
          properties:
            spec:
              type: object
              properties:
                replicas:
                  type: integer
                  minimum: 1
                  maximum: 10
                image:
                  type: string
                config:
                  type: object
                  properties:
                    logLevel:
                      type: string
                      enum: [debug, info, warn, error]
              required: [replicas, image]
            status:
              type: object
              properties:
                readyReplicas:
                  type: integer
                phase:
                  type: string
      subresources:
        status: {}
        scale:
          specReplicasPath: .spec.replicas
          statusReplicasPath: .status.readyReplicas
      additionalPrinterColumns:
        - name: Image
          type: string
          jsonPath: .spec.image
        - name: Replicas
          type: integer
          jsonPath: .spec.replicas
        - name: Ready
          type: integer
          jsonPath: .status.readyReplicas
  scope: Namespaced
  names:
    plural: myapps
    singular: myapp
    kind: MyApp
    shortNames: [ma]

이후:

kubectl get myapp
kubectl apply -f myapp-instance.yaml

apiVersion: example.com/v1alpha1
kind: MyApp
metadata:
  name: prod-app
spec:
  replicas: 3
  image: myapp:1.0
  config:
    logLevel: info

CRD 만 만들면 저장은 되지만 아무 일도 안 일어남. Controller 가 필요.

Controller (Operator 의 핵심)

Controller 는 CR 을 watch 하며 spec 대로 실제 리소스를 조정. Reconciliation loop:

for {
  observed := watch(CR)               // 관측
  desired := computeDesiredState(observed)
  actual := getCurrentState()
  diff := compareStates(desired, actual)
  applyChanges(diff)                   // 조정
}

기본 원칙

선언적 (declarative): spec 이 원하는 상태
Idempotent: 같은 spec 여러 번 reconcile 해도 동일 결과
Eventually consistent: 즉시 반영 아님, 최종 수렴

Kubebuilder / Operator SDK

Operator 를 처음부터 짜지 말고 프레임워크 활용:

Kubebuilder: kubernetes-sigs 프로젝트. Go 언어. controller-runtime 기반.
Operator SDK: Red Hat 주도. Kubebuilder + OperatorHub 통합. Go, Ansible, Helm.
KUDO: YAML DSL. 간단한 Operator.
Metacontroller: JavaScript/Python 등 임의 언어로 controller.
kopf: Python framework.

Kubebuilder 예시

# 초기화
mkdir myapp-operator && cd myapp-operator
kubebuilder init --domain example.com --repo example.com/myapp-operator

# API + Controller 생성
kubebuilder create api --group apps --version v1alpha1 --kind MyApp

# CRD schema 정의 (api/v1alpha1/myapp_types.go)
type MyAppSpec struct {
    Replicas int32  `json:"replicas"`
    Image    string `json:"image"`
}

type MyAppStatus struct {
    ReadyReplicas int32 `json:"readyReplicas"`
}

# Controller 로직 (controllers/myapp_controller.go)
func (r *MyAppReconciler) Reconcile(ctx context.Context, req ctrl.Request) (ctrl.Result, error) {
    var myapp examplev1.MyApp
    if err := r.Get(ctx, req.NamespacedName, &myapp); err != nil {
        return ctrl.Result{}, client.IgnoreNotFound(err)
    }

    // Deployment 존재 확인 & 조정
    deploy := &appsv1.Deployment{}
    err := r.Get(ctx, types.NamespacedName{Name: myapp.Name, Namespace: myapp.Namespace}, deploy)
    if apierrors.IsNotFound(err) {
        newDeploy := r.deploymentForMyApp(&myapp)
        r.Create(ctx, newDeploy)
        return ctrl.Result{RequeueAfter: time.Second * 30}, nil
    }

    // Replica 갱신
    if *deploy.Spec.Replicas != myapp.Spec.Replicas {
        deploy.Spec.Replicas = &myapp.Spec.Replicas
        r.Update(ctx, deploy)
    }

    // Status 갱신
    myapp.Status.ReadyReplicas = deploy.Status.ReadyReplicas
    r.Status().Update(ctx, &myapp)

    return ctrl.Result{}, nil
}

# 실행
make install run    # dev
make docker-build docker-push IMG=...
make deploy IMG=...  # prod

Capability Levels (Operator SDK)

Operator 성숙도 5단계:

Basic Install: 앱 설치
Seamless Upgrades: 버전 업그레이드
Full Lifecycle: 백업/복구, 실패 복구
Deep Insights: 메트릭, alert, 로그 통합
Auto Pilot: 자동 스케일링, 자가 튜닝, 이상 감지

프로덕션 사용 시 3+ 요구.

OperatorHub

operatorhub.io 에 커뮤니티 operator 목록. 유명 operator:

Prometheus Operator (kube-prometheus-stack)
cert-manager
ArgoCD Operator
PostgreSQL Operator (Zalando / CloudNativePG / crunchy-data)
Kafka Operator (Strimzi)
Redis Operator (spotahome, ot-container-kit)
Elastic Cloud on Kubernetes (ECK)
Istio Operator
Percona Operators (MySQL, MongoDB)

실전 CRD 팁

1. Version strategy

v1alpha1 -> v1beta1 -> v1 순 관용. Alpha 는 실험, beta 는 안정 후 GA 준비, v1 은 안정.

Conversion webhook: 여러 버전 지원 시 서버측 변환:

spec:
  conversion:
    strategy: Webhook
    webhook:
      clientConfig:
        service:
          name: myapp-webhook
          path: /convert
      conversionReviewVersions: [v1]

2. Status subresource

spec 과 status 를 별도 subresource 로 관리하면:

Controller 만 status 갱신 (RBAC 분리)
kubectl edit 이 status 조작 방지
Conflict 감소

3. Printer columns

kubectl get myapp 표시 컬럼 커스터마이제이션.

4. Validating admission webhook

CR 생성/수정 시 추가 검증. Simple validation 은 OpenAPI schema, complex 는 webhook.

5. Finalizer

CR 삭제 시 정리 작업. metadata.finalizers 에 이름 추가하면 controller 가 정리 후 finalizer 제거해야 실제 삭제.

함정

[!WARNING] CRD 는 cluster-scoped. Namespace 마다 다른 CRD 불가. 조심스러운 도입.

[!CAUTION] CR schema 변경은 breaking. 필드 추가는 OK, 삭제/타입 변경은 미리 마이그레이션 계획.

[!WARNING] Controller 다중 replica 는 leader election 필요. 안 그러면 두 controller 가 동시 조정 -> race.

[!IMPORTANT] Reconcile 는 idempotent 여야. 여러 번 호출해도 같은 결과. Requeue + RequeueAfter 로 retry.

[!CAUTION] Finalizer 잘못 걸면 CR 삭제 불가. Controller 죽으면 stuck. 신중히.

[!WARNING] CRD 는 API 부하 증가. 큰 status field, 많은 CR 인스턴스 = etcd 부담. Compaction 정기.

[Kubernetes] Debugging (kubectl debug, Ephemeral Containers, Events)

koa (김신건) — Tue, 07 Jul 2026 00:00:00 GMT

정의

Kubernetes Debugging 은 Pod, 노드, 클러스터 문제를 진단하는 도구/기법 집합입니다. 로그, 이벤트, kubectl describe, ephemeral container, kubectl debug 를 조합해 원인 추적합니다.

기본 진단 절차

# 1. 리소스 상태
kubectl get pods -n <ns>
kubectl get all -n <ns>

# 2. 자세한 상태
kubectl describe pod <name> -n <ns>

# 3. 이벤트 (원인 힌트)
kubectl get events -n <ns> --sort-by=.metadata.creationTimestamp
kubectl events --for pod/<name> -n <ns>   # v1.31+

# 4. 로그
kubectl logs <name> -n <ns>
kubectl logs <name> -c <container> -n <ns>       # multi-container
kubectl logs <name> --previous -n <ns>            # 이전 컨테이너 (crashed)
kubectl logs -f <name> -n <ns>                    # follow
kubectl logs -l app=web -n <ns> --tail=100

# 5. exec (컨테이너 안 진단)
kubectl exec -it <name> -n <ns> -- /bin/sh
kubectl exec -it <name> -c <container> -- bash

# 6. port-forward (로컬 접근)
kubectl port-forward pod/<name> 8080:80 -n <ns>

Pod 상태 코드

Pending

스케줄 실패: kubectl describe -> Events 에서 확인
원인:
- 노드 리소스 부족 (Insufficient cpu, memory)
- [[k8s-scheduling|Node Selector / Affinity]] 매치 안 됨
- Taint 매치 안 됨
- PVC 프로비저닝 실패
- Image pull 실패 (있으면 ImagePullBackoff)

ContainerCreating

Volume mount 진행 중
Image pulling
CNI 네트워크 설정 중

몇 초 이상 지속되면 문제. describe 로 확인.

Running

정상. 컨테이너 실행 중.

CrashLoopBackoff

컨테이너가 시작 후 exit -> kubelet 재시작 -> 다시 exit 반복
Backoff 는 10s -> 20s -> 40s -> … -> 5m 로 점진 증가
원인:
- 앱 오류 (config 잘못, DB 연결 실패)
- 시작 명령 오류
- 의존 서비스 부재
- Memory limit 초과 -> OOMKilled -> 재시작
kubectl logs --previous 로 이전 로그 확인 필수

ImagePullBackoff / ErrImagePull

이미지 pull 실패
원인:
- 이미지 이름/태그 오타
- Private registry 인증 실패 (imagePullSecrets 확인)
- Registry 접근 불가 (VPC endpoint, IAM)
- Rate limit (Docker Hub, ECR)

kubectl describe pod <name>
# Events 에서 pull error 메시지 확인

kubectl get secret <pull-secret> -o yaml
# 인증 정보 검증

CreateContainerError

Container runtime 오류
원인:
- 잘못된 command / args
- Config file 없음
- Volume mount 실패

CreateContainerConfigError

ConfigMap / Secret 참조 오류

OOMKilled

Memory limit 초과 -> 커널 OOM Killer 가 죽임
kubectl describe pod 에서 Last State: Terminated, Reason: OOMKilled
대응:
- Memory limit 증가
- Memory leak 조사 (heap dump, profiler)
- JVM -Xmx, Python resource.setrlimit, Node --max-old-space-size

Terminating (stuck)

Graceful termination 진행 중
terminationGracePeriodSeconds (기본 30초) 후에도 남으면:
- Finalizer 남아있음
- preStop hook 무한
- kubelet 통신 불가

강제 삭제 (주의):

kubectl delete pod <name> --grace-period=0 --force

kubectl describe

가장 중요한 명령. 모든 문제의 단서.

kubectl describe pod <name> -n <ns>

주요 섹션:

Status: Running / Pending / …
Containers: 각 컨테이너 상태, restart count, last state (with reason)
Volumes: mount 상태
QoS Class: [[k8s-resource-management|Guaranteed / Burstable / BestEffort]]
Node: 어느 노드에 배치
Events: 최근 이벤트 (시간순)

Node, StatefulSet, Deployment, PVC 등 모든 리소스에 사용.

로그 심화

이전 로그

kubectl logs <name> --previous

CrashLoopBackoff 디버깅에 필수.

여러 컨테이너

kubectl logs <name> --all-containers
kubectl logs <name> --all-containers --prefix    # 컨테이너 이름 prefix

라벨 선택

kubectl logs -l app=web --tail=100
kubectl logs -l app=web --max-log-requests=10

stern (외부 도구)

여러 pod 로그 병렬 스트리밍. 관리자 필수 도구.

stern --namespace prod 'web.*' --since 1h

kubectl exec

컨테이너 안 명령 실행.

kubectl exec -it <name> -- /bin/sh
kubectl exec <name> -- ls /var/log
kubectl exec <name> -c <container> -- env

함정:

Distroless 이미지는 shell 없음
Alpine 은 sh 만 (bash 없음)
이미지에 진단 도구 (curl, netcat, dig) 부재하면 exec 무력

Ephemeral Containers (kubectl debug)

기존 Pod 에 임시 컨테이너 삽입. Distroless / minimal 이미지 디버깅 의 답.

# 기존 pod 에 debug container 추가
kubectl debug -it <pod> --image=busybox --target=<container>

# 노드 디버깅 (node 에 privileged pod)
kubectl debug node/<node-name> -it --image=ubuntu

# Pod 복제 (원본 유지, 디버그 이미지로 새 pod)
kubectl debug <pod> -it --copy-to=<pod>-debug --container=<name> --image=busybox

Ephemeral container 는 Pod spec 에 자동 추가되지만 별도 리소스 관리.

주의:

Ephemeral container 는 재시작 안 됨
Resource limit 없음
Restart 불가

이벤트

# 전체 이벤트
kubectl get events -n <ns>

# 시간순
kubectl get events -n <ns> --sort-by=.metadata.creationTimestamp

# 특정 리소스
kubectl get events --field-selector involvedObject.name=<name>

# 새 명령 (v1.31+)
kubectl events --for pod/<name>

이벤트는 1시간 후 자동 삭제. Prometheus / Grafana 로 장기 보관 관용.

네트워크 디버깅

Service 도달 여부

# Pod 안에서
kubectl exec -it <pod> -- curl http://myservice.mynamespace.svc.cluster.local

# 임시 디버그 pod
kubectl run tmp-shell --rm -it --image=nicolaka/netshoot -- /bin/bash
# netshoot: curl, dig, nslookup, iperf, tcpdump 등 다 있음

DNS

kubectl exec -it <pod> -- nslookup myservice
kubectl exec -it <pod> -- dig myservice.mynamespace.svc.cluster.local

CoreDNS pod 확인:

kubectl get pods -n kube-system -l k8s-app=kube-dns
kubectl logs -n kube-system -l k8s-app=kube-dns

NetworkPolicy

Traffic 이 막힐 때:

kubectl get networkpolicy -n <ns>
kubectl describe networkpolicy <name> -n <ns>

임시 exec 로 tcp 시험:

kubectl exec <pod> -- nc -vz <target> <port>

kubectl top

리소스 사용량. metrics-server 필요.

kubectl top nodes
kubectl top pods -n <ns>
kubectl top pod --containers -n <ns>

CPU throttling / memory pressure 확인.

노드 디버깅

kubectl get nodes
kubectl describe node <name>
kubectl top nodes

# 노드에 SSH (관리형이면 SSM 등)
# ...

# 노드에 임시 디버그 pod
kubectl debug node/<name> -it --image=ubuntu
# host filesystem 은 /host 에 mount
chroot /host

노드 상태 조건:

Ready: kubelet 정상
MemoryPressure: 메모리 부족
DiskPressure: 디스크 부족
PIDPressure: PID 소진
NetworkUnavailable: 네트워크 문제

이미지 검증

# 이미지 pull 시험
kubectl run test-pull --image=<image> --restart=Never --rm -it -- true

# 이미지 크기 확인
kubectl get pod <name> -o jsonpath='{.spec.containers[*].image}'
docker manifest inspect <image>

흔한 문제와 해결

1. Pod 이 Pending

kubectl describe pod <name> | grep -A20 Events

Insufficient cpu/memory: 노드 리소스 부족. HPA, cluster autoscaler 확인.
No matching nodes: NodeSelector / Affinity / Taint 검토.
PVC pending: StorageClass 확인.

2. CrashLoopBackoff

kubectl logs <pod> --previous

Config 잘못
DB 연결 실패 (DNS, credential)
OOMKilled -> 메모리 늘리기

3. ImagePullBackoff

kubectl describe pod <name>
# Events 에서 pull error 상세

이미지 이름 오타
imagePullSecrets 잘못
Registry 접근 불가

4. Service 안 됨

kubectl get endpoints <service>

Endpoints 비어있음: selector 오타 or Pod 준비 안 됨
Endpoints 있음: 네트워크 정책 or Pod 앱 오류

5. Ingress 안 됨

kubectl describe ingress <name>
kubectl get ingressclass

IngressClass 미지정
Ingress controller 미설치
TLS secret 부재

함정

[!WARNING] kubectl delete pod 는 recreate. Deployment 가 있으면 새 pod. 근본 문제 안 잡히면 무한 실패.

[!CAUTION] --grace-period=0 --force 는 최후의 수단. Volume detach 실패 등 부작용 가능.

[!WARNING] 로그가 회전. 큰 로그는 오래 안 남음. Loki / CloudWatch Logs 로 장기 저장.

[!IMPORTANT] 이벤트는 1시간 만료. 장기 조사에는 별도 저장 (kubernetes-event-exporter).

[!CAUTION] kubectl 버전 skew. Client 와 cluster 버전이 심하게 다르면 옵션 안 먹음. 클러스터 버전에 맞춤.

[Kubernetes] Init Containers & Sidecar Containers

koa (김신건) — Tue, 07 Jul 2026 00:00:00 GMT

정의

Init Containers 는 Pod 의 메인 컨테이너보다 먼저 실행되어 초기화 작업을 완료하고 종료되는 컨테이너입니다.

Sidecar Containers 는 메인 컨테이너와 함께 실행되며 로깅/모니터링/프록시 등 부가 기능을 제공하는 컨테이너입니다. Kubernetes v1.33 (2025-04) 에서 native sidecar 지원이 GA 되어 (restartPolicy: Always 를 initContainers 에 지정) 기존 pattern 이 표준화되었습니다.

Init Container

특징

순차 실행: spec.initContainers 순서대로. 하나가 성공해야 다음 시작.
완료 후 종료: exit code 0 이면 성공. 실패면 Pod 재시작 정책에 따라 처리.
메인 컨테이너와 이미지 분리 가능: 초기화 도구는 초기화 이미지에.
네트워크/볼륨 공유: 메인과 같은 network namespace, 같은 volume.

사용 사례

DB migration: 앱 시작 전 alembic upgrade, rails db:migrate
설정 파일 생성: 원격 config service 에서 fetch 후 configMap/emptyDir 에 저장
의존 서비스 대기: wait-for-it db:5432 로 DB ready 확인
secret 처리: KMS 에서 decrypt 후 emptyDir 에
Git clone: 코드 저장소 clone

예시

apiVersion: v1
kind: Pod
metadata:
  name: web
spec:
  initContainers:
    - name: wait-for-db
      image: busybox:1.36
      command: ['sh', '-c', 'until nc -z db 5432; do sleep 1; done']
    - name: migrate
      image: myapp:1.0
      command: ['python', 'manage.py', 'migrate']
      envFrom:
        - secretRef:
            name: db-secret
  containers:
    - name: web
      image: myapp:1.0
      ports: [{containerPort: 8000}]

wait-for-db -> migrate -> web 순.

리소스 계산

Pod 의 effective request/limit 은:

$$ \max(\sum \text{main container requests}, \max \text{init container requests}) $$

Init container 는 순차 실행이라 동시에 존재하지 않지만, 스케줄러는 가장 큰 init container 도 감안하여 예약.

Sidecar (native) 는 initContainers 에 있지만 동시 실행 이라 합산.

Native Sidecar (v1.29 beta -> v1.33 GA)

배경

전통적 sidecar 는 containers[] 에 넣었지만 여러 문제:

시작 순서 불안정: Pod 시작 시 sidecar 와 main 이 동시 시작. Main 이 sidecar 필요 (예: log shipper) 하면 race.
종료 순서 불안정: Pod 종료 시 sidecar 가 main 보다 먼저 죽을 수 있음. Log 유실.
Job 문제: Sidecar 가 계속 돌면 Job 이 완료되지 않음. Workaround 로 self-kill 신호 등 복잡.

해결

Native sidecar 는 initContainers 에 넣되 restartPolicy: Always:

apiVersion: v1
kind: Pod
metadata:
  name: web
spec:
  initContainers:
    - name: log-agent           # native sidecar
      image: fluent/fluent-bit:3
      restartPolicy: Always      # 이것이 핵심
      volumeMounts:
        - name: logs
          mountPath: /var/log
    - name: db-migrator          # 전통 init container
      image: myapp:1.0
      command: ['python', 'manage.py', 'migrate']
  containers:
    - name: web
      image: myapp:1.0
      volumeMounts:
        - name: logs
          mountPath: /var/log
  volumes:
    - name: logs
      emptyDir: {}

Native sidecar 이점

명확한 시작 순서: sidecar 가 started 상태되면 다음 init container 시작. Sidecar 준비 후 main 이 시작.
명확한 종료 순서: main 이 완전히 종료된 후 sidecar 에 SIGTERM. 로그/메트릭 유실 없음.
Job 호환: restartPolicy: Never/OnFailure Job 에서 sidecar 가 완료를 막지 않음.
Probe 지원: liveness/readiness/startup probe 를 sidecar 에도.

언제 어느 것을?

유형	`containers[]`	`initContainers[]` restartPolicy 없음	`initContainers[]` restartPolicy: Always
메인 앱	✓	✗	✗
초기화 (완료 지향)	✗	✓	✗
Sidecar (병렬 실행)	예전	✗	✓ (권장)

주요 sidecar 패턴

1. Log agent

Fluent Bit 이 앱 로그를 수집해 원격 저장소로.

initContainers:
  - name: fluent-bit
    image: fluent/fluent-bit:3
    restartPolicy: Always
    volumeMounts:
      - name: logs
        mountPath: /logs
      - name: config
        mountPath: /fluent-bit/etc

2. Metrics exporter

Prometheus exporter 를 sidecar 로.

initContainers:
  - name: postgres-exporter
    image: prometheuscommunity/postgres-exporter:v0.15
    restartPolicy: Always
    env:
      - name: DATA_SOURCE_NAME
        value: "postgres://user:pass@localhost:5432/postgres?sslmode=disable"
    ports:
      - containerPort: 9187

3. Service mesh proxy (Envoy)

Istio, Linkerd 는 Envoy/linkerd-proxy 를 sidecar 로 auto-inject. Native sidecar 로 이관 진행 중.

4. Config reload

Config file 변경 감지 -> 앱에 SIGHUP.

5. Secret rotation

Vault agent injector, secrets-store-csi-driver.

Probe 통합

Init container (native sidecar) 도 probe 지원 (v1.28+):

initContainers:
  - name: log-agent
    image: fluent/fluent-bit:3
    restartPolicy: Always
    startupProbe:
      httpGet:
        path: /api/v1/health
        port: 2020
      failureThreshold: 30
      periodSeconds: 2
    livenessProbe:
      httpGet:
        path: /api/v1/health
        port: 2020

Sidecar 가 started 상태 되면 다음 init 또는 main 시작.

Migration Guide

기존 containers[] sidecar 를 native 로 옮기려면:

Before:

containers:
  - name: web
    image: myapp:1.0
  - name: log-agent
    image: fluent/fluent-bit:3

After:

initContainers:
  - name: log-agent
    image: fluent/fluent-bit:3
    restartPolicy: Always
containers:
  - name: web
    image: myapp:1.0

주의:

클러스터 버전이 v1.29+ (feature gate) 또는 v1.33+ (GA) 이어야 함.
자동 injector (Istio, Fluent Bit operator) 가 이미 native sidecar 지원하는지 확인.

Init container Anti-pattern

앱을 init 로 (X)

initContainers:
  - name: web         # 앱 자체
    image: myapp:1.0
    command: ['python', 'app.py']   # 계속 실행

Init 는 완료 지향. Long-running 을 넣으면 Pod 이 절대 Ready 안 됨.

초기화를 앱 안에서 (△)

containers:
  - name: web
    image: myapp:1.0
    command: ['sh', '-c', 'migrate && python app.py']   # 하나로

작동은 하지만:

앱 이미지에 migration 도구 포함 필요
Migration 실패 시 앱 재시작 loop
로그 구분 어려움

Init container 로 분리하는 편이 관용.

함정

[!WARNING] Native sidecar 는 클러스터 v1.29+ 필수. 오래된 클러스터에서는 restartPolicy: Always 가 조용히 무시되어 Pod 시작 실패.

[!CAUTION] Init container 실패는 Pod 실패로 카운트. restartPolicy: OnFailure/Always 라도 backoff 후 재시작. Init 가 무한 실패하면 CrashLoopBackoff.

[!WARNING] Init container 도 리소스 요청 필요. 안 걸면 BestEffort QoS -> 노드 압박 시 evict.

[!IMPORTANT] Sidecar 이미지 크기. Main + sidecar 합쳐 이미지 pull 시간 증가. 이미지 최적화.

[!CAUTION] Init 에서 network 접근 시 CNI 준비 여부. CNI 가 준비되기 전에 init 실행 가능성. 짧은 backoff + retry.

[Kubernetes] Kustomize

koa (김신건) — Tue, 07 Jul 2026 00:00:00 GMT

정의

Kustomize 는 Kubernetes manifests 를 템플릿 없이 overlay 방식으로 커스터마이제이션하는 도구입니다. kubectl v1.14+ 에 내장 (kubectl apply -k). YAML 을 그대로 두고, base + overlay 로 환경별 (dev/stg/prod) 차이만 표현합니다.

왜 Kustomize 인가

Helm 과 대비

Helm 은 템플릿 엔진 (Go template). YAML 에 {{ .Values.replicas }} 같은 placeholder.

단점:

YAML 이 진짜 YAML 이 아님 (템플릿 언어 삽입)
파싱 오류 디버깅 힘듦
Values.yaml 이 실질적으로 스키마 없는 dict

Kustomize 는 순수 YAML. Patch/overlay 로 조합.

단점:

로직 (조건, 반복) 표현 어려움
복잡한 시나리오에 부담
Helm 만큼 배포자 (user) 친화적이지 않음

결론:

자체 앱, 환경별 배포 -> Kustomize 자연스러움
외부 배포 대상 라이브러리 (Redis, Postgres, Prometheus) -> Helm 우세
조합 가능 (Helm chart 를 Kustomize 로 후처리)

기본 구조

kustomize-project/
├── base/
│   ├── kustomization.yaml
│   ├── deployment.yaml
│   ├── service.yaml
│   └── configmap.yaml
└── overlays/
    ├── dev/
    │   ├── kustomization.yaml
    │   ├── replica-patch.yaml
    │   └── env-patch.yaml
    ├── staging/
    │   ├── kustomization.yaml
    │   └── replica-patch.yaml
    └── prod/
        ├── kustomization.yaml
        ├── replica-patch.yaml
        └── resources-patch.yaml

Base

Base 는 공통 리소스.

base/kustomization.yaml:

apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization

resources:
  - deployment.yaml
  - service.yaml
  - configmap.yaml

commonLabels:
  app: web
  managed-by: kustomize

commonAnnotations:
  team: platform

base/deployment.yaml:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: web
spec:
  replicas: 1
  selector:
    matchLabels:
      app: web
  template:
    metadata:
      labels:
        app: web
    spec:
      containers:
        - name: web
          image: myapp:1.0
          ports:
            - containerPort: 8080
          env:
            - name: APP_ENV
              value: development
          resources:
            requests:
              cpu: 100m
              memory: 128Mi

Overlay

overlays/prod/kustomization.yaml:

apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization

namespace: prod                    # 모든 리소스가 prod namespace 에

resources:
  - ../../base                     # base 참조

commonLabels:
  environment: production

patches:
  - path: replica-patch.yaml
  - path: resources-patch.yaml
    target:
      kind: Deployment

images:
  - name: myapp
    newTag: 1.5.0                  # image tag 교체

configMapGenerator:
  - name: app-config
    behavior: merge
    literals:
      - APP_ENV=production
      - LOG_LEVEL=info

secretGenerator:
  - name: db-secret
    literals:
      - password=prod-secret-value

replicas:
  - name: web
    count: 5

Patch 종류

1. Strategic Merge Patch (기본)

YAML 조각을 base 위에 얹음. K8s API 지식 활용.

replica-patch.yaml:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: web
spec:
  replicas: 5

Deployment.spec.replicas 만 5 로 override.

2. JSON Patch (RFC 6902)

경로 기반 수정. 세밀 제어.

patches:
  - target:
      kind: Deployment
      name: web
    patch: |
      - op: replace
        path: /spec/replicas
        value: 5
      - op: add
        path: /spec/template/spec/containers/0/env/-
        value:
          name: FEATURE_FLAG
          value: "true"
      - op: remove
        path: /spec/template/spec/containers/0/env/0

3. Container 수준 patch

patches:
  - target:
      kind: Deployment
      name: web
    patch: |
      apiVersion: apps/v1
      kind: Deployment
      metadata:
        name: web
      spec:
        template:
          spec:
            containers:
              - name: web
                resources:
                  requests:
                    cpu: 500m
                    memory: 512Mi
                  limits:
                    cpu: 2
                    memory: 2Gi

Generator

ConfigMap

configMapGenerator:
  - name: app-config
    literals:
      - APP_ENV=production
      - LOG_LEVEL=info
    files:
      - config.json
      - nginx.conf
    envs:
      - .env.prod

생성된 ConfigMap 이름에 hash suffix 자동 추가 (app-config-abc123). 값 변경 시 새 hash -> Pod 자동 재배포.

Secret

secretGenerator:
  - name: db-secret
    literals:
      - username=admin
      - password=secret
    type: Opaque

주의: literals 는 kustomization.yaml 안에 평문. Git 에 커밋 금지. Sealed Secrets, SOPS, external secrets 로 대체.

Image 변경

images:
  - name: myapp                  # base 의 이미지 이름
    newName: registry.example.com/myapp
    newTag: 1.5.0
  - name: nginx
    newName: nginx
    digest: sha256:abc...

컨테이너 spec 을 손대지 않고 tag/registry 만 override.

Namespace 지정

namespace: prod

Overlay 안 모든 namespaced 리소스가 이 namespace 로.

Name Prefix / Suffix

namePrefix: prod-
nameSuffix: -v2

web -> prod-web-v2.

Component (v3.7+)

재사용 가능한 조합. 라이브러리 성격.

components/monitoring/kustomization.yaml:

apiVersion: kustomize.config.k8s.io/v1alpha1
kind: Component

patches:
  - target:
      kind: Deployment
    patch: |
      apiVersion: apps/v1
      kind: Deployment
      metadata:
        name: dummy
      spec:
        template:
          metadata:
            annotations:
              prometheus.io/scrape: "true"
              prometheus.io/port: "9090"

Overlay 에서 사용:

components:
  - ../../components/monitoring

여러 base

resources:
  - ../base/deployment
  - ../base/service
  - ../base/configmap

# 또는
bases:                       # deprecated in favor of resources
  - ../base

빌드 & 적용

# 렌더링만 (확인용)
kubectl kustomize overlays/prod/
kustomize build overlays/prod/

# 적용
kubectl apply -k overlays/prod/

# Diff
kubectl diff -k overlays/prod/

# 삭제
kubectl delete -k overlays/prod/

실전 워크플로

앱 배포

myapp/
├── base/
│   ├── kustomization.yaml
│   ├── deployment.yaml
│   ├── service.yaml
│   └── ingress.yaml
└── overlays/
    ├── dev/
    │   └── kustomization.yaml     # dev namespace, small resources
    ├── staging/
    │   └── kustomization.yaml     # stg namespace, prod-like
    └── prod/
        ├── kustomization.yaml
        ├── hpa.yaml                # prod 만 HPA
        └── pdb.yaml

Multi-cluster

myapp/
├── base/
└── overlays/
    ├── us-east-1/
    │   ├── prod/
    │   ├── staging/
    └── eu-west-1/
        ├── prod/
        └── staging/

Helm chart post-processing

Helm chart 를 base 로:

helmCharts:
  - name: nginx-ingress
    repo: https://kubernetes.github.io/ingress-nginx
    version: 4.11.0
    releaseName: ingress-nginx
    namespace: ingress-nginx
    valuesInline:
      controller:
        replicaCount: 3

patches:
  - patch: |
      apiVersion: apps/v1
      kind: Deployment
      metadata:
        name: ingress-nginx-controller
      spec:
        template:
          spec:
            nodeSelector:
              node-role: ingress

Kustomize + GitOps

[[argocd|ArgoCD]]: Native Kustomize 지원. Application 리소스에 kustomize path 지정.
Flux: Kustomization CRD (Flux 의 K CRD 는 kustomize 를 wrap).

함정

[!WARNING] Secret literal 을 git 에 커밋 금지. Sealed Secrets, SOPS, ExternalSecrets 로.

[!CAUTION] Generator hash 는 값 기반. 같은 값 = 같은 hash = 같은 이름. Rolling update 유발하려면 값 실제 변경.

[!WARNING] overlay 에서 base 리소스 순서. 여러 base 상속 시 순서에 따라 patch 결과 달라짐.

[!IMPORTANT] kubectl kustomize 로 렌더링 후 확인. 예상과 다르면 patch 로직 재검토.

[!CAUTION] JSON Patch path 오타. /spec/template/spec/containers/0/name 등 인덱스 실수 흔함. 정확 지정.

[Kubernetes] Labels & Selectors

koa (김신건) — Tue, 07 Jul 2026 00:00:00 GMT

정의

Labels 는 리소스에 붙이는 key-value 분류 태그 입니다. 사람과 컨트롤러가 리소스를 조직하고 선택할 때 사용합니다. Selectors 는 label 조합으로 대상 리소스를 지정하는 쿼리 문법입니다. Annotations 는 label 과 유사한 key-value 이지만 selector 대상이 아닌 도구/사람이 참조할 메타데이터입니다.

Label 기본

apiVersion: apps/v1
kind: Deployment
metadata:
  name: web
  labels:
    app: web
    tier: frontend
    version: v1.2.3
    environment: production
    team: platform
    owner: alice
spec:
  ...

규칙

Key: 최대 63자. Prefix example.com/ 형태 (선택).
- Prefix: DNS subdomain (kubernetes.io/, app.kubernetes.io/, example.com/)
- Name: [a-z0-9A-Z] + -, _, . (첫/끝은 alphanumeric)
Value: 최대 63자. 위와 같은 규칙 (빈 문자열도 가능).
Case-sensitive.

예약된 prefix

kubernetes.io/ , k8s.io/ : 시스템 사용, 사용자 금지
app.kubernetes.io/ : 권장 표준 (아래 참조)

권장 라벨 (recommended labels)

Kubernetes 공식 권장:

labels:
  app.kubernetes.io/name: myapp             # 앱 이름
  app.kubernetes.io/instance: myapp-prod    # 특정 인스턴스
  app.kubernetes.io/version: "1.2.3"        # 버전 (문자열로!)
  app.kubernetes.io/component: frontend     # 역할
  app.kubernetes.io/part-of: my-system      # 상위 시스템
  app.kubernetes.io/managed-by: helm         # 관리 도구 (helm, kustomize, terraform)

이를 지키면 Helm, Grafana, Prometheus, Argo 등이 자동으로 그룹핑.

Selector

두 종류:

1. Equality-based

key = value
key != value

예: environment=production, tier!=frontend.

2. Set-based

key in (v1, v2, v3)
key notin (v1, v2)
key             # key 존재
!key            # key 부재

예: environment in (staging, production), !experimental.

조합

콤마로 AND:

environment=production, tier=frontend, version notin (v0.9, v1.0)

OR 는 selector 자체에서 지원 안 함. 필요하면 여러 selector 로 별도 처리.

사용 사례

kubectl 필터

kubectl get pods -l app=web
kubectl get pods -l app=web,tier=frontend
kubectl get pods -l 'environment in (dev, staging)'
kubectl get pods -l '!experimental'
kubectl get all -l app.kubernetes.io/instance=myapp-prod
kubectl delete pods -l tier=canary

Deployment / ReplicaSet

Deployment 는 어느 Pod 을 관리할지 selector 로 지정:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: web
spec:
  replicas: 3
  selector:
    matchLabels:
      app: web
    matchExpressions:
      - key: tier
        operator: In
        values: [frontend]
  template:
    metadata:
      labels:
        app: web
        tier: frontend
    spec:
      ...

중요: spec.template.metadata.labels 는 반드시 spec.selector.matchLabels 를 포함 해야 함. 안 그러면 controller 가 자기 Pod 을 못 관리.

selector 는 immutable (한 번 만들면 수정 불가).

Service 라우팅

apiVersion: v1
kind: Service
metadata:
  name: web
spec:
  selector:
    app: web
    tier: frontend
  ports:
    - port: 80
      targetPort: 8080

app=web, tier=frontend 라벨을 가진 Pod 으로 트래픽 분산.

NetworkPolicy

podSelector:
  matchLabels:
    app: web
ingress:
  - from:
      - podSelector:
          matchLabels:
            app: gateway
      - namespaceSelector:
          matchLabels:
            environment: production

Node Selector / Affinity

apiVersion: v1
kind: Pod
spec:
  nodeSelector:
    disktype: ssd
    gpu: nvidia

또는 더 강력한 [[k8s-scheduling|Node Affinity]]:

affinity:
  nodeAffinity:
    requiredDuringSchedulingIgnoredDuringExecution:
      nodeSelectorTerms:
        - matchExpressions:
            - key: disktype
              operator: In
              values: [ssd, nvme]

HPA

kind: HorizontalPodAutoscaler
metadata:
  name: web-hpa
spec:
  scaleTargetRef:
    apiVersion: apps/v1
    kind: Deployment
    name: web

또는 selector 로 여러 대상.

Annotations

Label 과 유사하지만 selector 로 사용되지 않음. 도구/사람이 참조하는 메타데이터.

metadata:
  annotations:
    kubernetes.io/change-cause: "Upgraded nginx to 1.27"
    deployment.kubernetes.io/revision: "5"
    prometheus.io/scrape: "true"
    prometheus.io/port: "9090"
    prometheus.io/path: "/metrics"
    nginx.ingress.kubernetes.io/rewrite-target: /
    example.com/git-commit: "abc123"
    example.com/owner: "alice@example.com"
    example.com/documentation: "https://wiki/..."

특징

Value 는 임의 문자열, 길이 상한 없음 (실제로는 etcd 상한 1 MB)
여러 도구 (Ingress controller, monitoring, deployment tool) 가 참조
Kubectl rollout history 는 kubernetes.io/change-cause annotation 표시

Label 조작

추가 / 갱신

kubectl label pod my-pod environment=production
kubectl label pod my-pod environment=staging --overwrite
kubectl label pods -l app=web version=v1.2.3

삭제

kubectl label pod my-pod environment-   # 뒤에 하이픈

자주 쓰는 라벨 패턴

환경 태깅

labels:
  environment: production
  region: us-east-1
  cluster: prod-us-east

배포 track (canary)

labels:
  app: web
  track: stable
---
labels:
  app: web
  track: canary

Service 는 app: web 으로 두 track 모두 선택. Weight-based routing 은 [[k8s-service-mesh|Service Mesh]] 나 [[k8s-ingress|Ingress]] 로.

Blue/Green

labels:
  app: web
  color: blue
---
labels:
  app: web
  color: green

Service selector 를 color: blue -> color: green 으로 전환하여 스위칭.

Cost allocation

labels:
  cost-center: engineering
  cost-project: web-platform
  cost-owner: alice

Kubecost, OpenCost 등이 이 라벨로 비용 분석.

Label vs Annotation vs Selector

항목	Label	Annotation	Selector
용도	분류, 조직	도구 참조 메타	Label 쿼리
길이 제한	63자	상한 없음 (etcd 1 MB)	-
Selector 대상	✓	✗	-
사용자 검색	✓	제한적	-
예	`app=web`	`nginx.ingress.../rewrite-target`	`app=web,tier=frontend`

규칙:

선택하고 검색할 것 -> Label
도구가 참조할 값 -> Annotation

Label 로 인한 문제

실수: template.labels 와 selector 불일치

spec:
  selector:
    matchLabels:
      app: web
  template:
    metadata:
      labels:
        app: WEB   # 대소문자 다름! (실제로는 매칭 실패)

Controller 가 template 의 Pod 을 못 관리 -> 무한 Pod 생성.

selector immutable

# 초기
selector:
  matchLabels:
    app: web

# 나중
selector:
  matchLabels:
    app: my-web   # 오류: selector immutable

Deployment 를 삭제하고 재생성해야 함.

Owner reference vs label

Kubernetes 는 리소스 관리에 owner reference (metadata.ownerReferences) 도 사용. Selector 는 논리 쿼리, owner reference 는 실제 소속. Deployment 가 ReplicaSet 을 만들면 owner reference 설정.

함정

[!WARNING] selector 는 immutable. Deployment 의 spec.selector 를 바꾸려면 재생성 필요.

[!CAUTION] version: 1.2.3 (숫자) 는 YAML 파서가 float 로 오해. version: "1.2.3" (문자열).

[!WARNING] 오래된 라벨 정리 안 하면 selector 오작동. 예: 예전 replica 가 남아 새 selector 에 매칭되어 트래픽 유입.

[!IMPORTANT] Label 개수 제한. 실질적으로 리소스당 라벨 <20 개 권장 (etcd 성능).

[!CAUTION] Annotation 을 검색에 쓰지 마세요. selector 대상 아님. 대량 데이터 (base64 인코딩된 secret 등) 는 절대 annotation 에 넣지 말 것.

[Kubernetes] Namespace

koa (김신건) — Tue, 07 Jul 2026 00:00:00 GMT

정의

Namespace 는 같은 물리 클러스터 안에서 리소스 (Pod, Service, ConfigMap 등) 를 논리적으로 격리 하는 단위입니다. 이름 충돌 회피, [[k8s-rbac|RBAC]] 스코프, [[k8s-resource-management|ResourceQuota]], [[k8s-network-policy|NetworkPolicy]] 의 기본 경계로 사용됩니다.

왜 필요한가

환경/팀 분리: dev / stg / prod 를 한 클러스터에서 격리
이름 충돌 회피: 같은 이름 (web) 을 여러 팀이 각자 namespace 에 사용
리소스 제한: 팀별 CPU/메모리 총량 상한
RBAC 스코프: 특정 namespace 에만 권한 부여
NetworkPolicy 스코프: namespace 안/밖 트래픽 제어
관측성 분리: Prometheus / Loki 등에서 namespace 라벨로 필터

기본 namespace

새 클러스터에는 4개의 시스템 namespace 가 있습니다.

Namespace	역할
`default`	Namespace 지정 없이 만든 리소스 저장소. 프로덕션은 사용 지양
`kube-system`	클러스터 컴포넌트 (kube-proxy, CoreDNS, kubelet …)
`kube-public`	모든 사용자 (인증 안 된 사용자 포함) 가 읽는 리소스
`kube-node-lease`	Node heartbeat lease 저장 (성능 최적화)

default 에 앱을 배포하지 마세요. 항상 명시적 namespace.

생성 및 조작

CLI

# 생성
kubectl create namespace dev
kubectl create namespace stg
kubectl create namespace prod

# 목록
kubectl get namespaces
kubectl get ns   # 축약

# 삭제 (그 안의 모든 리소스도 함께 삭제!)
kubectl delete namespace dev

# 특정 namespace 리소스 조회
kubectl get pods -n dev
kubectl get all -n prod

YAML

apiVersion: v1
kind: Namespace
metadata:
  name: dev
  labels:
    environment: development
    team: platform
  annotations:
    description: "Development namespace for platform team"

리소스에 명시:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: web
  namespace: prod   # 명시!
spec:
  ...

명시 안 하면 default 에 생성됩니다.

Context 전환

매 명령마다 -n prod 붙이는 대신 default namespace 를 변경:

# 확인
kubectl config current-context
kubectl config view --minify | grep namespace:

# 변경
kubectl config set-context --current --namespace=prod

# 편의 도구: kubens
kubens prod

# 편의 도구: kubectx (context 전환)
kubectx aws-prod

kubectx / kubens (ahmetb) 는 클러스터 관리자의 필수 도구.

Namespace 스코프 vs 클러스터 스코프

Namespace scoped (namespace 안에 속함):

Pod, Service, Deployment, StatefulSet, DaemonSet
ConfigMap, Secret
PVC, ServiceAccount
Role, RoleBinding
NetworkPolicy, Ingress
Job, CronJob
HPA, PDB
Endpoints

Cluster scoped (namespace 없음):

Node, Namespace 자체
PersistentVolume (PV)
StorageClass, VolumeAttachment
ClusterRole, ClusterRoleBinding
CustomResourceDefinition (CRD)
ValidatingWebhookConfiguration, MutatingWebhookConfiguration
APIService, ComponentStatus
PriorityClass

목록 확인:

kubectl api-resources --namespaced=true
kubectl api-resources --namespaced=false

DNS

Namespace 는 클러스터 DNS 에 반영. 서비스 완전 이름:

<service-name>.<namespace>.svc.cluster.local

예: db.data.svc.cluster.local 은 data namespace 의 db service.

같은 namespace 안

# app-ns 안의 두 pod
curl http://api   # 같은 namespace 내에서는 short name OK

다른 namespace 참조

# frontend namespace 에서 backend namespace 의 서비스 호출
curl http://api.backend
curl http://api.backend.svc.cluster.local

ResourceQuota (팀별 리소스 상한)

apiVersion: v1
kind: ResourceQuota
metadata:
  name: team-quota
  namespace: dev
spec:
  hard:
    requests.cpu: "10"       # 총 CPU 요청 상한
    requests.memory: 20Gi
    limits.cpu: "20"
    limits.memory: 40Gi
    pods: "50"                # 총 Pod 수
    services: "10"
    services.loadbalancers: "2"
    persistentvolumeclaims: "10"
    configmaps: "50"
    secrets: "50"

한도 초과 시 새 Pod 생성 거부.

LimitRange (Pod/컨테이너별 기본값)

apiVersion: v1
kind: LimitRange
metadata:
  name: default-limits
  namespace: dev
spec:
  limits:
    - type: Container
      default:                # limit 안 지정 시 이 값
        cpu: 500m
        memory: 512Mi
      defaultRequest:         # request 안 지정 시
        cpu: 100m
        memory: 128Mi
      max:                    # 최대 허용
        cpu: 2
        memory: 4Gi
      min:                    # 최소
        cpu: 10m
        memory: 32Mi

개발자가 리소스 요청을 안 넣어도 sane defaults.

NetworkPolicy scope

기본적으로 namespace 는 네트워크 격리를 하지 않습니다 (모든 Pod 간 통신 허용). 격리하려면 [[k8s-network-policy|NetworkPolicy]]:

apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
metadata:
  name: deny-cross-namespace
  namespace: prod
spec:
  podSelector: {}
  policyTypes: [Ingress]
  ingress:
    - from:
        - namespaceSelector:
            matchLabels:
              environment: production

prod namespace 는 자기 자신 + environment: production 라벨의 namespace 만 허용.

RBAC 스코프

Namespace 스코프 role:

apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
  namespace: dev
  name: pod-reader
rules:
  - apiGroups: [""]
    resources: [pods]
    verbs: [get, list, watch]

dev namespace 에서만 유효. 자세한 것은 [[k8s-rbac|RBAC]] 참조.

Multi-tenancy 패턴

1. Namespace per team (가장 흔함)

team-alpha/
team-beta/
team-gamma/

팀별 RBAC + ResourceQuota + NetworkPolicy
실행 오버헤드 최소
Kernel 격리 없음 (같은 노드에 다른 팀 Pod 이 함께)

2. Namespace per environment

dev/
stg/
prod/

관용적. 그러나 dev 부하가 prod 에 영향 가능
진짜 격리는 클러스터 분리 (prod 는 별 클러스터)

3. Hierarchical Namespaces (HNC, sigs)

Namespace 를 트리로 조직:

team-alpha/
  ├─ team-alpha-dev/
  ├─ team-alpha-stg/
  └─ team-alpha-prod/

정책 상속 (RoleBinding, NetworkPolicy 등). kubectl-hns 로 관리.

4. Virtual Cluster (vcluster)

한 namespace 안에 완전한 가상 클러스터 실행. 강한 격리.

Namespace 삭제 시 주의

모든 리소스 재귀 삭제. Pod, Service, PVC 등 모두.
Finalizer 가 걸린 리소스는 stuck. kubectl get ns dev -o yaml 로 finalizer 확인 후 수동 제거.
CRD instance 는 삭제 순서에 따라 위험. CRD 자체가 cluster-scoped 이므로 남을 수 있음.

Stuck namespace 정리 (긴급):

kubectl get namespace stuck-ns -o json > stuck.json
# stuck.json 의 spec.finalizers 를 [] 로 변경 후
kubectl replace --raw "/api/v1/namespaces/stuck-ns/finalize" -f stuck.json

위험한 조치. 리소스가 진짜 정리 안 됐을 수 있음.

Namespace 라벨 활용

apiVersion: v1
kind: Namespace
metadata:
  name: prod
  labels:
    environment: production
    tier: critical
    team: platform
    pod-security.kubernetes.io/enforce: restricted

Pod Security Standards 자동 적용 (PSA), namespaceSelector 활용, Cost allocation 태깅.

함정

[!WARNING] default namespace 남용 금지. 팀/환경 격리가 사라짐.

[!CAUTION] Namespace 삭제 = 안의 모든 리소스 삭제. 실수 방지: 프로덕션 클러스터에는 sensitive namespace 에 kubectl-neat / OPA 로 delete 제한.

[!WARNING] Cluster-scoped 리소스 (PV, ClusterRole) 는 namespace 로 격리 안 됨. RBAC 로 개별 관리.

[!IMPORTANT] Namespace 격리는 네트워크 자동 격리 아님. NetworkPolicy 별도 설정.

[!CAUTION] 네트워크 이름 충돌. 같은 이름의 Service 를 여러 namespace 에 두면 short name 호출 시 자기 namespace 우선. 명시적 FQDN 사용.

[Kubernetes] Persistent Volumes (PV / PVC / StorageClass)

koa (김신건) — Tue, 07 Jul 2026 00:00:00 GMT

정의

Kubernetes Storage 계층 은 세 리소스로 구성됩니다.

PersistentVolume (PV): 실제 스토리지 (EBS, GCE PD, NFS, iSCSI 등) 를 나타내는 클러스터 리소스
PersistentVolumeClaim (PVC): 사용자가 스토리지를 요청하는 리소스 (크기, 접근 모드, StorageClass)
StorageClass: PV 를 동적으로 프로비저닝하는 템플릿

Pod 은 PVC 를 mount 하고, PVC 는 PV 에 binding 됩니다. 동적 프로비저닝 시에는 사용자가 PVC 만 만들면 StorageClass 가 자동으로 PV 를 만듭니다.

왜 필요한가

컨테이너는 stateless 지향이지만 실제 앱은 상태가 있습니다.

DB, 캐시, 큐: Postgres, Redis, Kafka 등
파일 업로드: 사용자 첨부 파일
로그, 메트릭: 영속 저장
모델, 데이터셋: ML 학습

Pod 이 재시작되거나 노드가 옮겨져도 데이터가 유지되어야 합니다.

컨셉

flowchart LR
  U[사용자] -->|PVC 생성| PVC[PVC]
  PVC -->|matches spec| PV[PV]
  PV -->|backed by| Storage[(EBS / NFS / etc.)]
  Pod[Pod] -->|volumeMount| PVC

  SC[StorageClass] -.->|dynamic provisioning| PV

PV vs PVC vs StorageClass

리소스	만드는 사람	스코프	역할
PV	관리자 (static) 또는 자동 (dynamic)	Cluster	실제 스토리지 표현
PVC	개발자	Namespace	스토리지 요청
StorageClass	관리자	Cluster	PV 자동 생성 템플릿

Static Provisioning (수동)

관리자가 미리 PV 를 만들고 사용자가 PVC 로 청구.

apiVersion: v1
kind: PersistentVolume
metadata:
  name: pv-example
spec:
  capacity:
    storage: 10Gi
  accessModes:
    - ReadWriteOnce
  persistentVolumeReclaimPolicy: Retain
  storageClassName: manual
  nfs:
    server: nfs.example.com
    path: /exports/data

apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: pvc-example
spec:
  accessModes:
    - ReadWriteOnce
  resources:
    requests:
      storage: 10Gi
  storageClassName: manual

Kubernetes 가 크기와 access mode 매칭되는 PV 를 찾아 binding.

Dynamic Provisioning (권장)

StorageClass 가 자동으로 PV 생성.

apiVersion: storage.k8s.io/v1
kind: StorageClass
metadata:
  name: gp3-encrypted
  annotations:
    storageclass.kubernetes.io/is-default-class: "true"
provisioner: ebs.csi.aws.com
parameters:
  type: gp3
  iops: "3000"
  throughput: "125"
  encrypted: "true"
  kmsKeyId: "arn:aws:kms:..."
reclaimPolicy: Delete
allowVolumeExpansion: true
volumeBindingMode: WaitForFirstConsumer

apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: postgres-data
spec:
  accessModes: [ReadWriteOnce]
  resources:
    requests:
      storage: 100Gi
  storageClassName: gp3-encrypted

PVC 를 만들면 EBS 볼륨이 자동 생성 -> PV 자동 생성 -> PVC 에 binding.

Access Modes

모드	의미	지원 스토리지
ReadWriteOnce (RWO)	한 노드에서 R/W	EBS, GCE PD, Azure Disk (대부분 블록)
ReadOnlyMany (ROX)	여러 노드에서 R only	NFS, CephFS
ReadWriteMany (RWX)	여러 노드에서 R/W	NFS, CephFS, EFS
ReadWriteOncePod (RWOP)	한 Pod 에서만 R/W	K8s 1.22+ CSI

주의: 접근 모드는 스토리지 driver 의 능력. 지원 안 하는 모드로 요청하면 binding 실패.

Reclaim Policy

PVC 삭제 시 PV 의 운명:

Delete (기본, dynamic): 실제 스토리지도 삭제
Retain: PV 는 남아 관리자가 수동 처리
Recycle (deprecated): 데이터 wipe 후 재사용

프로덕션 DB PVC 는 Retain 이 안전. 실수로 PVC 지워도 데이터 살아있음.

Volume Binding Mode

Immediate (기본): PVC 만드는 즉시 PV 프로비저닝
WaitForFirstConsumer: Pod 이 실제로 스케줄될 때 프로비저닝

WaitForFirstConsumer 권장 이유: 스케줄러가 노드 결정 후 그 노드의 AZ 에 볼륨 생성. 아니면 볼륨이 A zone 인데 Pod 이 B zone 에 스케줄되어 실패.

Volume Expansion

storageClassName: gp3-encrypted
allowVolumeExpansion: true

kubectl edit pvc 로 크기 증가:

resources:
  requests:
    storage: 200Gi   # 100 -> 200

CSI driver 가 volume + filesystem 확장. 축소는 대부분 지원 안 함.

Volume 유형

emptyDir

Pod 생명주기. Pod 삭제되면 사라짐.

volumes:
  - name: cache
    emptyDir:
      sizeLimit: 500Mi
      medium: Memory   # tmpfs (RAM), 기본은 disk

hostPath

노드의 파일시스템 mount. 보안 위험 (탈출 가능), 프로덕션 지양.

configMap / secret

ConfigMap/Secret 을 파일로 mount.

volumes:
  - name: config
    configMap:
      name: app-config
volumeMounts:
  - name: config
    mountPath: /etc/config
    readOnly: true

PVC (persistent)

volumes:
  - name: data
    persistentVolumeClaim:
      claimName: postgres-data

Projected

여러 소스를 한 디렉토리에 합쳐 mount (secret + configMap + downwardAPI + serviceAccountToken).

CSI ephemeral (K8s 1.25+)

Pod 생명주기지만 CSI driver 로 프로비저닝 (secrets store CSI, secrets manager 등).

CSI (Container Storage Interface)

CSI 는 스토리지 provider 와 컨테이너 오케스트레이터 사이의 표준 인터페이스. 이전에는 k8s 안에 in-tree driver (EBS, GCE PD 등) 였지만, 이제는 모두 CSI out-of-tree 로 이관.

CSI 컴포넌트:

Controller Plugin: 볼륨 생성/삭제/attach/detach. Deployment 로 실행.
Node Plugin: 볼륨을 파일시스템에 mount/unmount. DaemonSet 로 각 노드.
CSI Sidecar: external-provisioner, external-attacher, external-resizer, external-snapshotter 표준 컨트롤러들.

주요 CSI drivers:

[[aws-ebs-vs-instance-store|AWS EBS CSI]] (ebs.csi.aws.com)
AWS EFS CSI (efs.csi.aws.com) - RWX
GCE PD CSI
Azure Disk / File CSI
Ceph RBD / CephFS CSI
Longhorn (Rancher)
OpenEBS
Rook (Ceph 관리)

Volume Snapshot

CSI 스냅샷 지원 시:

apiVersion: snapshot.storage.k8s.io/v1
kind: VolumeSnapshot
metadata:
  name: postgres-snap-20260707
spec:
  volumeSnapshotClassName: csi-hostpath-snapclass
  source:
    persistentVolumeClaimName: postgres-data

Snapshot 에서 새 PVC 복원:

apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: postgres-restored
spec:
  storageClassName: gp3-encrypted
  dataSource:
    name: postgres-snap-20260707
    kind: VolumeSnapshot
    apiGroup: snapshot.storage.k8s.io
  resources:
    requests:
      storage: 100Gi

StatefulSet 과의 조합

[[k8s-statefulset|StatefulSet]] 의 volumeClaimTemplates 는 각 Pod 마다 PVC 자동 생성:

kind: StatefulSet
spec:
  volumeClaimTemplates:
    - metadata:
        name: data
      spec:
        accessModes: [ReadWriteOnce]
        storageClassName: gp3-encrypted
        resources:
          requests:
            storage: 100Gi

web-0, web-1, web-2 각 Pod 이 data-web-0, data-web-1, data-web-2 PVC 를 갖음. Pod 삭제 후 재생성해도 같은 PVC 재연결.

Multi-AZ 함정

블록 스토리지 (EBS, GCE PD) 는 한 AZ 에 종속. 다른 AZ 로 옮기려면:

Snapshot 생성
Snapshot 을 새 AZ 에 복제
새 PV 생성

이래서 StatefulSet + [[k8s-scheduling|topology spread]] 가 조합됩니다. Pod 이 AZ 를 옮기면 PVC 재연결 실패 가능성.

RWX 파일시스템 (EFS, NFS) 은 AZ 무관 하지만 성능 낮음.

함정

[!WARNING] reclaimPolicy: Delete 로 프로덕션 DB PVC 를 만들면 실수로 PVC 삭제 시 데이터 영구 소실. 반드시 Retain.

[!CAUTION] RWO 는 한 노드. Multi-writer 앱은 실패. RWX 필요.

[!WARNING] AZ 교차 볼륨 attach 불가 (EBS 등). WaitForFirstConsumer + AZ affinity 필수.

[!IMPORTANT] StorageClass 없이 PVC 만들면 default StorageClass 로 fallback. 없으면 pending. 명시적 지정.

[!CAUTION] CSI 스냅샷 삭제 정책. 스냅샷 class 의 deletionPolicy: Retain 이 아니면 원본 삭제 시 함께 삭제.

[Kubernetes] Resource Management (Requests, Limits, QoS)

koa (김신건) — Tue, 07 Jul 2026 00:00:00 GMT

정의

Kubernetes Resource Management 는 CPU, 메모리, ephemeral storage, hugepages 등의 리소스를 파드에 할당하고 제한하는 시스템입니다. 각 컨테이너의 request (스케줄링 기준, 보장) 와 limit (사용 상한) 을 지정하고, Pod 전체의 QoS Class (Guaranteed / Burstable / BestEffort) 가 결정됩니다.

Request vs Limit

Request (요청)

스케줄러가 노드 선택 시 기준. 노드에 request 총합 만큼의 여유가 있어야 스케줄링.
최소 보장: 노드 부하 중에도 request 만큼은 사용 가능 (실제로는 CPU 는 항상 보장, 메모리는 상황 따라).

Limit (상한)

사용 상한. 초과 시 CPU 는 throttling, 메모리는 OOM Kill.
스케줄러 기준 아님: 노드가 100 vCPU 인데 limit 총합 200 vCPU 여도 스케줄링 OK (over-commit).

apiVersion: v1
kind: Pod
metadata:
  name: web
spec:
  containers:
    - name: web
      image: nginx
      resources:
        requests:
          cpu: 500m         # 0.5 vCPU 보장
          memory: 512Mi
          ephemeral-storage: 1Gi
        limits:
          cpu: 2            # 최대 2 vCPU
          memory: 2Gi
          ephemeral-storage: 5Gi

단위

CPU

1 = 1 vCPU (또는 1 hyperthread on x86)
1000m (milliCPU) = 1 vCPU
500m = 0.5 vCPU (fractional 표현)
100m = 0.1 vCPU (매우 작은 요청)

Memory

Ki, Mi, Gi, Ti (2진, IEC): 1024 배
K, M, G, T (10진, SI): 1000 배
1 Gi = 1 073 741 824 bytes
1 G = 1 000 000 000 bytes

관용: 항상 Mi, Gi.

QoS Classes

Pod 의 request/limit 조합으로 결정. 노드 압박 (memory pressure) 시 BestEffort 부터 evict.

1. Guaranteed

모든 컨테이너가 request == limit 이고 CPU + memory 모두 지정.

resources:
  requests:
    cpu: 500m
    memory: 512Mi
  limits:
    cpu: 500m
    memory: 512Mi

노드 압박 시 가장 나중에 evict
CPU pinning 가능 (--cpu-manager-policy=static)
실시간 워크로드 (DB, Kafka broker 등) 관용

2. Burstable

Request < limit 이거나 부분 지정. Guaranteed 와 BestEffort 사이.

resources:
  requests:
    cpu: 100m
    memory: 128Mi
  limits:
    cpu: 500m
    memory: 512Mi

대부분 워크로드가 여기
Request 보장 + burst 여유

3. BestEffort

Request/limit 아예 없음.

resources: {}

가장 먼저 evict
실전 프로덕션 지양

CPU throttling

CFS (Completely Fair Scheduler) 에 limit 을 quota 로 설정. 100ms 주기 (cpu.cfs_period_us) 안에 limit * 100ms 이상 사용 시 throttle.

함정: CPU limit 은 성능 저하 원인이 됩니다. Multi-threaded 앱이 짧은 순간 burst 하면 throttle. 특히 GC (JVM, .NET, Go), warm-up 단계.

권장 정책

CPU limit 없이 request 만: 노드 유휴 시 자유 사용, 부하 시 request 보장
CPU limit 필요: 매우 노이지 이웃 방지 필요 시, throttling 인지하고 성능 테스트

이견도 있음. Multi-tenant 환경, quota 회계 필요 시 limit 유지. Java/Python 은 throttling 취약, Go 는 상대적으로 관대.

Memory OOM

Memory limit 초과 -> kernel OOM Killer 가 프로세스 죽임 (SIGKILL). Pod OOMKilled 상태.

함정:

JVM heap 은 limit 을 자동 감지 못 함 (< JDK 10). -Xmx 명시 필요. 또는 -XX:MaxRAMPercentage.
Python multiprocessing: fork 시 copy-on-write 로 실제 메모리 계산 어려움.
Node.js: --max-old-space-size 로 heap 상한.
Go runtime: 원격 GC 인지, GOMEMLIMIT (Go 1.19+) 로 조절.

Memory limit 없이 방치하면 노드의 다른 Pod 을 굶겨 시스템 전체 위험. 반드시 limit 설정.

QoS 노드 압박 시

Node 가 memory pressure 감지 -> kubelet 이 Pod 순서대로 evict:

BestEffort
Burstable (request 를 초과 사용하는 것 우선)
Guaranteed

CPU pressure 는 evict 없이 throttling 만. Memory 만 evict 발동.

LimitRange (namespace 기본값)

apiVersion: v1
kind: LimitRange
metadata:
  name: default-limits
  namespace: dev
spec:
  limits:
    - type: Container
      default:                # limit 안 지정 시 이 값
        cpu: 500m
        memory: 512Mi
      defaultRequest:         # request 안 지정 시
        cpu: 100m
        memory: 128Mi
      max:
        cpu: 4
        memory: 8Gi
      min:
        cpu: 10m
        memory: 32Mi
      maxLimitRequestRatio:
        cpu: 4                 # limit/request 비율 상한
        memory: 4

max*, min 초과 시 admission 에서 거부.

ResourceQuota (namespace 총 상한)

apiVersion: v1
kind: ResourceQuota
metadata:
  name: team-quota
  namespace: dev
spec:
  hard:
    requests.cpu: "10"
    requests.memory: 20Gi
    limits.cpu: "20"
    limits.memory: 40Gi
    pods: "100"
    persistentvolumeclaims: "20"
    requests.storage: 500Gi

Namespace 안 총합 초과 시 새 리소스 거부. 자세한 것은 [[k8s-namespace|Namespace]] 참조.

PriorityClass & Preemption

높은 priority Pod 은 낮은 priority Pod 을 evict (preemption) 하여 스케줄 자리 확보.

apiVersion: scheduling.k8s.io/v1
kind: PriorityClass
metadata:
  name: high-priority
value: 1000000
globalDefault: false
description: "Critical workloads"
---
apiVersion: v1
kind: Pod
spec:
  priorityClassName: high-priority

시스템 컴포넌트는 system-cluster-critical (2000000000), system-node-critical (2000001000) 사용.

VPA (Vertical Pod Autoscaler)

Request/limit 을 자동 조정. 관찰된 사용량 기반.

apiVersion: autoscaling.k8s.io/v1
kind: VerticalPodAutoscaler
metadata:
  name: web-vpa
spec:
  targetRef:
    apiVersion: apps/v1
    kind: Deployment
    name: web
  updatePolicy:
    updateMode: "Auto"    # 또는 "Recreate", "Off" (recommendation only)
  resourcePolicy:
    containerPolicies:
      - containerName: web
        minAllowed:
          cpu: 100m
          memory: 128Mi
        maxAllowed:
          cpu: 2
          memory: 4Gi

자세한 것은 [[k8s-hpa-vpa|HPA / VPA]] 참조.

Ephemeral Storage

컨테이너의 writable layer + emptyDir. 노드의 filesystem 사용.

resources:
  requests:
    ephemeral-storage: 1Gi
  limits:
    ephemeral-storage: 5Gi

초과 시 Pod evict.

주의: 로그도 여기에 씀 (kubectl logs 소스). 큰 로그 = ephemeral 소모.

Extended Resources

GPU, RDMA, SR-IOV 등:

resources:
  limits:
    nvidia.com/gpu: 2
    intel.com/rdma: 1

Device plugin 이 노드 리소스로 등록.

In-place resize (K8s 1.27+ Alpha, 1.33+ Beta)

Pod 재시작 없이 request/limit 조정:

resources:
  requests:
    cpu: 500m
    memory: 512Mi
  limits:
    cpu: 2
    memory: 2Gi
  resizePolicy:
    - resourceName: cpu
      restartPolicy: NotRequired    # CPU 는 재시작 없이
    - resourceName: memory
      restartPolicy: RestartContainer

VPA 와 통합 진행 중. 미래에는 재시작 없는 vertical scaling.

함정

[!WARNING] CPU limit 없이 memory limit 없이 Pod = BestEffort. 노드 부하 시 최우선 evict.

[!CAUTION] CPU throttling 이 latency 를 죽입니다. JVM warm-up, GC, burst 트래픽. limit 없이 request 만 두는 편이 성능 유리.

[!WARNING] Memory limit 초과 = 즉시 SIGKILL. Graceful 종료 없음. JVM, Node 등은 자동 heap 튜닝 안 됨, 명시적 세팅.

[!IMPORTANT] Request 는 스케줄러 기준. 실제 사용량이 아님. 사용량 지속 초과하면 evict 는 아니지만 node pressure 유발.

[!CAUTION] JVM -XX:+UseContainerSupport (default 후 JDK 11+) 없으면 컨테이너 limit 안 봄. 명시.

[!WARNING] ephemeral-storage limit 을 안 걸면 로그 폭주로 노드 fill. 반드시 설정.

[Kubernetes] Scheduling (Taints, Affinity, Topology Spread)

koa (김신건) — Tue, 07 Jul 2026 00:00:00 GMT

정의

Kubernetes Scheduling 은 kube-scheduler 가 새 Pod 을 어느 노드에 배치할지 결정하는 과정입니다. 두 단계 (Filtering + Scoring), 여러 정책 (nodeSelector, Affinity, Taints/Tolerations, Topology Spread, PriorityClass) 을 조합해 세밀한 배치 제어를 제공합니다.

기본 흐름

flowchart LR
  P[새 Pod] --> F[Filtering]
  F -->|후보 노드| S[Scoring]
  S -->|최고 점수| N[선정 노드]

Filtering (predicates)

노드가 Pod 실행 조건 만족하는지 검사:

리소스 여유 (CPU, memory)
nodeSelector / nodeAffinity 매치
Taints 를 tolerate
Volume affinity (AZ 매치)
Port 충돌 없음
노드 상태 Ready

Scoring (priorities)

살아남은 노드에 점수 (0-100):

LeastRequested: request 여유 많은 노드 선호
BalancedResourceAllocation: CPU/memory 균형
NodeAffinity preferred: 선호도 매치
InterPodAffinity preferred
ImageLocality: 이미지 이미 있는 노드
TopologySpread: 균형 분산

nodeSelector (가장 단순)

apiVersion: v1
kind: Pod
metadata:
  name: gpu-workload
spec:
  nodeSelector:
    accelerator: nvidia
    disktype: ssd
  containers: [...]

노드에 라벨이 있어야 매치. 정확히 이 라벨을 가진 노드에만 배치.

단점: AND 만 지원. 유연성 낮음. 신규 코드는 Node Affinity 권장.

Node Affinity

requiredDuringScheduling (hard)

affinity:
  nodeAffinity:
    requiredDuringSchedulingIgnoredDuringExecution:
      nodeSelectorTerms:
        - matchExpressions:
            - key: topology.kubernetes.io/zone
              operator: In
              values: [us-east-1a, us-east-1b]
            - key: node-type
              operator: NotIn
              values: [spot]

만족 못 하면 스케줄 안 됨. IgnoredDuringExecution 은 실행 중 노드 라벨 바뀌어도 evict 안 함.

preferredDuringScheduling (soft)

affinity:
  nodeAffinity:
    preferredDuringSchedulingIgnoredDuringExecution:
      - weight: 100
        preference:
          matchExpressions:
            - key: instance-type
              operator: In
              values: [m5.large]
      - weight: 50
        preference:
          matchExpressions:
            - key: zone
              operator: In
              values: [us-east-1a]

선호도. 완벽 매치 못 해도 스케줄됨.

Operators

In, NotIn: 값 목록
Exists, DoesNotExist: 라벨 존재 여부
Gt, Lt: 숫자 비교

Pod Affinity / Anti-Affinity

Pod Affinity (다른 Pod 옆에)

같은 노드/AZ 에 있는 다른 Pod 옆에 배치. 캐시 지역성, 통신 지연 최소화.

affinity:
  podAffinity:
    requiredDuringSchedulingIgnoredDuringExecution:
      - labelSelector:
          matchLabels:
            app: cache
        topologyKey: kubernetes.io/hostname   # 같은 노드

topologyKey: 어느 단위 (호스트, zone, region) 로 판단.

Pod Anti-Affinity (다른 Pod 피해)

같은 노드/AZ 에 없어야. HA 의 핵심.

affinity:
  podAntiAffinity:
    requiredDuringSchedulingIgnoredDuringExecution:
      - labelSelector:
          matchLabels:
            app: web
        topologyKey: kubernetes.io/hostname

app: web Pod 이 같은 노드에 있으면 스케줄 실패. Replica 를 여러 노드에 강제 분산.

AZ 분산:

topologyKey: topology.kubernetes.io/zone

각 AZ 에 최대 하나. 3 AZ + 3 replica 면 각 zone 1개.

주의: required anti-affinity 는 스케줄러가 O(N^2) 검사. 큰 클러스터에서 느림. 대안: Topology Spread.

Topology Spread Constraints

topologySpreadConstraints:
  - maxSkew: 1
    topologyKey: topology.kubernetes.io/zone
    whenUnsatisfiable: DoNotSchedule
    labelSelector:
      matchLabels:
        app: web

각 zone 의 Pod 수 차이 (skew) 가 maxSkew 이하가 되도록. app: web Pod 이 zone A 에 5개, B 에 4개인데 새 pod 추가하면 A 에는 못 감 (skew 2 초과).

whenUnsatisfiable:

DoNotSchedule (hard): 불만족이면 pending
ScheduleAnyway (soft): 조건 안 맞아도 스케줄

Anti-affinity 보다 성능 좋고 유연. HA + 균형 분산의 표준.

Taints and Tolerations

Taint 는 노드에 붙이는 “특정 Pod 만 허용” 표시. Toleration 은 Pod 이 taint 를 견딜 수 있다는 선언.

Taint 부여

kubectl taint nodes node1 dedicated=gpu:NoSchedule
kubectl taint nodes node1 spot=true:PreferNoSchedule
kubectl taint nodes node1 out-of-service:NoExecute

Effect

NoSchedule: 매치 안 되는 Pod 은 스케줄 안 됨 (기존 Pod 은 유지)
PreferNoSchedule: soft 버전
NoExecute: 매치 안 되는 기존 Pod evict + 새 Pod 안 옴

Toleration

tolerations:
  - key: dedicated
    operator: Equal
    value: gpu
    effect: NoSchedule
  - key: spot
    operator: Exists                # 값 무관, 키만 매치
    effect: PreferNoSchedule
  - key: out-of-service
    operator: Exists
    effect: NoExecute
    tolerationSeconds: 300           # evict 유예 (초)

관용

dedicated=team-x:NoSchedule: 특정 팀 전용 노드
nvidia.com/gpu:NoSchedule: GPU 노드 (Karpenter, GPU Operator 자동)
node.kubernetes.io/unreachable:NoExecute: 시스템 taint, unreachable 노드
node.kubernetes.io/not-ready:NoExecute: NotReady 노드

PodDisruptionBudget (PDB)

Voluntary disruption (Drain, PDB 존중 rolling update 등) 중 최소 실행 Pod 수 보장.

apiVersion: policy/v1
kind: PodDisruptionBudget
metadata:
  name: web-pdb
spec:
  minAvailable: 2       # 항상 2개 이상 실행
  # 또는
  maxUnavailable: 1     # 최대 1개만 죽어도 됨
  selector:
    matchLabels:
      app: web

kubectl drain 시 PDB 위반될 pod 은 evict 안 함.

주의: PDB 는 voluntary 만 적용. Node crash, kernel OOM 등 involuntary 는 못 막음.

Priority & Preemption

높은 priority Pod 이 낮은 priority Pod 을 evict.

apiVersion: scheduling.k8s.io/v1
kind: PriorityClass
metadata:
  name: prod-critical
value: 1000000
description: "Production critical workloads"

spec:
  priorityClassName: prod-critical

System critical: system-cluster-critical (2 000 000 000), system-node-critical (2 000 001 000)
User: 0 ~ 1 000 000 000 권장

nodeName (강제 지정, 지양)

spec:
  nodeName: node1

스케줄러 우회. 노드 이름 하드코딩 => 확장성 없음. 개발/디버깅만.

스케줄러 확장

Scheduling Framework: 커스텀 plugin (필터, 스코어 등) 삽입
Multiple Schedulers: spec.schedulerName 으로 다른 스케줄러 선택
Volcano: 배치/ML 워크로드 스케줄러
Karpenter (AWS/Azure): 노드 프로비저닝 스케줄러 (kube-scheduler 보완)

실전 패턴

HA 웹앱 (3 replica, 3 AZ 분산)

spec:
  replicas: 3
  template:
    spec:
      topologySpreadConstraints:
        - maxSkew: 1
          topologyKey: topology.kubernetes.io/zone
          whenUnsatisfiable: DoNotSchedule
          labelSelector:
            matchLabels:
              app: web
      affinity:
        podAntiAffinity:
          preferredDuringSchedulingIgnoredDuringExecution:
            - weight: 100
              podAffinityTerm:
                labelSelector:
                  matchLabels:
                    app: web
                topologyKey: kubernetes.io/hostname

zone 균등 + 같은 노드 회피 (soft).

GPU 워크로드 (전용 노드)

spec:
  nodeSelector:
    accelerator: nvidia-tesla-t4
  tolerations:
    - key: nvidia.com/gpu
      operator: Exists
      effect: NoSchedule
  containers:
    - name: trainer
      resources:
        limits:
          nvidia.com/gpu: 1

Spot 노드 (비용 절감)

spec:
  nodeSelector:
    node-type: spot
  tolerations:
    - key: spot
      operator: Exists
      effect: PreferNoSchedule

함정

[!WARNING] Anti-affinity required + 대규모 클러스터 = 스케줄러 성능 저하. Topology Spread 로 대체.

[!CAUTION] AZ 3개 + replica 4 개 에 maxSkew: 1 이면 균등 분산 불가. 조합 수학 확인.

[!WARNING] Taint 잘못 걸면 시스템 pod 도 못 뜸. NoExecute 는 특히 위험. Test cluster 에서 검증.

[!IMPORTANT] PDB 는 rolling update 를 막을 수도 있음. 항상 maxUnavailable 이 replica 총합보다 작아야 rolling 가능.

[!CAUTION] nodeName 하드코딩 지양. Pod 이 오직 그 노드에 만. 노드 죽으면 재스케줄 없음.

[Kubernetes] Service Mesh (Istio, Linkerd, Cilium)

koa (김신건) — Tue, 07 Jul 2026 00:00:00 GMT

정의

Service Mesh 는 마이크로서비스 간 통신에 L7 정책, mTLS 암호화, 트래픽 관리, 관측성 을 제공하는 인프라 계층입니다. 앱 코드를 바꾸지 않고 프록시 (sidecar 또는 데이터 플레인) 가 모든 트래픽을 가로챕니다.

세 대표 프로젝트: Istio, Linkerd, Cilium Service Mesh.

왜 필요한가

Kubernetes 내장 [[k8s-service|Service]] + [[k8s-ingress|Ingress]] 만으로는 부족한 것들:

mTLS: Pod 간 자동 암호화 + 상호 인증
L7 라우팅: HTTP path / header 기반, canary, mirroring
Retry / timeout / circuit breaking: 앱 코드 없이 정책으로
관측성: 자동 metric (RPS, latency, error rate), 분산 트레이스
인증/인가: 서비스 identity, JWT 검증
Rate limiting: 서비스별 한도

두 가지 데이터 플레인 모델

1. Sidecar

각 Pod 에 프록시 (Envoy 등) sidecar 추가. Istio 전통, Linkerd 기본.

장점: 격리, per-pod 정책 세밀 단점: 리소스 오버헤드 (Pod 당 프록시), 시작 지연

2. Sidecarless (Node-level / eBPF)

프록시가 노드 레벨 (DaemonSet, eBPF program). Cilium Service Mesh, Istio Ambient.

장점: 리소스 절감, 지연 감소 단점: 격리 감소, 새로운 개념

Istio

가장 기능 풍부. Google 발원, IBM/Red Hat/Solo.io 등 광범 참여.

아키텍처

Envoy (data plane): Sidecar 프록시 (또는 Ambient 의 ztunnel + waypoint)
Istiod (control plane): pilot (트래픽 관리), citadel (mTLS 인증서), galley (config)

주요 리소스

# VirtualService: 라우팅
apiVersion: networking.istio.io/v1
kind: VirtualService
metadata:
  name: web-vs
spec:
  hosts: [web]
  http:
    - match:
        - headers:
            x-version:
              exact: v2
      route:
        - destination:
            host: web
            subset: v2
    - route:
        - destination:
            host: web
            subset: v1
          weight: 90
        - destination:
            host: web
            subset: v2
          weight: 10
    - retries:
        attempts: 3
        perTryTimeout: 2s
    - timeout: 10s
---
# DestinationRule: 로드밸런싱, TLS
apiVersion: networking.istio.io/v1
kind: DestinationRule
metadata:
  name: web-dr
spec:
  host: web
  trafficPolicy:
    tls:
      mode: ISTIO_MUTUAL
    connectionPool:
      tcp:
        maxConnections: 100
      http:
        http2MaxRequests: 1000
    outlierDetection:
      consecutive5xxErrors: 5
      interval: 30s
      baseEjectionTime: 30s
  subsets:
    - name: v1
      labels: {version: v1}
    - name: v2
      labels: {version: v2}

Istio Ambient Mesh

Sidecar 없는 새 데이터 플레인 (v1.22+ GA):

ztunnel: 노드마다 DaemonSet. L4 mTLS + tunneling.
waypoint: L7 정책 필요 시 별도 Envoy proxy.

계층 분리: L4 는 ztunnel (모든 트래픽 자동), L7 는 waypoint (필요한 곳만). 점진 도입.

Linkerd

Buoyant 개발. “가장 단순한 mesh” 지향.

아키텍처

linkerd-proxy (Rust, 매우 가벼움): sidecar
linkerd control plane: destination, identity, proxy-injector

특징

Rust 프록시: Envoy 보다 훨씬 가벼움 (< 10 MB memory)
mTLS default: 옵션 아닌 기본
Zero-config: 대부분 자동
CNCF Graduated (2021)

사용

linkerd install | kubectl apply -f -
linkerd inject deployment.yaml | kubectl apply -f -

linkerd inject 는 pod template 에 sidecar 주석 자동 추가.

리소스

apiVersion: policy.linkerd.io/v1alpha1
kind: Server
metadata:
  name: web-server
spec:
  podSelector:
    matchLabels:
      app: web
  port: 8080
  proxyProtocol: HTTP/1
---
apiVersion: policy.linkerd.io/v1alpha1
kind: ServerAuthorization
metadata:
  name: web-clients
spec:
  server:
    name: web-server
  client:
    meshTLS:
      identities:
        - "gateway.default.serviceaccount.identity.linkerd.cluster.local"

Istio 보다 정책 문법 단순.

Cilium Service Mesh

eBPF 기반. CNI + service mesh 통합.

아키텍처

Cilium DaemonSet: eBPF program 을 kernel 에 로드. L3-L7 처리.
Envoy 통합: L7 정책 필요 시 노드에 Envoy 실행.

장점

Sidecarless: 리소스 절감
CNI 통합: 별도 mesh 설치 불필요
Hubble: 관측 UI + CLI (자체)
kube-proxy replacement: eBPF 로 대체 성능 향상

리소스

Gateway API 및 자체 CiliumEnvoyConfig 등 지원.

기능 비교

기능	Istio	Linkerd	Cilium
mTLS	✓ (선택/강제)	✓ (기본)	✓
L7 라우팅	매우 풍부	기본	풍부 (Envoy)
Traffic split	✓	✓	✓
Retry / Timeout	✓	✓	✓
Circuit breaking	✓	✗ (부재)	✓
Rate limiting	✓ (with Envoy)	✗	✓
JWT auth	✓	✗	✓
관측성	매우 풍부 (Kiali, Jaeger)	좋음 (자체 dashboard)	좋음 (Hubble)
Multi-cluster	✓	✓	✓ (Cluster Mesh)
리소스 부담	큼 (Envoy)	작음 (Rust)	작음 (eBPF)
학습 곡선	가파름	완만	중간
Ambient/Sidecarless	✓ (Ambient)	✗	✓ (native)

결론:

Simple + 최소 오버헤드: Linkerd
최대 기능 + 다양한 정책: Istio
CNI + Mesh 통합, 성능: Cilium

Gateway API

Ingress 의 후속 표준. 3-role 모델 (Infrastructure Provider, Cluster Operator, Application Developer). Istio/Cilium/Linkerd 모두 지원 (Linkerd 2.15+).

apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: main
spec:
  gatewayClassName: istio
  listeners:
    - name: https
      port: 443
      protocol: HTTPS
      tls:
        mode: Terminate
        certificateRefs:
          - name: tls-secret
      allowedRoutes:
        namespaces:
          from: All
---
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: web
spec:
  parentRefs:
    - name: main
  hostnames: [web.example.com]
  rules:
    - matches:
        - path:
            type: PathPrefix
            value: /
      backendRefs:
        - name: web
          port: 80
          weight: 90
        - name: web-canary
          port: 80
          weight: 10

VirtualService/DestinationRule 을 대체하는 방향. Long-term 표준.

도입 결정

Service Mesh 가 필요한가

필요 신호:

여러 팀이 마이크로서비스 배포
mTLS 요구
Canary / traffic mirroring 필요
Retry / timeout 정책이 앱 코드에 산재
관측성이 부족

불필요 신호:

단일 앱 / 소수 서비스
통신이 단순
이미 API Gateway 하나로 충분
팀이 mesh 운영 여력 없음

Mesh 는 운영 부담 이 큽니다. 잘 몰라서 mesh 설치 후 유령 지연이 생기는 흔한 실패.

도입 단계

관측만: mTLS + 자동 metrics 만 (traffic policy 없음)
정책 도입: retry, timeout, circuit breaker
Canary: VirtualService 로 weight-based
Zero-trust: AuthorizationPolicy 로 서비스 인증

함정

[!WARNING] Mesh 는 latency 를 추가합니다. Envoy per-hop ~ 1-3 ms. Sub-ms 요구 워크로드는 부담.

[!CAUTION] Sidecar 오류 디버깅. 앱이 정상인데 mesh 프록시가 문제일 수 있음. Envoy access log, retry counter 확인.

[!WARNING] Multi-mesh 금지. Istio + Linkerd 동시 X.

[!IMPORTANT] Bootstrap 순서. cert-manager, Istiod, sidecar injector 순으로. mesh 자체는 mesh 밖에서 관리.

[!CAUTION] CNI 와 mesh 상호작용. Cilium CNI + Istio 는 알려진 조합 이슈. Cilium Mesh 또는 Istio Ambient 로 통일.

kubectl

koa (김신건) — Tue, 07 Jul 2026 00:00:00 GMT

정의

kubectl 은 Kubernetes API 를 명령줄에서 조작하는 공식 CLI 입니다. kube-apiserver 와 통신해 리소스를 조회, 생성, 수정, 삭제하고, 로그/exec/포트포워딩 같은 상호작용을 제공합니다.

설치 & 설정

설치

# macOS
brew install kubectl
# 또는
brew install kubernetes-cli

# Linux
curl -LO "https://dl.k8s.io/release/$(curl -L -s https://dl.k8s.io/release/stable.txt)/bin/linux/amd64/kubectl"
sudo install -o root -g root -m 0755 kubectl /usr/local/bin/kubectl

# Windows
choco install kubernetes-cli

kubeconfig

~/.kube/config 파일. 여러 클러스터/context 정보.

apiVersion: v1
kind: Config
clusters:
  - name: prod
    cluster:
      server: https://api.prod.example.com
      certificate-authority-data: <base64>
users:
  - name: alice
    user:
      client-certificate-data: <base64>
      client-key-data: <base64>
      # 또는
      token: <bearer-token>
      # 또는
      exec:
        apiVersion: client.authentication.k8s.io/v1beta1
        command: aws
        args: ["eks", "get-token", "--cluster-name", "prod"]
contexts:
  - name: alice@prod
    context:
      cluster: prod
      user: alice
      namespace: default
current-context: alice@prod

기본 명령

CRUD

# 리소스 조회
kubectl get pods
kubectl get all -n prod
kubectl get pod <name> -o yaml
kubectl get pod <name> -o json
kubectl get pods -l app=web -o wide
kubectl get pods --sort-by=.metadata.creationTimestamp

# 자세한 정보
kubectl describe pod <name>
kubectl describe node <name>

# 생성/갱신 (선언적)
kubectl apply -f deployment.yaml
kubectl apply -f ./manifests/     # 디렉토리 전체
kubectl apply -k ./overlays/prod/  # kustomize

# 생성 (명령형)
kubectl create namespace dev
kubectl create deployment web --image=nginx:1.27 --replicas=3
kubectl create secret generic db --from-literal=password=secret

# 실행 명령형
kubectl run tmp --image=busybox --rm -it --restart=Never -- /bin/sh

# 편집 (직접, 지양)
kubectl edit deployment web

# 삭제
kubectl delete pod <name>
kubectl delete -f deployment.yaml
kubectl delete deployment,service --all -n dev

apply vs create vs replace

apply (선언적, 권장): 최종 상태 지정. 3-way merge (last-applied annotation + live + config).
create (명령형): 없으면 생성, 있으면 오류.
replace (명령형): 완전 교체. --force 로 삭제 + 생성.

Rollout

kubectl rollout status deployment/web
kubectl rollout history deployment/web
kubectl rollout undo deployment/web
kubectl rollout undo deployment/web --to-revision=3
kubectl rollout restart deployment/web    # 모든 pod 재시작

# 상태
kubectl rollout pause deployment/web
kubectl rollout resume deployment/web

Scaling

kubectl scale deployment web --replicas=5
kubectl scale --replicas=3 -f deployment.yaml
kubectl autoscale deployment web --min=2 --max=10 --cpu-percent=80

Context / Namespace

Context 전환

kubectl config get-contexts
kubectl config current-context
kubectl config use-context prod-cluster

# 편의 도구
kubectx prod-cluster        # ahmetb/kubectx

Namespace 전환

kubectl config set-context --current --namespace=prod

# 편의 도구
kubens prod

# 특정 명령만
kubectl get pods -n prod

Output 형식

kubectl get pods -o wide             # 추가 정보
kubectl get pod <name> -o yaml       # YAML
kubectl get pod <name> -o json       # JSON
kubectl get pods -o name             # 이름만
kubectl get pods -o custom-columns=NAME:.metadata.name,NODE:.spec.nodeName

# JSONPath
kubectl get pods -o jsonpath='{.items[*].metadata.name}'
kubectl get pods -o jsonpath='{range .items[*]}{.metadata.name}{"\t"}{.status.phase}{"\n"}{end}'

# jq 조합
kubectl get pods -o json | jq '.items[] | select(.status.phase != "Running") | .metadata.name'

Label / Field selector

# Label selector
kubectl get pods -l app=web
kubectl get pods -l 'environment in (dev, staging)'
kubectl get pods -l '!experimental'

# Field selector
kubectl get pods --field-selector status.phase=Running
kubectl get pods --field-selector spec.nodeName=node1
kubectl get events --field-selector involvedObject.name=<pod>

# 조합
kubectl get pods -l app=web --field-selector status.phase=Failed -n prod

Logs

kubectl logs <pod>
kubectl logs <pod> -c <container>            # multi-container
kubectl logs <pod> --previous                 # 이전 컨테이너 (crashed)
kubectl logs <pod> --follow                   # 실시간
kubectl logs <pod> --tail=100
kubectl logs <pod> --since=1h
kubectl logs -l app=web --all-containers=true --tail=50
kubectl logs -l app=web --max-log-requests=20   # 최대 pod 수

Exec / Port-forward / Copy

# Exec
kubectl exec -it <pod> -- /bin/sh
kubectl exec -it <pod> -c <container> -- bash
kubectl exec <pod> -- ls /var/log

# Port-forward (로컬 -> pod)
kubectl port-forward pod/<pod> 8080:80
kubectl port-forward service/<svc> 5000:5000
kubectl port-forward deployment/web 3000:8080

# Copy 파일
kubectl cp <pod>:/etc/config.yaml ./local-config.yaml
kubectl cp ./local-file.tgz <ns>/<pod>:/tmp/

Debug

# Ephemeral container (K8s 1.25+)
kubectl debug -it <pod> --image=busybox --target=<container>
kubectl debug <pod> --copy-to=<pod>-debug --set-image=<container>=busybox

# Node debug
kubectl debug node/<node> -it --image=ubuntu

# 임시 pod (테스트)
kubectl run tmp --rm -it --image=nicolaka/netshoot -- /bin/bash

자세한 것은 [[k8s-debugging|Debugging]] 참조.

리소스 사용량

# metrics-server 필요
kubectl top nodes
kubectl top pods -n <ns>
kubectl top pod --containers -n <ns>
kubectl top pod --sort-by=cpu

Diff

kubectl diff -f deployment.yaml     # 적용 전 차이 확인
kubectl diff -k ./overlays/prod

Wait

kubectl wait --for=condition=Ready pod/<name> --timeout=60s
kubectl wait --for=condition=Available deployment/web --timeout=5m
kubectl wait --for=jsonpath='{.status.readyReplicas}'=3 deployment/web
kubectl wait --for=delete pod/<name>

CI/CD 스크립트에서 유용.

Cluster info

kubectl cluster-info
kubectl cluster-info dump   # 방대한 진단
kubectl api-resources        # 지원 리소스 목록
kubectl api-versions          # API 버전
kubectl version --short

컨텍스트 이해에 유용한 명령

# 지원 필드 확인
kubectl explain pod
kubectl explain pod.spec.containers
kubectl explain pod --recursive
kubectl explain pod.spec.containers.resources

# 이벤트
kubectl get events --sort-by=.metadata.creationTimestamp
kubectl events --for pod/<name>    # v1.31+

Plugins (krew)

Plugin manager. Extra 명령 설치.

# 설치
(
  set -x; cd "$(mktemp -d)" &&
  OS="$(uname | tr '[:upper:]' '[:lower:]')" &&
  ARCH="$(uname -m | sed -e 's/x86_64/amd64/')" &&
  KREW="krew-${OS}_${ARCH}" &&
  curl -fsSLO "https://github.com/kubernetes-sigs/krew/releases/latest/download/${KREW}.tar.gz" &&
  tar zxvf "${KREW}.tar.gz" &&
  ./"${KREW}" install krew
)

# PATH
export PATH="${KREW_ROOT:-$HOME/.krew}/bin:$PATH"

# 사용
kubectl krew install neat        # kubectl-neat (YAML 정리)
kubectl krew install ctx         # kubectl-ctx (context 전환)
kubectl krew install ns          # kubectl-ns (namespace 전환)
kubectl krew install tree        # kubectl-tree (owner reference tree)
kubectl krew install stern       # 로그 tail

자주 쓰는 플러그인

kubectx / kubens: context / namespace 전환
stern: 여러 pod 로그
kubectl-tree: owner 관계 표시
kubectl-neat: managedFields 등 노이즈 제거
kubectl-node-shell: 노드에 shell (SSH 없이)
kubectl-view-secret: secret decode
kubectl-lineage: 리소스 계보

Bash 완성

source <(kubectl completion bash)   # bash
source <(kubectl completion zsh)     # zsh

# alias
alias k=kubectl
complete -F __start_kubectl k

kubectl.kubernetes.io/last-applied-configuration

apply 는 이전에 적용한 config 를 annotation 에 저장. 3-way merge 에 사용. 손으로 수정하면 다음 apply 시 오해.

kubectl-neat 로 이 annotation 제거하고 저장:

kubectl get deployment web -o yaml | kubectl neat > clean.yaml

Dry run

kubectl apply -f deployment.yaml --dry-run=client    # 로컬만 검증
kubectl apply -f deployment.yaml --dry-run=server    # 서버 admission 통과

# YAML 생성만 (실제 적용 X)
kubectl create deployment web --image=nginx --dry-run=client -o yaml > deployment.yaml

Server-side apply

kubectl apply --server-side -f manifest.yaml

전통적 (client-side) apply 는 last-applied-configuration annotation 을 사용. Server-side apply 는 field ownership 를 서버가 관리. GitOps + operator 조합에 유리.

함정

[!WARNING] kubectl edit 남용. 클러스터 상태와 git 이 어긋남. GitOps 위반.

[!CAUTION] kubectl delete --all. Namespace 전체 삭제 확인 없이. 항상 --dry-run=client 로 먼저.

[!WARNING] kubectl 버전 skew. Client 와 cluster 버전 차이가 크면 명령 불일치. K8s 공식 지원은 ±1 버전.

[!IMPORTANT] kubeconfig 여러 개. KUBECONFIG=$HOME/.kube/config:$HOME/.kube/prod.config 처럼 병합.

[!CAUTION] kubectl apply 는 관리 field 만 갱신. 다른 도구 (operator) 가 만든 필드는 건드리지 않음. 예상 밖 결과 시 diff 확인.

Kubernetes

koa (김신건) — Tue, 07 Jul 2026 00:00:00 GMT

정의

Kubernetes (k8s) 는 컨테이너화된 애플리케이션의 배포, 스케일링, 관리 를 자동화하는 오픈소스 오케스트레이터입니다. Google 이 2014년 발표하고 2015년 v1.0 릴리스 이후 CNCF (Cloud Native Computing Foundation) 재단으로 이관되어 사실상 클라우드 네이티브 표준이 되었습니다.

이름은 그리스어 “조타수” 에서 왔고, 약어 k8s 는 “K” 와 “s” 사이에 8글자 (ubernete) 가 있다는 뜻입니다.

왜 Kubernetes 인가

컨테이너만으로는 부족한 것들을 채웁니다.

선언적 관리: kubectl apply -f deployment.yaml -> 원하는 상태 선언, k8s 가 실제 상태를 그것에 맞춤
자동 스케일링: HPA/VPA/CA 가 부하에 따라 파드/노드 조정
자가 치유: 실패한 컨테이너/노드를 자동 재시작/재배치
롤링 업데이트: 무중단 배포 (canary, blue/green)
서비스 디스커버리: DNS + Service 로 앱 간 연결 (IP 불변)
로드 밸런싱: 파드에 트래픽 분산
비밀 관리: Secret + KMS 로 API key, 비밀번호 저장
스토리지 오케스트레이션: CSI 로 PV/PVC 자동 프로비저닝
배치 처리: Job, CronJob

아키텍처 요약

flowchart LR
  U[사용자 / kubectl / CI] --> API[kube-apiserver]

  subgraph "Control Plane"
    API --> etcd[(etcd)]
    API --> SCH[kube-scheduler]
    API --> CM[kube-controller-manager]
  end

  subgraph "Worker Node"
    Kubelet --> Runtime[Container Runtime<br/>containerd / CRI-O]
    KP[kube-proxy] --> IPtables
    Runtime --> Pod1[Pod A]
    Runtime --> Pod2[Pod B]
  end

  API --> Kubelet
  API --> KP

[[k8s-architecture|Control Plane]]: kube-apiserver, etcd, kube-scheduler, kube-controller-manager, cloud-controller-manager
Worker Node: kubelet, kube-proxy, container runtime (CRI 호환), CNI 플러그인
네트워킹: 모든 Pod 이 유일한 IP, Pod 간 NAT 없이 통신 (Kubernetes network model)

자세한 것은 [[k8s-architecture|Kubernetes Architecture]] 참조.

핵심 리소스

리소스	역할	자세히
**[[k8s-pod	Pod]]**	1+ 컨테이너의 최소 배포 단위
**[[k8s-deployment	Deployment]]**	Stateless 앱 배포 (ReplicaSet 관리)
**[[k8s-statefulset	StatefulSet]]**	Stateful 앱 (DB, Kafka 등)
**[[k8s-daemonset	DaemonSet]]**	모든 노드에 1개씩 (로그, 모니터링)
**[[k8s-job-cronjob	Job / CronJob]]**	배치, 스케줄
**[[k8s-service	Service]]**	Pod 그룹의 안정된 endpoint
**[[k8s-ingress	Ingress]]**	HTTP(S) L7 라우팅
**[[k8s-configmap-secret	ConfigMap / Secret]]**	설정 / 비밀 값 주입
**[[k8s-persistent-volumes	PV / PVC]]**	영속 스토리지
**[[k8s-namespace	Namespace]]**	논리적 격리 단위
**[[k8s-labels-selectors	Labels / Selectors]]**	리소스 조직화
**[[k8s-rbac	RBAC]]**	권한 관리
**[[k8s-network-policy	NetworkPolicy]]**	Pod 간 네트워크 제어
**[[k8s-hpa-vpa	HPA / VPA]]**	자동 스케일링

선언적 워크플로

# 1. 원하는 상태를 YAML 로 선언
cat > deploy.yaml <<EOF
apiVersion: apps/v1
kind: Deployment
metadata:
  name: web
spec:
  replicas: 3
  selector:
    matchLabels: {app: web}
  template:
    metadata:
      labels: {app: web}
    spec:
      containers:
        - name: nginx
          image: nginx:1.27
          ports: [{containerPort: 80}]
EOF

# 2. apply -> 컨트롤러가 실제 상태를 그것에 맞춤
kubectl apply -f deploy.yaml

# 3. 확인
kubectl get pods -l app=web
kubectl describe deploy web
kubectl logs -l app=web

이 선언적 방식이 k8s 의 정수. 명령형 (kubectl run) 은 학습/디버깅용, 선언적 (kubectl apply) 은 프로덕션.

컴포넌트 상세 (한 줄 소개)

Control Plane

kube-apiserver: 모든 요청의 진입점. RESTful API. etcd 앞의 유일한 클라이언트.
etcd: 클러스터 상태 저장. Raft 합의 알고리즘. 백업 필수.
kube-scheduler: 새 Pod 을 어느 노드에 배치할지 결정.
kube-controller-manager: Deployment/ReplicaSet/Node 등 컨트롤러 실행.
cloud-controller-manager: 클라우드 특화 (LB, Volume, Route). AWS/GCP/Azure 마다 다름.

Node

kubelet: 노드의 Pod 을 관리. Container Runtime 과 CRI 로 통신.
kube-proxy: 노드의 Service iptables/IPVS 규칙 관리.
Container Runtime: containerd (기본), CRI-O. Docker 는 v1.24+ 제거.
CNI 플러그인: Pod 네트워킹. Calico, Cilium, Flannel, Weave 등.

관리형 vs 자체 운영

옵션	설명	언제
**[[aws-eks	EKS]]**	AWS 관리형
GKE	Google 관리형	GCP, 원조 답게 안정성 최상급
AKS	Azure 관리형	Azure 워크로드
Rancher / RKE2	오픈소스 배포판	온프렘
kubeadm	표준 부트스트랩 도구	커스텀 노드
k3s / k3d	경량 (< 100 MB)	엣지, 로컬 개발
minikube / kind	로컬 개발	개발자 노트북

결정 룰: 프로덕션이면 관리형 (EKS/GKE/AKS). 학습/특수 요구면 kubeadm 이나 k3s.

배포 관리 도구

[[helm|Helm]]: 패키지 매니저. Chart = k8s manifests 템플릿
[[k8s-kustomize|Kustomize]]: overlay 기반 manifest 조합. kubectl 내장
[[argocd|ArgoCD]] / Flux: GitOps CD
Terraform + kubectl_manifest: IaC

관측성

로그: kubectl logs, Fluent Bit -> Loki/Elasticsearch
메트릭: [[prometheus|Prometheus]] + Grafana
트레이스: [[opentelemetry|OpenTelemetry]] + Jaeger/Tempo
이벤트: kubectl get events

보안 계층

[[k8s-rbac|RBAC]]: 사용자/ServiceAccount 권한
[[k8s-network-policy|NetworkPolicy]]: L3/L4 Pod 간 네트워크
Pod Security Admission (PSA): privileged/baseline/restricted 정책 강제
[[k8s-admission-controllers|Admission Controllers]]: MutatingWebhook, ValidatingWebhook (OPA/Gatekeeper, Kyverno)
Secrets: KMS 암호화 at rest
imagePullPolicy + 이미지 서명 (Sigstore, Cosign)
CIS Benchmark: kube-bench 로 감사

Release Cadence

Kubernetes 는 약 3-4개월마다 마이너 릴리스. 각 마이너는 약 14개월 지원. 오래된 클러스터는 정기적 업그레이드 필수.

최근 하이라이트 (2024-2025):

v1.29 (2024-01): [[k8s-init-sidecar|SidecarContainers]] 기능 게이트 default enabled
v1.31 (2024-08): AppArmor 프로필 stable, VolumeAttributes API 등
v1.32 (2024-12): Dynamic Resource Allocation beta, memory manager stable
v1.33 (2025-04): SidecarContainers GA, Pod-level 리소스 옵션 등
v1.34+ (2025): 지속 진화

학습 로드맵

Pod, Deployment, Service 이해 -> 앱 배포 성공
ConfigMap, Secret -> 설정 관리
Ingress + Cert-Manager -> 외부 노출 + TLS
StatefulSet + PV -> 상태 있는 앱
HPA + 리소스 요청/한계 -> 스케일링
RBAC + NetworkPolicy -> 보안
Helm / Kustomize -> 패키지 관리
CRD + Operator -> 확장
관측 (Prom, OTel) -> 프로덕션 운영
GitOps (ArgoCD) -> 배포 자동화

함정

[!WARNING] latest 이미지 태그 사용 금지. Immutable digest 나 semver pin.

[!CAUTION] 리소스 요청/한계 안 걸면 노이지 이웃. Memory limit 없으면 OOM 도미노.

[!WARNING] etcd 백업 필수. 클러스터 완전 재구성 유일 수단.

[!IMPORTANT] 버전 스킵 업그레이드 금지. 마이너 하나씩만 (n → n+1). API 폐지 정보 확인.

[!CAUTION] kubectl edit 남용. 클러스터 상태와 git 이 어긋남. GitOps 로 통일.

[K8s] Helm: 패키지 매니저, chart, release, hook

koa (김신건) — Thu, 25 Jun 2026 00:00:00 GMT

정의

Helm = K8s 의 패키지 매니저. Chart (YAML 템플릿 + 메타데이터) → Release (cluster 에 배포된 인스턴스).

구조

my-chart/
├── Chart.yaml        # 메타데이터 (이름, 버전)
├── values.yaml       # 기본 설정값
├── templates/        # Go template YAML
│   ├── deployment.yaml
│   ├── service.yaml
│   ├── ingress.yaml
│   └── _helpers.tpl  # 공통 함수
└── charts/           # 의존 chart

Chart.yaml

apiVersion: v2
name: my-app
description: A web application
type: application
version: 0.1.0          # chart 버전
appVersion: "1.27.0"    # 앱 버전
dependencies:
  - name: postgresql
    version: "16.x.x"
    repository: https://charts.bitnami.com/bitnami

values.yaml

replicaCount: 3
image:
  repository: nginx
  tag: "1.27"
  pullPolicy: IfNotPresent
service:
  type: ClusterIP
  port: 80
ingress:
  enabled: true
  className: nginx
  hosts:
    - host: my-app.example.com
      paths: [{ path: /, pathType: Prefix }]
resources:
  limits: { cpu: 500m, memory: 512Mi }
  requests: { cpu: 100m, memory: 128Mi }

Template 예시

# templates/deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: {{ include "my-app.fullname" . }}
  labels: {{- include "my-app.labels" . | nindent 4 }}
spec:
  replicas: {{ .Values.replicaCount }}
  selector:
    matchLabels: {{- include "my-app.selectorLabels" . | nindent 6 }}
  template:
    metadata:
      labels: {{- include "my-app.selectorLabels" . | nindent 8 }}
    spec:
      containers:
        - name: {{ .Chart.Name }}
          image: "{{ .Values.image.repository }}:{{ .Values.image.tag }}"
          ports:
            - containerPort: {{ .Values.service.port }}
          resources: {{- toYaml .Values.resources | nindent 12 }}

흔한 명령

helm install my-release ./my-chart
helm install my-release oci://registry-1.docker.io/bitnamicharts/postgresql
helm upgrade my-release ./my-chart --set image.tag=1.28
helm rollback my-release 2          # 2번 revision 으로
helm uninstall my-release
helm list
helm template ./my-chart            # 렌더만 (apply X)
helm lint ./my-chart
helm package ./my-chart             # tgz 패키지
helm repo add bitnami https://charts.bitnami.com/bitnami
helm search repo postgresql
helm show values bitnami/postgresql

Release 의 lifecycle

stateDiagram-v2
    [*] --> Pending: install
    Pending --> Deployed: 성공
    Pending --> Failed: 실패
    Deployed --> Pending: upgrade
    Pending --> Superseded: 옛 revision
    Deployed --> Uninstalling: uninstall
    Uninstalling --> [*]

helm history my-release    # 모든 revision
helm rollback my-release 3

Hooks

Hook	시점
`pre-install`	install 직전
`post-install`	install 직후
`pre-upgrade` / `post-upgrade`	upgrade
`pre-delete` / `post-delete`	uninstall
`pre-rollback` / `post-rollback`	rollback
`test`	`helm test` 명령

metadata:
  annotations:
    "helm.sh/hook": pre-install
    "helm.sh/hook-weight": "0"
    "helm.sh/hook-delete-policy": before-hook-creation,hook-succeeded

DB migration, secret pre-creation 등에 활용.

Helm vs Kustomize

항목	Helm	Kustomize
메커니즘	Go template + values	overlay (patch)
패키지 관리	예 (repo, chart)	없음
변수 표현력	강	약
학습 곡선	높음	낮음
배포 도구	helm CLI	kubectl 내장 (`kubectl apply -k`)
적합	3rd-party 도구 설치	자기 앱 환경별

자주 Helm chart + Kustomize overlay 조합.

Helmfile (multi-release 관리)

# helmfile.yaml
releases:
  - name: postgres
    namespace: data
    chart: bitnami/postgresql
    version: 16.x.x
    values:
      - environments/prod/postgres.yaml
  - name: redis
    namespace: data
    chart: bitnami/redis
    values:
      - environments/prod/redis.yaml

helmfile sync

흔한 함정

[!WARNING]

values.yaml 의 secret 평문 = git 에 secret 노출. SOPS / Sealed Secrets.

template 안 디버깅 어려움 = helm template . --debug 로 렌더 결과 확인.

chart upgrade 시 의도 외 변경 = --reset-values vs --reuse-values 명시.

hook 의 cleanup 정책 = hook resource 가 cluster 에 영구 남음 가능. hook-delete-policy 명시.

OCI Registry (Helm 3.8+)

차트를 Docker Hub / ECR / GHCR 에 OCI Artifact 로 저장:

# Bitnami 공식 OCI 설치 예시
helm install my-release oci://registry-1.docker.io/bitnamicharts/postgresql

# 직접 패키지 + Push
helm package ./my-chart                     # my-app-0.1.0.tgz 생성
helm push my-app-0.1.0.tgz oci://ghcr.io/my-org/charts

# Pull + Install
helm install my-release oci://ghcr.io/my-org/charts/my-app --version 0.1.0

OCI 는 helm repo add 불필요. 컨테이너 레지스트리가 그대로 차트 저장소.

시크릿 관리

SOPS + Helm Secrets Plugin

helm plugin install https://github.com/jkroepke/helm-secrets

# SOPS 로 암호화된 values 파일로 배포
helm secrets upgrade my-release ./my-chart \
  -f values.yaml \
  -f secrets.enc.yaml

External Secrets Operator (권장)

apiVersion: external-secrets.io/v1beta1
kind: ExternalSecret
metadata:
  name: my-app-secret
spec:
  refreshInterval: 5m
  secretStoreRef:
    name: aws-secrets-manager
    kind: ClusterSecretStore
  target:
    name: my-app-secret
  data:
    - secretKey: db_password
      remoteRef:
        key: prod/my-app
        property: db_password

[!WARNING] values.yaml 에 평문 시크릿 절대 금지. SOPS 또는 External Secrets Operator 로 분리.

CI/CD 통합

flowchart LR
    Dev["개발자 Push"] --> CI["CI 파이프라인"]
    CI -->|"helm lint + template"| Valid["검증"]
    Valid -->|staging| Stage["helm upgrade staging"]
    Stage -->|"수동 승인"| Prod["helm upgrade prod"]
    Prod -->|실패| Rollback["helm rollback"]

ArgoCD 를 통한 GitOps 패턴은 [[argocd]] 참조.

Helm 3 vs Helm 2

항목	Helm 2	Helm 3
Tiller	클러스터 서버 컴포넌트	제거 (클라이언트만)
보안	Tiller RBAC 복잡	kubeconfig 권한 직접 사용
Release 저장	ConfigMap	Secret (기본)
3-way merge	미지원	지원
OCI 지원	없음	지원 (3.8+)
Namespace	글로벌 릴리스	release 별 namespace

Helm 2 는 2022 년 EOL. 신규 구축은 Helm 3 만 사용.

[K8s] Ingress: L7 라우팅, TLS termination, Gateway API

koa (김신건) — Thu, 25 Jun 2026 00:00:00 GMT

정의

Ingress = 클러스터 외부 HTTP/HTTPS 트래픽 → 내부 Service 라우팅. L7 LB 역할. Service 의 LoadBalancer 다수 대안.

[!IMPORTANT] Ingress 오브젝트는 표준, 컨트롤러는 별도. nginx, Traefik, Envoy, AWS Load Balancer Controller 등 직접 설치 필요.

아키텍처

flowchart LR
    Internet --> ALB["ALB / nginx<br/>(IngressController)"]
    ALB -->|"Host: api.example.com<br/>Path: /v1/*"| Sv1[Service: api-v1]
    ALB -->|"Host: api.example.com<br/>Path: /v2/*"| Sv2[Service: api-v2]
    ALB -->|"Host: web.example.com"| Sv3[Service: web]
    Sv1 --> P1[Pods]
    Sv2 --> P2[Pods]
    Sv3 --> P3[Pods]

YAML 예시

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: web
  annotations:
    kubernetes.io/ingress.class: nginx
    cert-manager.io/cluster-issuer: letsencrypt-prod
    nginx.ingress.kubernetes.io/rewrite-target: /
spec:
  tls:
    - hosts: [api.example.com]
      secretName: api-tls
  rules:
    - host: api.example.com
      http:
        paths:
          - path: /v1
            pathType: Prefix
            backend:
              service:
                name: api-v1
                port: { number: 80 }
          - path: /v2
            pathType: Prefix
            backend:
              service:
                name: api-v2
                port: { number: 80 }

Path Type

pathType	동작
`Exact`	정확 일치
`Prefix`	prefix 일치 (`/api` matches `/api/...`)
`ImplementationSpecific`	컨트롤러 정의

Ingress Controller 비교

Controller	강점
ingress-nginx	표준, 모든 기능, 무거움
Traefik	자동 cert (Let’s Encrypt), 동적
Envoy / Contour	L7 advanced, gRPC, service mesh 친화
AWS Load Balancer Controller	ALB / NLB 직접
HAProxy Ingress	매우 빠름
Istio Ingress Gateway	service mesh 통합

TLS Termination

flowchart LR
    Client -->|HTTPS| Ingress
    Ingress -->|"HTTP (cluster-internal)"| Service
    Cert["cert-manager<br/>(Let's Encrypt ACME)"] -.자동 갱신.-> Ingress

cert-manager 가 Let’s Encrypt 인증서 자동 발급 / 갱신. 거의 모든 클러스터 표준.

Rewrite / Redirect

rewrite-target 으로 업스트림에 전달되는 경로를 변환:

metadata:
  annotations:
    nginx.ingress.kubernetes.io/rewrite-target: /$2
spec:
  rules:
    - host: example.com
      http:
        paths:
          - path: /api/v1(/|$)(.*)
            pathType: ImplementationSpecific
            backend:
              service: { name: api-v1, port: { number: 80 } }

/api/v1/users → /users 로 upstream 전달. 캡처 그룹 $1, $2 사용.

영구 / 임시 리다이렉트:

annotations:
  nginx.ingress.kubernetes.io/permanent-redirect: "https://new.example.com"
  nginx.ingress.kubernetes.io/permanent-redirect-code: "301"
  # 임시 302: permanent-redirect 없이 app-root 사용
  nginx.ingress.kubernetes.io/app-root: "/app"

Rate Limiting

IP 기준 속도 제한:

annotations:
  nginx.ingress.kubernetes.io/limit-rps: "10"            # 초당 요청
  nginx.ingress.kubernetes.io/limit-rpm: "100"            # 분당 요청
  nginx.ingress.kubernetes.io/limit-connections: "20"    # 동시 연결
  nginx.ingress.kubernetes.io/limit-burst-multiplier: "5"
  nginx.ingress.kubernetes.io/limit-whitelist: "10.0.0.0/8"

어노테이션	의미
`limit-rps`	초당 허용 요청 (IP 기반)
`limit-rpm`	분당 허용 요청
`limit-connections`	동시 연결 수 제한
`limit-burst-multiplier`	버스트 배수 (기본 5)

[!IMPORTANT] Rate limit 은 IngressController 파드 기준. 파드 3개면 실제 한도 = 3 × limit. 정밀한 제어는 API Gateway 레이어 (Kong, AWS API Gateway) 로.

Sticky Session / 세션 어피니티

stateful 앱 (파일 업로드 진행 상태, 세션 기반 인증 등) 에서 동일 파드로 고정:

annotations:
  nginx.ingress.kubernetes.io/affinity: "cookie"
  nginx.ingress.kubernetes.io/session-cookie-name: "INGRESSCOOKIE"
  nginx.ingress.kubernetes.io/session-cookie-expires: "172800"
  nginx.ingress.kubernetes.io/session-cookie-max-age: "172800"
  nginx.ingress.kubernetes.io/session-cookie-path: "/"

[!WARNING] Sticky Session + HPA 조합: 신규 파드는 기존 쿠키가 없어 트래픽 불균등 발생. 가능하면 stateless + Redis 세션 공유 설계 권장.

Observability

ingress-nginx Prometheus 메트릭 (Helm values):

controller:
  metrics:
    enabled: true
    serviceMonitor:
      enabled: true   # kube-prometheus-stack ServiceMonitor CRD

메트릭	의미
`nginx_ingress_controller_requests`	요청 수 (status, ingress 별)
`nginx_ingress_controller_request_duration_seconds`	레이턴시 분포
`nginx_ingress_controller_connect_duration_seconds`	upstream 연결 시간
`nginx_ingress_controller_ssl_expire_time_seconds`	TLS 인증서 만료 시각

Grafana 에서 rate(nginx_ingress_controller_requests[5m]) 로 per-ingress 처리량 실시간 모니터링.

Gateway API (Ingress 의 차세대)

apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: prod-gateway
spec:
  gatewayClassName: nginx
  listeners:
    - name: https
      port: 443
      protocol: HTTPS
      tls:
        certificateRefs:
          - name: prod-tls
---
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: api
spec:
  parentRefs: [{ name: prod-gateway }]
  hostnames: [api.example.com]
  rules:
    - matches:
        - path: { type: PathPrefix, value: /v1 }
      backendRefs:
        - name: api-v1
          port: 80

Gateway API 리소스 계층

리소스	관리 주체	역할
`GatewayClass`	인프라 팀	구현체 선택 (nginx, envoy 등), ClusterScoped
`Gateway`	플랫폼 팀	포트 / 프로토콜 / TLS 정책
`HTTPRoute`	앱 팀	호스트 / 경로 / 헤더 기반 매칭, backendRef
`GRPCRoute`	앱 팀	gRPC method / service 매칭
`TCPRoute`	플랫폼 팀	L4 TCP 포워딩
`TLSRoute`	플랫폼 팀	TLS SNI 기반 라우팅

Ingress 와 달리 역할별 리소스 분리로 RBAC 제어가 세밀해짐. 각 팀이 독립적으로 배포 가능.

Ingress vs Gateway API

항목	Ingress	Gateway API
출시	2015	2021+
표현력	제한적 (annotation 의존)	풍부 (HTTPRoute, TCPRoute, TLSRoute)
역할 분리	단일	GatewayClass / Gateway / Route 분리
트래픽 정책	annotation	정식 필드
상태	stable	beta → GA (2026 대다수)

[!IMPORTANT] 2026 시점 Gateway API 가 점점 표준. 신규 클러스터는 Gateway API 추천.

흔한 패턴: Canary

metadata:
  annotations:
    nginx.ingress.kubernetes.io/canary: "true"
    nginx.ingress.kubernetes.io/canary-weight: "10"   # 10% 만 새 버전

또는 헤더 기반:

metadata:
  annotations:
    nginx.ingress.kubernetes.io/canary-by-header: "X-Canary"
    nginx.ingress.kubernetes.io/canary-by-header-value: "always"

흔한 함정

[!WARNING]

IngressClass 누락 = 다중 컨트롤러 환경에서 동작 안 함. spec.ingressClassName 명시.

TLS secret namespace 다름 = Ingress 와 같은 namespace 의 secret 만 사용.

cert-manager rate limit = Let’s Encrypt staging 으로 테스트 후 production.

Ingress + WebSocket = nginx.ingress.kubernetes.io/proxy-read-timeout, proxy-send-timeout 늘려야 idle close 회피.

[K8s] Pod: 컨테이너의 최소 단위, sidecar, lifecycle

koa (김신건) — Thu, 25 Jun 2026 00:00:00 GMT

정의

Pod = K8s 의 가장 작은 배포 단위. 1개 이상의 컨테이너 + 공유 네트워크 + 공유 스토리지.

[!IMPORTANT] Pod 는 컨테이너의 wrapping 이 아니다. 서로 강하게 결합한 컨테이너들의 묶음 (메인 + sidecar). 단일 컨테이너 pod 가 가장 흔함.

구조

flowchart TB
    subgraph Pod
        Pause["pause container<br/>(네트워크 namespace)"]
        Main[Main container<br/>nginx]
        Side[Sidecar container<br/>logger]
        Init["Init container<br/>(완료 후 종료)"]
    end
    Pod --> Net[공유 IP + 포트]
    Pod --> Vol[공유 volume]

라이프사이클

stateDiagram-v2
    [*] --> Pending: scheduled
    Pending --> ContainerCreating: pull image
    ContainerCreating --> Running: init + main start
    Running --> Succeeded: 모든 컨테이너 0 exit
    Running --> Failed: 컨테이너 fail
    Running --> Terminating: delete
    Terminating --> [*]

Phase	의미
Pending	스케줄링 대기 / 이미지 pull
Running	모든 컨테이너 시작
Succeeded	모든 컨테이너 성공 종료
Failed	컨테이너 실패
Unknown	API server 통신 실패

YAML 예시

apiVersion: v1
kind: Pod
metadata:
  name: web
  labels:
    app: web
spec:
  initContainers:
    - name: setup
      image: busybox
      command: ['sh', '-c', 'echo init done > /shared/ready']
      volumeMounts:
        - name: shared
          mountPath: /shared
  containers:
    - name: nginx
      image: nginx:1.27
      ports:
        - containerPort: 80
      resources:
        requests: { cpu: 100m, memory: 128Mi }
        limits:   { cpu: 500m, memory: 512Mi }
      livenessProbe:
        httpGet: { path: /, port: 80 }
        initialDelaySeconds: 10
      readinessProbe:
        httpGet: { path: /ready, port: 80 }
      volumeMounts:
        - name: shared
          mountPath: /var/data
    - name: log-sidecar
      image: fluent-bit:3
      volumeMounts:
        - name: shared
          mountPath: /var/log/source
  volumes:
    - name: shared
      emptyDir: {}

Probes (3종)

Probe	목적	실패 시
Startup	느린 시작 보호	죽인 후 재시작
Liveness	살아있나	컨테이너 재시작
Readiness	트래픽 받을 준비	Service endpoint 에서 제외

flowchart LR
    Start[컨테이너 시작] --> Startup[Startup probe 통과까지<br/>liveness 무시]
    Startup --> Live[Liveness 시작]
    Startup --> Ready[Readiness 시작]
    Live --|실패|--> Restart[컨테이너 재시작]
    Ready --|실패|--> RemoveFromLB[Service 에서 제외]
    Ready --|성공|--> AddToLB[Service 에 추가]

[!IMPORTANT] Probe 가 없으면 K8s 가 언제 트래픽 보낼지 모름 → 첫 요청 실패. readiness 는 거의 필수.

Sidecar Pattern

flowchart LR
    Main[Main: app] -.공유 volume.-> Log
    Main -.공유 network.-> Proxy
    Log[Sidecar: log shipper<br/>fluent-bit]
    Proxy[Sidecar: envoy<br/>mTLS, retry]

흔한 sidecar:

Log shipper (fluent-bit, vector)
Service mesh proxy (envoy, linkerd)
Secret rotation (vault-agent)
TLS termination (nginx)
Metrics adapter (statsd → prometheus)

Init Container

sequenceDiagram
    Scheduler->>Pod: start
    Pod->>Init1: init-1 실행
    Init1-->>Pod: exit 0
    Pod->>Init2: init-2 실행
    Init2-->>Pod: exit 0
    Pod->>Main: main + sidecars 시작

용도:

DB schema migration
설정 파일 생성
TLS cert pre-fetch
데이터 download

Resource: Requests / Limits

flowchart LR
    Req[requests<br/>= 최소 보장] --> Schedule[스케줄링 결정 기준]
    Lim[limits<br/>= 최대 한도] --> Throttle["CPU: throttle<br/>Memory: OOM kill"]

[!CAUTION] Memory limit 초과 = OOM kill (즉시). CPU limit 초과 = throttle (느려짐). memory 는 보수적으로.

Pod 의 변경 불가성

Pod spec 의 대부분 필드 = immutable
변경하려면 → 새 Pod 생성, 옛 Pod 삭제

→ 직접 Pod 만들 일 거의 없음. Deployment / StatefulSet / DaemonSet 이 자동 관리.

흔한 함정

[!WARNING]

Probe 없음 = 트래픽 일부 실패. readiness 필수.

Memory limit 너무 작음 = OOM kill 반복. Resource 측정 후 결정.

Sidecar 가 main 보다 늦게 종료 = pre-stop hook + grace period 부족 → log 누락.

Init container 가 느림 = pod 시작 자체 지연.

Pod 보안 컨텍스트

spec:
  securityContext:
    runAsNonRoot: true
    runAsUser: 1000
    fsGroup: 2000
  containers:
    - name: app
      securityContext:
        allowPrivilegeEscalation: false
        readOnlyRootFilesystem: true
        capabilities:
          drop: ["ALL"]

설정	의미
`runAsNonRoot`	root 로 실행 금지
`runAsUser`	특정 UID 로 실행
`readOnlyRootFilesystem`	루트 파일시스템 읽기 전용
`allowPrivilegeEscalation`	권한 상승 금지
`capabilities.drop`	Linux capability 제거

[!IMPORTANT] CIS Kubernetes Benchmark 기준: runAsNonRoot: true, readOnlyRootFilesystem: true, allowPrivilegeEscalation: false 는 프로덕션 기본 설정.

Pod Disruption Budget

apiVersion: policy/v1
kind: PodDisruptionBudget
metadata:
  name: web-pdb
spec:
  minAvailable: 2
  selector:
    matchLabels:
      app: web

노드 드레인, 업그레이드 시 최소 가용 Pod 수 보장.
minAvailable 또는 maxUnavailable 중 하나 선택.
Deployment 와 함께 사용해야 의미 있음.

Grace Period 와 종료 순서

sequenceDiagram
    K8s->>Pod: SIGTERM 전송
    Pod->>App: SIGTERM
    Note over Pod,App: terminationGracePeriodSeconds 대기, 기본 30초
    App-->>Pod: 정상 종료
    Pod-->>K8s: 종료 완료

terminationGracePeriodSeconds 기본값: 30초.
앱이 SIGTERM 을 받으면 graceful shutdown 처리 후 종료.
시간 내 종료 안 되면 SIGKILL 강제 종료.
preStop hook 으로 종료 전 작업 가능.

lifecycle:
  preStop:
    exec:
      command: ["/bin/sh", "-c", "sleep 5"]

실무 체크리스트

flowchart TD
    Start["Pod 배포 전 확인"] --> R["resources 설정 여부"]
    R -->|미설정| FR["requests/limits 추가"]
    R -->|설정됨| P["readinessProbe 여부"]
    P -->|없음| FP["readinessProbe 추가"]
    P -->|있음| S["securityContext 여부"]
    S -->|없음| FS["runAsNonRoot 등 추가"]
    S -->|있음| OK["배포 OK"]

항목	이유
`resources.requests/limits`	스케줄링 + OOM 방지
`readinessProbe`	트래픽 라우팅 정확성
`livenessProbe`	데드락 자동 복구
`securityContext`	최소 권한 원칙
`PodDisruptionBudget`	롤링 업데이트 안전성

멀티 컨테이너 패턴 요약

패턴	구성	용도
Sidecar	main + helper	로그, 프록시, 인증
Ambassador	main + proxy	외부 서비스 추상화
Adapter	main + transformer	출력 형식 변환
Init	init 완료 후 종료 + main	사전 준비 작업

Pod QoS Classes

K8s 는 resource 설정에 따라 Pod 에 세 가지 QoS 클래스 를 자동으로 부여한다. 노드 리소스 부족 시 eviction 우선순위에 영향을 준다.

QoS Class	조건	특징
Guaranteed	모든 컨테이너의 requests == limits	OOM 에서 마지막 희생
Burstable	일부 컨테이너에 requests < limits	중간 우선순위
BestEffort	requests / limits 모두 미지정	리소스 압박 시 첫 희생

flowchart TD
    Q{"requests, limits 설정?"}
    Q -->|"requests == limits (모든 컨테이너)"| G[Guaranteed]
    Q -->|"requests 있지만 limits 다름"| B[Burstable]
    Q -->|"모두 미지정"| BE[BestEffort]
    G --> E1["OOM 발생 시: 마지막으로 종료"]
    B --> E2["OOM 발생 시: 중간 순위"]
    BE --> E3["OOM 발생 시: 첫 번째로 종료"]

[!TIP] 운영 환경 목표: Guaranteed 클래스. requests 와 limits 를 동일하게 설정하면 스케줄러 예측이 쉽고 OOM kill 위험이 줄어든다.

[K8s] Service: ClusterIP / NodePort / LoadBalancer / ExternalName

koa (김신건) — Thu, 25 Jun 2026 00:00:00 GMT

정의

Service = Pod 집합에 안정 가상 IP + DNS 부여. Pod 가 죽고 다시 만들어져도 Service IP 는 그대로.

{}

4가지 타입

flowchart TB
    Q{Service 종류}
    Q --> CIP["ClusterIP<br/>(기본)<br/>클러스터 안에서만"]
    Q --> NP[NodePort<br/>각 노드의 포트 노출]
    Q --> LB[LoadBalancer<br/>클라우드 LB 자동 생성]
    Q --> EN[ExternalName<br/>외부 DNS 별칭]

1. ClusterIP (기본)

apiVersion: v1
kind: Service
metadata:
  name: api
spec:
  type: ClusterIP
  selector: { app: api }
  ports:
    - port: 80
      targetPort: 8080

클러스터 안에서만 접근.
다른 pod 가 http://api:80 로 호출.
DNS: <service>.<namespace>.svc.cluster.local.

2. NodePort

spec:
  type: NodePort
  ports:
    - port: 80
      targetPort: 8080
      nodePort: 30080   # 옵션

모든 노드의 30000-32767 포트 에서 접근.
http://<any-node>:30080.
보통 개발용. 프로덕션은 LoadBalancer 또는 Ingress.

3. LoadBalancer

spec:
  type: LoadBalancer
  selector: { app: api }
  ports: [{ port: 80, targetPort: 8080 }]

클라우드 (AWS, GCP) 가 자동으로 LB 생성 + 외부 IP.
AWS = ALB / NLB.
Service 당 LB 하나 → 많으면 비싸다. Ingress 가 대안.

4. ExternalName

spec:
  type: ExternalName
  externalName: api.external.com

DNS CNAME 처럼 외부 호스트 별칭.
기존 외부 service 와 통합 용.

Headless Service

spec:
  clusterIP: None    # ← Headless

Service IP 없음.
DNS 가 모든 pod IP 직접 반환.
StatefulSet 의 peer discovery 에 필수.

DNS 와 Service Discovery

nslookup api
→ api.default.svc.cluster.local
→ 10.96.0.42 (ClusterIP)

nslookup api-headless
→ 10.244.0.5  (pod-1)
→ 10.244.0.6  (pod-2)
→ 10.244.0.7  (pod-3)

내부 동작: kube-proxy

flowchart LR
    Client[Client pod] -->|Service IP| KP["kube-proxy<br/>(node)"]
    KP -->|iptables / IPVS rule| P1[pod 1]
    KP -->|iptables / IPVS rule| P2[pod 2]
    KP -->|iptables / IPVS rule| P3[pod 3]

모드	특징
`iptables` (기본)	nat 규칙. 수천 Service 까지 OK
`IPVS`	더 빠름, 더 큰 규모
`nftables` (1.31+)	iptables 대체, 더 빠름

트래픽 분배

Service → endpoints (Pod IP 목록)
kube-proxy → random pick (iptables) 또는 알고리즘 (IPVS)

L4 round-robin. 세션 sticky 가 필요하면 service.spec.sessionAffinity: ClientIP.

Service 와 Endpoints

kubectl get endpoints api
NAME   ENDPOINTS                                AGE
api    10.244.0.5:8080,10.244.0.6:8080,...      5m

Service = 추상.
Endpoints = 실제 pod IP.
Pod 의 readiness 가 OK 인 것만 endpoint 에 포함.

EndpointSlice (1.21+)

큰 클러스터에서 Endpoints 의 확장. 1000+ pod 의 Service 에 효율적.

흔한 함정

[!WARNING]

LoadBalancer 남발 = AWS 1 LB = 시간당 비용 + LCU. Ingress 로 통합 권장.

Service IP 변경 시도 = ClusterIP 는 immutable. 변경하려면 삭제 + 재생성.

Headless 잘못 사용 = LB 동작 없음. StatefulSet 만.

selector label 오타 = endpoints 0개. Service 동작 안 함.

Multi-Port Service

한 Service 에서 여러 포트 노출 시 이름 필수.

spec:
  type: ClusterIP
  selector: { app: api }
  ports:
    - name: http
      port: 80
      targetPort: 8080
    - name: grpc
      port: 9090
      targetPort: 9090
    - name: metrics
      port: 9100
      targetPort: 9100

Port Naming 컨벤션

Ingress, Istio, Prometheus 가 이름으로 프로토콜 자동 감지.

Port 이름	프로토콜
`http`	HTTP/1.1
`https`	HTTPS/TLS
`grpc`	gRPC
`http2`	HTTP/2 평문
`metrics`	Prometheus scrape

Session Affinity 상세

spec:
  sessionAffinity: ClientIP
  sessionAffinityConfig:
    clientIP:
      timeoutSeconds: 3600

같은 ClientIP 의 요청을 동일 Pod 으로 고정. None (기본) = 무작위. L7 쿠키 sticky 는 Ingress 레벨.

External Traffic Policy

외부 트래픽 (NodePort / LoadBalancer) 의 라우팅 전략.

spec:
  type: LoadBalancer
  externalTrafficPolicy: Local

Policy	동작	트레이드오프
`Cluster`	모든 노드 경유, SNAT	균등 분배, 클라이언트 IP 유실
`Local`	같은 노드 Pod 만	소스 IP 보존, Pod 없는 노드에서 드롭

Service + NetworkPolicy 연계

flowchart LR
    FE["frontend Pod"] -->|"port 80"| SVC["api Service"]
    SVC --> API["api Pod"]
    NP["NetworkPolicy"] -.->|"허용 제어"| API

NetworkPolicy 는 Service IP 가 아니라 최종 Pod IP 에 적용. Service 는 변환 중간점.

apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
metadata:
  name: api-allow-frontend
spec:
  podSelector:
    matchLabels:
      app: api
  ingress:
    - from:
        - podSelector:
            matchLabels:
              app: frontend
      ports:
        - port: 8080

Service vs Ingress 비교

flowchart TB
    Ext["외부 트래픽"]
    Ext -->|"LoadBalancer (L4)"| SVC["Service (LB)"]
    Ext -->|"HTTP (L7)"| ING["Ingress Controller"]
    ING -->|"host/path 라우팅"| S1["Service A"]
    ING --> S2["Service B"]
    SVC --> P1["Pod"]

항목	Service LoadBalancer	Ingress
레이어	L4	L7
LB 개수	Service 당 1개	1개로 N 서비스
비용	높음	낮음
기능	포트 포워딩	호스트/경로 라우팅, TLS, 재작성

트러블슈팅

# Endpoint 확인 (0 이면 selector 불일치)
kubectl get endpoints <svc-name>

# Pod label 확인
kubectl get pods --show-labels -l app=<name>

# Service 상세 (Selector, Port, Endpoints 포함)
kubectl describe service <svc-name>

# DNS 조회 (파드 내부에서)
kubectl exec -it <pod> -- nslookup <svc>.<ns>.svc.cluster.local

# ClusterIP 직접 접근 테스트
kubectl exec -it <pod> -- curl http://<cluster-ip>:<port>

[!TIP] Endpoints 가 0 이면 selector label 불일치. kubectl describe service 의 Selector 와 Pod 의 실제 label 을 비교.

김신건의 로그 - 위키 / kubernetes

[K8s] HPA / VPA / KEDA: 자동 확장

정의

3가지 스케일링

HPA (Horizontal Pod Autoscaler)

HPA 알고리즘

HPA 제어 루프

Custom Metrics: Prometheus Adapter

VPA (Vertical Pod Autoscaler)

VPA 모드 비교

KEDA (Kubernetes Event-Driven Autoscaling)

KEDA: Prometheus 기반 스케일링

Cluster Autoscaler / Karpenter

HPA vs KEDA 선택 기준

흔한 함정

관련 위키

[K8s] Job / CronJob: 일회성 + 스케줄 작업

정의

Job

흐름

Job 생명주기 상세

병렬 실행 (parallelism / completions)

activeDeadlineSeconds

Job Suspend (1.24+)

Failure Policy (1.26+)

작업 큐 패턴

Indexed Job (1.24+)

CronJob

concurrencyPolicy

CronJob 누락 스케줄 처리

Cron 식

Job vs Deployment 선택 기준

흔한 함정

관련 위키

[K8s] StatefulSet: 순서 보장, 고유 ID, 영속 스토리지

정의

사용처

YAML

Pod 이름과 DNS

Peer Discovery 패턴

시작 / 종료 순서

initContainers로 초기화

PVC per Pod (영속 스토리지)

PVC 생명주기 관리

Update 전략

Canary Update (partition 활용)

운영 패턴: Operator

Primary 장애 복구 흐름

흔한 함정

관련 위키

[K8s] ConfigMap & Secret: 설정과 비밀의 분리

정의

ConfigMap

ConfigMap 생성

CLI 생성

Secret

Secret 생성 (YAML)

Secret 타입

Pod 에서 사용

1. 환경 변수 (개별)

2. 환경 변수 (전체 import)

3. Volume mount (파일로 마운트)

env vs volume mount 비교

Immutable ConfigMap / Secret

Secret 관리: git 에 평문 절대 금지

1. Sealed Secrets (Bitnami)

2. External Secrets Operator (ESO)

3. SOPS (Secrets OPerationS)

4. 관리 방식 비교

etcd Encryption at Rest

흔한 함정

관련 위키

[K8s] DaemonSet: 모든 노드에 한 pod

정의

언제 쓰이나

동작 원리

기본 YAML: fluent-bit 로그 수집

node-exporter: Prometheus 메트릭 수집

Tolerations: 특정 노드 포함/제외

Node Selector: 특정 노드만 대상

1. `latest` 이미지 금지