본문으로 건너뛰기

K8s 인증서 갱신

런타임 환경 - 인증서 관리 탭

Kubernetes 클러스터 인증서가 만료되면 클러스터 전체가 작동을 멈출 수 있습니다. KIWI를 사용하면 인증서 만료 전에 미리 알림을 받고, 간단한 클릭으로 갱신할 수 있습니다.

인증서 만료의 심각성

인증서가 만료되면 kubectl 명령이 실패하고, Pod 스케줄링이 중단되며, 최악의 경우 클러스터 전체에 접근할 수 없게 됩니다. 정기적인 인증서 관리가 필수입니다.

인증서 개요​

Kubernetes 클러스터는 컴포넌트 간 안전한 통신을 위해 여러 종류의 인증서를 사용합니다.

주요 인증서​

  • CA 인증서 (유효 기간 10년): 클러스터의 루트 인증 기관 인증서입니다. 다른 모든 인증서의 서명에 사용되므로 가장 중요하며, 10년의 긴 유효 기간을 가집니다.
  • API Server 인증서 (유효 기간 1년): API 서버의 TLS 통신에 사용됩니다. 만료 시 kubectl 명령과 모든 API 호출이 실패합니다.
  • Controller Manager 인증서 (유효 기간 1년): 컨트롤러 매니저가 API 서버와 통신할 때 사용합니다. 만료 시 Deployment, ReplicaSet 등의 컨트롤러가 작동하지 않습니다.
  • Scheduler 인증서 (유효 기간 1년): 스케줄러가 API 서버와 통신할 때 사용합니다. 만료 시 새로운 Pod가 노드에 스케줄링되지 않습니다.
  • Kubelet 인증서 (유효 기간 1년): 각 노드의 kubelet이 마스터와 통신할 때 사용합니다. 만료 시 해당 노드가 NotReady 상태가 됩니다.
  • etcd 인증서 (유효 기간 1년): etcd 클러스터 내 노드 간 통신에 사용됩니다. 만료 시 클러스터 데이터에 접근할 수 없어 전체 클러스터가 마비됩니다.

인증서 만료의 영향​

인증서 종류에 따라 영향이 다릅니다. 모든 인증서가 만료되면 클러스터가 완전히 마비됩니다.

  • API Server (매우 심각): 만료 시 kubectl 명령이 실패하고 모든 관리 작업이 불가능해집니다 .
  • Kubelet (심각): 만료 시 노드-마스터 통신이 실패하고 Pod 스케줄링이 불가능해집니다 .
  • etcd (매우 심각): 만료 시 클러스터 데이터에 접근할 수 없게 됩니다 .
미리 대비하세요

인증서가 만료되기 30일 전에 갱신 계획을 세우는 것이 좋습니다. KIWI의 알림 기능을 활용하세요.

사전 요구사항​

  • Kubernetes 클러스터가 KIWI에 등록되어 있어야 합니다 .
  • 클러스터 마스터 노드에 SSH 접근이 설정되어 있어야 합니다 .

권한 안내: 이 기능에 접근할 수 없다면 기관 관리자에게 권한을 요청하세요.

인증서 상태 확인​

Step 1: 런타임 환경 페이지 이동​

  1. [런타임 환경] 페이지에서 대상 클러스터를 선택합니다 .
  2. 클러스터 상세 페이지로 이동합니다 .

Step 2: 인증서 탭 확인​

  1. 인증서 탭을 클릭합니다 .
  2. 모든 인증서의 만료 상태가 표시됩니다 .

인증서 상태 표시​

  • 정상: 인증서 만료까지 30일 이상 남은 상태입니다. 특별한 조치가 필요하지 않지만, 정기적으로 상태를 모니터링하세요.
  • 경고: 인증서 만료까지 30일 이내로 남은 상태입니다. 갱신 일정을 계획하고, 유지보수 창을 예약하세요.
  • 위험: 인증서 만료까지 7일 이내로 남은 상태입니다. 즉시 갱신 작업을 수행해야 합니다. 방치하면 클러스터 장애가 발생합니다.
  • 만료됨: 인증서가 이미 만료된 상태입니다. 클러스터 기능에 영향이 있으므로 긴급하게 갱신 작업을 수행하세요.

