사례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-0154 SFO3 코어 라우터의 라인 카드가 하드웨어 오류로 한꺼번에 재부팅된 뒤 게스트 네트워킹이 돌아오지 않은 DOKS 노드가 비정상으로 남아, 일부 클러스터의 연결과 컨트롤 플레인 접속이 01:40 UTC까지 불안정했다.

   DigitalOcean2024

   증상

   2024년 9월 25일 22:25 UTC부터 SFO3 리전의 DigitalOcean 서비스 전반에서 네트워크 연결 문제가 생겼다. 리전 전체 서비스는 22:50에 회복됐지만 일부 Managed Kubernetes 클러스터는 그 뒤에도 연결이 불안정했다.

   노드 NotReady컨트롤 플레인 무응답간헐적 연결 실패

   촉발

   SFO3 코어 라우터 한 대에서 하드웨어 오류로 라인 카드 대부분이 동시에 재부팅됐다.

   원인

   DNS·네트워크 장애

   구성 요소

   쿠버네티스 API 서버kubelet

   기여 요인

   –

   조치

   • 죽었던 라인 카드가 모두 빠르게 다시 올라와 네트워크 트래픽이 다시 흐르고 코어 라우터가 정상으로 돌아왔다.
   • SFO3 리전 DOKS 전체에서 영향받은 노드를 손으로 모두 재생성했다.

   후속 조치

   • 장비 벤더 지원팀과 함께 라인 카드가 죽은 근본 원인을 찾는다.
   • SFO3 리전 코어 라우터의 소프트웨어를 업그레이드한다.
   • 자동 복구 조치의 임계값을 높여 사람이 손으로 노드를 복구해야 하는 일을 줄인다.

   교훈

   네트워크가 몇 분 만에 돌아와도 게스트 네트워킹이 회복되지 않은 노드는 사람이 재생성할 때까지 비정상으로 남았다. 리전 전체 서비스는 25분 만에 돌아왔지만 DOKS 는 01:40까지 영향을 받았다. 자동 복구 조치가 이 경우를 처리하지 못해 SFO3 DOKS 전체에서 수동 작업이 필요했다.

   사례 보기
3. IL-0184 kubeadm 클러스터의 API 서버와 내부 인증서가 만료돼 JupyterHub KubeSpawner 가 컨테이너를 만들지 못하고 kubectl 연결이 거부됐다

   dbhang2021

   증상

   JupyterHub 의 KubeSpawner 로 컨테이너를 만들 때 처음 보는 오류가 나며 생성이 실패했다. 오류는 SSL 인증서가 만료됐다는 내용이었다.

   컨트롤 플레인 무응답배포 실패

   원인

   인증서·자격 증명 만료

   구성 요소

   쿠버네티스 API 서버kubelet

   기여 요인

   한계 미인지한계 경보 부재

   감지

   KubeSpawner 가 컨테이너를 만들다가 처음 보는 SSL 인증서 오류를 냈다. 글쓴이는 오류 로그를 검색해 클러스터 내부 인증서 만료가 원인임을 알았다.

   조치

   • `kubeadm alpha certs check-expiration` 으로 인증서별 남은 기간을 확인했다.
   • 기존 인증서 파일과 `/etc/kubernetes/*.conf` 파일을 백업 디렉터리로 옮겼다.
   • `kubeadm init phase certs all` 로 모든 인증서를 새로 만들었다.
   • `kubeadm init phase kubeconfig all` 로 admin.conf 를 비롯한 kubeconfig 파일을 새로 만들었다.
   • 새 admin.conf 를 `~/.kube/config` 로 복사하고 kubelet 을 재시작했다.
   • 예전 인증 정보를 들고 있던 kube-system 컨테이너들을 `docker restart` 로 모두 재시작했다.

   교훈

   kubeadm 클러스터의 인증서가 만료되면 kubectl 이 API 서버에 연결하지 못하므로 kubectl 로는 갱신할 수 없고, 노드에서 kubeadm 으로 직접 갱신해야 한다. 갱신 뒤에는 인증서만이 아니라 kubeconfig 파일도 새로 만들어야 하고, 예전 인증 정보를 들고 있는 kube-system 파드도 재시작해야 한다. 글쓴이는 클러스터를 처음부터 직접 구성해 봤다면 인증서를 쓴다는 것을 바로 알았을 것이고, 명령 한 줄로 막을 수 있는 문제였다고 돌아봤다.

   사례 보기
