Kubernetes 1.35: 버전이 적용된 z-페이지 API를 통한 향상된 디버깅 기능

Kubernetes 1.35: 버전이 적용된 z-페이지 API를 통한 향상된 디버깅 기능

쿠버네티스 컨트롤 플레인 컴포넌트 디버깅은 어려울 수 있습니다. 특히 컴포넌트의 런타임 상태를 신속하게 파악하거나 구성을 확인할 때 더욱 그렇습니다. 쿠버네티스 1.35에서는 z-페이지 디버깅 엔드포인트에 구조화되고 기계가 파싱할 수 있는 응답 기능을 추가하여 도구 개발 및 문제 해결 워크플로우 자동화를 더욱 용이하게 합니다.

z-페이지란 무엇인가요?

현재 쿠버네티스는 두 가지 주요 z-페이지 엔드포인트를 지원합니다.

/statusz

버전 정보, 시작 시간, 가동 시간, 사용 가능한 디버그 경로를 포함한 높은 수준의 컴포넌트 정보를 표시합니다.

/flagz

컴포넌트 시작에 사용된 모든 커맨드라인 인수 및 해당 값(보안을 위해 기밀 값은 수정됨)을 보여줍니다.

이러한 엔드포인트는 사람이 컴포넌트 상태를 신속하게 검사하는 데 유용했지만, 지금까지는 프로그래밍 방식으로 파싱하기 어려운 일반 텍스트 출력만 반환했습니다.

쿠버네티스 1.35의 새로운 기능은 무엇인가요?

하위 호환 가능한 디자인

$ curl --cert /etc/kubernetes/pki/apiserver-kubelet-client.crt \
--key /etc/kubernetes/pki/apiserver-kubelet-client.key \
--cacert /etc/kubernetes/pki/ca.crt \
https://localhost:6443/statusz
kube-apiserver statusz
Warning: This endpoint is not meant to be machine parseable, has no formatting compatibility guarantees and is for debugging purposes only.
Started: Wed Oct 16 21:03:43 UTC 2024
Up: 0 hr 00 min 16 sec
Go version: go1.23.2
Binary version: 1.35.0-alpha.0.1595
Emulation version: 1.35
Paths: /healthz /livez /metrics /readyz /statusz /version

구조화된 JSON 응답

Accept: application/json;v=v1alpha1;g=config.k8s.io;as=Statusz

그러면 버전이 적용된 JSON 응답이 반환됩니다.

{
 "kind": "Statusz",
 "apiVersion": "config.k8s.io/v1alpha1",
 "metadata": {
 "name": "kube-apiserver"
 },
 "startTime": "2025-10-29T00:30:01Z",
 "uptimeSeconds": 856,
 "goVersion": "go1.23.2",
 "binaryVersion": "1.35.0",
 "emulationVersion": "1.35",
 "paths": [
 "/healthz",
 "/livez",
 "/metrics",
 "/readyz",
 "/statusz",
 "/version"
 ]
}

마찬가지로, /flagz는 다음 헤더를 사용하여 구조화된 응답을 지원합니다.

Accept: application/json;v=v1alpha1;g=config.k8s.io;as=Flagz

예시 응답:

{
 "kind": "Flagz",
 "apiVersion": "config.k8s.io/v1alpha1",
 "metadata": {
 "name": "kube-apiserver"
 },
 "flags": {
 "advertise-address": "192.168.8.4",
 "allow-privileged": "true",
 "authorization-mode": "[Node,RBAC]",
 "enable-priority-and-fairness": "true",
 "profiling": "true"
 }
}

구조화된 응답이 중요한 이유

1. **자동화된 상태 확인 및 모니터링**

2. **더 나은 디버깅 도구**

3. **API 버전 관리 및 안정성**

구조화된 z-페이지 사용 방법

전제 조건

• /statusz: ComponentStatusz 기능 게이트를 활성화합니다.
• /flagz: ComponentFlagz 기능 게이트를 활성화합니다.

