인증·권한·어드미션 (AuthN/AuthZ/Admission)

인증·권한·어드미션 (AuthN/AuthZ/Admission)

이 페이지는 어드미션 컨트롤러(admission controller) 에 대한 개요를 다룹니다.

어드미션 컨트롤러는 Kubernetes API 서버로 들어오는 요청을 가로채는 코드 조각입니다. 리소스가 저장(persistence)되기 전에, 그리고 요청이 인증·인가(authenticated and authorized)된 후에 개입합니다.

Kubernetes의 중요한 기능 몇 가지는 제대로 동작하려면 어드미션 컨트롤러가 활성화되어 있어야 합니다. 그 때문에 올바른 어드미션 컨트롤러 세트로 설정되지 않은 API 서버는 불완전한 서버라서, 기대하는 모든 기능을 지원하지 못합니다.

어드미션 컨트롤러가 뭐예요?

어드미션 컨트롤러는 Kubernetes API 서버 안에 있는 코드로, 리소스를 수정하는 요청에 실려 오는 데이터를 확인하는 역할을 합니다.

어드미션 컨트롤러는 객체를 생성(create), 삭제(delete), 수정(modify) 하는 요청에 적용됩니다. 또한 pod에 API 서버 프록시로 연결(connect)하는 요청처럼 사용자 정의 동사(custom verb)를 차단할 수도 있어요. 반면 읽기 요청 — get, watch, list — 은 차단하지 않으며 차단할 수도 없습니다. 읽기는 어드미션 컨트롤 계층을 우회하기 때문이죠.

어드미션 컨트롤 메커니즘은 검증(validating), 변경(mutating), 또는 둘 다일 수 있습니다. 변경 컨트롤러는 수정되는 리소스의 데이터를 바꿀 수 있고, 검증 컨트롤러는 바꿀 수 없습니다.

Kubernetes 1.36의 어드미션 컨트롤러는 아래 목록으로 구성되며, kube-apiserver 바이너리에 컴파일되어 있고 오직 클러스터 관리자만 설정할 수 있습니다.

어드미션 컨트롤 확장 지점

전체 목록 가운데 특별한 컨트롤러가 세 개 있습니다: MutatingAdmissionWebhook, ValidatingAdmissionWebhook, ValidatingAdmissionPolicy입니다. 두 웹훅 컨트롤러는 각각 API에 설정된 변경·검증 어드미션 컨트롤 웹훅을 실행합니다. ValidatingAdmissionPolicy는 외부 HTTP 호출에 의존하지 않고 API 안에 선언적(declarative) 검증 코드를 심을 수 있는 방법을 제공합니다.

이 세 컨트롤러를 이용하면 어드미션 시점에 클러스터 동작을 맞춤 설정할 수 있습니다.

어드미션 컨트롤 단계

어드미션 컨트롤 과정은 두 단계로 진행됩니다. 첫 번째 단계에서는 변경(mutating) 어드미션 컨트롤러가 실행되고, 두 번째 단계에서는 검증(validating) 어드미션 컨트롤러가 실행됩니다. 일부 컨트롤러가 둘 다라는 점을 다시 짚어둘게요.

어느 단계든 어떤 컨트롤러가 요청을 거부하면 전체 요청은 즉시 거부되고 최종 사용자에게 오류가 반환됩니다.

마지막으로, 어드미션 컨트롤러는 해당 객체를 변경하는 것 외에도 가끔 부수 효과(side effect)를 일으킬 수 있습니다. 즉 요청 처리 과정에서 관련 리소스를 함께 바꾸는 거죠. 쿼터(quota) 사용량을 증가시키는 것이 이런 일이 필요한 대표적인 예입니다. 이런 부수 효과는 대응하는 회수(reclamation) 또는 재조정(reconciliation) 과정이 필요합니다. 어드미션 컨트롤러 하나가 주어진 요청이 다른 모든 어드미션 컨트롤러를 통과할지 확신할 수는 없기 때문이에요.

이 호출들의 순서는 아래 다이어그램에서 볼 수 있습니다.

kube-apiserver가 어드미션 단계에서 요청을 처리하는 시퀀스 다이어그램. 변경 웹훅이 먼저 실행되고, 이어서 validatingadmissionpolicy, 마지막으로 검증 웹훅이 실행됩니다. 첫 번째 거부가 있을 때까지, 또는 전부 수락될 때까지 계속됩니다. 또한 변경 웹훅의 변경으로 인해 이전에 호출된 모든 웹훅이 다시 호출되는 것을 보여줍니다.

왜 필요해요?

Kubernetes의 중요한 기능 몇 가지는 제대로 동작하려면 어드미션 컨트롤러가 활성화되어 있어야 합니다. 그 때문에 올바른 어드미션 컨트롤러 세트로 설정되지 않은 API 서버는 불완전한 서버라서, 기대하는 모든 기능을 지원하지 못합니다.

어드미션 컨트롤러는 어떻게 켜요?

Kubernetes API 서버 플래그 enable-admission-plugins는 클러스터의 객체를 수정하기 전에 호출할 어드미션 컨트롤 플러그인 목록을 쉼표로 구분해 받습니다. 예를 들어 다음 명령줄은 NamespaceLifecycle과 LimitRanger 어드미션 컨트롤 플러그인을 활성화합니다:

kube-apiserver --enable-admission-plugins=NamespaceLifecycle,LimitRanger ...

참고:

클러스터가 배포된 방식과 API 서버가 시작되는 방식에 따라 설정을 적용하는 방법이 달라질 수 있습니다. 예를 들어 API 서버를 systemd 서비스로 배포했다면 systemd 유닛 파일을 수정해야 하고, 셀프 호스팅 방식으로 배포했다면 API 서버 매니페스트 파일을 수정해야 할 수 있어요.

어드미션 컨트롤러는 어떻게 꺼요?

Kubernetes API 서버 플래그 disable-admission-plugins는 기본적으로 활성화된 플러그인 목록에 있더라도 비활성화할 플러그인 목록을 쉼표로 구분해 받습니다.

kube-apiserver --disable-admission-plugins=PodNodeSelector,AlwaysDeny ...

기본적으로 활성화된 플러그인은 뭐예요?

활성화된 어드미션 플러그인을 확인하려면:

kube-apiserver -h | grep enable-admission-plugins

Kubernetes 1.36에서 기본값은 다음과 같습니다:

CertificateApproval, CertificateSigning, CertificateSubjectRestriction, DefaultIngressClass, DefaultStorageClass, DefaultTolerationSeconds, LimitRanger, MutatingAdmissionWebhook, NamespaceLifecycle, PersistentVolumeClaimResize, PodSecurity, Priority, ResourceQuota, RuntimeClass, ServiceAccount, StorageObjectInUseProtection, TaintNodesByCondition, ValidatingAdmissionPolicy, ValidatingAdmissionWebhook

각 어드미션 컨트롤러는 무엇을 하나요?

AlwaysAdmit

FEATURE STATE: Kubernetes v1.13 [deprecated]

유형: Validating.

이 어드미션 컨트롤러는 모든 pod를 클러스터에 허용합니다. 어드미션 컨트롤러가 전혀 없는 것과 동일한 동작이기 때문에 deprecated(더 이상 권장되지 않음) 처리되었습니다.

AlwaysDeny

FEATURE STATE: Kubernetes v1.13 [deprecated]

유형: Validating.

모든 요청을 거부합니다. AlwaysDeny는 실제 의미가 없기 때문에 deprecated 처리되었습니다.

AlwaysPullImages

유형: Mutating and Validating.

이 어드미션 컨트롤러는 모든 새 Pod를 수정해 이미지 pull 정책을 Always로 강제합니다. 멀티테넌트 클러스터에서 유용한데, 사용자들이 자신의 프라이빗 이미지를 이를 pull할 자격(credential)이 있는 사람만 쓸 수 있음을 보장할 수 있기 때문입니다. 이 컨트롤러가 없으면 이미지를 한 번 node에 pull한 뒤에는 (Pod이 올바른 node에 스케줄된 경우) 어느 사용자든 이미지 이름만 알면 이미지에 대한 인가 검사 없이 사용할 수 있어요. 이 어드미션 컨트롤러를 활성화하면 컨테이너를 시작하기 전에 항상 이미지를 pull하므로, 유효한 자격이 필수입니다.

CertificateApproval

유형: Validating.

이 어드미션 컨트롤러는 CertificateSigningRequest 리소스의 승인(approve) 요청을 관찰하고, 승인하는 사용자가 CertificateSigningRequest 리소스에 요청된 spec.signerName으로 인증서 요청을 승인할 권한이 있는지 추가 인가 검사를 수행합니다.

CertificateSigningRequest 리소스에서 여러 동작을 수행하는 데 필요한 권한에 대한 자세한 내용은 Certificate Signing Requests를 참고하세요.

CertificateSigning

유형: Validating.

이 어드미션 컨트롤러는 CertificateSigningRequest 리소스의 status.certificate 필드에 대한 업데이트를 관찰하고, 서명하는 사용자가 CertificateSigningRequest 리소스에 요청된 spec.signerName으로 인증서 요청을 서명(sign) 할 권한이 있는지 추가 인가 검사를 수행합니다.

CertificateSigningRequest 리소스에서 여러 동작을 수행하는 데 필요한 권한에 대한 자세한 내용은 Certificate Signing Requests를 참고하세요.

CertificateSubjectRestriction

유형: Validating.

이 어드미션 컨트롤러는 spec.signerName이 kubernetes.io/kube-apiserver-client인 CertificateSigningRequest 리소스의 생성을 관찰합니다. system:masters의 'group'(또는 'organization attribute')을 지정하는 요청은 모두 거부합니다.

DefaultIngressClass

유형: Mutating.

이 어드미션 컨트롤러는 특정 ingress class를 요청하지 않는 Ingress 객체의 생성을 관찰하고, 자동으로 기본 ingress class를 추가합니다. 이렇게 하면 특별한 ingress class를 요청하지 않는 사용자들은 전혀 신경 쓸 필요 없이 기본값을 받게 됩니다.

기본 ingress class가 설정되어 있지 않으면 이 컨트롤러는 아무 것도 하지 않습니다. 두 개 이상의 ingress class가 기본값으로 표시되면 Ingress 생성 시 오류와 함께 거부하며, 관리자는 IngressClass 객체를 다시 확인해 하나만 기본값으로 표시해야 합니다("ingressclass.kubernetes.io/is-default-class" 어노테이션 사용). 이 어드미션 컨트롤러는 Ingress 업데이트는 무시하고 생성 시에만 동작합니다.

ingress class와 기본값 표시 방법에 대한 자세한 내용은 Ingress 문서를 참고하세요.

