본문으로 건너뛰기

Kubernetes 클러스터 등록

KIWI 플랫폼에 Kubernetes 클러스터를 연결하여 컨테이너 관리 환경을 구성할 수 있습니다. 클러스터를 등록하면 복잡한 kubectl 명령어 없이도 웹 UI에서 편리하게 서비스를 관리할 수 있습니다.

런타임 환경 페이지

왜 Kubernetes 클러스터를 등록하나요?​

Kubernetes는 대규모 컨테이너 환경을 관리하기 위한 강력한 도구이지만, 학습 곡선이 가파릅니다. KIWI에 클러스터를 등록하면 다음과 같은 이점이 있습니다:

  • 클러스터 상태를 대시보드에서 한눈에 확인
  • 클릭 몇 번으로 서비스 배포 및 업데이트
  • 복잡한 YAML 파일 작성 없이 자동 생성된 설정 사용
  • 여러 클러스터를 한 곳에서 통합 관리
Kubernetes란?

Kubernetes(K8s)는 컨테이너화된 애플리케이션의 배포, 확장, 관리를 자동화하는 오픈소스 플랫폼입니다. 여러 대의 서버에 걸쳐 컨테이너를 효율적으로 운영할 수 있게 해줍니다.

사전 요구사항​

클러스터를 등록하기 전에 다음 조건이 충족되어야 합니다:

  • Kubernetes 버전 1.20 이상이 설치되어 있어야 합니다 .
  • 클러스터에 접근할 수 있는 유효한 kubeconfig 파일이 필요합니다 .
  • KIWI 서버에서 K8s API Server(기본 6443 포트)로 네트워크 통신이 가능해야 합니다 .
kubeconfig 파일 위치

kubeconfig 파일은 보통 ~/.kube/config에 위치합니다. Kubernetes를 설치할 때 자동으로 생성되며, 클러스터 접속 정보와 인증 정보가 포함되어 있습니다.

등록 절차​

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

  1. 좌측 메뉴에서 [런타임 환경] 페이지를 클릭합니다 .
  2. 상단의 K8s 클러스터 추가 버튼을 클릭합니다 .

Step 2: 클러스터 정보 입력​

클러스터 등록 모달에서 다음 정보를 입력합니다:

  • 이름: 클러스터를 구분할 수 있는 식별명입니다 .

    • 예: prod-cluster, dev-k8s
    • 환경과 용도가 명확하게 드러나도록 작성하세요

  • API Server: Kubernetes API Server의 주소입니다 .

    • 예: https://192.168.1.10:6443
    • 반드시 포트 번호(기본 6443)를 포함해야 합니다 .

  • 네임스페이스: 기본으로 사용할 네임스페이스입니다 .

    • 비워두면 default가 사용됩니다 .
    • 팀별로 네임스페이스를 분리하여 사용하는 것을 권장합니다 .

Step 3: 인증 설정​

kubeconfig 파일을 업로드하여 클러스터 인증을 설정합니다.

kubeconfig 파일 예시:

apiVersion: v1
kind: Config
clusters:
- cluster:
    server: https://192.168.1.10:6443
    certificate-authority-data: LS0tLS1CRUdJTi...
  name: my-cluster
contexts:
- context:
    cluster: my-cluster
    user: admin
  name: my-cluster-context
current-context: my-cluster-context
users:
- name: admin
  user:
    client-certificate-data: LS0tLS1CRUdJTi...
    client-key-data: LS0tLS1CRUdJTi...
kubeconfig 파일 보안

kubeconfig 파일에는 클러스터 접근 권한이 포함되어 있습니다. 파일을 안전하게 관리하고, 필요 이상의 권한이 포함되지 않도록 주의하세요.

Step 4: 연결 확인 및 저장​

  1. 테스트 연결 버튼을 클릭하여 클러스터에 정상적으로 접속되는지 확인합니다 .
  2. 연결이 성공하면 저장 버튼을 클릭하여 클러스터를 등록합니다 .

클러스터 상태 확인​

등록이 완료되면 다음 정보를 확인할 수 있습니다:

  • 노드 목록: 클러스터에 참여한 노드들의 상태(Ready/NotReady)와 CPU/메모리 현황을 확인합니다 .
  • 네임스페이스: 클러스터 내 사용 가능한 네임스페이스 목록을 조회합니다 .
  • 리소스 사용량: 전체 CPU와 메모리 사용량을 실시간으로 모니터링합니다 .
  • 워크로드: Deployment, Pod, Service 등의 상태를 확인합니다 .
클러스터 헬스체크

클러스터 상세 페이지에서 노드 상태가 모두 'Ready'인지 확인하세요. 'NotReady' 상태의 노드가 있다면 해당 노드에 문제가 있을 수 있습니다.

문제 해결​

연결 실패 (Unable to connect to the server)​

Unable to connect to the server

원인: KIWI 서버가 Kubernetes API Server에 연결하지 못하고 있습니다.

확인 사항:

  1. API Server 주소 확인

    • 주소에 https://가 포함되어 있는지 확인합니다 .
    • 포트 번호(기본 6443)가 포함되어 있는지 확인합니다 .

  2. 네트워크 연결 확인

    • KIWI 서버에서 클러스터 API Server로 통신이 가능한지 확인합니다 .
    curl -k https://192.168.1.10:6443/healthz

  3. 방화벽 설정 확인

    • 6443 포트가 방화벽에서 허용되어 있는지 확인합니다 .

  4. 인증 정보 확인

    • kubeconfig 파일의 인증 정보(인증서)가 만료되지 않았는지 확인합니다 .

권한 부족 (Forbidden)​

Forbidden: User cannot list pods

원인: kubeconfig에 설정된 사용자에게 충분한 권한이 없습니다.

해결 방법:

KIWI가 클러스터를 관리하려면 적절한 권한이 필요합니다. 다음 명령으로 ClusterRole을 바인딩하세요:

# cluster-admin 역할 바인딩 (모든 권한)
kubectl create clusterrolebinding kiwi-admin \
  --clusterrole=cluster-admin \
  --user=<kubeconfig의 사용자명>
ServiceAccount 사용 시

ServiceAccount를 사용하는 경우, 해당 ServiceAccount에 적절한 권한을 부여해야 합니다. 운영 환경에서는 최소 권한 원칙에 따라 필요한 권한만 부여하는 것이 좋습니다.

다음 단계​

클러스터 등록이 완료되었습니다! 이제 서비스를 등록하고 Kubernetes에 배포할 준비가 되었습니다: