🚀 Kubernetes webhook 운영 - 개발자 경험은 살리고, 리스크는 줄이는 사례 공유

[cloudbro-radar]

Admission Controller를 이용하여, Cluster 및 Pod 등 다양한 영역에 문제가 되는 것을 사전에 막고자하는 경험의 글을 공유합니다. [출처] https://medium.com/@sridharcloud/kubernetes-admission-controllers-how-20-webhooks-saved-my-production-cluster-104d930f87dc

Kubernetes Admission Webhook 운영에 대해서

1) 개요

• 목적: Kubernetes 클러스터의 안정성·보안·컴플라이언스를 강화하기 위해 Admission Webhook을 체계적으로 도입·운영하는 표준을 제시한다.
• 적용 대상: 플랫폼 엔지니어링 팀, SRE, 보안팀, 각 서비스 팀의 배포 파이프라인 담당자.
• 범위: OPA Gatekeeper, cert-manager, Datadog(모니터링 주입), Azure Policy/Workload Identity, Linkerd(Service Mesh) 등 주요 Webhook과 정책 롤아웃·최적화 절차.

---

2) 배경 및 문제 정의

• 팀 분산(6개 팀/30명), Kubernetes 숙련도 편차, 문서·교육·리마인더 중심의 사후적 통제 한계 발생.
• 대표 사고 유형:
  • 리소스 고갈: Memory limit 미설정 Pod로 인한 Node NotReady.
  • 운영 누락: 라벨/어노테이션 미흡으로 모니터링 사각지대 발생.
  • 보안/컴플라이언스: 조직 정책 불일치, 수동 점검 비용 과다.
  • 인증서 만료: 수동 관리로 갱신 누락 → 서비스 중단.
• 핵심 인식: “사람이 47개 규칙을 기억”하는 접근에서 “Admission 단계 자동 집행”으로 전환 필요.

---

3) 목표

1. 사전 차단: 잘못된 설정이 클러스터에 반영되기 전 Admission 단계에서 자동 검증/수정.
2. 표준화: 팀·서비스 간 운영 기준 일관성 확보.
3. 가시성·신뢰성: 모니터링/보안/인증서 등 기본 품질 속성의 자동 부여.
4. 개발 생산성 유지: 점진적 롤아웃과 예외·튜닝으로 마찰 최소화.
5. 성능 보전: Webhook 증가에 따른 배포 지연을 허용 가능한 범위(3~4초)로 관리.

---

4) 도입 솔루션 개요

4.1 OPA Gatekeeper (Policy as Code)

• 역할: Validating(검증) 및 제한과 기준(Constraint)을 선언적으로 집행.
• 핵심 정책: Resource limits, Security Context, Network Policy 등.
• 교훈: 과도한 일괄 강제는 서비스 메시 주입 등과 충돌 가능 → 단순 시작 후 점진 강화.

4.2 cert-manager (Certificate Lifecycle)

• 역할: Certificate 리소스 검증/변환, 자동 갱신(Webhook)으로 만료 위험 제거.
• 효과: 인증서 만료로 인한 서비스 중단 예방(“망각 방지” 계층).

4.3 Datadog Mutating Webhook (Monitoring-by-Default)

• 역할: Pod에 모니터링 라벨/어노테이션 자동 주입.
• 효과: 모니터링 커버리지 60% → 95% (1개월). 기본값의 힘으로 운영 품질 확보.

4.4 Azure Policy / Workload Identity

• 역할: 조직 보안 정책 자동 집행(검증), Azure 서비스 인증 자동화(변환).
• 효과: 보안 감사 대비 수주 분량 수작업 제거, 인증 오류 감소.

4.5 Linkerd Webhook (Service Mesh)

• 구성: Proxy Injector, Tap Injector, Service Profile Validator, Policy Validator.
• 효과: 개발자는 메시 복잡도를 몰라도 자동 주입/검증으로 이점 획득.

---

5) 정책 설계 원칙

1. 최소 기능·명확 책임: 각 Webhook의 목적과 입력/출력(변경 항목)을 명시.
2. 예외 설계: System Namespace, Legacy App, Sidecar 주입 등 예외 경로를 먼저 정의.
3. 정책 계층화: Must-Have → Should-Have → Nice-to-Have 3단계로 분류/적용.
4. 가시성: 위반 메시지는 명확·행동가능하게(수정 예시·참조 링크 포함).
5. 관측 가능성: 위반·지연·실패율을 대시보드/KPI로 상시 추적.

---

6) 단계적 롤아웃(4주 표준 절차)

