Admission 웹훅 모범 사례

Admission 웹훅 모범 사례 (Admission Webhook Good Practices)

이 페이지는 쿠버네티스에서 admission 웹훅을 설계할 때의 모범 사례와 고려 사항을 제공해요. 이 정보는 admission 웹훅 서버를 실행하거나 여러분의 API 요청을 수정/검증하는 서드파티 애플리케이션을 운영하는 클러스터 운영자를 위한 것이에요.

이 페이지를 읽기 전에 다음 개념에 익숙한지 확인하세요:

• Admission 컨트롤러
• Admission 웹훅

출처: 문서

본문

좋은 웹훅 설계의 중요성

Admission 제어는 생성, 업데이트, 삭제 요청이 쿠버네티스 API로 전송될 때 발생해요. Admission 컨트롤러는 여러분이 정의한 특정 기준과 일치하는 요청을 가로채요. 이 요청들은 그런 다음 변형(mutating) admission 웹훅이나 검증(validating) admission 웹훅으로 보내져요. 이 웹훅들은 종종 객체 스펙의 특정 필드가 존재하거나 특정 허용 값이 있는지 보장하도록 작성돼요.

웹훅은 쿠버네티스 API를 확장하는 강력한 메커니즘이에요. 잘못 설계된 웹훅은 클러스터의 객체에 대한 제어권이 많기 때문에 종종 워크로드 중단을 초래해요. 다른 API 확장 메커니즘처럼, 웹훅은 모든 워크로드, 다른 웹훅, 애드온, 플러그인과의 호환성을 위해 대규모로 테스트하기 어려워요.

또한 매 릴리스마다 쿠버네티스는 새 기능, 베타나 안정 상태로의 기능 승격, 폐기(deprecation)로 API를 추가하거나 수정해요. 심지어 안정적인 쿠버네티스 API조차 변경될 가능성이 커요. 예를 들어 Pod API는 v1.29에서 사이드카 컨테이너 기능을 추가하도록 변경됐어요. 쿠버네티스 객체가 새 쿠버네티스 API 때문에 손상된 상태로 들어가는 것은 드물지만, 이전 버전의 API에서 예상대로 작동하던 웹훅이 그 API의 더 최근 변경 사항을 조정하지 못할 수 있어요. 이는 클러스터를 새 버전으로 업그레이드한 후 예기치 않은 동작을 초래할 수 있어요.

이 페이지는 일반적인 웹훅 실패 시나리오와, 웹훅을 신중하고 사려 깊게 설계하고 구현함으로써 그것들을 피하는 방법을 설명해요.

admission 웹훅을 사용하는지 식별하기

자신의 admission 웹훅을 실행하지 않더라도, 클러스터에서 실행하는 일부 서드파티 애플리케이션이 변형 또는 검증 admission 웹훅을 사용할 수 있어요.

클러스터에 어떤 변형 admission 웹훅이 있는지 확인하려면 다음 명령을 실행해요:

kubectl get mutatingwebhookconfigurations

출력은 클러스터의 모든 변형 admission 컨트롤러를 나열해요.

클러스터에 어떤 검증 admission 웹훅이 있는지 확인하려면 다음 명령을 실행해요:

kubectl get validatingwebhookconfigurations

출력은 클러스터의 모든 검증 admission 컨트롤러를 나열해요.

admission 제어 메커니즘 선택

쿠버네티스는 여러 admission 제어 및 정책 강제 옵션을 포함해요. 특정 옵션을 언제 사용해야 하는지 아는 것은 지연 시간과 성능을 개선하고, 관리 오버헤드를 줄이며, 버전 업그레이드 중 문제를 피하는 데 도움이 될 수 있어요. 다음 표는 admission 중에 리소스를 변형하거나 검증할 수 있게 해주는 메커니즘을 설명해요:

