Kubernetes 클러스터 등록
KIOPS 플랫폼에 Kubernetes 클러스터를 등록하면 웹 UI에서 노드/네임스페이스/워크로드를 통합 관리할 수 있습니다. 등록은 새 런타임 설치(신규) 또는 기존 런타임 연결(임포트) 두 가지 흐름으로 진행됩니다.
이 가이드는 K8s를 직접 설치해 본 적이 없는 운영자도 모달 화면 따라가기만으로 클러스터를 KIOPS에 올릴 수 있도록 안내합니다. 새로 설치할지, 이미 돌고 있는 클러스터를 연결할지부터 정하면 나머지는 KIOPS가 SSH로 알아서 진행합니다.
시작하기 전에: 알아둘 용어
K8s 용어는 처음 보면 어렵게 느껴질 수 있습니다. 이 가이드에서만 알면 되는 용어를 짧게 정리합니다.
- 클러스터(Cluster): 하나의 K8s 시스템 전체입니다. 여러 서버를 묶어 하나의 컴퓨터처럼 다룹니다.
- 마스터 노드 / 워커 노드: 마스터는 두뇌 역할(스케줄링/관리), 워커는 실제 컨테이너가 도는 손발 역할입니다.
- kubeadm: K8s를 표준 방식으로 설치/초기화하는 도구입니다. KIOPS의 신규 설치도 이 방식을 사용합니다.
- preflight(사전 점검): 임포트 직전 KIOPS가 노드 8개 항목(kubeadm, kubelet, container_runtime, cni_plugin, token_creation, cert_expiration, sudo_access, swap_status)을 자동 검사하는 단계입니다.
- management_level: preflight 결과로 부여되는 운영 등급입니다.
full/limited/readonly3등급으로 기능 가용 범위가 달라집니다. - VIP / HA: 다중 마스터 구성을 위한 가상 IP입니다. 마스터 하나가 죽어도 클러스터가 계속 동작하도록 만드는 장치입니다.
- 임포트(Import): 이미 설치된 클러스터를 KIOPS에 가져오는 흐름입니다 (kubeconfig 업로드 아님, SSH 자동 감지).
왜 Kubernetes 클러스터를 등록하나요?
- 클러스터 상태를 대시보드에서 한눈에 확인
- 클릭 몇 번으로 서비스 배포 및 업데이트
- 복잡한 YAML 파일 작성 없이 자동 생성된 설정 사용
- 여러 클러스터를 한 곳에서 통합 관리
Kubernetes(K8s)는 컨테이너화된 애플리케이션의 배포, 확장, 관리를 자동화하는 오픈소스 플랫폼입니다. 여러 대의 서버에 걸쳐 컨테이너를 효율적으로 운영할 수 있게 해줍니다.
사전 요구사항
- 클러스터를 구성할 노드(또는 임포트할 기존 클러스터의 마스터/워커 노드)가 장비로 먼저 등록되어 있어야 합니다.
- KIOPS 서버가 각 노드에 SSH로 접속 가능해야 합니다 (등록된 장비 또는 hop 체인 사용).
- 신규 설치의 경우 노드는 swap이 비활성화되어 있고 kubeadm 호환 OS(Ubuntu 20.04+, RHEL 8+ 등)여야 합니다.
- 임포트의 경우 노드에 kubeadm/kubelet/kubectl이 이미 설치되어 있어야 합니다.
등록 진입점: 런타임 환경 추가
K8s 클러스터는 별도의 "K8s 추가" 버튼이 아닌 공통 진입점에서 시작합니다.
- 좌측 메뉴에서 [런타임 환경] 페이지를 클릭합니다.
- 우측 상단의 런타임 환경 추가 버튼을 클릭하면 추가 방식 선택 모달(내부 컴포넌트명: AddInfraSelectModal)이 열립니다.
- 두 가지 흐름 중 하나를 선택합니다.
이미 kubeadm으로 설치되어 운영 중인 클러스터에 새 런타임 설치를 선택하면 기존 클러스터를 재초기화하려다 실패합니다. 이미 돌고 있는 클러스터는 반드시 기존 런타임 연결(임포트) 을 선택하세요 (용어 사전 참고).
신규 설치 흐름
새 런타임 설치 모달(내부 컴포넌트명: AddInfraModal)에서 진행합니다. KIOPS가 SSH로 마스터/워커 노드에 접속해 kubeadm 기반 클러스터를 직접 설치합니다. 단일 마스터부터 VIP를 사용한 HA 구성까지 지원합니다.
Step 1: 입력
다음 항목을 입력합니다.
- 환경 이름: 클러스터를 구분할 식별명 (예:
prod-cluster,dev-k8s). 이 이름은 Kubernetes 노드 이름(kubeadm --node-name)으로 사용되므로 RFC 1123 규칙을 따라야 합니다. 영소문자/숫자/하이픈(-)/점(.)만 사용할 수 있고 영숫자로 시작·끝나야 하며 63자 이하여야 합니다. 공백·한글·대문자·언더스코어(_)는 사용할 수 없으며, 위반 시 등록이 거부됩니다. - 환경 정보(설명): 자유 형식 설명
- 마스터 노드 선택: 등록된 장비 중 마스터로 사용할 노드를 선택합니다 (단일 또는 다수).
- 워커 노드 선택: 워커로 참여할 노드를 선택합니다.
- VIP / HA 설정 (선택): 다중 마스터 구성 시 컨트롤 플레인용 VIP, 인터페이스 등을 입력합니다.
Step 2: 미리보기
입력 → 다음 단계로 진행하면 클러스터 토폴로지 다이어그램과 선택된 노드 테이블이 함께 표시됩니다.
- 마스터/워커 구성, VIP 위치, hop 경로를 시각적으로 확인합니다.
- 잘못된 부분이 있으면 이전 단계로 돌아가 수정합니다.
Step 3: 등록
- 등록 버튼을 클릭하면 KIOPS가 각 노드에 SSH로 접속해 kubeadm 설치 및 클러스터 초기화를 진행합니다.
- 진행 상황은 모달에서 실시간으로 표시되며, 완료 후 클러스터가 런타임 목록에 추가됩니다.
기존 연결 (임포트) 흐름
기존 런타임 연결 모달(내부 컴포넌트명: ImportInfraModal)에서 진행합니다. 이미 운영 중인 클러스터를 KIOPS에 등록합니다. kubeconfig 파일 업로드는 사용하지 않으며, SSH 접속을 통해 노드를 자동 감지하고 preflight 검증을 수행합니다.
Step 1: 환경 유형 선택
임포트 모달의 환경 유형 Select 옵션에 사용자가 보는 라벨은 "Kubernetes / Docker / Podman" (한글 라벨)으로 표시됩니다. (external_kubernetes, external_docker, external_podman은 백엔드 내부 식별자입니다.)
- Kubernetes: 기존 K8s 클러스터 (내부 식별자
external_kubernetes) - Docker / Podman: 컨테이너 런타임 (별도 가이드 참고)
Step 2: 접속 경로 입력
다음 중 하나를 선택합니다.
- 등록된 장비 선택: 마스터 노드로 사용할 장비를 드롭다운에서 선택합니다.
- SSH hops 직접 입력: 점프 서버를 포함한 hop 체인을 직접 입력합니다.
Step 3: 노드 자동 감지
- 가져오기 버튼을 클릭하면 KIOPS가
calculateNodes로직으로 마스터 노드에 접속해 클러스터의 전체 노드(마스터+워커)를 자동 감지합니다. - 별도의 "테스트 연결" 버튼은 없으며, 가져오기 시점에 SSH 접속과 preflight 검증이 함께 수행됩니다.
Step 4: preflight 검증 (8항목)
각 노드에 대해 다음 8가지 항목을 검사합니다.
kubeadm설치 여부kubelet설치 및 동작 상태- container_runtime (containerd/docker/cri-o) 동작 여부
- cni_plugin (calico/flannel/cilium 등) 설치 여부
- token_creation 가능 여부 (
kubeadm token create권한) - cert_expiration 인증서 만료 여부
- sudo_access 권한
- swap_status (비활성화 여부)
Step 5: management_level 평가
preflight 결과를 종합해 노드별로 다음 등급이 부여됩니다.
- full: 8개 항목 모두 통과 - 설치/배포/인증서 갱신 등 모든 기능 사용 가능
- limited: 일부 항목 누락 - 조회/일부 운영만 가능
- readonly: 핵심 항목 실패 - 상태 조회만 가능
limited나 readonly인 상태로 등록을 진행해도 클러스터는 등록되지만, 이후 배포/인증서 갱신 등 핵심 기능이 막혀 운영 중 당황하기 쉽습니다. 가능하면 등록 전에 실패 항목을 먼저 해결해 full로 맞춰두세요.
Step 6: 중복 검사 및 등록
- 노드의 IP가 이미 등록된 장비와 중복되면, KIOPS는 새로 만들지 않고 기존 장비를 재사용합니다.
- 사용자가 등록 대상으로 선택한 노드만 필터링하여 일괄 등록됩니다.
- 등록이 완료되면 클러스터가 런타임 목록에 추가됩니다.
KIOPS는 신규 설치와 임포트 모두에서 kubeconfig 파일 업로드를 받지 않습니다. 모든 클러스터 명령은 마스터 노드에 SSH로 직접 접속하여 kubectl을 실행하는 방식으로 처리됩니다.
다른 K8s 관리 도구를 사용하던 운영자가 "kubeconfig 파일 어디에 올리나요?"라고 묻는 경우가 많습니다. KIOPS에는 kubeconfig 업로드 칸이 없습니다. 마스터 노드를 장비로 등록하고 SSH 접근만 확보하면 됩니다.
클러스터 상태 확인
등록이 완료되면 다음 정보를 확인할 수 있습니다.
- 노드 목록: 클러스터에 참여한 노드들의 상태(Ready/NotReady)와 CPU/메모리 현황을 확인합니다.
- 네임스페이스: 클러스터 내 사용 가능한 네임스페이스 목록을 조회합니다.
- 리소스 사용량: 전체 CPU와 메모리 사용량을 실시간으로 모니터링합니다 (metrics-server 설치 시).
- 워크로드: Deployment, Pod, Service 등의 상태를 확인합니다.
클러스터 상세 페이지에서 노드 상태가 모두 'Ready'인지 확인하세요. 'NotReady' 상태의 노드가 있다면 해당 노드에 문제가 있을 수 있습니다.
문제 해결
임포트 시 preflight 실패
management_level이 limited 또는 readonly로 표시되는 경우, 해당 노드에서 실패한 항목을 점검합니다.
- kubeadm/kubelet 미설치: kubeadm 클러스터가 아닐 수 있습니다. 해당 노드에서
kubeadm version,kubelet --version을 확인하세요. - container_runtime 실패:
systemctl status containerd(또는 docker/cri-o)로 런타임이 실행 중인지 확인합니다. - cni_plugin 누락:
/etc/cni/net.d/디렉터리에 CNI 설정 파일이 있는지 확인합니다. - swap_status 실패:
swapoff -a후/etc/fstab에서 swap 항목을 제거합니다. - sudo_access 실패: SSH 사용자에게 NOPASSWD sudo 또는 적절한 sudo 권한을 부여합니다.
연결 실패 (Unable to connect to the server)
- 마스터 노드의 IP/포트와 SSH 자격증명이 올바른지 확인합니다.
- hop 체인을 사용하는 경우 각 경유 장비의 SSH 접근이 모두 가능해야 합니다.
- 방화벽에서 KIOPS 서버 ↔ 마스터 노드 통신이 허용되어 있는지 확인합니다.
다음에 할 일
클러스터 등록이 완료되었습니다. 다음 작업을 우선순위 순으로 권장합니다.
- 서비스 등록 - 등록된 클러스터에 배포할 서비스를 먼저 정의합니다.
- 메트릭 서버 설치 - HPA/리소스 모니터링의 기반이 되는 메트릭 서버를 설치합니다.
- K8s RBAC 관리 - 팀별 권한 분리가 필요하다면 ServiceAccount/네임스페이스로 권한을 나눕니다.