Container & Orchestration/Kubenetes

Kubernetes - Validating, Mutating Admission Controller

YongE 2025. 5. 16. 17:52

🛡️ 쿠버네티스 어드미션 컨트롤러 (Kubernetes Admission Controller)

쿠버네티스 어드미션 컨트롤러(Admission Controller)는 API 서버로 들어오는 요청을 가로채서 처리하는 플러그인의 집합이다. 이 컨트롤러는 인증(Authentication)과 인가(Authorization) 단계를 통과한 요청에 대해, 해당 요청을 최종적으로 수락할지 또는 거절할지를 결정하는 역할을 수행한다. 수락된 요청은 클러스터의 영구 저장소인 etcd에 저장된다.

어드미션 컨트롤러를 사용하는 주된 이유는 다음과 같다.

  • 보안성 향상. 사전에 정의된 정책을 강제하여 클러스터의 보안 수준을 높인다. 예를 들어, 특정 보안 기준을 충족하지 않는 파드 생성을 막을 수 있다.
  • 제어성 및 일관성 강화. 리소스 생성 및 수정 시 특정 레이블을 강제로 추가하거나, 리소스 사용량(CPU, 메모리)을 제한하는 등 클러스터 내 리소스를 효과적으로 제어하고 일관성을 유지할 수 있도록 한다.

쿠버네티스 API 서버로 요청이 들어오면 다음의 단계를 거쳐 처리된다.

  1. 인증 (Authentication). 요청을 보낸 사용자가 누구인지 확인한다.
  2. 인가 (Authorization). 인증된 사용자가 해당 요청을 수행할 권한이 있는지 확인한다.
  3. 어드미션 컨트롤 (Admission Control). 요청 내용이 클러스터 정책에 부합하는지 검증하거나 요청 내용을 변경한다.

🔎 어드미션 컨트롤러의 유형 및 실행 순서

어드미션 컨트롤러는 크게 두 가지 유형으로 나뉜다. 변형(Mutating) 어드미션 컨트롤러와 검증(Validating) 어드미션 컨트롤러다.

✨ 변형 어드미션 컨트롤러 (Mutating Admission Controller)

변형 어드미션 컨트롤러는 API 서버로 들어온 요청 객체를 변경하거나 수정하는 역할을 한다. 예를 들어, 사용자가 파드를 생성할 때 특정 레이블을 자동으로 추가하거나, 기본값을 설정하는 등의 작업을 수행한다.

  • 주요 기능. 요청된 리소스 객체의 내용을 수정한다.
  • 예시.
    • DefaultStorageClass. PersistentVolumeClaim(PVC) 생성 요청 시 storageClassName 필드가 명시되지 않은 경우, 클러스터에 설정된 기본 스토리지 클래스를 자동으로 삽입한다.
    • NamespaceAutoProvision. 존재하지 않는 네임스페이스에 리소스를 생성하려는 요청이 들어오면, 해당 네임스페이스를 자동으로 생성한다.

✅ 검증 어드미션 컨트롤러 (Validating Admission Controller)

검증 어드미션 컨트롤러는 API 요청이 클러스터 정책이나 보안 규칙을 준수하는지 검증한 후, 요청을 통과시킬지 또는 거부할지를 결정한다. 이 컨트롤러는 요청 내용을 변경하지 않고 오직 유효성만 검사한다.

  • 주요 기능. 요청된 리소스 객체의 유효성을 검사하고, 유효하지 않은 경우 요청을 거부한다.
  • 예시.
    • NamespaceExists. 리소스 생성 요청 시 명시된 네임스페이스가 실제로 존재하는지 확인하고, 존재하지 않으면 요청을 거부한다.
    • 리소스 객체의 필수 필드가 채워졌는지, 사양이 유효한지 등을 확인할 수 있다.

🔄 실행 순서

어드미션 컨트롤은 두 단계로 진행되며, 항상 변형(Mutating) 단계가 먼저 실행된 후 검증(Validating) 단계가 실행된다. 이는 변형 어드미션 컨트롤러에 의해 수정된 요청 내용을 기준으로 검증 어드미션 컨트롤러가 유효성을 판단해야 하기 때문이다. 만약 검증이 먼저 수행된다면, 변형 후에는 유효해질 수 있는 요청이 미리 거부될 수 있다.