메커니즘	설명	사용 사례
변형 admission 웹훅	admission 전에 API 요청을 가로채 사용자 지정 로직으로 필요에 따라 수정.	리소스 admission 전에 일어나야 하는 중요 수정. 외부 API 호출 같은 고급 로직이 필요한 복잡한 수정.
변형 admission 정책	admission 전에 API 요청을 가로채 CEL 표현식을 사용해 필요에 따라 수정.	리소스 admission 전에 일어나야 하는 중요 수정. 레이블이나 레플리카 수 조정 같은 단순한 수정.
검증 admission 웹훅	admission 전에 API 요청을 가로채 복잡한 정책 선언에 대해 검증.	리소스 admission 전에 중요 구성 검증. admission 전에 복잡한 정책 로직 강제.
검증 admission 정책	admission 전에 API 요청을 가로채 CEL 표현식에 대해 검증.	리소스 admission 전에 중요 구성 검증. CEL 표현식을 사용한 정책 로직 강제.

일반적으로 로직을 선언하거나 구성하는 확장 가능한 방식을 원할 때 웹훅 admission 제어를 사용해요. 웹훅 서버 실행의 오버헤드 없이 더 단순한 로직을 선언하려면 내장 CEL 기반 admission 제어를 사용해요. 쿠버네티스 프로젝트는 가능하면 CEL 기반 admission 제어를 사용할 것을 권장해요.

CustomResourceDefinitions에 내장 검증과 기본값 설정 사용하기

CustomResourceDefinition을 사용한다면, CustomResource 스펙의 값을 검증하거나 필드의 기본값을 설정하기 위해 admission 웹훅을 사용하지 마세요. 쿠버네티스는 CustomResourceDefinition을 만들 때 검증 규칙과 기본 필드 값을 정의할 수 있게 해줘요.

자세한 내용은 다음 리소스를 참조하세요:

• 검증 규칙(Validation rules)
• 기본값 설정(Defaulting)

성능과 지연 시간

이 섹션은 성능을 개선하고 지연 시간을 줄이기 위한 권장 사항을 설명해요. 요약하면 다음과 같아요:

• 웹훅을 통합하고 웹훅당 API 호출 수를 제한하기.
• 감사 로그를 사용해 반복적으로 같은 작업을 하는 웹훅을 확인하기.
• 웹훅 가용성을 위해 로드 밸런싱 사용하기.
• 각 웹훅에 작은 타임아웃 값 설정하기.
• 웹훅 설계 중 클러스터 가용성 요구 사항 고려하기.

낮은 지연 시간을 위한 admission 웹훅 설계

변형 admission 웹훅은 순차적으로 호출돼요. 변형 웹훅 설정에 따라 일부 웹훅이 여러 번 호출될 수 있어요. 모든 변형 웹훅 호출은 admission 과정에 지연 시간을 더해요. 이것은 병렬로 호출되는 검증 웹훅과는 달라요.

변형 웹훅을 설계할 때 지연 시간 요구 사항과 허용 범위를 고려하세요. 클러스터에 변형 웹훅이 많을수록 지연 시간이 증가할 가능성이 커져요.

지연 시간을 줄이기 위해 다음을 고려하세요:

• 다른 객체에 대해 비슷한 변형을 수행하는 웹훅을 통합하기.
• 변형 웹훅 서버 로직에서 이루어지는 API 호출 수를 줄이기.
• 특정 API 요청에 의해 트리거되는 웹훅 수를 줄이도록 각 변형 웹훅의 일치 조건을 제한하기.
• 순서와 구성을 돕기 위해 작은 웹훅을 하나의 서버와 구성으로 통합하기.

경쟁 컨트롤러로 인한 루프 방지

클러스터에서 실행 중인, 여러분의 웹훅이 만드는 변형과 충돌할 수 있는 다른 컴포넌트를 고려하세요. 예를 들어 웹훅이 다른 컨트롤러가 제거하는 레이블을 추가하면 웹훅이 다시 호출돼요. 이것은 루프로 이어져요.

이러한 루프를 감지하려면 다음을 시도해 보세요:

