Kubernetes 1.35: 버전화된 z‑pages API를 통한 향상된 디버깅

Source: Kubernetes Blog

z‑pages란?

z‑pages는 Kubernetes 컨트롤‑플레인 컴포넌트가 노출하는 특수 디버깅 엔드포인트입니다. Kubernetes 1.32에서 알파 기능으로 도입된 이 엔드포인트는 다음과 같은 컴포넌트에 대한 런타임 진단을 제공합니다:

• kube-apiserver
• kube-controller-manager
• kube-scheduler
• kubelet
• kube-proxy

“z‑pages”라는 이름은 디버깅 엔드포인트에 /*z 경로를 사용하는 관례에서 유래되었습니다.

현재 z‑page 엔드포인트

이 엔드포인트는 컴포넌트 상태를 빠르게 확인해야 하는 사람 운영자에게 유용하지만, 지금까지는 플레인 텍스트 출력만 제공해 프로그램적으로 파싱하기 어려웠습니다.

Kubernetes 1.35의 새로운 기능은 무엇인가요?

Kubernetes 1.35는 구조화된 버전 관리 응답을 /statusz와 /flagz 모두에 도입했습니다. 주요 개선 사항:

• 하위 호환성 유지 – 평문 텍스트가 여전히 기본값입니다.
• 선택적 JSON 출력 추가 – 기계가 읽을 수 있고 버전이 지정됩니다.

하위 호환성 설계

새로운 구조화된 응답은 옵트인 방식입니다. Accept 헤더를 지정하지 않으면 엔드포인트는 기존의 익숙한 평문 텍스트 형식을 그대로 반환합니다:

$ 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 헤더를 포함합니다:

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

/statusz 응답 예시

{
  "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. 향상된 디버깅 도구 – 개발자는 구성 요소 간 설정을 비교(diff)하고, 시간에 따른 드리프트를 추적하며, 정교한 진단을 구축할 수 있습니다.
3. API 버전 관리 및 안정성 – 버전이 지정된 API(v1alpha1)를 도입하면 명확한 마이그레이션 경로(향후 v1beta1, 그 다음 v1)를 제공하여 도구가 릴리스 간에 안정적으로 유지됩니다.

구조화된 z‑pages 사용 방법

전제 조건

두 엔드포인트 모두 해당 feature gates가 활성화되어 있어야 합니다:

예시: curl 로 구조화된 응답 받기

# Structured statusz response
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 .

# Structured flagz response
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 .

참고

• 예시에서는 client‑certificate authentication을 사용하고 --cacert 로 서버 인증서를 검증합니다.
• 테스트 환경에서는 --insecure(또는 -k) 로 검증을 우회할 수 있지만, 절대 프로덕션에서는 사용하지 마세요 – 중간자 공격에 노출됩니다.

중요한 고려 사항

알파 기능 상태

• 구조화된 z‑page 응답은 Kubernetes 1.35에서 알파 단계입니다.
• API 형식은 향후 릴리스에서 변경될 수 있습니다.
• 이러한 엔드포인트는 디버깅용으로 설계되었으며, 프로덕션‑중요 자동화를 위해서는 사용하지 마세요.
• 베타 또는 안정화 상태가 될 때까지 중요한 모니터링에 의존하지 마세요.

보안 및 접근 제어

z‑pages는 내부 컴포넌트 정보를 노출하므로 적절한 접근 제어가 필수적입니다:

• 신뢰할 수 있는 사용자 또는 서비스 계정에만 접근을 제한하세요.
• 네트워크 정책, RBAC, TLS 클라이언트 인증을 사용해 노출을 제한하세요.
• /*z 엔드포인트에 접근 가능한 대상을 정기적으로 감사하세요.

TL;DR

• Kubernetes 1.35는 /statusz와 /flagz에 선택적 JSON 출력을 추가합니다.
• Accept: application/json;v=v1alpha1;g=config.k8s.io;as=… 헤더를 사용해 JSON을 요청합니다.
• 기능 게이트 ComponentStatusz와 ComponentFlagz를 활성화해야 합니다.
• 구조화된 데이터를 자동 검사, 보다 풍부한 디버깅 도구, 미래 지향적인 통합에 활용하세요—단, 이 기능은 아직 알파 단계이며 엄격한 접근 제어로 보호해야 함을 기억하십시오.

z‑page 엔드포인트에 대한 접근

z‑page 엔드포인트에 대한 접근은 system:monitoring 그룹 구성원에게만 제한되며, 이는 /healthz, /livez, /readyz와 같은 다른 디버깅 엔드포인트와 동일한 권한 모델을 따릅니다. 이를 통해 권한이 부여된 사용자와 서비스 계정만 디버깅 정보를 조회할 수 있습니다.

• 클러스터가 RBAC를 사용한다면, 이 그룹에 적절한 권한을 부여하여 접근을 관리하십시오.

인증

이 엔드포인트에 대한 인증 요구 사항은 클러스터 구성에 따라 달라집니다.

• 익명 인증이 활성화되지 않은 경우, 일반적으로 클라이언트 인증서와 같은 인증 메커니즘을 사용하여 이 엔드포인트에 접근해야 합니다.

정보 공개

이 엔드포인트는 클러스터 구성 요소에 대한 설정 정보를 공개합니다. 포함되는 내용은 다음과 같습니다:

• 구성 요소 버전 및 빌드 정보
• 모든 명령줄 인수와 그 값(민감한 값은 가려짐)
• 사용 가능한 디버그 엔드포인트

권고사항: 신뢰할 수 있는 운영자와 디버깅 도구에만 접근을 허용하십시오. 이 수준의 접근이 필요하지 않은 무단 사용자나 자동화 시스템에 엔드포인트를 노출하지 마세요.

향후 발전

기능이 성숙해짐에 따라 Kubernetes SIG Instrumentation 팀은 다음을 기대합니다:

1. v1beta1을 도입하고 궁극적으로 API의 v1 버전을 제공할 예정입니다.
2. 응답 스키마에 대한 커뮤니티 피드백을 수집합니다.
3. 사용자 요구에 따라 추가적인 z‑page 엔드포인트를 추가할 가능성이 있습니다.

시도해 보기

우리는 테스트 환경에서 구조화된 z‑pages를 실험해 보시길 권장합니다:

1. Enable the ComponentStatusz and ComponentFlagz feature gates on your control‑plane components.
2. Query the endpoints using both plain‑text and structured formats.
3. Build a simple tool or script that consumes the structured data.
4. Share your feedback with the community.

자세히 알아보기

• z‑pages 문서
• KEP‑4827: Component Statusz
• KEP‑4828: Component Flagz
• Kubernetes Slack의 #sig-instrumentation 채널에서 토론에 참여하세요.

참여하기

피드백을 듣고 싶습니다! 구조화된 z‑pages 기능은 Kubernetes를 더 쉽게 디버그하고 모니터링하도록 설계되었습니다. 여러분이:

• 내부 도구 구축
• 오픈소스 프로젝트 기여
• 기능 탐색

어떤 경우든 여러분의 의견은 Kubernetes 관측 가능성의 미래를 형성하는 데 도움이 됩니다.

• 질문, 제안 또는 이슈가 있나요? Slack의 SIG Instrumentation에 연락하거나 정기 커뮤니티 회의에 참석하세요.

디버깅을 즐기세요!