DefaultStorageClass

유형: Mutating.

이 어드미션 컨트롤러는 특정 storage class를 요청하지 않는 PersistentVolumeClaim 객체의 생성을 관찰하고, 자동으로 기본 storage class를 추가합니다. 이렇게 하면 특별한 storage class를 요청하지 않는 사용자들은 전혀 신경 쓸 필요 없이 기본값을 받게 됩니다.

기본 StorageClass가 없으면 이 컨트롤러는 아무 것도 하지 않습니다. storage class가 두 개 이상 기본값으로 표시된 상태에서 storageClassName을 지정하지 않은 PersistentVolumeClaim을 생성하면, Kubernetes는 가장 최근에 생성된 기본 StorageClass를 사용합니다. volumeName을 지정해 PersistentVolumeClaim을 생성할 때, 기본 StorageClass가 적용된 후에도 정적 볼륨의 storageClassName이 PersistentVolumeClaim의 storageClassName과 일치하지 않으면 pending 상태로 남습니다. 이 어드미션 컨트롤러는 PersistentVolumeClaim 업데이트는 무시하고 생성 시에만 동작합니다.

persistent volume claim과 storage class, 기본값 표시 방법에 대한 자세한 내용은 persistent volume 문서를 참고하세요.

DefaultTolerationSeconds

유형: Mutating.

이 어드미션 컨트롤러는 pod이 node.kubernetes.io/not-ready:NoExecute 또는 node.kubernetes.io/unreachable:NoExecute taint에 대한 toleration을 이미 갖고 있지 않으면, k8s-apiserver 입력 파라미터 default-not-ready-toleration-seconds와 default-unreachable-toleration-seconds를 기반으로 notready:NoExecute와 unreachable:NoExecute taint를 견딜 수 있는 기본 관용(forgiveness) toleration을 pod에 설정합니다. default-not-ready-toleration-seconds와 default-unreachable-toleration-seconds의 기본값은 5분입니다.

DenyServiceExternalIPs

유형: Validating.

이 어드미션 컨트롤러는 Service 필드 externalIPs의 모든 신규 사용을 거부합니다. 이 기능은 매우 강력하며(네트워크 트래픽 가로채기를 허용) 정책으로 잘 통제되지 않습니다. 활성화하면 클러스터 사용자는 externalIPs를 사용하는 새 Service를 만들 수 없고, 기존 Service 객체의 externalIPs에 새 값을 추가할 수도 없습니다. 기존 externalIPs 사용에는 영향을 주지 않으며, 사용자는 기존 Service 객체의 externalIPs에서 값을 제거할 수는 있습니다.

대부분의 사용자는 이 기능이 전혀 필요 없으므로, 클러스터 관리자는 비활성화를 고려해야 합니다. 이 기능이 필요한 클러스터는 사용을 관리하기 위한 사용자 정의 정책을 고려해 보세요.

이 어드미션 컨트롤러는 기본적으로 비활성화되어 있습니다.

EventRateLimit

FEATURE STATE: Kubernetes v1.13 [alpha]

유형: Validating.

이 어드미션 컨트롤러는 새 Event를 저장하는 요청으로 API 서버가 범람하는 문제를 완화합니다. 클러스터 관리자는 다음으로 event rate limit을 지정할 수 있습니다:

  • EventRateLimit 어드미션 컨트롤러 활성화;
  • API 서버의 명령줄 플래그 --admission-control-config-file에 제공하는 파일에서 EventRateLimit 설정 파일을 참조:
apiVersion: apiserver.config.k8s.io/v1
kind: AdmissionConfiguration
plugins:
  - name: EventRateLimit
    path: eventconfig.yaml
...

설정에 지정할 수 있는 제한 유형은 네 가지입니다:

  • Server: API 서버가 받은 모든 Event 요청(생성 또는 수정)이 하나의 버킷을 공유합니다.
  • Namespace: 각 네임스페이스마다 전용 버킷이 있습니다.
  • User: 각 사용자마다 버킷이 할당됩니다.
  • SourceAndObject: 이벤트의 소스와 관련 객체 각 조합마다 버킷이 할당됩니다.

다음은 이런 설정을 위한 eventconfig.yaml 예시입니다:

apiVersion: eventratelimit.admission.k8s.io/v1alpha1
kind: Configuration
limits:
  - type: Namespace
    qps: 50
    burst: 100
    cacheSize: 2000
  - type: User
    qps: 10
    burst: 50

자세한 내용은 EventRateLimit Config API (v1alpha1)를 참고하세요.

이 어드미션 컨트롤러는 기본적으로 비활성화되어 있습니다.

ExtendedResourceToleration

유형: Mutating.

이 플러그인은 extended resource를 가진 전용 노드 생성을 돕습니다. 운영자가 (GPU, FPGA 등의) 확장 리소스를 가진 전용 노드를 만들려면 extended resource 이름을 키로 해서 노드에 taint를 걸 것으로 기대됩니다. 이 어드미션 컨트롤러를 활성화하면 확장 리소스를 요청하는 pod에 그러한 taint에 대한 toleration을 자동으로 추가하므로, 사용자가 수동으로 toleration을 추가할 필요가 없습니다.

이 어드미션 컨트롤러는 기본적으로 비활성화되어 있습니다.

ImagePolicyWebhook

유형: Validating.

ImagePolicyWebhook 어드미션 컨트롤러는 백엔드 웹훅이 어드미션 결정을 내리도록 허용합니다.