• 감사 이벤트를 기록하도록 클러스터 감사 정책을 업데이트해요. 다음 파라미터를 사용해요: level: RequestResponse, verbs: ["patch"], omitStages: RequestReceived. 웹훅이 변형하는 특정 리소스에 대한 이벤트를 만들도록 감사 규칙을 설정해요.
• 같은 객체에 같은 패치가 적용되며 웹훅이 여러 번 재호출되는지, 또는 객체가 필드를 여러 번 업데이트하고 되돌리는지 감사 이벤트를 확인해요.

작은 타임아웃 값 설정

Admission 웹훅은 API 요청 지연 시간에 더해지므로 가능한 한 빨리(보통 밀리초 단위로) 평가해야 해요. 웹훅에 작은 타임아웃을 사용하세요.

자세한 내용은 타임아웃(Timeouts)을 참조하세요.

로드 밸런서를 사용해 웹훅 가용성 보장

Admission 웹훅은 높은 가용성과 성능 이점을 제공하기 위해 어떤 형태의 로드 밸런싱을 활용해야 해요. 웹훅이 클러스터 내에서 실행되고 있다면, ClusterIP 유형의 Service 뒤에서 여러 웹훅 백엔드를 실행할 수 있어요.

고가용성 배포 모델 사용

웹훅을 설계할 때 클러스터의 가용성 요구 사항을 고려하세요. 예를 들어 노드 중단이나 영역(zonal) 중단 중에 쿠버네티스는 로드 밸런서가 트래픽을 사용 가능한 영역과 노드로 다시 라우팅할 수 있도록 파드를 NotReady로 표시해요. 이러한 파드 업데이트는 변형 웹훅을 트리거할 수 있어요. 영향받는 파드 수에 따라 변형 웹훅 서버는 타임아웃되거나 파드 처리에 지연을 일으킬 위험이 있어요. 결과적으로 트래픽이 필요한 만큼 빨리 다시 라우팅되지 않을 수 있어요.

웹훅을 작성할 때 앞의 예시와 같은 상황을 고려하세요. 피할 수 없는 사고에 대한 응답으로 일어나는 쿠버네티스의 작업 결과인 작업을 제외하세요.

요청 필터링

이 섹션은 어떤 요청이 특정 웹훅을 트리거하는지 필터링하기 위한 권장 사항을 제공해요. 요약하면 다음과 같아요:

• 시스템 컴포넌트와 읽기 전용 요청을 피하도록 웹훅 범위를 제한하기.
• 웹훅을 특정 네임스페이스로 제한하기.
• 세분화된 요청 필터링을 위해 일치 조건(match conditions) 사용하기.
• 객체의 모든 버전 일치시키기.

각 웹훅의 범위 제한

Admission 웹훅은 API 요청이 해당 웹훅 구성과 일치할 때만 호출돼요. 웹훅 서버에 대한 불필요한 호출을 줄이도록 각 웹훅의 범위를 제한하세요. 다음 범위 제한을 고려하세요:

• kube-system 네임스페이스의 객체 매칭을 피하세요. kube-system 네임스페이스에서 자신의 파드를 실행한다면, 중요한 워크로드를 변형하지 않도록 objectSelector를 사용하세요.
• kube-node-lease 시스템 네임스페이스에 Lease 객체로 존재하는 노드 리스를 변형하지 마세요. 노드 리스를 변형하면 노드 업그레이드가 실패할 수 있어요. 이 네임스페이스의 Lease 객체에 대한 검증 제어는 그 제어가 클러스터를 위험에 빠뜨리지 않을 것이라고 확신할 때만 적용하세요.
• TokenReview, SubjectAccessReview, 또는 다른 가상 인증 및 권한 부여 리소스를 일치시키지 마세요. 이것들은 항상 읽기 전용 요청이며, 그것들을 가로채면 클러스터를 깨뜨릴 수 있어요. 쿠버네티스 v1.37부터 admission 웹훅은 기본적으로 이러한 리소스에 대해 호출되지 않아요.
• namespaceSelector를 사용해 각 웹훅을 특정 네임스페이스로 제한하세요.