4. IL-0008 응답하지 않는 OPA 검증 웹훅 때문에 GKE 마스터 업그레이드가 멈추고 API 서버가 간헐적으로 끊기면서 노드가 끝없이 재생성됐다

   Jetstack2019

   증상

   Jetstack 은 europe-west1 에 있는 GKE 리전 클러스터의 마스터를 업그레이드하고 있었다. 이 개발 클러스터는 여러 팀이 낮 동안 앱을 시험하는 데 쓴다. GKE Terraform 파이프라인으로 업그레이드를 시작했는데, 마스터 업그레이드가 20분으로 잡아 둔 Terraform 타임아웃 안에 끝나지 않았다. GKE 콘솔에는 클러스터가 여전히 업그레이드 중으로 나왔다.

   업그레이드 정체컨트롤 플레인 무응답노드 재생성 반복서비스 중단

   촉발

   마스터 업그레이드 중 두 번째 마스터 인스턴스의 API 서버가 ca-registration PostStartHook 을 실행하면서 kube-system 의 extension-apiserver-authentication ConfigMap 을 갱신하려 했다. 이 요청은 설정해 둔 OPA 검증 웹훅의 백엔드가 응답하지 않아 타임아웃 났다.

   원인

   설정 변경

   구성 요소

   어드미션 웹훅GKE 컨트롤 플레인쿠버네티스 API 서버kubelet

   기여 요인

   과도한 영향 범위헬스 프로브 부재모니터링 사각지대자동화 증폭

   감지

   GKE Terraform 파이프라인으로 시작한 마스터 업그레이드가 20분으로 잡아 둔 Terraform 타임아웃 안에 끝나지 않은 것이 첫 신호였다. 파이프라인을 다시 돌리자 kube-apiserver 가 unhealthy 라는 오류가 났다. 원인은 Google Support 의 도움을 받아 찾았다.

   조치

   • API 서버에 간헐적으로 접근될 때를 이용해 OPA 의 ValidatingAdmissionWebhook 리소스를 지워 클러스터를 복구했다.

   후속 조치

   • OPA 의 ValidatingAdmissionWebhook 이 정책이 적용되고 개발 팀이 접근하는 네임스페이스만 보도록 범위를 좁혔다.
   • 웹훅을 정책이 실제로 검증하는 Ingress 와 Service 리소스에만 켰다.
   • OPA 가 응답하지 않으면 재시작되도록 liveness probe 를 더하고 문서를 고쳤다.
   • 이 동작을 개선하자는 쿠버네티스 업스트림 이슈가 아직 열려 있어, 그 진행을 지켜본다.

   교훈

   API 서버 응답 시간에 알림을 걸어 두었다면, OPA 웹훅을 처음 배포한 뒤 모든 CREATE 와 UPDATE 요청의 응답 시간이 늘어난 것을 알아챘을 수도 있다. 모든 워크로드에 프로브를 설정하는 것이 중요하다. 팀은 OPA 배포가 너무 간단해 보여서 Helm 차트를 쓰지 않았는데, 그 차트에는 어드미션 컨트롤러 컨테이너의 livenessProbe 를 포함해 튜토리얼 기본 설정에 없는 조정이 여럿 들어 있었다. 노드 자동 복구를 끄는 것도 검토했지만 끄지 않기로 했다. 같은 문제를 겪은 것은 Jetstack 이 처음이 아니며, 관련 업스트림 이슈는 아직 열려 있다.

   사례 보기
5. IL-0059 kubeadm이 만든 etcd 정적 파드의 liveness probe가 실패해 kubelet이 약 2분마다 etcd를 재시작했고, 단일 마스터 클러스터의 API 서버가 계속 끊겼다

   NRE Labs2018

   증상

   2018년 12월 4일 아침 8시 회의 중 운영자가 NRE Labs의 일일 통계를 보다가 레슨 사용량이 떨어진 것을 알아챘다.

   컨트롤 플레인 무응답프로브 실패서비스 중단

   촉발

   kubeadm이 etcd 정적 파드 매니페스트에 넣은 liveness probe가 실패하기 시작했다. 이 probe는 etcdctl로 foo 키를 조회한다. failureThreshold가 8, timeoutSeconds가 15라서 약 2분 동안 실패가 이어지면 kubelet이 etcd를 재시작한다. probe가 왜 실패하기 시작했는지는 끝내 밝히지 못했다.

   원인

   unknown

   구성 요소

   etcdkubelet쿠버네티스 API 서버

   기여 요인

   단일 장애점기본 설정 방치수동 조치 악화초기 신호 무시모니터링 사각지대

   감지

   운영자가 아침 회의 중 NRE Labs 일일 통계를 보다가 레슨 사용량이 떨어진 것을 보고 알았다. 클러스터 모니터링은 갖추지 않은 상태였고, 원문은 모니터링이 우선순위에서 밀려 있었다고 적었다.

   조치

   • kubeadm이 만든 etcd 매니페스트에서 liveness probe 부분을 통째로 지우고, 다음 etcd 재시작 때 kubectl apply로 반영했다.

   후속 조치

   • 단일 마스터 클러스터에 모니터링을 갖춘다.
   • 장애가 나면 트위터를 보라고 안내하는 점검 페이지를 Google Cloud Functions에 만든다. 계획된 작업이든 아니든 일이 생기면 트래픽을 그 페이지로 돌린다.

   교훈

   모든 인프라를 코드로 관리한 덕에 클러스터를 금방 다시 만들 수 있었다. 하지만 원인을 모른 채 지우면 증거도 함께 사라진다. 단일 마스터로 운영한다면 모니터링이 더 중요하다. kubectl 출력에서 Running만 보지 말고 재시작 횟수까지 읽어야 한다. 복잡한 원인을 기대하기 전에 기본부터 의심하고, 장애의 급박함에 밀려 성급한 결정을 내리지 않는다. 사이트를 반쯤 망가진 채로 두지 말고 점검 페이지로 상황을 알려야 한다.

   사례 보기

원인별4