사례7건

7건 중 1~5번째

1. IL-0183 kubeadm 으로 만든 클러스터의 1년짜리 인증서가 만료되어 kube-apiserver 가 etcd 와 TLS 연결을 맺지 못하고 재시작을 반복했고, 클러스터에 접속할 수 없게 됐다.

   ckck8032026

   증상

   외부에서 쿠버네티스 클러스터에 접속할 수 없었다. 작성자는 컨트롤 플레인 노드로 들어가 sudo systemctl status kubelet 으로 kubelet 로그를 확인했다.

   컨트롤 플레인 무응답컨테이너 재시작 반복

   촉발

   kubeadm 이 만든 하위 인증서의 기본 유효기간 1년이 2026-02-20 16:16 UTC 에 끝났다.

   원인

   인증서·자격 증명 만료

   구성 요소

   쿠버네티스 API 서버etcdkubeletCalico

   기여 요인

   기본 설정 방치

   감지

   외부에서 클러스터에 접속이 안 되는 것으로 알아챘다. 컨트롤 플레인 노드에서 kubelet 로그, containerd 로그, kube-apiserver 컨테이너 로그를 차례로 보다가 kube-apiserver 로그의 x509 만료 오류에서 원인을 확인했다.

   조치

   • sudo kubeadm certs renew all 로 만료된 인증서를 한 번에 갱신했다.
   • containerd 와 kubelet 을 재시작해 Static Pod 로 도는 컨트롤 플레인 컴포넌트를 새 인증서로 다시 띄웠다.
   • /etc/kubernetes/admin.conf 를 $HOME/.kube/config 로 복사하고 소유자를 바꿔 kubeconfig 를 새 인증서로 바꿨다.

   교훈

   sudo kubeadm certs check-expiration 으로 만료일을 주기적으로 확인하고, 만료 30일 전부터 갱신하는 것이 좋다. kubeadm upgrade apply 를 실행하면 인증서도 함께 갱신되므로, 1년에 한 번 이상 쿠버네티스 버전을 올리는 클러스터는 이 문제를 자연스럽게 피한다. 버전을 올리지 않고 오래 운영하는 클러스터라면 kubeadm certs renew all 과 kubelet 재시작을 cron 으로 매년 걸어 둘 수 있다. 작성자가 든 예시에서는 매년 1월 1일 새벽 3시에 실행한다.

   사례 보기
2. IL-0204 Render 프랑크푸르트 클러스터에서 etcd 메모리 급증으로 컨트롤 플레인이 과부하에 걸렸고, 컨트롤 플레인 노드를 재부팅하자 그 위의 CoreDNS 가 다시 뜨지 못해 DNS 가 멈췄다.

   Render2024

   증상

   2022년 1월 Render 의 프랑크푸르트 Kubernetes 클러스터 하나에서 새 배포와 크론 잡 실행이 실패했다. etcd 메모리 급증으로 컨트롤 플레인이 과부하에 걸린 상태였다.

   컨트롤 플레인 무응답배포 실패DNS 조회 실패오류율 상승

   촉발

   etcd 메모리가 급증해 Kubernetes 컨트롤 플레인이 과부하에 걸렸다.

   원인

   용량 한계

   구성 요소

   etcdCoreDNS쿠버네티스 API 서버

   기여 요인

   기본 설정 방치수동 조치 악화

   후속 조치

   • CoreDNS 를 컨트롤 플레인 노드가 아닌 데이터 플레인 노드에서 돌게 했다.
   • etcd 를 전용 노드에서 돌게 했다.

   교훈

   CoreDNS 는 API 서버가 내려가 있어도 메모리 캐시로 DNS 질의에 답할 수 있지만, 초기화할 때는 API 서버가 필요하다. CoreDNS 가 컨트롤 플레인 노드에 있었기 때문에, 컨트롤 플레인 장애 중에 노드를 재부팅하자 새 배포와 크론 잡만 실패하던 장애가 이미 돌던 서비스로 가는 요청까지 실패하는 장애로 커졌다. 핵심 문제는 데이터 플레인이 컨트롤 플레인에서 충분히 분리되어 있지 않았다는 점이다. 노드를 재부팅하지 않았더라도 etcd 메모리 급증만으로 CoreDNS 가 재시작될 수 있었다.

   사례 보기