인증서 상세 정보​

각 인증서를 클릭하면 상세 정보를 확인할 수 있습니다:

  • 발급일: 인증서 발급 날짜
  • 만료일: 인증서 만료 날짜
  • 남은 기간: 만료까지 남은 일수
  • Subject: 인증서 주체
  • Issuer: 인증서 발급자

인증서 갱신​

자동 갱신 (권장)​

KIWI를 통해 모든 인증서를 한 번에 갱신합니다.

Step 1: 갱신 시작​

  1. 인증서 탭에서 인증서 갱신 버튼을 클릭합니다 .
  2. 갱신 확인 대화상자가 표시됩니다 .

Step 2: 갱신 옵션 확인​

  • 모든 인증서 (기본 선택): 클러스터의 모든 인증서를 한 번에 갱신합니다. 대부분의 경우 이 옵션을 사용하는 것이 안전하고 편리합니다.
  • 선택적 갱신: 특정 인증서만 선택하여 갱신합니다. 특별한 이유가 있는 경우에만 사용하세요. 일부 인증서만 갱신하면 버전 불일치 문제가 발생할 수 있습니다.
  • 컴포넌트 재시작 (기본 활성화): 인증서 갱신 후 관련 컴포넌트(kubelet, API 서버 등)를 자동으로 재시작합니다. 비활성화하면 수동으로 재시작해야 새 인증서가 적용됩니다.

Step 3: 갱신 실행​

  1. 갱신 버튼을 클릭합니다 .
  2. KIWI가 마스터 노드에 SSH로 접속합니다 .
  3. 갱신 진행 상황이 표시됩니다:
    • 기존 인증서 백업
    • 새 인증서 생성
    • 컴포넌트 재시작
    • 연결 확인

Step 4: 갱신 완료 확인​

  1. "인증서가 갱신되었습니다" 메시지 확인
  2. 인증서 목록에서 새 만료일 확인
  3. 클러스터 연결 상태 확인

선택적 갱신​

특정 인증서만 갱신하는 경우:

  1. 선택적 갱신 옵션 선택
  2. 갱신할 인증서 체크박스 선택
  3. 갱신 실행

갱신 후 확인​

클러스터 상태 확인​

갱신 후 다음 항목을 확인합니다:

  1. 노드 상태: 모든 노드 Ready 상태
  2. Pod 상태: 시스템 Pod 정상 실행
  3. API 접근: kubectl 명령 정상 작동

KIWI에서 확인​

  1. 런타임 환경 페이지에서 클러스터 상태 확인
  2. 인증서 탭에서 새 만료일 확인
  3. 서비스 배포/운영 기능 테스트

수동 갱신​

KIWI 자동 갱신이 실패하거나 직접 갱신이 필요한 경우:

kubeadm 클러스터​

마스터 노드에서 SSH로 실행:

# 인증서 만료 확인
kubeadm certs check-expiration

# 모든 인증서 갱신
kubeadm certs renew all

# 컴포넌트 재시작
systemctl restart kubelet

# 컨트롤 플레인 Pod 재시작 (static pod 사용 시)
# Pod manifest 파일을 잠시 이동하면 자동 재시작됨

개별 인증서 갱신​

# 특정 인증서만 갱신
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 연결 실패가 발생하는 경우: KIWI가 마스터 노드에 SSH로 접속할 수 없습니다. 런타임 환경 설정에서 SSH 연결 정보(호스트, 포트, 사용자, 비밀번호 또는 SSH 키)가 올바른지 확인하고, 방화벽 설정을 점검하세요.
  • 권한 오류가 발생하는 경우: SSH 사용자에게 인증서 갱신을 위한 sudo 권한이 없습니다. 해당 사용자가 kubeadm certs renew 명령을 sudo로 실행할 수 있는지 확인하세요.
  • kubeadm을 찾을 수 없는 경우: kubeadm으로 설치되지 않은 클러스터입니다. 수동 갱신 절차를 따르거나, 클러스터 설치 문서를 참조하세요.

