사례5건

5건 중 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-0087 RKE2 클러스터 노드를 재부팅한 뒤 Multus 가 쿠버네티스 API 에 닿지 못해 파드가 IP 를 받지 못했고, 같은 장애가 모든 노드로 번져 전체 서비스가 멈췄다.

   Fyra Labs2023

   증상

   ICT 기준 2023-04-09 새벽 2시쯤 클러스터 노드 하나가 평소와 다른 CPU 사용을 보였다. 팀은 containerd 와 runc 의 상위 프로젝트에 있는 CRI 버그로 추정했다. 이 노드가 다른 서비스를 모두 스로틀링해 서비스가 실패하고 있었다.

   노드 CPU 고부하서비스 중단

   촉발

   평소와 다른 CPU 사용을 보인 노드를 바로잡으려고, 시스템을 쓰는 사람이 없는 시간이라고 보고 클러스터를 정비 상태로 내린 뒤 영향받은 노드를 전부 재부팅했다.

   원인

   unknown

   구성 요소

   Multus 메타 CNICalico컨테이너 런타임

   기여 요인

   수동 조치 악화미검증 가정

   감지

   새벽 2시쯤 노드 하나의 평소와 다른 CPU 사용을 발견했다. 재부팅 뒤 2시 30분쯤 일부 서비스에서 이상한 문제가 보여 네트워크 장애를 알아챘고, 6시 31분에는 개발자들이 Terra 저장소가 내려갔다고 알려 왔다.

   조치

   • Multus 와 Calico 를 완전히 지우고 Cilium CNI 로 바꿨다.
   • 14:30 ICT 까지 CNI 를 뺀 클러스터 설정 대부분을 되돌려 모든 서비스를 다시 올렸다.

   교훈

   팀은 처음 장애를 저절로 풀릴 일시적인 문제로 보고 다른 노드까지 재부팅했는데, 이 판단은 완전히 틀렸고 장애가 모든 노드로 번졌다. 바꿔 넣은 Cilium 은 이 클러스터에서 Calico 보다도 잘 동작했다. 팀은 한 블로그 글의 자원 사용량 비교를 보고 Cilium 을 피했었지만, 실제로는 Calico, Canal, Flannel 과 마찬가지로 노드당 1코어라는 허용 범위 안에서 돌았다. 작은 클러스터에서는 Cilium 의 조금 더 큰 자원 사용량이 문제가 되지 않았다.

   사례 보기