3. IL-0194 kube-apiserver 재시작 뒤 Vector DaemonSet 의 파드 list 요청이 한꺼번에 몰려 etcd 메모리가 세 배 가까이 늘고 마스터 노드가 연쇄적으로 재시작했다.

   Palark2023

   증상

   일상적인 kube-apiserver 재시작 직후 etcd 메모리 사용량이 거의 세 배로 치솟았고, 그 여파로 모든 마스터 노드가 연쇄적으로 재시작했다. 고객사의 운영 클러스터였다.

   컨트롤 플레인 무응답데이터베이스 과부하

   촉발

   일상적인 kube-apiserver 재시작 뒤, Vector 로그 수집기 DaemonSet 의 파드 전부가 캐시를 다시 채우려고 한꺼번에 파드 list 요청을 보냈다.

   원인

   용량 한계

   구성 요소

   etcd쿠버네티스 API 서버텔레메트리 에이전트

   기여 요인

   한계 미인지기본 설정 방치

   감지

   kube-apiserver 재시작 직후 마스터 노드 전체 메모리와 etcd 메모리 그래프가 치솟고 마스터 노드가 연쇄적으로 재시작하면서 알았다. 원인이 된 DaemonSet 은 감사 로그를 보고 찾았다.

   조치

   • limit-list-custom 이라는 PriorityLevelConfiguration 을 만들어 요청 대기열을 설정했다. 값은 문서의 표준 설정을 그대로 썼다.
   • 같은 이름의 FlowSchema 를 만들어, 이 DaemonSet 서비스 어카운트가 보내는 파드 list 와 get 요청을 그 대기열로 보냈다.

   후속 조치

   • 쿠버네티스 Rust 라이브러리에 resourceVersion 설정을 넣는 PR 을 냈다.
   • Vector 로그 수집기 쪽에 이 문제를 고치는 PR 을 열었다.
   • Cilium CNI 에서도 비슷한 문제를 찾아 같은 방법으로 해결했다.

   교훈

   etcd 는 필드 셀렉터와 레이블 셀렉터를 모르기 때문에, kube-apiserver 에는 가벼워 보이는, 필터를 건 list 요청도 etcd 에서는 그 종류의 객체 전체를 읽는 일이 된다. 데이터가 꼭 최신이어야 하는 컨트롤러가 아니라면 resourceVersion=0 으로 kube-apiserver 캐시에서 읽게 할 수 있다. 다만 kube-apiserver 가 여러 대면 인스턴스마다 다른 데이터를 받을 수 있다. 여러 파드가 한꺼번에 보내는 요청은 Priority and Fairness 로 대기열에 넣어 kube-apiserver 와 etcd 를 지킬 수 있다. 위험한 것은 파드 요청만이 아니어서 Cilium CNI 에서도 비슷한 문제가 나왔다.

   사례 보기