갱신 후 문제​

  • API 연결이 실패하는 경우: 인증서는 갱신되었지만 컴포넌트가 재시작되지 않아 이전 인증서를 사용 중입니다. 마스터 노드에서 systemctl restart kubelet 명령을 실행하고, 컨트롤 플레인 Pod가 재시작되었는지 확인하세요.
  • 노드가 NotReady 상태인 경우: 해당 노드의 kubelet이 새 인증서를 로드하지 못했습니다. 문제가 있는 노드에 SSH로 접속하여 systemctl restart kubelet 명령을 실행하세요.
  • etcd 연결이 실패하는 경우: etcd 인증서 문제로 데이터 저장소에 접근할 수 없습니다. etcd Pod를 재시작하거나, etcd 인증서가 올바르게 갱신되었는지 확인하세요.

긴급 복구​

인증서 만료로 클러스터 접근이 불가한 경우:

  1. 마스터 노드에 직접 SSH 접속
  2. 수동으로 인증서 갱신
  3. 컴포넌트 재시작
  4. KIWI에서 클러스터 재연결

자동 알림 설정​

인증서 만료 알림을 받도록 설정합니다.

알림 설정​

  1. 런타임 환경 > 설정 탭으로 이동
  2. 알림 설정 섹션에서:
    • 인증서 만료 알림: 활성화
    • 알림 시기: 30일/14일/7일 전
    • 알림 방법: 이메일/Slack

권장 알림 일정​

  • 30일 전: 갱신 계획을 수립합니다. 담당자를 지정하고, 갱신 작업에 필요한 사전 준비(etcd 백업, 테스트 환경 검증 등)를 진행하세요.
  • 14일 전: 구체적인 갱신 작업 일정을 예약합니다. 서비스 영향이 최소화되는 유지보수 창을 선택하고, 관련 팀에 공지하세요.
  • 7일 전: 아직 갱신하지 않았다면 즉시 갱신 작업을 수행하세요. 이 시점 이후로는 예기치 않은 클러스터 장애 위험이 높아집니다.

베스트 프랙티스​

인증서 관리를 위한 검증된 권장 사항입니다.

예방적 관리​

인증서 관리 체크리스트

아래 항목을 정기적으로 확인하면 인증서 만료로 인한 장애를 예방할 수 있습니다.

  1. 정기 점검: 매월 인증서 상태를 확인합니다 .
  2. 알림 설정: 30일, 14일, 7일 전 알림을 설정합니다 .
  3. 문서화: 갱신 이력과 담당자를 기록합니다 .
  4. 테스트: 갱신 절차를 테스트 환경에서 먼저 테스트합니다 .

갱신 계획​

갱신 작업은 계획적으로 진행해야 합니다.

  1. 유지보수 창: 트래픽이 적은 시간대(새벽 등)를 선택합니다 .
  2. 백업: 갱신 전에 반드시 etcd를 백업합니다 .
  3. 롤백 계획: 실패 시 복구 절차를 미리 준비합니다 .
  4. 검증: 갱신 후 모든 컴포넌트가 정상 동작하는지 테스트합니다 .

보안 고려사항​

인증서는 클러스터 보안의 핵심입니다.

  1. CA 보호: CA 인증서와 키는 안전한 장소에 보관합니다 .
  2. 키 순환: 정기적으로 인증서를 갱신하여 보안을 유지합니다 .
  3. 접근 제한: 인증서 파일에 대한 접근 권한을 최소화합니다 .
  4. 감사: 인증서 관련 모든 작업을 로깅합니다 .
CA 인증서 주의

CA 인증서가 유출되면 클러스터 전체가 위험에 노출됩니다. CA 인증서는 특히 주의하여 관리하세요.

관련 가이드​