다음은 API 요청 처리 흐름을 시각화한 것이다.

[클라이언트 요청] ---> [API 서버]
                       |
                       V
               [인증 (Authentication)]
                       |
                       V
               [인가 (Authorization)]
                       |
                       V
       [변형 어드미션 컨트롤러 (Mutating Admission Controllers)] (요청 변경/수정)
                       |
                       V
          [스키마 유효성 검사 (Object Schema Validation)]
                       |
                       V
      [검증 어드미션 컨트롤러 (Validating Admission Controllers)] (요청 검증)
                       |
                       V
       [etcd에 저장 (요청 승인 시)] 또는 [요청 거부]

이 흐름에서 스키마 유효성 검사는 변형된 객체가 쿠버네티스 리소스의 기본 형식을 따르는지 확인하는 과정이며, 검증 어드미션 컨트롤러는 그 이후에 사용자 정의 정책 준수 여부를 확인한다. 모든 검증을 통과한 요청은 etcd에 저장되어 클러스터 상태를 변경한다.

⚙️ 웹훅(Webhook)을 이용한 어드미션 컨트롤러 확장

쿠버네티스는 기본적으로 여러 유용한 어드미션 컨트롤러 플러그인을 제공하지만, 사용자는 웹훅(Webhook)을 통해 자신만의 커스텀 어드미션 로직을 구현하고 클러스터 정책을 더욱 유연하게 확장할 수 있다.

🔌 웹훅의 역할

웹훅은 쿠버네티스 API 서버가 특정 이벤트(예. 파드 생성 요청) 발생 시 외부 HTTP 콜백 엔드포인트로 요청을 보내도록 하는 메커니즘이다. 이를 통해 관리자는 클러스터 외부 또는 내부에 자체 개발한 로직을 실행하여 요청을 동적으로 변경하거나 검증할 수 있다.

쿠버네티스에서 웹훅 기반 어드미션 컨트롤러는 다음 두 가지 설정을 통해 정의된다.

  • MutatingWebhookConfiguration. 요청을 변경하는 웹훅 서버를 등록한다.
  • ValidatingWebhookConfiguration. 요청을 검증하는 웹훅 서버를 등록한다.

📜 웹훅 동작 과정

  1. 요청 수신. API 서버는 MutatingWebhookConfiguration 또는 ValidatingWebhookConfiguration에 정의된 규칙과 일치하는 요청이 발생하면, 해당 웹훅 서버의 엔드포인트로 AdmissionReview라는 JSON 객체를 HTTP POST 요청으로 전송한다.
    • AdmissionReview 객체. 이 객체에는 API 서버가 클라이언트로부터 받은 요청의 상세 정보가 포함된다. 주요 필드는 다음과 같다.
      • kind. 요청된 쿠버네티스 리소스의 종류 (예. Pod, Deployment).
      • operation. 수행되는 작업 (예. CREATE, UPDATE, DELETE).
      • userInfo. 요청을 보낸 사용자의 정보.
      • object. 실제 리소스의 명세 (예. 파드의 상세 스펙).
      • oldObject. 리소스 변경(Update) 요청일 경우, 변경 전 리소스의 스펙.
  2. 로직 처리 및 응답. 웹훅 서버는 수신한 AdmissionReview 객체를 기반으로 자체 로직을 수행한다.
    • 변형 웹훅 (Mutating Webhook). 요청을 수정해야 하는 경우, 변경 사항을 JSON Patch 형식으로 AdmissionReview 응답 객체의 patch 필드에 담아 반환한다. allowed 필드는 true로 설정한다.
    • 검증 웹훅 (Validating Webhook). 요청의 유효성을 검사하고, 결과를 AdmissionReview 응답 객체의 allowed 필드에 true(허용) 또는 false(거부)로 설정하여 반환한다. status 필드에 거부 사유 등을 포함할 수 있다.
  3. API 서버의 후속 조치. API 서버는 웹훅 서버로부터 받은 응답에 따라 요청을 처리한다. allowed가 false이면 요청은 거부된다. allowed가 true이고 변형 웹훅의 경우, 반환된 JSON Patch를 원본 요청에 적용한 후 다음 단계를 진행한다.