4. IL-0190 쿠버네티스 업그레이드로 etcd 리더가 있던 노드가 갑자기 종료된 뒤, Cortex distributor 두 개가 옛 리더와 맺은 TCP 연결이 멈춘 채 그 연결을 계속 써서 런던 리전 Hosted Prometheus 쓰기가 12분 동안 일부 실패했다.

   Grafana Labs2020

   증상

   2020년 3월 16일 11:31 UTC에 SLO 기반 알림이 당직 엔지니어를 호출했다. 런던 리전 Hosted Prometheus 로 들어오는 쓰기의 약 20%가 실패하고 있었다. 문제는 이미 11분 전에 시작된 상태였다.

   오류율 상승간헐적 타임아웃

   촉발

   예약된 쿠버네티스 버전 업그레이드가 etcd 리더가 돌던 노드를 정상 종료 절차 없이 갑자기 종료했다.

   원인

   소프트웨어 결함

   구성 요소

   etcd노드 풀

   기여 요인

   기본 설정 방치파괴적 변경 보호 장치 부재

   감지

   SLO 기반 알림이 11:31 UTC에 당직 엔지니어를 호출했다. 장애가 시작되고 11분이 지난 시점이었다. 오류율이 20% 수준이었기 때문에 이대로 두었다면 월간 SLA 를 넘기기까지 약 18시간이 걸렸을 것이다.

   조치

   • 11:32 UTC에 영향받은 distributor 를 재시작했고, 오류가 멈췄다.

   후속 조치

   • Cortex 의 etcd 클라이언트 설정에 gRPC keepalive 프로브를 켠다. DialKeepAliveTime 은 10초, DialKeepAliveTimeout 은 DialTimeout 의 두 배로 두고 PermitWithoutStream 을 true 로 한다.
   • 쿠버네티스 업그레이드 절차를 고쳐, etcd operator 가 관리하는 etcd 파드까지 포함해 파드와 머신을 정상 종료 절차로 내리게 한다.

   교훈

   노드가 죽으면 TCP 연결이 정상적으로 닫히지 않고 멈춘 채 남을 수 있다. etcd 클라이언트에 keepalive 를 설정하지 않으면 새 리더가 뽑힌 뒤에도 클라이언트는 죽은 연결을 계속 쓴다. 노드를 내리는 업그레이드 스크립트는 operator 가 관리하는 파드까지 정상 종료할 수 있어야 한다. 장애 대응과 복구, 사후 분석 동안 Grafana Loki 로 로그를 빠르게 뒤질 수 있어서 복구 시간이 줄었다.

   사례 보기
5. IL-0076 dex의 AuthRequest 리소스가 끝없이 쌓였고, 이를 치우려고 네임스페이스를 지우자 목록 조회 타임아웃과 재시도가 반복되며 쿠버네티스 마스터가 내려갔다

   Fullstaq2019

   증상

   dex의 AuthRequest 리소스가 엄청난 수로 쌓여 있었다. 발표자는 그 전부터 이미 징후가 있었다고 했다.

   컨트롤 플레인 무응답모니터링 중단

   촉발

   dex의 잘못된 기본값 때문에 AuthRequest 리소스가 쌓였다. 발표는 원인으로 지나치게 긴 TTL, 계속 새로고침되는 대시보드, 실제 보안 버그를 꼽았다. 그리고 쌓인 리소스를 치우려고 dex 네임스페이스를 지우자 마스터가 내려갔다.

   원인

   용량 한계

   구성 요소

   쿠버네티스 API 서버etcd클러스터 인증 제공자

   기여 요인

   기본 설정 방치수동 조치 악화재시도 폭주디버그 접근 제한초기 신호 무시

   감지

   발표자는 그 전부터 이미 징후가 있었다고 했다. 마스터가 내려간 뒤에는 Slack에 경보가 많이 들어왔지만, 인증도 port-forward도 되지 않아 모니터링에는 들어갈 수 없었다.

   조치

   • kill-kube-ns 도구로 API를 직접 호출해 dex 네임스페이스에 남은 kubernetes finalizer를 지웠다.
   • dex를 적절한 기본값으로 설정해 새 네임스페이스에 다시 배포했다.

   교훈

   외부 도구의 기본값을 그대로 믿지 않는다. 목록 조회도 안 될 만큼 쌓인 리소스를 네임스페이스 삭제로 치우면 정리 루프가 타임아웃과 재시도를 반복해 마스터를 내릴 수 있다. 클러스터 인증이 클러스터 안에 있으면 클러스터가 죽었을 때 모니터링에도 들어갈 수 없다. API로 finalizer를 직접 지우는 방법은 발표자도 절대 하지 말라고 한 마지막 수단이다.

   사례 보기

원인별4