일치 조건을 사용해 특정 요청 필터링

Admission 컨트롤러는 특정 기준을 충족하는 요청을 일치시키기 위해 사용할 수 있는 여러 필드를 지원해요. 예를 들어 특정 네임스페이스를 대상으로 하는 요청을 필터링하기 위해 namespaceSelector를 사용할 수 있어요.

더 세분화된 요청 필터링을 위해 웹훅 구성의 matchConditions 필드를 사용하세요. 이 필드를 사용하면 요청이 admission 웹훅을 트리거하기 위해 true로 평가되어야 하는 여러 CEL 표현식을 작성할 수 있어요. matchConditions를 사용하면 웹훅 서버에 대한 호출 수를 크게 줄일 수 있어요.

자세한 내용은 일치하는 요청: matchConditions를 참조하세요.

API의 모든 버전 일치시키기

기본적으로 admission 웹훅은 지정된 리소스에 영향을 주는 모든 API 버전에서 실행돼요. 웹훅 구성의 matchPolicy 필드가 이 동작을 제어해요. 모든 API 버전에서 웹훅이 실행되도록 하려면 matchPolicy 필드에 Equivalent 값을 지정하거나 필드를 생략하세요.

자세한 내용은 일치하는 요청: matchPolicy를 참조하세요.

변형 범위와 필드 고려 사항

이 섹션은 변형의 범위와 객체 필드에 대한 특별한 고려 사항에 대한 권장 사항을 제공해요. 요약하면 다음과 같아요:

• 패치해야 할 필드만 패치하기.
• 배열 값을 덮어쓰지 않기.
• 가능하면 변형에서 부작용을 피하기.
• 자기 변형을 피하기.
• 실패 열기(fail open)와 최종 상태 검증.
• 이후 버전의 향후 필드 업데이트를 계획하기.
• 웹훅이 자기 트리거하는 것을 방지하기.
• 변경 불가능한 객체를 변경하지 않기.

필수 필드만 패치

Admission 웹훅 서버는 특정 쿠버네티스 API 요청으로 무엇을 할지 나타내기 위해 HTTP 응답을 보내요. 이 응답은 AdmissionReview 객체예요. 변형 웹훅은 응답의 patchType 필드와 patch 필드를 사용해 admission을 허용하기 전에 변형할 특정 필드를 추가할 수 있어요. 변경이 필요한 필드만 수정하도록 하세요.

예를 들어 웹 서버 Deployment가 최소 3개의 레플리카를 갖도록 보장하도록 구성된 변형 웹훅을 고려해 보세요. Deployment 객체를 만들라는 요청이 웹훅 구성과 일치하면, 웹훅은 spec.replicas 필드의 값만 업데이트해야 해요.

배열 값 덮어쓰지 않기

쿠버네티스 객체 스펙의 필드는 배열을 포함할 수 있어요. 일부 배열은 키:값 쌍을 포함하고(컨테이너 스펙의 envVar 필드처럼), 다른 배열은 키가 없어요(파드 스펙의 readinessGates 필드처럼). 배열 필드의 값 순서는 어떤 상황에서는 중요할 수 있어요. 예를 들어 컨테이너 스펙의 args 필드의 인수 순서는 컨테이너에 영향을 줄 수 있어요.

배열을 수정할 때 다음을 고려하세요:

• 가능하면 필수 값을 실수로 교체하지 않도록 replace 대신 add JSONPatch 작업을 사용하기.
• 키:값 쌍을 사용하지 않는 배열을 집합으로 취급하기.
• 수정하는 필드의 값이 특정 순서로 있어야 하는 것은 아닌지 확인하기.
• 꼭 필요하지 않으면 기존 키:값 쌍을 덮어쓰지 않기.
• 레이블 필드를 수정할 때 주의하기. 실수로 수정하면 레이블 셀렉터가 깨져 의도하지 않은 동작이 발생할 수 있어요.

