클러스터 관리
클러스터는 gShare 오퍼레이터(Operator)가 실행되는 Kubernetes 데이터 플레인 클러스터를 의미합니다. 제어 플레인(Control Plane)은 사용자 계정, 지갑/크레딧, 자원 할당 정책을 총괄하며, 각 데이터 플레인 클러스터는 제어 플레인의 결정을 실제 파드(Pod) 자원으로 프로비저닝하고 클러스터 내 발생 이벤트를 제어 플레인으로 보고합니다.
| 연관 문서 | 주요 내용 |
|---|---|
| 노드 | 노드 인프라 관리: 차단(Cordon), 비우기(Drain), 삭제 및 생존 하트비트 판정 |
| 노드 풀 | 특정 테넌트(조직/부서) 전용 노드 자원 예약 및 격리 관리 |
클러스터 목록 속성
| 테이블 항목 | 설명 및 의미 |
|---|---|
| 클러스터 | 클러스터 명칭 및 고유 식별자 (clu_... - 오퍼레이터 설정의 clusterId와 일치) |
| API 주소 | 제어 플레인이 해당 클러스터의 세션 리소스를 프로비저닝 및 동기화할 때 접근하는 API 서버 엔드포인트 |
| 세션 도메인 | 해당 클러스터에서 구동되는 세션 서비스에 할당되는 와일드카드 호스트명 (미지정 시 제어 플레인 기본 도메인 적용) |
| 상태 | connected (정상 연결) 또는 연결 상태 프로브(Probe) 실행 시 수집된 최근 오류 메시지 |
| 노드 / GPU / 실행 세션 | 해당 클러스터가 전체 플릿에 기여하고 있는 노드 수, GPU 카드 수, 현재 실행 중인 세션 수 |
| 하트비트 | 데이터 플레인 오퍼레이터로부터 마지막 인벤토리 보고가 수신된 후 경과된 시간 |
클러스터 목록 행을 클릭하면 해당 클러스터에 속한 상세 노드 목록이 하단으로 펼쳐집니다.
클러스터 등록
제어 플레인이 구동되는 로컬 클러스터는 설치 시 자동 등록됩니다 (bootstrapLocalCluster: true). 멀티 클러스터 환경에서 추가 데이터 플레인 클러스터를 연동할 때는 주로 hack/attach-cluster.sh 자동화 스크립트를 사용합니다. 해당 스크립트는 클러스터 등록과 함께 오퍼레이터, HAMi, Ingress Controller 및 선택적 CSI 드라이버 배포까지 한 번에 수행합니다. 상세한 절차는 멀티 클러스터 가이드를 참조하세요.
관리자 콘솔 UI에서 대화 상자를 통해 직접 등록할 경우 클러스터 이름과 대상 클러스터의 kubeconfig 파일이 필요합니다. 등록 요청 제출 시 제어 플레인은 승인 전 사전 프로브(Probe) 검증을 수행합니다.
- API 서버 통신 검증: 제출된
kubeconfig를 통한 API 서버 도달 가능성 확인 - RuntimeClass 검증:
nvidiaRuntimeClass 가용성 확인 - vGPU 모니터 검증: HAMi 오퍼레이터의
nvidia.com/gpumem리소스 노출/광고 상태 확인
프로브 검사 실패 시 연동 실패 단계 및 구체적 원인을 명시합니다.
클러스터 등록 시 필수 점검 사항:
kubeconfig내 API Server 주소 (server:): 제어 플레인 파드 내부 네트워크에서 직접 통신이 가능한 IP/도메인이어야 합니다. 로컬 개발 환경의 kubeadmadmin.conf에서 주로 사용되는127.0.0.1주소는 파드 내부에서 도달할 수 없어 연결 실패의 주된 원인이 됩니다.- 클러스터 ID 동기화: 등록 절차를 통해 발급된 고유
clusterId(clu_...)는 대상 클러스터에 배포되는 오퍼레이터 Helm 차트 설정에 정확히 일치하도록 지정해야 합니다. ID가 불일치할 경우 오퍼레이터의 인벤토리 보고 및 상태 콜백이 거부됩니다.
제출된 kubeconfig 정보는 데이터베이스에 평문으로 저장되지 않으며, 시크릿(Secret) 참조 형태로 안전하게 보관됩니다.
세션 도메인 (Session Domain)
각 클러스터는 자체 Ingress Controller를 통해 해당 클러스터에서 구동되는 세션의 웹 접속 URL을 서비스합니다. 따라서 **세션 도메인(Session Domain)**은 해당 데이터 플레인 클러스터의 Ingress IP로 라우팅되는 DNS 호스트명이어야 합니다.
- 설정 방식:
attach-cluster.sh --session-domain옵션으로 최초 지정하거나, API를 통해PATCH /api/v1/clusters/{id}(session_domain필드)로 변경할 수 있습니다. (콘솔 UI에서는 조회만 제공하며 직접 수정은 API를 통해 수행합니다.) - 주의사항: 세션 도메인을 비워둘 경우 세션 접속 URL이 제어 플레인 기본 도메인으로 안내되어 Ingress 라우팅 실패(404 Error)가 발생합니다. 멀티 클러스터 구성 시 가장 흔히 발생하는 설정 오류 중 하나입니다.
클러스터 정보 편집
클러스터 목록의 편집 버튼을 통해 표시 이름, 클러스터 역할(primary 또는 standby), API 주소를 변경할 수 있습니다.
이미 등록된 클러스터의
kubeconfig자격 증명 자체를 인플레이스(In-place) 교체하는 것은 지원되지 않습니다. 자격 증명 교체가 필요한 경우 아래 등록 해제 절차를 참조하세요.
클러스터 등록 해제 (Unregister)
실행 중인 세션이나 자원 할당이 남아있는 클러스터는 등록 해제 요청이 거부됩니다. 클러스터가 성공적으로 제거되면 다음과 같이 처리됩니다.
- 해당 클러스터 소속 노드, GPU 디바이스, 스토리지 풀 개체가 콘솔 인벤토리에서 삭제 정리됩니다.
- 이전 세션 실행 이력 및 원장 기록은 영구 보존됩니다. (과금 및 감사 원장에서 참조)
- 해당 클러스터의 오퍼레이터 파드는 Helm 삭제 처리 전까지 계속 실행되지만, 제어 플레인으로의 모든 콜백 요청은 거부됩니다.
클러스터 자격 증명(
kubeconfig) 교체 절차: 클러스터 인증 정보를 교체하려면 클러스터를 등록 해제한 후 재등록해야 합니다. 이때 신규clusterId가 새로 발급되므로, 재등록 후 오퍼레이터 Helm 차트의clusterId설정값을 업데이트하여 재배포를 진행하세요.