3. IL-0060 쿠버네티스 1.24 업그레이드로 node-role.kubernetes.io/master 레이블이 사라지자 이 레이블에 기대던 Calico 라우트 리플렉터가 동작을 멈춰 레거시 클러스터의 네트워크가 모두 끊기고 Reddit 이 314분 동안 멈췄다

   Reddit2023

   증상

   2023년 3월 14일 19시 UTC 직후 엔지니어가 Old Reddit 이라 불리는 레거시 스택을 돌리는 클러스터의 업그레이드를 시작했다. 2분쯤은 괜찮아 보였지만 곧 사이트 전체가 갑자기 멈췄다. CDN 엣지의 상태 코드별 RPS 그래프가 이를 보여 주었다. 사용자는 오류 페이지나 글이 하나도 없는 홈페이지를 보았다.

   서비스 중단오류율 상승DNS 조회 실패모니터링 중단파드 ContainerCreating 정체컨트롤 플레인 지연

   촉발

   Reddit 에서 가장 중요한 클러스터 가운데 하나인 레거시 클러스터를 쿠버네티스 1.23 에서 1.24 로 업그레이드했다.

   원인

   업그레이드로 깨진 호환성

   구성 요소

   Calico쿠버네티스 API 서버어드미션 웹훅etcd

   기여 요인

   코드로 관리되지 않는 설정스테이징 불일치미검증 백업모니터링 사각지대단일 장애점

   감지

   업그레이드를 시작하고 2분쯤 뒤 CDN 엣지의 상태 코드별 RPS 그래프에서 사이트가 멈춘 것이 보였다. 팀은 곧바로 장애를 선언했고 3분 안에 대응 인원이 통화에 모였다. 엣지 지표는 일부러 클러스터와 분리되어 있어 살아 있었지만, 클러스터 자체의 지표는 모두 사라졌다.

   조치

   • API 서버에서 타임아웃을 내던 Open Policy Agent 의 웹훅 설정을 지웠다.
   • 복원 뒤 어차피 쓸 수 없게 될 워커 노드를 모두 종료했다.
   • 컨트롤 플레인 노드 두 대를 종료하고, 남은 한 대의 구성 요소를 다운그레이드한 뒤 그 노드에 백업 데이터를 복원했다.
   • 단일 노드 컨트롤 플레인이 부하에 무너지지 않도록 클러스터 오토스케일러를 껐다.
   • 새 컨트롤 플레인 노드를 띄우고, 호스트명이 맞지 않던 TLS 인증서를 새로 만들어 노드들을 합류시켰다.
   • 트래픽을 1% 에서 시작해 5%, 10%, 20%, 35%, 55%, 80%, 100% 로 조금씩 늘렸다.
   • 트래픽이 돌아올 때 문제를 일으키지 않도록 손으로 멈춰 두었던 민감한 레거시 서비스를 조심스럽게 다시 켰다.

   후속 조치

   • 클러스터 구성을 코드로 관리해 모든 선택에 기록이 남게 하고, 코드로 만들 수 없는 것은 자세히 문서로 남긴다.
   • 클러스터마다 다른 맞춤형 구성을 걷어 내고 모든 클러스터의 구성 요소를 표준화한다.
   • 모든 클러스터를 최대한 같은 모습으로 유지하고 필요하면 다시 만들거나 복제할 수 있도록 클러스터 전체의 수명 주기를 관리하는 도구를 만든다.
   • 믿고 테스트에 쓸 수 있는 프리프로덕션 클러스터를 더 둔다.
   • 백업 복원 절차를 개선하고 클러스터 업그레이드를 안전하게 만든다.

   교훈

   쿠버네티스 버전과 구성 요소 업그레이드는 여전히 위험하다. 미리 테스트하고 검증해도 이번처럼 처음 보는 방식으로 깨질 수 있다. 쿠버네티스에는 공식 다운그레이드 절차가 없어, 롤백하는 방법은 백업에서 복원하는 것뿐이다. 복원 절차가 환경 변화를 따라가지 못하면 실제 장애 때 그 자리에서 고쳐 써야 하고, 복원을 결정하기까지 오래 망설이게 된다. 이번 복원은 결국 성공했지만 절차는 개선해야 한다. 코드로 남기지 않은 설정은 아는 사람이 떠나면 아무 기록도 남지 않는다. 라우트 리플렉터 설정이 어디에도 커밋되어 있지 않아 장애 중에 누구도 의심하지 못했다. 지표가 클러스터 안에서만 수집되면 클러스터가 망가질 때 함께 사라진다. 이번에는 로그 수집 에이전트가 영향을 받지 않아 원인을 추적할 수 있었다. 클러스터마다 다른 맞춤형 구성이 쌓이면 장애가 잦아진다. 직접 원인은 노드 레이블이었지만 근본 원인은 일관성 부족이었다.

   사례 보기