부작용 피하기

웹훅이 보내진 AdmissionReview 내용에만 작동하고 대역 외(out-of-band) 변경을 하지 않도록 하세요. 부작용(side effects)이라고 하는 이러한 추가 변경은 제대로 조정되지 않으면 admission 중에 충돌을 일으킬 수 있어요. 웹훅에 부작용이 없다면 .webhooks[].sideEffects 필드는 None으로 설정해야 해요.

admission 평가 중에 부작용이 필요하다면, dryRun이 true로 설정된 AdmissionReview 객체를 처리할 때 부작용이 억제되어야 하며, .webhooks[].sideEffects 필드는 NoneOnDryRun으로 설정해야 해요.

자세한 내용은 부작용(Side effects)을 참조하세요.

자기 변형 피하기

클러스터 내에서 실행되는 웹훅은 자신의 파드를 시작하는 데 필요한 리소스를 가로채도록 구성되면 자신의 배포에 데드락을 일으킬 수 있어요.

예를 들어 변형 admission 웹훅이 특정 레이블(예: env: prod)이 파드에 설정된 경우에만 파드 생성 요청을 승인하도록 구성되어 있다고 해요. 웹훅 서버는 env 레이블을 설정하지 않은 Deployment에서 실행돼요.

웹훅 서버 파드를 실행하는 노드가 불건전해지면, 웹훅 Deployment가 파드를 다른 노드로 재스케줄링하려고 해요. 그러나 기존 웹훅 서버는 env 레이블이 설정되지 않았으므로 요청을 거부해요. 결과적으로 마이그레이션이 일어날 수 없어요.

namespaceSelector로 웹훅이 실행되는 네임스페이스를 제외하세요.

의존성 루프 피하기

의존성 루프는 다음과 같은 시나리오에서 발생할 수 있어요:

• 두 웹훅이 서로의 파드를 확인해요. 두 웹훅이 동시에 사용 불가능해지면 어느 웹훅도 시작할 수 없어요.
• 웹훅이 네트워킹 플러그인이나 저장소 플러그인 같은 웹훅이 의존하는 클러스터 애드온 컴포넌트를 가로채요. 웹훅과 의존 애드온 모두 사용 불가능해지면 어느 컴포넌트도 기능할 수 없어요.

이러한 의존성 루프를 피하려면 다음을 시도해 보세요:

• 의존성을 도입하지 않도록 ValidatingAdmissionPolicies를 사용하기.
• 웹훅이 다른 웹훅을 검증하거나 변형하지 못하게 하기. 특정 네임스페이스를 웹훅 트리거에서 제외하는 것을 고려하세요.
• objectSelector를 사용해 웹훅이 의존 애드온에 작용하지 못하게 하기.

실패 열기와 최종 상태 검증

변형 admission 웹훅은 failurePolicy 구성 필드를 지원해요. 이 필드는 웹훅이 실패하면 API 서버가 요청을 승인 또는 거부해야 하는지를 나타내요. 웹훅 실패는 타임아웃이나 서버 로직의 오류 때문에 발생할 수 있어요.

기본적으로 admission 웹훅은 failurePolicy 필드를 Fail로 설정해요. API 서버는 웹훅이 실패하면 요청을 거부해요. 그러나 기본적으로 요청을 거부하면 웹훅 중단 동안 준수(compliant) 요청이 거부될 수 있어요.

failurePolicy 필드를 Ignore로 설정해 변형 웹훅이 "실패 열기(fail open)"하게 하세요. 요청 상태를 확인해 정책을 준수하는지 보장하기 위해 검증 컨트롤러를 사용하세요.

이 접근 방식은 다음 이점이 있어요:

• 변형 웹훅 중단이 준수 리소스의 배포에 영향을 주지 않아요.
• 정책 강제가 검증 admission 제어 중에 발생해요.
• 변형 웹훅이 클러스터의 다른 컨트롤러를 방해하지 않아요.

필드의 향후 업데이트 계획

일반적으로 쿠버네티스 API가 이후 버전에서 변경될 수 있다는 가정 하에 웹훅을 설계하세요. API의 안정성을 당연하게 여기는 서버를 작성하지 마세요. 예를 들어 쿠버네티스의 사이드카 컨테이너 릴리스는 Pod API에 restartPolicy 필드를 추가했어요.

웹훅이 스스로 트리거하는 것 방지

광범위한 API 요청에 응답하는 변형 웹훅은 실수로 스스로를 트리거할 수 있어요. 예를 들어 클러스터의 모든 요청에 응답하는 웹훅을 고려해 보세요. 모든 변형에 대해 Event 객체를 만들도록 웹훅을 구성하면, 웹훅은 자신의 Event 객체 생성 요청에 응답할 거예요.

이를 피하려면 웹훅이 만드는 모든 리소스에 고유한 레이블을 설정하는 것을 고려하세요. 이 레이블을 웹훅 일치 조건에서 제외하세요.

변경 불가능한 객체 변경하지 않기

API 서버의 일부 쿠버네티스 객체는 변경될 수 없어요. 예를 들어 정적 파드(static Pod)를 배포하면 노드의 kubelet이 정적 파드를 추적하기 위해 API 서버에 미러 파드를 만들어요. 그러나 미러 파드에 대한 변경은 정적 파드로 전파되지 않아요.

admission 중에 이러한 객체를 변형하려 하지 마세요. 모든 미러 파드는 kubernetes.io/config.mirror 어노테이션을 가져요. 어노테이션 무시의 보안 위험을 줄이면서 미러 파드를 제외하려면, 정적 파드가 특정 네임스페이스에서만 실행되도록 허용하세요.

변형 웹훅 순서와 멱등성

이 섹션은 웹훅 순서와 멱등적(idempotent) 웹훅 설계에 대한 권장 사항을 제공해요. 요약하면 다음과 같아요:

• 특정 실행 순서에 의존하지 않기.
• admission 전에 변형을 검증하기.
• 다른 컨트롤러가 변형을 덮어쓰는지 확인하기.
• 개별 웹훅뿐 아니라 변형 웹훅 집합이 멱등적이도록 보장하기.

변형 웹훅 호출 순서에 의존하지 않기

변형 admission 웹훅은 일관된 순서로 실행되지 않아요. 다양한 요인이 특정 웹훅이 호출되는 때를 변경할 수 있어요. 웹훅이 admission 과정의 특정 시점에 실행된다고 의존하지 마세요. 다른 웹훅이 여전히 수정한 객체를 변형할 수 있어요.

의도하지 않은 변경의 위험을 최소화하는 데 다음 권장 사항이 도움이 될 수 있어요:

• admission 전에 변형을 검증하기.
• 재호출 정책(reinvocation policy)을 사용해 다른 플러그인의 객체 변경을 관찰하고 필요에 따라 웹훅을 재실행하기. 자세한 내용은 재호출 정책(Reinvocation policy)을 참조하세요.

클러스터의 변형 웹훅이 멱등적이도록 보장

모든 변형 admission 웹훅은 멱등적이어야 해요. 웹훅은 이미 수정한 객체에 대해 원래 변경 외의 추가 변경 없이 실행될 수 있어야 해요.

또한 클러스터의 모든 변형 웹훅은 집합적으로 멱등적이어야 해요. admission 제어의 변형 단계가 끝난 후, 모든 개별 변형 웹훅은 객체에 추가 변경을 하지 않고서도 객체에서 실행될 수 있어야 해요.

환경에 따라 대규모로 멱등성을 보장하는 것은 어려울 수 있어요. 다음 권장 사항이 도움이 될 수 있어요:

• 검증 admission 컨트롤러를 사용해 중요 워크로드의 최종 상태를 확인하기.
• 스테이징 클러스터에서 배포를 테스트해 같은 웹훅에 의해 객체가 여러 번 수정되는지 확인하기.
• 각 변형 웹훅의 범위가 구체적이고 제한되도록 보장하기.

다음 예시는 멱등적 변형 로직을 보여 줘요:

• 파드 생성 요청에 대해 파드의 .spec.securityContext.runAsNonRoot 필드를 true로 설정하기.
• 파드 생성 요청에 대해 컨테이너의 .spec.containers[].resources.limits 필드가 설정되지 않았으면 기본 리소스 한도를 설정하기.
• 파드 생성 요청에 대해 foo-sidecar라는 이름의 컨테이너가 아직 없으면 이름이 foo-sidecar인 사이드카 컨테이너를 주입하기.

이러한 경우 웹훅은 안전하게 재호출되거나 필드가 이미 설정된 객체를 승인할 수 있어요.

다음 예시는 비멱등적 변형 로직을 보여 줘요:

• 파드 생성 요청에 대해 현재 타임스탬프(예: foo-sidecar-19700101-000000)가 접미사로 붙은 foo-sidecar라는 이름의 사이드카 컨테이너를 주입하기. 웹훅을 재호출하면 같은 사이드카가 파드에 여러 번 주입되고, 매번 다른 컨테이너 이름이 될 수 있어요. 마찬가지로, 사이드카가 이미 사용자가 제공한 파드에 존재한다면 웹훅이 중복 컨테이너를 주입할 수 있어요.
• 파드 생성/업데이트 요청에 대해 파드에 env 레이블이 설정되어 있으면 거부하고, 그렇지 않으면 env: prod 레이블을 파드에 추가하기. 웹훅을 재호출하면 웹훅이 자신의 출력에서 실패할 거예요.
• 파드 생성 요청에 대해 foo-sidecar 컨테이너가 존재하는지 확인하지 않고 foo-sidecar라는 이름의 사이드카 컨테이너를 추가하기. 웹훅을 재호출하면 파드에 중복 컨테이너가 생겨 요청이 유효하지 않게 되고 API 서버가 거부해요.

변형 테스트와 검증

이 섹션은 변형 웹훅을 테스트하고 변형된 객체를 검증하기 위한 권장 사항을 제공해요. 요약하면 다음과 같아요:

• 스테이징 환경에서 웹훅 테스트하기.
• 검증을 위반하는 변형 피하기.
• 회귀와 충돌에 대해 마이너 버전 업그레이드 테스트하기.
• admission 전에 변형된 객체 검증하기.

스테이징 환경에서 웹훅 테스트하기

강력한 테스트는 새롭거나 업데이트된 웹훅의 릴리스 주기의 핵심 부분이어야 해요. 가능하면 프로덕션 클러스터와 매우 유사한 스테이징 환경에서 클러스터 웹훅의 변경을 테스트하세요. 최소한 minikube나 kind 같은 도구를 사용해 웹훅 변경을 위한 작은 테스트 클러스터를 만드는 것을 고려하세요.

변형이 검증을 위반하지 않도록 보장

변형 웹훅은 admission 전에 객체에 적용되는 검증 중 어떤 것도 깨뜨리면 안 돼요. 예를 들어 파드의 기본 CPU 요청을 특정 값으로 설정하는 변형 웹훅을 고려해 보세요. 그 파드의 CPU 한도가 변형된 요청보다 낮게 설정되어 있으면 파드는 admission에 실패해요.

모든 변형 웹훅을 클러스터에서 실행되는 검증에 대해 테스트하세요.

마이너 버전 업그레이드 테스트로 일관된 동작 보장

프로덕션 클러스터를 새 마이너 버전으로 업그레이드하기 전에 스테이징 환경에서 웹훅과 워크로드를 테스트하세요. 결과를 비교해 업그레이드 후에도 웹훅이 예상대로 계속 기능하는지 확인하세요.

또한 API 변경에 대해 잘 알고 있게 다음 리소스를 사용하세요:

• 쿠버네티스 릴리스 노트
• 쿠버네티스 블로그

admission 전에 변형 검증하기

변형 웹훅은 검증 웹훅이 실행되기 전에 완료까지 실행돼요. 객체에 변형이 적용되는 안정적인 순서는 없어요. 결과적으로 변형이 나중에 실행되는 변형 웹훅에 의해 덮어써질 수 있어요.

변형이 여전히 존재하는지 확인하기 위해 ValidatingAdmissionWebhook이나 ValidatingAdmissionPolicy 같은 검증 admission 컨트롤러를 클러스터에 추가하세요. 예를 들어 특정 이닛 컨테이너를 사이드카 컨테이너로 실행되게 만들기 위해 restartPolicy: Always 필드를 삽입하는 변형 웹훅을 고려해 보세요. 모든 변형이 완료된 후 이닛 컨테이너가 restartPolicy: Always 구성을 유지했는지 확인하기 위해 검증 웹훅을 실행할 수 있어요.

자세한 내용은 다음 리소스를 참조하세요:

• 검증 admission 정책(Validating Admission Policy)
• ValidatingAdmissionWebhooks

변형 웹훅 배포

이 섹션은 변형 admission 웹훅을 배포하기 위한 권장 사항을 제공해요. 요약하면 다음과 같아요:

• 웹훅 구성을 점진적으로 롤아웃하고 네임스페이스별로 문제를 모니터링하기.
• 웹훅 구성 리소스를 편집할 수 있는 접근을 제한하기.
• 서버가 클러스터 내에 있으면 웹훅 서버를 실행하는 네임스페이스에 대한 접근을 제한하기.

변형 웹훅 설치와 활성화

변형 웹훅을 클러스터에 배포할 준비가 되면 다음 작업 순서를 사용하세요:

• 웹훅 서버를 설치하고 시작하기.
• MutatingWebhookConfiguration 매니페스트의 failurePolicy 필드를 Ignore로 설정하기. 이는 잘못 구성된 웹훅으로 인한 중단을 피하게 해줘요.
• MutatingWebhookConfiguration 매니페스트의 namespaceSelector 필드를 테스트 네임스페이스로 설정하기.
• MutatingWebhookConfiguration을 클러스터에 배포하기.

테스트 네임스페이스에서 웹훅을 모니터링해 문제가 없는지 확인한 다음, 웹훅을 다른 네임스페이스로 롤아웃하세요. 웹훅이 의도하지 않았던 API 요청을 가로채면 롤아웃을 일시 중지하고 웹훅 구성의 범위를 조정하세요.

변형 웹훅에 대한 편집 접근 제한

변형 웹훅은 강력한 쿠버네티스 컨트롤러예요. RBAC 또는 다른 권한 부여 메커니즘을 사용해 웹훅 구성과 서버에 대한 접근을 제한하세요. RBAC의 경우 다음 접근이 신뢰된 엔티티에만 제공되도록 하세요:

• 동사: create, update, patch, delete, deletecollection
• API 그룹: admissionregistration.k8s.io/v1
• API 유형: MutatingWebhookConfigurations

변형 웹훅 서버가 클러스터 내에서 실행된다면, 그 네임스페이스의 리소스를 만들거나 수정하는 접근을 제한하세요.

좋은 구현의 예시

다음 프로젝트는 "좋은" 사용자 지정 웹훅 서버 구현의 예시예요. 그것들을 자신의 웹훅을 설계할 때 시작점으로 사용할 수 있어요. 이 예시를 그대로 사용하지 말고, 시작점으로 사용하고 특정 환경에서 잘 실행되도록 웹훅을 설계하세요.

• cert-manager
• Gatekeeper Open Policy Agent (OPA)

더 알아보기 (Learn more)

• 인증과 권한 부여에 웹훅 사용하기.
• MutatingAdmissionPolicies에 대해 배우기.
• ValidatingAdmissionPolicies에 대해 배우기.