🛠️ 웹훅 설정 방법

사용자 정의 어드미션 웹훅을 설정하는 일반적인 단계는 다음과 같다.

  1. 웹훅 서버 개발.
    • 선호하는 프로그래밍 언어(Go, Python 등)를 사용하여 HTTP 서버를 개발한다.
    • 이 서버는 쿠버네티스로부터 AdmissionReview 요청을 JSON 형식으로 수신하고, 처리 결과를 AdmissionReview JSON 형식으로 응답할 수 있어야 한다.
    • 변형 웹훅의 경우 /mutate 엔드포인트, 검증 웹훅의 경우 /validate 엔드포인트 등을 구현할 수 있다.
  2. 웹훅 서버 호스팅.
    • 개발된 웹훅 서버를 독립적인 서버에 배포하거나, 쿠버네티스 클러스터 내에 파드(Pod)로 배포할 수 있다.
    • 클러스터 내에 배포하는 경우, API 서버가 웹훅 서버에 접근할 수 있도록 서비스(Service) 객체를 생성해야 한다.
    • API 서버와 웹훅 서버 간의 통신은 TLS로 암호화되어야 하므로, 적절한 인증서 설정이 필요하다.
  3. 웹훅 구성 객체 생성.
    • MutatingWebhookConfiguration 또는 ValidatingWebhookConfiguration 매니페스트 파일을 작성하여 쿠버네티스 클러스터에 적용한다.
    • 이 설정 객체에는 웹훅 서버의 주소(서비스 이름 또는 URL), API 서버와 웹훅 서버 간의 통신에 필요한 CA 번들, 어떤 리소스와 오퍼레이션에 대해 웹훅을 호출할지에 대한 규칙(rules) 등이 정의된다.

아래는 ValidatingWebhookConfiguration의 간략한 예시이다.

apiVersion: admissionregistration.k8s.io/v1
kind: ValidatingWebhookConfiguration
metadata:
  name: "pod-policy.example.com"
webhooks:
  - name: "pod-policy.example.com" # 웹훅의 고유한 이름
    clientConfig:
      service: # 클러스터 내부 서비스로 웹훅 서버를 지정
        namespace: "webhook-services" # 웹훅 서비스가 있는 네임스페이스
        name: "example-webhook-service" # 웹훅 서비스의 이름
        path: "/validate" # 웹훅 서버의 검증 로직을 처리하는 경로
      caBundle: "Ci0tLS0tQk......LS0K" # API 서버가 웹훅 서버의 인증서를 검증하기 위한 CA 인증서 (실제 값으로 대체 필요)
    rules:
      - operations: ["CREATE", "UPDATE"] # 파드 생성 및 업데이트 시 웹훅 호출
        apiGroups: [""] # 핵심 API 그룹
        apiVersions: ["v1"] # API 버전 v1
        resources: ["pods"] # 파드 리소스에 대해 적용
        scope: "Namespaced" # 네임스페이스 범위의 리소스에 적용
    admissionReviewVersions: ["v1"] # 지원하는 AdmissionReview API 버전
    sideEffects: "None" # 이 웹훅 호출이 다른 리소스에 영향을 주지 않음을 명시
    timeoutSeconds: 5 # 웹훅 호출 타임아웃 시간(초)

위 YAML 파일에서 caBundle은 API 서버가 웹훅 서버의 TLS 인증서를 신뢰할 수 있도록 CA 인증서를 Base64로 인코딩한 값을 실제로 채워 넣어야 한다. 이 구성을 통해 특정 조건(예. 파드 생성/수정)을 만족하는 API 요청이 발생하면, 정의된 웹훅 서버로 AdmissionReview 요청이 전달되어 사용자 정의 로직이 실행된다.

반응형