혼합 버전 프록시

혼합 버전 프록시 (Mixed Version Proxy)

기능 상태: Kubernetes v1.36부터 Beta; 기본적으로 활성화.

Kubernetes 1.37에는 API Server가 리소스 요청을 다른 피어(peer) API 서버로 프록시하게 해 주는 베타 기능이 포함돼 있어요. 또한 클라이언트가 디스커버리를 통해 클러스터 전체에서 서빙되는 리소스의 전체적인 관점을 얻을 수 있게 해 줘요. 하나의 클러스터에 서로 다른 버전의 쿠버네티스를 실행하는 여러 API 서버가 있을 때(예: 새 쿠버네티스 릴리스로의 오래 걸리는 롤아웃 중) 유용해요.

이 기능은 클러스터 관리자가 더 안전하게 업그레이드할 수 있는 고가용성 클러스터를 구성할 수 있게 해 줘요. 다음을 통해요.

중요한 작업을 위한 포괄적인 리소스 목록을 보여주기 위해 디스커버리에 의존하는 컨트롤러가 항상 모든 리소스의 완전한 관점을 얻도록 보장해요. 이를 피어 집계 디스커버리(Peer-aggregated discovery)라고 불러요.
(업그레이드 중 이루어지는) 리소스 요청을 올바른 kube-apiserver로 보내요. 이 프록시는 사용자가 업그레이드 과정에서 오는 예상치 못한 404 Not Found 오류를 보지 못하게 해요. 이 메커니즘을 혼합 버전 프록시(Mixed Version Proxy)라고 불러요.

출처: 문서

본문

피어 집계 디스커버리와 혼합 버전 프록시 활성화하기 (Enabling Peer-aggregated Discovery and Mixed Version Proxy)

API Server를 시작할 때 UnknownVersionInteroperabilityProxy 기능 게이트가 활성화돼 있는지 확인하세요.

kube-apiserver \
--feature-gates=UnknownVersionInteroperabilityProxy=true \
# 이 기능에 필요한 필수 명령줄 인자
--peer-ca-file=<kube-apiserver CA 인증서 경로>
--proxy-client-cert-file=<aggregator proxy 인증서 경로>,
--proxy-client-key-file=<aggregator proxy 키 경로>,
--requestheader-client-ca-file=<aggregator CA 인증서 경로>,
# requestheader-allowed-names는 어떤 Common Name도 허용하려면 비워 둘 수 있음
--requestheader-allowed-names=<proxy 클라이언트 인증서를 검증할 유효한 Common Names>,

# 이 기능의 선택적 플래그
--peer-advertise-ip=`피어가 요청을 프록시할 때 사용해야 하는 이 kube-apiserver의 IP`
--peer-advertise-port=`피어가 요청을 프록시할 때 사용해야 하는 이 kube-apiserver의 포트`

# …그 외 평소처럼 플래그 사용

API 서버 간 프록시 전송과 인증 (Proxy transport and authentication between API servers)

소스 kube-apiserver는 기존 APIserver 클라이언트 인증 플래그인 --proxy-client-cert-file과 --proxy-client-key-file을 재사용해, 피어(대상 kube-apiserver)가 검증할 자신의 정체성을 제시해요. 대상 API 서버는 --requestheader-client-ca-file 명령줄 인자로 지정한 구성에 따라 피어 연결을 검증해요.

대상 서버의 서빙 인증서를 인증하려면, 소스 API 서버에 --peer-ca-file 명령줄 인자를 지정해 인증 기관 번들을 구성해야 해요.

피어 API 서버 연결성 구성 (Configuration for peer API server connectivity)

피어가 요청을 프록시할 때 사용할 kube-apiserver의 네트워크 위치를 설정하려면 kube-apiserver에 --peer-advertise-ip와 --peer-advertise-port 명령줄 인자를 사용하거나 API 서버 구성 파일에 이 필드들을 지정하세요. 이 플래그들이 지정되지 않으면 피어는 kube-apiserver의 --advertise-address 또는 --bind-address 명령줄 인자 값을 사용해요. 그것들도 설정되지 않았다면 호스트의 기본 인터페이스를 사용해요.

피어 집계 디스커버리 (Peer-aggregated discovery)

기능을 활성화하면 디스커버리 요청이 기본적으로 포괄적인 디스커버리 문서(클러스터의 모든 apiserver가 서빙하는 모든 리소스를 나열)를 제공하도록 자동 활성화돼요. 비-피어 집계 디스커버리 문서를 요청하려면 디스커버리 요청에 다음 Accept 헤더를 추가해 표시할 수 있어요.

application/json;g=apidiscovery.k8s.io;v=v2;as=APIGroupDiscoveryList;profile=nopeer

참고: 피어 집계 디스커버리는 /apis 엔드포인트에 대한 Aggregated Discovery 요청에서만 지원되고, Unaggregated(Legacy) Discovery 요청에서는 지원되지 않아요.

혼합 버전 프록시 (Mixed version proxying)

혼합 버전 프록시를 활성화하면 집계 계층(aggregation layer)이 다음을 수행하는 특수 필터를 로드해요.

리소스 요청이 그 API를 서빙할 수 없는 API 서버(API 도입 이전 버전이거나 API 서버에서 API가 꺼져 있기 때문)에 도달하면, API 서버가 그 요청을 요청된 API를 서빙할 수 있는 피어 API 서버로 보내려 시도해요. 로컬 서버가 인식하지 못하는 API 그룹/버전/리소스를 식별하고, 그 요청을 처리할 수 있는 피어 API 서버로 프록시하려 시도해요.
피어 API 서버가 응답에 실패하면, 소스 API 서버는 503("Service Unavailable") 오류로 응답해요.

내부 동작 방식 (How it works under the hood)

API Server가 리소스 요청을 받으면 먼저 요청된 리소스를 서빙할 수 있는 API 서버를 확인해요. 이 확인은 비-피어 집계 디스커버리 문서를 사용해 이루어져요.

리소스가 요청을 받은 API 서버에서 가져온 비-피어 집계 디스커버리 문서(예: GET /api/v1/pods/some-pod)에 나열돼 있으면, 요청은 로컬로 처리돼요.
요청의 리소스(예: GET /apis/resource.k8s.io/v1beta1/resourceclaims)가 요청을 처리하려는 API 서버(처리 API 서버)에서 가져온 비-피어 집계 디스커버리 문서에 없으면, 아마도 resource.k8s.io/v1beta1 API가 더 새로운 쿠버네티스 버전에서 도입됐고 처리 API 서버가 이를 지원하지 않는 더 오래된 버전을 실행 중이기 때문일 거예요. 그러면 처리 API 서버는 모든 피어 API 서버의 비-피어 집계 디스커버리 문서를 확인해 관련 API 그룹/버전/리소스(이 경우 resource.k8s.io/v1beta1/resourceclaims)를 서빙하는 피어 API 서버를 찾아요. 그런 다음 처리 API 서버는 요청된 리소스를 아는 일치하는 피어 kube-apiserver 중 하나로 요청을 프록시해요.
그 API 그룹/버전/리소스에 대해 알려진 피어가 없으면, 처리 API 서버는 요청을 자체 핸들러 체인에 넘기고, 결국 404("Not Found") 응답을 반환해야 해요.
처리 API 서버가 피어 API 서버를 식별하고 선택했지만 그 피어가 응답에 실패하면(네트워크 연결 문제나, 요청이 수신되는 것과 컨트롤러가 피어 정보를 컨트롤 플레인에 등록하는 것 사이의 데이터 경합 같은 이유로), 처리 API 서버는 503("Service Unavailable") 오류로 응답해요.