4. IL-0139 Calico 네트워크 정책을 쓰는 GKE 클러스터를 1.22 이상으로 업그레이드하자 경쟁 조건 때문에 CNI 정리가 Unauthorized 로 실패해 파드가 Terminating 이나 Pending 에 멈췄다.

   Google Cloud2022

   증상

   GKE 를 1.22 이상으로 업그레이드한 뒤 Calico 네트워크 정책을 쓰는 클러스터에서 파드가 Terminating 이나 Pending 상태에서 빠져나오지 못했다. 실제로 파드가 멈춘 클러스터는 소수였다.

   파드 Terminating 정체파드 Pending

   촉발

   Calico 네트워크 정책을 켠 GKE 클러스터를 1.22 이상 버전으로 업그레이드했다.

   원인

   소프트웨어 결함

   구성 요소

   Calicokubelet파드 종료 처리

   기여 요인

   –

   조치

   • 1.24.4-gke.800 에 수정을 넣고 1.23 과 1.22 로 백포트했으며, 고객이 수정 버전으로 직접 업그레이드할 수 있게 했다.
   • 영향받는 버전의 고객에게 Google Cloud 지원팀을 통해 내부 패치를 적용받도록 권했다.
   • kubelet 과 calico-node 를 재시작해 멈춘 파드를 풀어 주는 우회책을 안내했다.
   • Calico 가 꼭 필요하지 않은 고객에게는 Calico 네트워크 정책을 끄는 우회책을 안내했다.

   후속 조치

   • 1.22 나 1.23 을 쓰는 RAPID, REGULAR, STABLE 릴리스 채널의 클러스터를 앞으로 몇 주에 걸쳐 수정 버전으로 자동 업그레이드한다.

   교훈

   클러스터 오토스케일러를 쓰면 이 경쟁 조건에 걸릴 확률이 높아진다. 수정 버전으로 올리기 전에는 kubelet 과 calico-node 를 재시작해 멈춘 파드를 풀 수 있고, Calico 가 꼭 필요하지 않다면 Calico 네트워크 정책을 끄는 방법도 있다.

   사례 보기
5. IL-0086 테스트 Kubernetes 클러스터용 배포가 운영 클러스터의 Traefik 과 Calico 리소스까지 지워 CircleCI UI 와 runner.circleci.com 이 1시간 54분 동안 내려갔다.

   CircleCI2021

   증상

   2021년 3월 11일 15:35 EST 에 CircleCI UI 에 접속할 수 없게 됐다. API 는 별도 인그레스로 들어오기 때문에 계속 응답했고 빌드도 계속 돌았다.

   서비스 중단리소스 삭제

   촉발

   테스트 Kubernetes 클러스터를 대상으로 한 배포가 테스트 클러스터와 운영 클러스터 양쪽에서 Traefik 과 Calico 리소스를 지웠다.

   원인

   배포 결함

   구성 요소

   인그레스 컨트롤러Calico

   기여 요인

   과도한 영향 범위런북 부재모니터링 사각지대

   감지

   알림을 받은 엔지니어들이 조사를 시작했다. 상태 페이지에는 20:45 UTC 에 첫 공지가 올라왔다.

   조치

   • 지워진 Traefik 을 복구했다.
   • Calico 를 복구해 운영 클러스터의 파드가 다시 고객 요청을 처리하게 했다.

   후속 조치

   • Kubernetes 네트워크의 여러 계층을 모두 다루도록 네트워크 수준 문서와 런북을 보강한다.
   • 네트워크 인프라 쪽 모니터링과 알림을 개선했다.
   • 운영 클러스터와 스테이징 클러스터가 서로 간섭하지 않도록 둘을 더 확실히 떼어 놓는 안전장치를 추가한다.

   교훈

   테스트 클러스터용 배포가 운영 클러스터의 리소스를 건드릴 수 있으면 스테이징 작업이 곧 운영 장애가 된다. 스테이징 배포가 운영에 영향을 줬다는 사실이 바로 보이지 않아 조사가 DNS 와 AWS 에서 시작됐다. Traefik 만 되살려서는 복구되지 않았고 Calico 와 Traefik 의 관계까지 알아야 했다. CircleCI 는 Kubernetes 네트워크의 모든 계층을 담은 문서와 런북이 필요하다고 정리했다.

   사례 보기

원인별5