• 1주 차 – 공지: 정책 목적·영향 범위·수정 가이드·지원 채널 안내.
• 2주 차 – 경고 모드: Warn-only(차단 없음)로 로그/알림만 발행, 자율 수정 기간.
• 3주 차 – 집행 모드: 차단 활성화(Blocking). 이 시점엔 다수 위반 해소 상태.
• 4주 차 – 최적화: 실제 위반 패턴·엣지 케이스 반영해 Constraint/Webhook 튜닝.

---

7) 성능 최적화 전략

• Namespace 타겟팅: 관련 네임스페이스에만 Webhook 실행.
• 리소스 필터링: 필요한 리소스 타입에만 훅 적용.
• Timeout 튜닝: 30s → 5s로 축소(서비스 특성에 맞게).
• FailurePolicy: 서비스 영향도에 따라 Fail-Open vs Fail-Closed 구분 적용.
• 효과: 20+ Webhook 구동 환경에서 배포 지연 8–10초 → 3–4초로 단축.

---

8) 우선순위(Webhook 정책 계층)

Must-Have

• Resource Limits Validation: CPU/Memory 한도 미설정 차단 → 리소스 고갈 방지.
• Security Context Policies: RunAsNonRoot, readOnlyRootFilesystem 등 보안 기준 강제.
• Network Policy Validation: 네임스페이스/서비스 레벨 세분화 보장.
• Certificate Management: 인증서 발급·갱신 자동화로 가용성 확보.

Really-Should-Have

• Label/Annotation Injection: 모니터링·라우팅·백업 등 태그 자동 주입.
• Image Policy Enforcement: 취약/미인가 이미지 사용 차단(Registry·서명·SBOM 기준).
• Service Mesh Injection: 사이드카 자동 주입으로 메시 표준화.
• Backup Annotation Injection: 데이터 영속성·백업 정책 일관화.

Nice-to-Have

• Cost Allocation Labels: 비용 태깅 자동화로 팀/서비스 단위 정산 가능.
• Compliance Validation: 규제 준수 검증(산업별 필수 항목).
• Custom Business Logic: 조직/도메인별 특화 정책(승인·라벨·이름 규칙 등).

---

9) 운영 표준 및 거버넌스

• 변경 관리: 정책 변경은 PR·코드리뷰·스테이징 검증 후 점진 반영.
• 예외 승인: 한시적 예외는 만료일/사유/보완 계획 명시, 대체 통제 적용.
• 장애 대응: 정책 오탑지(blocking) 발생 시 Fail-Open 전환 기준·절차 사전 정의.
• 지표/KPI:
  • 배포 평균 지연 시간(p50/p95), Webhook 타임아웃/실패율
  • 정책 위반 발생 건수·해결 리드타임
  • 모니터링 커버리지, 인증서 만료 사고 건수
  • 이미지 정책 위반률, 네트워크 정책 준수율

---

10) 위험 및 대응

• 과도한 차단으로 개발 마찰 → 경고 모드·가이드·사전 공지로 완화.
• 레거시·사이드카 충돌 → Namespace/Label 기반 예외와 스코프 한정.
• 성능 저하 → 타겟팅·필터링·Timeout·FailurePolicy 최적화.
• 운영 복잡성 증가 → 정책 카탈로그·Runbook·대시보드로 표준화.

---

11) 부록 A: Gatekeeper 예시 스켈레톤

apiVersion: templates.gatekeeper.sh/v1beta1
kind: ConstraintTemplate
metadata:
  name: k8srequiredresources
# spec.crd/spec.targets/rego 등은 조직 표준 레포에 예시 본문 참조

예시 에러 메시지(검증 실패)

admission webhook "validation.gatekeeper.sh" denied the request:
[denied by k8srequiredresources] Container must have memory limits set

---

12) 부록 B: 표준 Webhook 카탈로그(샘플)

• cert-manager-webhook — Certificate 검증/변환/자동 갱신
• gatekeeper-webhook — OPA Policy 검증
• datadog-webhook — 모니터링 라벨/어노테이션 자동 주입
• azure-policy-validating-webhook-configuration — 조직 정책 검증
• azure-wi-webhook-mutating-webhook-configuration — Workload Identity 주입
• linkerd-proxy-injector-webhook-config — 사이드카 프록시 주입
• linkerd-tap-injector-webhook-config — Tap 디버깅 주입
• linkerd-sp-validator-webhook-config — 서비스 프로필 검증
• linkerd-policy-validator-webhook-config — 권한 정책 검증

---

13) 결론

Admission Webhook은 사람의 실수와 사람의 망각을 모두 다루는 자동화 층이다. 단순한 출발, 명확한 예외, 점진적 집행, 성능 최적화라는 4축을 지키면 개발자 경험과 플랫폼 신뢰성을 동시에 달성할 수 있다.