예시: 구조화된 응답 받기

# 구조화된 statusz 응답 받기
curl \
 --cert /etc/kubernetes/pki/apiserver-kubelet-client.crt \
 --key /etc/kubernetes/pki/apiserver-kubelet-client.key \
 --cacert /etc/kubernetes/pki/ca.crt \
 -H "Accept: application/json;v=v1alpha1;g=config.k8s.io;as=Statusz" \
 https://localhost:6443/statusz | jq .

# 구조화된 flagz 응답 받기
curl \
 --cert /etc/kubernetes/pki/apiserver-kubelet-client.crt \
 --key /etc/kubernetes/pki/apiserver-kubelet-client.key \
 --cacert /etc/kubernetes/pki/ca.crt \
 -H "Accept: application/json;v=v1alpha1;g=config.k8s.io;as=Flagz" \
 https://localhost:6443/flagz | jq .

중요 고려 사항

알파 기능 상태

• API 형식은 향후 릴리스에서 변경될 수 있습니다.
• 이러한 엔드포인트는 디버깅용이며, 프로덕션 자동화용이 아닙니다.
• 이러한 기능이 베타 또는 안정(stable) 상태에 도달하기 전까지는 중요한 모니터링 워크플로우에 의존하지 않아야 합니다.

보안 및 접근 제어

인가(Authorization): z-페이지 엔드포인트에 대한 접근은 system:monitoring 그룹의 구성원으로 제한되며, 이는 /healthz, /livez, /readyz와 같은 다른 디버깅 엔드포인트와 동일한 인가 모델을 따릅니다. 이는 승인된 사용자 및 서비스 계정만 디버깅 정보에 접근할 수 있도록 보장합니다. 클러스터가 RBAC를 사용하는 경우, 이 그룹에 적절한 권한을 부여하여 접근을 관리할 수 있습니다.

인증(Authentication): 이 엔드포인트에 대한 인증 요구 사항은 클러스터 구성에 따라 달라집니다. 클러스터에 익명 인증이 활성화되어 있지 않는 한, 일반적으로 클라이언트 인증서와 같은 인증 메커니즘을 사용하여 이러한 엔드포인트에 접근해야 합니다.

정보 공개(Information disclosure): 이러한 엔드포인트는 클러스터 컴포넌트에 대한 구성 세부 정보를 공개하며, 다음을 포함합니다.

• 컴포넌트 버전 및 빌드 정보
• 모든 커맨드라인 인수 및 해당 값(기밀 값은 수정됨)
• 사용 가능한 디버그 엔드포인트

신뢰할 수 있는 운영자와 디버깅 도구에만 접근 권한을 부여해야 합니다. 이러한 수준의 접근이 필요 없는 승인되지 않은 사용자나 자동화 시스템에는 이 엔드포인트를 노출하지 마십시오.

향후 발전

• API의 v1beta1 및 궁극적으로 v1 버전을 도입합니다.
• 응답 스키마에 대한 커뮤니티 피드백을 수집합니다.
• 사용자 요구에 따라 추가 z-페이지 엔드포인트를 잠재적으로 추가합니다.

지금 사용해보세요

1. 컨트롤 플레인 컴포넌트에서 ComponentStatusz 및 ComponentFlagz 기능 게이트를 활성화합니다.
2. 일반 텍스트 형식과 구조화된 형식으로 엔드포인트를 쿼리해 봅니다.
3. 구조화된 데이터를 사용하는 간단한 도구 또는 스크립트를 만들어 봅니다.
4. 커뮤니티와 피드백을 공유합니다.

더 알아보기

참여하기

질문, 제안 또는 문제가 발생하면 SIG Instrumentation에 문의하십시오. 슬랙이나 정기적인 커뮤니티 회의에서 만날 수 있습니다.

즐거운 디버깅 되세요!