K8s 인증서 갱신
Kubernetes 클러스터 인증서가 만료되면 클러스터 전체가 작동을 멈출 수 있습니다. KIOPS를 사용하면 인증서 만료 전에 미리 확인하고, 간단한 클릭으로 갱신할 수 있습니다.
인증서가 만료되면 kubectl 명령이 실패하고, Pod 스케줄링이 중단되며, 최악의 경우 클러스터 전체에 접근할 수 없게 됩니다. 정기적인 인증서 관리가 필수입니다.
인증서 관리 탭 위치
KIOPS의 인증서 관리 화면은 [런타임 환경] > Kubernetes 클러스터 선택 > 인증서 관리 탭에 위치합니다.
- 좌측 메뉴에서 [런타임 환경] 으로 이동합니다.
- 관리할 Kubernetes 클러스터를 선택하여 상세 화면으로 진입합니다.
- 상단 탭 중 인증서 관리 탭을 클릭합니다.
컴포넌트 파일은
services/operate-modal/tabs/k8s/경로에 위치하지만, 실제 사용 위치는 런타임 환경의 Kubernetes 클러스터 상세 화면(InfraKubernetesSetting)입니다.
인증서 개요
Kubernetes 클러스터는 컴포넌트 간 안전한 통신을 위해 여러 종류의 인증서를 사용합니다. KIOPS는 kubeadm certs check-expiration 결과를 기반으로 다음 13개의 인증서를 표시합니다.
kubeadm으로 갱신 가능한 13개 인증서
| 인증서 | 설명 |
|---|---|
admin.conf | kubeadm으로 생성된 cluster admin kubeconfig |
apiserver | API 서버 TLS 인증서 |
apiserver-etcd-client | API 서버가 etcd에 접속할 때 사용 |
apiserver-kubelet-client | API 서버가 kubelet에 접속할 때 사용 |
controller-manager.conf | 컨트롤러 매니저의 kubeconfig |
front-proxy-client | front-proxy 클라이언트 인증서 |
scheduler.conf | 스케줄러의 kubeconfig |
etcd/ca | etcd 클러스터의 CA 인증서 |
etcd/server | etcd 서버 인증서 |
etcd/peer | etcd 노드 간 통신 인증서 |
etcd/healthcheck-client | etcd 헬스체크용 클라이언트 인증서 |
super-admin.conf | super-admin kubeconfig (Kubernetes 1.29+) |
kubelet.conf | kubelet의 kubeconfig |
CA 인증서 (예: cluster CA, etcd CA root)는 kubeadm certs renew 명령으로 갱신되지 않습니다. CA 인증서는 약 10년의 유효기간을 가지며, 갱신이 필요한 경우 클러스터 재구성에 가까운 작업이 필요합니다. KIOPS 인증서 탭에서는 CA 인증서가 별도 영역으로 표시되며, 만료일만 확인할 수 있고 갱신 버튼은 제공되지 않습니다.
사전 요구사항
- Kubernetes 클러스터가 KIOPS에 등록되어 있어야 합니다.
- 클러스터 마스터 노드에 SSH 접근이 설정되어 있어야 합니다.
- 사용자에게 인증서 관리 권한 (
can_manage_certificates)이 부여되어 있어야 합니다.
권한 안내: 권한이 없으면 인증서 탭의 갱신 버튼이 비활성화됩니다. 기관 관리자에게 권한을 요청하세요.
인증서 상태 확인
Step 1: 인증서 관리 탭 진입
- [런타임 환경] > Kubernetes 클러스터 선택 > 인증서 관리 탭으로 이동합니다.
- 백엔드가 마스터 노드에서
kubeadm certs check-expiration명령을 실행합니다. - 모든 인증서의 만료 상태가 표시됩니다.
Step 2: 통계 카드 확인
화면 상단에 다음 4개의 통계 카드 가 표시됩니다.
- 전체: 추적 중인 전체 인증서 수
- 정상: 만료까지 90일 이상 남은 인증서 수
- 주의·위험: 만료까지 90일 이하 남은 인증서 수 (warning 또는 error 상태)
- 만료됨: 이미 만료된 인증서 수
Step 3: 인증서 상태 표시
각 인증서 행에는 Progress 막대로 남은 기간이 시각화됩니다. 색상 임계값은 다음과 같습니다.
- 정상 (녹색): 만료까지 90일 초과
- 주의 (노랑/warning): 만료까지 90일 이하
- 위험 (빨강/error): 만료까지 30일 이하
- 만료됨: 이미 만료된 상태
Step 4: 원본 출력 확인
화면 하단에서 kubeadm certs check-expiration 명령의 원본 출력 을 그대로 확인할 수 있습니다. 디버깅이나 정확한 확인이 필요할 때 활용하세요.
인증서 갱신
Step 1: 유효기간 선택
화면 상단 드롭다운에서 새 인증서의 유효기간 을 선택합니다.
- 1년 (기본)
- 2년
- 3년
- 5년
- 10년
선택한 유효기간은 kubeadm certs renew 실행 시 적용됩니다. 일반적으로 1년이 안전하며, 운영 부담을 줄이려면 더 긴 기간을 선택할 수 있습니다.
Step 2: 갱신 방식 선택
다음 두 가지 방식 중 하나를 선택합니다.
- 모든 인증서 갱신 버튼: 13개 인증서를 일괄 갱신합니다. 대부분의 경우 이 방식을 사용하는 것이 안전합니다.
- 각 행의 개별 갱신 버튼: 특정 인증서 하나만 선택적으로 갱신합니다.
"선택적 갱신 체크박스"와 "컴포넌트 재시작 토글"은 제공되지 않습니다. 갱신 후 kubelet은 자동으로 재시작되며, 컨트롤 플레인 정적 Pod는 인증서 변경을 감지하여 자동으로 다시 로드됩니다.
Step 3: 갱신 실행
- 갱신 버튼을 클릭하면 확인 대화상자가 표시됩니다.
- 갱신 을 클릭하면 KIOPS가 마스터 노드에 SSH로 접속하여
kubeadm certs renew명령을 실행합니다. - 진행 상태가 표시되며, 완료 후 새 만료일이 인증서 목록에 반영됩니다.
Step 4: 갱신 완료 확인
- "인증서가 갱신되었습니다" 메시지가 표시됩니다.
- 인증서 목록에서 새 만료일을 확인합니다.
- 통계 카드의 "주의·위험"/"만료됨" 수치가 0으로 변경되었는지 확인합니다.
HA 클러스터에서의 갱신
Control Plane 노드가 여러 개인 HA 클러스터에서는 모든 Control Plane 노드에서 인증서를 갱신 해야 합니다.
- 첫 번째 Control Plane 노드에서 KIOPS 인증서 갱신을 실행합니다.
- 다른 Control Plane 노드에 SSH로 접속하여
kubeadm certs renew all명령을 수동으로 실행합니다. - 각 노드에서 kubelet이 자동 재시작되었는지 확인합니다.
한 노드만 갱신하고 다른 노드를 갱신하지 않으면 API 호출이 노드에 따라 성공/실패가 갈리는 혼란이 발생합니다. 가능하면 짧은 시간 안에 모든 Control Plane을 갱신하세요.
갱신 후 확인
클러스터 상태 확인
갱신 후 다음 항목을 확인합니다:
- 노드 상태: 모든 노드 Ready 상태
- Pod 상태: 시스템 Pod 정상 실행
- API 접근: kubectl 명령 정상 작동
KIOPS에서 확인
- 인증서 탭에서 새 만료일 확인
- 통계 카드 값이 모두 정상으로 변경되었는지 확인
- 서비스 배포/운영 기능 테스트
수동 갱신
KIOPS 자동 갱신이 실패하거나 직접 갱신이 필요한 경우:
kubeadm 클러스터
마스터 노드에서 SSH로 실행:
# 인증서 만료 확인
kubeadm certs check-expiration
# 모든 인증서 갱신
kubeadm certs renew all
# 컴포넌트 재시작 (대부분 자동 재시작되지만 명시적으로 수행 가능)
systemctl restart kubelet
개별 인증서 갱신
# 특정 인증서만 갱신
kubeadm certs renew apiserver
kubeadm certs renew apiserver-kubelet-client
kubeadm certs renew front-proxy-client
kubeconfig 파일 갱신
# admin.conf 갱신
kubeadm certs renew admin.conf
# 다른 kubeconfig 갱신
kubeadm certs renew controller-manager.conf
kubeadm certs renew scheduler.conf
문제 해결
갱신 실패
- SSH 연결 실패가 발생하는 경우: KIOPS가 마스터 노드에 SSH로 접속할 수 없습니다. 런타임 환경 설정에서 SSH 연결 정보(호스트, 포트, 사용자, 비밀번호 또는 SSH 키)가 올바른지 확인하고, 방화벽 설정을 점검하세요.
- 권한 오류가 발생하는 경우: SSH 사용자에게 인증서 갱신을 위한 sudo 권한이 없습니다. 해당 사용자가
kubeadm certs renew명령을 sudo로 실행할 수 있는지 확인하세요. - kubeadm을 찾을 수 없는 경우: kubeadm으로 설치되지 않은 클러스터입니다. 수동 갱신 절차를 따르거나, 클러스터 설치 문서를 참조하세요.
- 권한 검증 실패:
can_manage_certificates권한이 없으면 갱신 버튼이 비활성화됩니다. 기관 관리자에게 권한을 요청하세요.
갱신 후 문제
- API 연결이 실패하는 경우: 컨트롤 플레인 정적 Pod가 새 인증서를 로드하지 못한 상태일 수 있습니다. 마스터 노드에서
systemctl restart kubelet명령을 실행하고, 잠시 후 다시 시도하세요. - 노드가 NotReady 상태인 경우: 해당 노드의 kubelet이 새 인증서를 로드하지 못했습니다. 문제가 있는 노드에 SSH로 접속하여
systemctl restart kubelet명령을 실행하세요. - etcd 연결이 실패하는 경우: etcd 인증서 문제로 데이터 저장소에 접근할 수 없습니다. etcd Pod를 재시작하거나, etcd 인증서가 올바르게 갱신되었는지 확인하세요.
베스트 프랙티스
인증서 관리를 위한 검증된 권장 사항입니다.
예방적 관리
아래 항목을 정기적으로 확인하면 인증서 만료로 인한 장애를 예방할 수 있습니다.
- 정기 점검: 매월 인증서 탭에서 통계 카드를 확인합니다.
- 임계값 활용: "주의·위험" (90일 이하) 단계에서 갱신 일정을 계획합니다.
- 문서화: 갱신 이력과 담당자를 기록합니다.
- 테스트: 갱신 절차를 테스트 환경에서 먼저 검증합니다.
갱신 계획
갱신 작업은 계획적으로 진행해야 합니다.
- 유지보수 창: 트래픽이 적은 시간대(새벽 등)를 선택합니다.
- 백업: 갱신 전에 반드시 etcd를 백업합니다.
- HA 노드 일괄 갱신: HA 클러스터는 모든 Control Plane 노드를 짧은 시간 안에 갱신합니다.
- 검증: 갱신 후 모든 컴포넌트가 정상 동작하는지 테스트합니다.
보안 고려사항
인증서는 클러스터 보안의 핵심입니다.
- CA 보호: CA 인증서와 키는 안전한 장소에 보관합니다.
- 키 순환: 정기적으로 인증서를 갱신하여 보안을 유지합니다.
- 접근 제한: 인증서 파일에 대한 접근 권한을 최소화합니다.
- 감사: 인증서 관련 모든 작업을 로깅합니다.
CA 인증서가 유출되면 클러스터 전체가 위험에 노출됩니다. CA 인증서는 특히 주의하여 관리하세요.
관련 가이드
- 런타임 환경 등록 - K8s 클러스터 등록
- K8s RBAC 관리 - ServiceAccount 관리
- 백업 복원 - 클러스터 복구