이 어드미션 컨트롤러는 기본적으로 비활성화되어 있습니다.

설정 파일 형식

ImagePolicyWebhook은 백엔드 동작 옵션을 설정하기 위해 구성 파일을 사용합니다. 이 파일은 json 또는 yaml이며 다음 형식을 갖습니다:

imagePolicy:
  kubeConfigFile: /path/to/kubeconfig/for/backend
  # 승인(approval)을 캐시할 시간(s)
  allowTTL: 50
  # 거부(denial)를 캐시할 시간(s)
  denyTTL: 50
  # 재시도 사이 대기 시간(ms)
  retryBackoff: 500
  # 웹훅 백엔드가 실패할 때의 동작 결정
  defaultAllow: true

ImagePolicyWebhook 설정 파일을 API 서버의 명령줄 플래그 --admission-control-config-file에 제공되는 파일에서 참조합니다:

apiVersion: apiserver.config.k8s.io/v1
kind: AdmissionConfiguration
plugins:
  - name: ImagePolicyWebhook
    path: imagepolicyconfig.yaml
...

또는 설정을 파일에 직접 내장할 수도 있습니다:

apiVersion: apiserver.config.k8s.io/v1
kind: AdmissionConfiguration
plugins:
  - name: ImagePolicyWebhook
    configuration:
      imagePolicy:
        kubeConfigFile: <path-to-kubeconfig-file>
        allowTTL: 50
        denyTTL: 50
        retryBackoff: 500
        defaultAllow: true

ImagePolicyWebhook 설정 파일은 백엔드와의 연결을 설정하는 kubeconfig 형식 파일을 참조해야 합니다. 백엔드가 TLS로 통신하는 것이 요구됩니다.

kubeconfig 파일의 cluster 필드는 원격 서비스를 가리켜야 하며, user 필드는 반환된 authorizer를 담아야 합니다.

# clusters는 원격 서비스를 가리킵니다.
clusters:
  - name: name-of-remote-imagepolicy-service
    cluster:
      certificate-authority: /path/to/ca.pem    # 원격 서비스 검증용 CA.
      server: https://images.example.com/policy # 조회할 원격 서비스 URL. 'https'를 사용해야 함.

# users는 API 서버의 웹훅 설정을 가리킵니다.
users:
  - name: name-of-api-server
    user:
      client-certificate: /path/to/cert.pem # 웹훅 어드미션 컨트롤러가 사용할 인증서
      client-key: /path/to/key.pem          # 인증서와 일치하는 키

추가 HTTP 설정은 kubeconfig 문서를 참고하세요.

요청 페이로드

어드미션 결정에 직면하면 API 서버는 작업을 설명하는 JSON 직렬화된 imagepolicy.k8s.io/v1alpha1 ImageReview 객체를 POST합니다. 이 객체는 어드미션 대상이 되는 컨테이너를 설명하는 필드와 *.image-policy.k8s.io/*와 일치하는 pod 어노테이션을 포함합니다.

참고:

웹훅 API 객체는 다른 Kubernetes API 객체와 동일한 버전 관리 호환성 규칙을 따릅니다. 구현자는 alpha 객체의 느슨한 호환성 약속을 인지하고, 올바른 역직렬화(deserialization)를 위해 요청의 apiVersion 필드를 확인해야 합니다. 또한 API 서버는 imagepolicy.k8s.io/v1alpha1 API 확장 그룹을 활성화해야 합니다(--runtime-config=imagepolicy.k8s.io/v1alpha1=true).

요청 본문 예시:

{
  "apiVersion": "imagepolicy.k8s.io/v1alpha1",
  "kind": "ImageReview",
  "spec": {
    "containers": [
      {
        "image": "myrepo/myimage:v1"
      },
      {
        "image": "myrepo/myimage@sha256:beb6bd6a68f114c1dc2ea4b28db81bdf91de202a9014972bec5e4d9171d90ed"
      }
    ],
    "annotations": {
      "mycluster.image-policy.k8s.io/ticket-1234": "break-glass"
    },
    "namespace": "mynamespace"
  }
}

원격 서비스는 요청의 status 필드를 채우고 허용 또는 거부로 응답할 것으로 기대됩니다. 응답 본문의 spec 필드는 무시되며 생략할 수 있습니다. 허용(permissive) 응답은 다음을 반환합니다:

{
  "apiVersion": "imagepolicy.k8s.io/v1alpha1",
  "kind": "ImageReview",
  "status": {
    "allowed": true
  }
}

접근을 거부하려면 서비스는 다음을 반환합니다:

{
  "apiVersion": "imagepolicy.k8s.io/v1alpha1",
  "kind": "ImageReview",
  "status": {
    "allowed": false,
    "reason": "image currently blacklisted"
  }
}

참고:

ImageReview 객체에는 컨테이너로 실행될 Pod의 모든 이미지가 포함됩니다. Pod 스펙의 containers, initContainers, ephemeralContainers 필드에 지정된 이미지를 모두 포함합니다. 그 결과 image volume 아래 포함된 이미지는 ImagePolicyWebhook의 범위에 들지 않습니다.

추가 문서는 imagepolicy.v1alpha1 API를 참고하세요.

어노테이션으로 확장하기

Pod의 어노테이션 중 *.image-policy.k8s.io/*와 일치하는 모든 것은 웹훅에 전송됩니다. 어노테이션을 전송하면 이미지 정책 백엔드를 아는 사용자가 백엔드에 추가 정보를 보낼 수 있고, 서로 다른 백엔드 구현이 서로 다른 정보를 받아들이도록 할 수 있습니다.

여기에 넣을 수 있는 정보의 예는:

  • 긴급 상황에서 정책을 재정의하는 "break glass" 요청.
  • break-glass 요청을 기록하는 티켓 시스템의 티켓 번호.
  • 제공되는 이미지의 imageID에 대한 힌트를 정책 서버에 주어 조회를 절약.

어느 경우든 어노테이션은 사용자가 제공하며 Kubernetes가 어떤 식으로도 검증하지 않습니다.

LimitPodHardAntiAffinityTopology

유형: Validating.

이 어드미션 컨트롤러는 requiredDuringSchedulingIgnoredDuringExecution에서 kubernetes.io/hostname이 아닌 AntiAffinity 토폴로지 키를 정의하는 모든 pod를 거부합니다.

이 어드미션 컨트롤러는 기본적으로 비활성화되어 있습니다.

LimitRanger

유형: Mutating and Validating.

이 어드미션 컨트롤러는 들어오는 요청을 관찰하고 Namespace의 LimitRange 객체에 열거된 제약 중 어느 것도 위반하지 않는지 확인합니다. Kubernetes 배포에서 LimitRange 객체를 사용한다면 이 제약을 강제하기 위해 이 어드미션 컨트롤러를 반드시 사용해야 합니다. LimitRanger는 리소스 요청을 지정하지 않은 Pod에 기본 리소스 요청을 적용하는 데도 쓸 수 있습니다. 현재 기본 LimitRanger는 default 네임스페이스의 모든 Pod에 CPU 0.1 요건을 적용합니다.

자세한 내용은 LimitRange API reference와 LimitRange 예시를 참고하세요.

MutatingAdmissionWebhook

유형: Mutating.

이 어드미션 컨트롤러는 요청과 일치하는 모든 변경(mutating) 웹훅을 호출합니다. 일치하는 웹훅은 직렬로 호출되며, 각각 원하면 객체를 수정할 수 있습니다.

이 어드미션 컨트롤러는(이름이 암시하듯) 변경 단계에서만 실행됩니다.

이것이 호출하는 웹훅에 부수 효과가 있다면(예: 쿼터 감소) 반드시 재조정 시스템이 있어야 합니다. 이후의 웹훅이나 검증 어드미션 컨트롤러가 요청 완료를 허용할 것이라는 보장이 없기 때문입니다.

MutatingAdmissionWebhook을 비활성화하면 admissionregistration.k8s.io/v1 그룹/버전의 MutatingWebhookConfiguration 객체도 --runtime-config 플래그로 비활성화해야 합니다. 둘 다 기본적으로 켜져 있습니다.

  • 사용자는 자신이 만들려는 객체가 돌아온 객체와 다를 때 혼란을 겪을 수 있습니다.
  • 내장 제어 루프는 자신이 만들려는 객체가 읽어올 때 다를 경우 깨질 수 있습니다.
    • 원래 설정되지 않은 필드를 설정하는 것은 원래 요청에 설정된 필드를 덮어쓰는 것보다 문제를 일으킬 가능성이 낮습니다. 후자는 피하세요.
  • 내장 리소스나 서드파티 리소스의 제어 루프에 대한 향후 변경은 오늘 잘 동작하는 웹훅을 깨뜨릴 수 있습니다. 웹훅 설치 API가 확정된 뒤에도 모든 가능한 웹훅 동작이 무기한 지원된다고 보장되지는 않습니다.

NamespaceAutoProvision

유형: Mutating.

이 어드미션 컨트롤러는 네임스페이스가 지정된(namespaced) 리소스에 대한 모든 들어오는 요청을 검사하고 참조된 네임스페이스가 존재하는지 확인합니다. 찾을 수 없으면 네임스페이스를 생성합니다. 이 어드미션 컨트롤러는 사용 전에 네임스페이스 생성을 제한하고 싶지 않은 배포에서 유용합니다.

NamespaceExists

유형: Validating.

이 어드미션 컨트롤러는 Namespace 자체를 제외한 네임스페이스가 지정된 리소스에 대한 모든 요청을 검사합니다. 요청에서 참조하는 네임스페이스가 존재하지 않으면 거부됩니다.

NamespaceLifecycle

유형: Validating.

이 어드미션 컨트롤러는 종료(termination)되고 있는 Namespace에는 새 객체를 만들 수 없도록 강제하고, 존재하지 않는 Namespace의 요청은 거부되도록 보장합니다. 또한 default, kube-system, kube-public의 세 가지 시스템 예약 네임스페이스 삭제도 방지합니다.

Namespace 삭제는 해당 네임스페이스의 모든 객체(pods, services 등)를 제거하는 일련의 작업을 시작합니다. 그 과정의 무결성을 강제하기 위해 이 어드미션 컨트롤러를 실행할 것을 강력히 권장합니다.

NodeDeclaredFeatureValidator

FEATURE STATE: Kubernetes v1.36 [beta](기본 활성화)

유형: Validating.

이 어드미션 컨트롤러는 바인딩된 Pod에 대한 쓰기를 가로채어, 그 변경이 현재 Pod가 실행 중인 노드가 선언한 기능과 호환되는지 확인합니다. Node의 .status.declaredFeatures 필드를 사용해 활성화된 기능 집합을 판별합니다. Pod 업데이트에 현재 노드의 기능 목록에 없는 기능이 필요하면, 어드미션 컨트롤러가 업데이트 요청을 거부합니다. 이는 Pod가 스케줄된 후 기능 불일치로 인한 런타임 실패를 방지합니다.

이 어드미션 컨트롤러는 NodeDeclaredFeatures feature gate가 활성화되어 있으면 기본적으로 활성화됩니다.

NodeRestriction

유형: Validating.

이 어드미션 컨트롤러는 kubelet이 수정할 수 있는 Node와 Pod 객체를 제한합니다. 이 어드미션 컨트롤러의 제한을 받으려면 kubelet은 system:nodes 그룹의 자격 증명을 system:node:<nodeName> 형태의 사용자 이름과 함께 사용해야 합니다. 그런 kubelet은 자신의 Node API 객체만 수정할 수 있고, 자신의 노드에 바인딩된 Pod API 객체만 수정할 수 있습니다. kubelet은 자신의 Node API 객체에서 taint를 업데이트하거나 제거할 수 없습니다.

NodeRestriction 어드미션 플러그인은 kubelet이 자신의 Node API 객체를 삭제하는 것을 막고, kubernetes.io/ 또는 k8s.io/ 접두사 아래 라벨의 kubelet 수정을 다음과 같이 강제합니다:

  • 금지 (kubelet이 수정할 수 없음):
    • node-restriction.kubernetes.io/ 접두사의 라벨. 이 접두사는 관리자가 워크로드 격리를 위해 Node 객체에 라벨을 붙이도록 예약되었습니다.
    • node-role.kubernetes.io/ 접두사의 라벨(예: node-role.kubernetes.io/control-plane). 권한이 없는 노드가 클러스터 역할을 스스로 선언하지 못하도록 제한됩니다.
  • 허용 (kubelet이 추가/제거/업데이트 가능):
    • kubernetes.io/hostname
    • kubernetes.io/arch
    • kubernetes.io/os
    • beta.kubernetes.io/instance-type
    • node.kubernetes.io/instance-type
    • failure-domain.beta.kubernetes.io/region (deprecated)
    • failure-domain.beta.kubernetes.io/zone (deprecated)
    • topology.kubernetes.io/region
    • topology.kubernetes.io/zone
    • kubelet.kubernetes.io/ 접두사 라벨
    • node.kubernetes.io/ 접두사 라벨
  • 예약됨: kubelet이 kubernetes.io 또는 k8s.io 접두사 아래의 다른 라벨을 사용하는 것은 예약되어 있습니다. NodeRestriction 어드미션 플러그인은 일반적으로 인가되지 않은 자기 라벨링을 막기 위해 이를 불허하지만, 향후 기능의 일부로 이 접두사 아래 추가 라벨을 허용할 수도 있습니다.

ServiceAccountNodeAudienceRestriction feature gate가 활성화되면, 이 어드미션 플러그인은 kubelet이 TokenRequest API를 통해 서비스 계정 토큰을 요청할 수 있는 audience도 제한합니다. kubelet은 해당 노드의 pod가 이미 참조하는 audience(projected service account token volume 또는 CSI 드라이버 토큰 요청을 통해) 또는 RBAC에서 request-serviceaccounts-token-audience 동사로 명시적으로 부여된 audience에 대해서만 토큰을 요청할 수 있습니다. 자세한 내용은 Service account token audience restriction을 참고하세요.

향후 버전에서는 kubelet이 올바르게 동작하는 데 필요한 최소 권한 집합을 갖도록 추가 제한을 더할 수 있습니다.

유형: Validating.

이 어드미션 컨트롤러는 객체의 metadata.ownerReferences 접근을 보호하여, 객체에 대한 delete 권한이 있는 사용자만 변경할 수 있게 합니다. 또한 객체의 metadata.ownerReferences[x].blockOwnerDeletion 접근도 보호하여, 참조된 owner의 finalizers 하위 리소스에 대한 update 권한이 있는 사용자만 변경할 수 있게 합니다.

PersistentVolumeClaimResize

FEATURE STATE: Kubernetes v1.24 [stable]

유형: Validating.

이 어드미션 컨트롤러는 들어오는 PersistentVolumeClaim 크기 조정(resize) 요청을 확인하는 추가 검증을 구현합니다.

PersistentVolumeClaimResize 어드미션 컨트롤러를 활성화하는 것이 권장됩니다. 이 컨트롤러는 클레임의 StorageClass가 allowVolumeExpansion을 true로 설정해 명시적으로 크기 조정을 활성화하지 않는 한, 기본적으로 모든 클레임의 크기 조정을 방지합니다.

예를 들어 다음 StorageClass에서 생성된 모든 PersistentVolumeClaim은 볼륨 확장을 지원합니다:

apiVersion: storage.k8s.io/v1
kind: StorageClass
metadata:
  name: gluster-vol-default
provisioner: kubernetes.io/glusterfs
parameters:
  resturl: "http://192.168.10.100:8080"
  restuser: ""
  secretNamespace: ""
  secretName: ""
allowVolumeExpansion: true

persistent volume claim에 대한 자세한 내용은 PersistentVolumeClaims를 참고하세요.

PodNodeSelector

FEATURE STATE: Kubernetes v1.5 [alpha]

유형: Validating.

이 어드미션 컨트롤러는 네임스페이스 어노테이션과 전역 설정을 읽어 네임스페이스 내에서 사용할 수 있는 node selector를 기본값으로 설정하고 제한합니다.

이 어드미션 컨트롤러는 기본적으로 비활성화되어 있습니다.

설정 파일 형식

PodNodeSelector는 백엔드 동작 옵션을 설정하기 위해 구성 파일을 사용합니다. 설정 파일 형식은 향후 릴리스에서 버전이 있는 파일로 옮겨질 것입니다. 이 파일은 json 또는 yaml이며 다음 형식을 갖습니다:

podNodeSelectorPluginConfig:
  clusterDefaultNodeSelector: name-of-node-selector
  namespace1: name-of-node-selector
  namespace2: name-of-node-selector

PodNodeSelector 설정 파일을 API 서버의 명령줄 플래그 --admission-control-config-file에 제공되는 파일에서 참조합니다:

apiVersion: apiserver.config.k8s.io/v1
kind: AdmissionConfiguration
plugins:
- name: PodNodeSelector
  path: podnodeselector.yaml
...

설정 어노테이션 형식

PodNodeSelector는 어노테이션 키 scheduler.alpha.kubernetes.io/node-selector를 사용해 네임스페이스에 node selector를 할당합니다.

apiVersion: v1
kind: Namespace
metadata:
  annotations:
    scheduler.alpha.kubernetes.io/node-selector: name-of-node-selector
  name: namespace3

내부 동작

이 어드미션 컨트롤러는 다음 동작을 갖습니다:

  1. Namespace에 scheduler.alpha.kubernetes.io/node-selector 키의 어노테이션이 있으면 그 값을 node selector로 사용합니다.
  2. 네임스페이스에 그런 어노테이션이 없으면 PodNodeSelector 플러그인 설정 파일에 정의된 clusterDefaultNodeSelector를 node selector로 사용합니다.
  3. pod의 node selector를 네임스페이스 node selector와 비교해 충돌을 확인합니다. 충돌은 거부로 이어집니다.
  4. pod의 node selector를 플러그인 설정 파일에 정의된 네임스페이스별 허용 selector와 비교해 충돌을 확인합니다. 충돌은 거부로 이어집니다.

참고:

PodNodeSelector는 pod가 특정 라벨이 붙은 노드에서 실행되도록 강제합니다. 특정 taint가 붙은 노드에서 pod가 실행되는 것을 막는 PodTolerationRestriction 어드미션 플러그인도 함께 참고하세요.

PodSecurity

FEATURE STATE: Kubernetes v1.25 [stable]

유형: Validating.

PodSecurity 어드미션 컨트롤러는 새 Pod가 어드미션되기 전에 확인하고, 요청된 보안 컨텍스트와 Pod가 속할 네임스페이스에 대해 허용된 Pod Security Standards의 제한을 기반으로 어드미션 여부를 결정합니다.

자세한 내용은 Pod Security Admission 문서를 참고하세요.

PodSecurity는 PodSecurityPolicy라는 더 오래된 어드미션 컨트롤러를 대체했습니다.

PodTolerationRestriction

FEATURE STATE: Kubernetes v1.7 [alpha]

유형: Mutating and Validating.

PodTolerationRestriction 어드미션 컨트롤러는 pod의 toleration과 해당 네임스페이스의 toleration 사이의 충돌을 확인합니다. 충돌이 있으면 pod 요청을 거부합니다. 그런 다음 네임스페이스에 어노테이션된 toleration을 pod의 toleration에 병합합니다. 결과 toleration은 네임스페이스에 어노테이션된 허용 toleration 목록과 대조합니다. 검사가 성공하면 pod 요청이 어드미션되고, 그렇지 않으면 거부됩니다.

pod의 네임스페이스에 연결된 기본(default) toleration이나 허용 toleration 어노테이션이 없으면, 지정된 경우 클러스터 수준 기본 toleration이나 클러스터 수준 허용 toleration 목록이 대신 사용됩니다.

네임스페이스에 toleration은 scheduler.alpha.kubernetes.io/defaultTolerations 어노테이션 키로 할당됩니다. 허용 toleration 목록은 scheduler.alpha.kubernetes.io/tolerationsWhitelist 어노테이션 키로 추가할 수 있습니다.

네임스페이스 어노테이션 예시:

apiVersion: v1
kind: Namespace
metadata:
  name: apps-that-need-nodes-exclusively
  annotations:
    scheduler.alpha.kubernetes.io/defaultTolerations: '[{"operator": "Exists", "effect": "NoSchedule", "key": "dedicated-node"}]'
    scheduler.alpha.kubernetes.io/tolerationsWhitelist: '[{"operator": "Exists", "effect": "NoSchedule", "key": "dedicated-node"}]'

이 어드미션 컨트롤러는 기본적으로 비활성화되어 있습니다.

PodTopologyLabels

FEATURE STATE: Kubernetes v1.35 [beta](기본 활성화)

유형: Mutating

PodTopologyLabels 어드미션 컨트롤러는 Node에 바인딩된 모든 pod의 pods/binding 하위 리소스를 변경해, 바인딩된 Node와 일치하는 토폴로지 라벨을 추가합니다. 이를 통해 Node 토폴로지 라벨을 pod 라벨로 사용할 수 있으며, Downward API를 사용해 실행 중인 컨테이너에 표면화할 수 있습니다. 이 컨트롤러의 결과로 사용할 수 있는 라벨은 topology.kubernetes.io/region과 topology.kubernetes.io/zone 라벨입니다.

참고:

어떤 변경(mutating) 어드미션 웹훅이 pods/binding 하위 리소스의 라벨을 추가하거나 수정하면, 이 컨트롤러의 결과로 이러한 변경이 pod 라벨로 전파되어 충돌하는 키의 라벨을 덮어씁니다.

이 어드미션 컨트롤러는 PodTopologyLabelsAdmission feature gate가 활성화되면 활성화됩니다.

Priority

유형: Mutating and Validating.

priority 어드미션 컨트롤러는 priorityClassName 필드를 사용해 priority의 정수 값을 채웁니다. priority class를 찾을 수 없으면 Pod는 거부됩니다.

ResourceQuota

유형: Validating.

이 어드미션 컨트롤러는 들어오는 요청을 관찰하고 Namespace의 ResourceQuota 객체에 열거된 제약 중 어느 것도 위반하지 않는지 확인합니다. Kubernetes 배포에서 ResourceQuota 객체를 사용한다면 쿼터 제약을 강제하기 위해 이 어드미션 컨트롤러를 반드시 사용해야 합니다.

자세한 내용은 ResourceQuota API reference와 Resource Quota 예시를 참고하세요.

RuntimeClass

유형: Mutating and Validating.

Pod overhead가 설정된 RuntimeClass를 정의하면 이 어드미션 컨트롤러가 들어오는 Pod를 확인합니다. 활성화되면 이 컨트롤러는 overhead가 이미 설정된 어떤 Pod 생성 요청도 거부합니다. .spec에 RuntimeClass가 설정되고 선택된 Pod의 경우, 이 어드미션 컨트롤러는 해당 RuntimeClass에 정의된 값을 기반으로 Pod의 .spec.overhead를 설정합니다.

자세한 내용은 Pod Overhead도 참고하세요.

ServiceAccount

유형: Mutating and Validating.

이 어드미션 컨트롤러는 serviceAccount를 위한 자동화를 구현합니다. Kubernetes 프로젝트는 이 어드미션 컨트롤러를 활성화할 것을 강력히 권장합니다. Kubernetes의 ServiceAccount 객체를 어떤 식으로든 사용할 계획이라면 이 어드미션 컨트롤러를 활성화해야 합니다.

Secrets 주변의 보안 조치를 강화하려면 별도의 네임스페이스를 사용해 마운트된 secret에 대한 접근을 격리하세요.

StorageObjectInUseProtection

유형: Mutating.

StorageObjectInUseProtection 플러그인은 새로 생성된 Persistent Volume Claim(PVC) 또는 Persistent Volume(PV)에 kubernetes.io/pvc-protection 또는 kubernetes.io/pv-protection finalizer를 추가합니다. 사용자가 PVC나 PV를 삭제하면 PVC 또는 PV 보호 컨트롤러가 PVC나 PV에서 finalizer를 제거할 때까지 해당 PVC나 PV는 제거되지 않습니다. 자세한 내용은 Storage Object in Use Protection을 참고하세요.

TaintNodesByCondition

유형: Mutating.

이 어드미션 컨트롤러는 새로 생성된 Node를 NotReady와 NoSchedule로 taint합니다. 이 taint 처리는 새 Node에서 taint가 보고된 조건을 정확히 반영하도록 업데이트되기 전에 Pod가 스케줄될 수 있는 경합 조건(race condition)을 피합니다.

ValidatingAdmissionPolicy

유형: Validating.

이 어드미션 컨트롤러는 일치하는 들어오는 요청에 대해 CEL 검증을 구현합니다. feature gate validatingadmissionpolicy와 admissionregistration.k8s.io/v1alpha1 그룹/버전이 모두 활성화되어 있을 때 활성화됩니다. 어떤 ValidatingAdmissionPolicy라도 실패하면 요청은 실패합니다.

ValidatingAdmissionWebhook

유형: Validating.

이 어드미션 컨트롤러는 요청과 일치하는 모든 검증(validating) 웹훅을 호출합니다. 일치하는 웹훅은 병렬로 호출되며, 그중 하나라도 요청을 거부하면 요청은 실패합니다. 이 어드미션 컨트롤러는 검증 단계에서만 실행됩니다. 이것이 호출하는 웹훅은 객체를 변경할 수 없는데, 이는 MutatingAdmissionWebhook 어드미션 컨트롤러가 호출하는 웹훅과 대조됩니다.

이것이 호출하는 웹훅에 부수 효과가 있다면(예: 쿼터 감소) 반드시 재조정 시스템이 있어야 합니다. 이후의 웹훅이나 다른 검증 어드미션 컨트롤러가 요청 완료를 허용할 것이라는 보장이 없기 때문입니다.

ValidatingAdmissionWebhook을 비활성화하면 admissionregistration.k8s.io/v1 그룹/버전의 ValidatingWebhookConfiguration 객체도 --runtime-config 플래그로 비활성화해야 합니다.

권장 어드미션 컨트롤러 세트가 있나요?

네. 권장 어드미션 컨트롤러는 기본적으로 활성화되어 있으므로(여기에서 확인) 명시적으로 지정할 필요가 없습니다. --enable-admission-plugins 플래그로 기본 세트를 넘어 추가 어드미션 컨트롤러를 활성화할 수 있습니다(순서는 상관없습니다).