[Vagrant,Kubernetes] 인증서 만료되기 전 : 인증서 갱신 가이드

kubeadm 기반 Kubernetes 클러스터의 인증서 유효기간은 1년이다. 만료되면 API 서버부터 kubelet까지 전부 멈춰서 복구에 30분 이상 걸리는 전면 장애가 되지만, 만료 전에 갱신하면 5분짜리 작업이다 (API 서버 순단 수십 초).

이 글은 만료 40일을 남기고 선제 갱신한 실제 작업 기록이다. 환경은 Kubespray로 구축된 클러스터(외부 etcd)지만, 순수 kubeadm 클러스터에도 거의 그대로 적용된다.

■ 환경

항목	값
Kubernetes	v1.32.5 (Kubespray 구축, kubeadm 관리 인증서)
etcd	외부 systemd 서비스 (별도 인증서 체계 — kubeadm 갱신 대상 아님)
작업 위치	모든 명령은 control-plane 노드에서 실행

■ 1단계. 만료일 확인

sudo kubeadm certs check-expiration

• 클러스터가 살아있으면 옵션 없이도 ConfigMap에서 설정을 읽어온다.
• RESIDUAL TIME이 실제 남은 기간이다 (이번 케이스: 40~45일).
• CA는 유효기간이 10년이므로 갱신 대상이 아니다.

CERTIFICATE                EXPIRES                  RESIDUAL TIME   CERTIFICATE AUTHORITY
admin.conf                 Aug 13, 2026 02:04 UTC   40d             ca
apiserver                  Aug 18, 2026 09:03 UTC   45d             ca
apiserver-kubelet-client   Aug 13, 2026 02:04 UTC   40d             ca
controller-manager.conf    Aug 13, 2026 02:04 UTC   40d             ca
front-proxy-client         Aug 13, 2026 02:04 UTC   40d             front-proxy-ca
scheduler.conf             Aug 13, 2026 02:04 UTC   40d             ca
super-admin.conf           Aug 13, 2026 02:04 UTC   40d             ca

참고: Kubespray처럼 외부 etcd를 쓰는 환경에서 etcd 인증서가 !MISSING!으로 표시되면 --config /etc/kubernetes/kubeadm-config.yaml을 붙이면 된다. 원래 kubeadm 관리 대상이 아니라서 그렇다.

■ 2단계. kubelet 자동 갱신(rotation) 여부 확인

각 노드에서 kubelet.conf가 무엇을 참조하는지 확인한다.

grep client-certificate /etc/kubernetes/kubelet.conf
# 기대값: client-certificate: /var/lib/kubelet/pki/kubelet-client-current.pem

sudo openssl x509 -enddate -noout -in /var/lib/kubelet/pki/kubelet-client-current.pem

• kubelet-client-current.pem을 참조하고 있으면 kubelet 인증서는 자동 갱신되므로 아무 작업도 필요 없다. (이번 확인 결과: 워커 노드들은 이미 스스로 갱신해서 1년 남아 있었다)
• client-certificate-data:(내장 인증서)로 되어 있으면 rotation 전환을 해두는 것을 권장한다.

■ 3단계. 백업

sudo cp -a /etc/kubernetes /root/kubernetes-backup-$(date +%Y%m%d)

■ 4단계. 인증서 일괄 갱신

sudo kubeadm certs renew all

7개 인증서(admin.conf, apiserver, apiserver-kubelet-client, controller-manager.conf, front-proxy-client, scheduler.conf, super-admin.conf)가 실행 시점 기준 +1년으로 갱신된다.

certificate embedded in the kubeconfig file for the admin to use and for kubeadm itself renewed
certificate for serving the Kubernetes API renewed
certificate for the API server to connect to kubelet renewed
...
Done renewing certificates. You must restart the kube-apiserver, kube-controller-manager,
kube-scheduler and etcd, so that they can use the new certificates.

■ 5단계. 컨트롤 플레인 컴포넌트 재시작

갱신된 인증서는 파일만 바뀐 것이고, 실행 중인 static pod는 재시작해야 새 인증서를 읽는다. 매니페스트를 잠시 옮겼다가 되돌리는 방식이 가장 확실하다. (이때 API 서버 순단 수십 초 발생)

sudo mkdir -p /root/mfs-tmp
sudo bash -c 'mv /etc/kubernetes/manifests/*.yaml /root/mfs-tmp/'
sleep 20
sudo bash -c 'mv /root/mfs-tmp/*.yaml /etc/kubernetes/manifests/'

참고: 블로그나 문서에서 종종 보이는 kill -s SIGHUP $(pidof kube-apiserver) 방식은 프로세스를 죽여 재기동을 유도하는 우회 방법이고, systemctl restart kubelet이나 systemctl restart containerd는 실행 중인 static pod 컨테이너를 재시작하지 않으므로 인증서 반영이 보장되지 않는다.

■ 6단계. 사용자 kubeconfig 교체

admin.conf가 갱신됐으므로 복사해서 쓰던 kubeconfig도 교체한다. sudo cp만 하면 소유자가 root가 되어 일반 계정의 kubectl이 permission denied가 나므로 소유권 변경까지 해준다.

sudo cp /etc/kubernetes/admin.conf /tmp/kc
sudo chown $(id -u):$(id -g) /tmp/kc
mv /tmp/kc ~/.kube/config

■ 7단계. 최종 확인

# 전 노드 Ready 확인
kubectl get nodes

# 만료일이 +1년으로 바뀌었는지 확인
sudo kubeadm certs check-expiration

# API 서버가 실제 서빙 중인 인증서의 만료일 확인 (재시작 반영 검증)
echo | openssl s_client -connect 127.0.0.1:6443 2>/dev/null | openssl x509 -enddate -noout

# 전체 파드 정상 확인
kubectl get pods -A | grep -v Running | grep -v Completed

■ 만료 전 vs 만료 후 — 무엇이 다른가

같은 클러스터에서 두 케이스를 모두 겪어본 결과를 비교하면 이렇다. 만료 전에 하는 것이 압도적으로 이득이다.

구분	만료 전 (이 글)	만료 후
클러스터 상태	정상 동작 중	API 서버 다운, kubelet 재시작 루프
renew all 옵션	옵션 불필요 (ConfigMap 사용)	--config 필수 (ConfigMap을 못 읽음)
kubelet 인증서	rotation이 알아서 갱신 (작업 없음)	전 노드 수동 재발급 필요 (가장 오래 걸림)
서비스 영향	API 순단 수십 초	만료 시점부터 복구까지 전면 장애
소요 시간	약 5분	30분 이상 + 파드 복구 시간

만료 후 복구(kubelet 인증서 전 노드 재발급 포함)는 절차가 완전히 달라서 별도 글로 정리할 예정이다.

■ 마무리

• kubeadm 인증서 갱신은 만료 전이라면 백업 → renew all → 컨트롤 플레인 재시작 → kubeconfig 교체 → 검증, 5분이면 끝난다.
• kubelet.conf가 kubelet-client-current.pem을 참조하도록(rotation) 해두면 매년 신경 쓸 대상이 컨트롤 플레인 인증서 하나로 줄어든다.
• 갱신 후에는 check-expiration뿐 아니라 openssl s_client로 API 서버가 실제로 새 인증서를 서빙하는지까지 확인하자. 파일 갱신과 반영은 별개다.
• 만료일을 캘린더에 등록해두자. 이번처럼 40일 전에 하면 여유롭고, 만료 후에 하면 장애 대응이 된다.