쿠버네티스 클러스터

개요

쿠버네티스 클러스터는 ECI가 컨트롤 플레인을 운영하는 관리형 쿠버네티스입니다. 사용자는 노드 풀로 워크로드가 실행될 노드를 구성하고, kubectl로 클러스터를 사용합니다.

이 문서는 쿠버네티스 클러스터를 처음 사용하는 개발자와 운영자를 대상으로 합니다. 전체 흐름은 다음과 같습니다.

클러스터 생성
노드 풀 추가
kubectl로 연결
필요한 경우 로드밸런서와 영구 볼륨 사용 설정

구성 요소

구성 요소	설명
클러스터	쿠버네티스 클러스터 하나. 이름, 버전, 서브넷, API 엔드포인트를 가집니다
컨트롤 플레인	클러스터를 관리하는 서버. ECI가 운영하며 1대 또는 3대로 구성합니다
노드 풀	같은 사양의 노드 묶음. 한 클러스터에 여러 개를 둘 수 있습니다
노드	노드 풀에 속한 가상머신. 워크로드(파드)가 실행됩니다

시작하기 전에

필요 권한

작업	권한 코드
클러스터 생성	`ACL.Resource.Compute.KubernetesCluster.CREATE`
노드 풀 추가	`ACL.Resource.Compute.KubernetesNodePool.CREATE`
kubeconfig 발급	`ACL.Resource.Compute.KubernetesCluster.ACCESS_API`, `ACL.User.UserAccessToken.CREATE`

kubeconfig 발급 권한은 기본 역할 중 Owner, Contributor, Support에 포함되며 Reader에는 없습니다. 권한이 없으면 화면에 필요한 권한의 이름과 코드가 표시되므로, 이 코드를 관리자에게 전달합니다. 권한 관리는 역할 기반 접근 제어를 참고하세요.

네트워크 요건

클러스터를 배치할 가상머신 용도의 서브넷이 필요합니다.
서브넷에는 컨트롤 플레인과 노드 수만큼 빈 IP가 있어야 합니다. 노드 한 대가 IP 하나를 사용합니다.
서브넷이 속한 가상 네트워크의 대역은 10.96.0.0/16, 10.244.0.0/16과 겹치지 않아야 합니다. 이 두 대역은 클러스터 내부의 Service와 파드가 사용합니다.

요금

쿠버네티스 클러스터 자체에는 요금이 부과되지 않습니다. 클러스터와 노드 풀을 구성하는 아래 리소스에 각각 요금이 부과되며, 할당량도 이 리소스를 기준으로 확인합니다.

단위	과금 대상 리소스
컨트롤 플레인 노드 1대	가상머신, 부트 디스크, 네트워크 인터페이스, 공인 IP
클러스터 1개	엔드포인트용 로드밸런서 1개, 공인 IP 1개
노드 1대	가상머신, 부트 디스크, 네트워크 인터페이스, 공인 IP

예를 들어 컨트롤 플레인 3대와 노드 5대로 구성하면 공인 IP 9개와 로드밸런서 1개가 사용됩니다.

클러스터 생성

컴퓨트 > 쿠버네티스에서 클러스터 생성을 클릭합니다.
아래 항목을 입력합니다.
화면 하단 리소스 구성에서 사양, 시간당 요금, 할당량을 확인합니다.
생성을 클릭합니다.

항목	설명
이름	클러스터 이름
쿠버네티스 버전	클러스터의 쿠버네티스 버전
가상 네트워크	클러스터를 배치할 가상 네트워크
서브넷	선택한 가상 네트워크 안에서 컨트롤 플레인과 노드가 사용할 서브넷
컨트롤 플레인 노드 수	1대 · 단일 또는 3대 · 고가용성
사용자 이름 / 비밀번호	컨트롤 플레인 노드의 운영체제 계정

입력 규칙은 다음과 같습니다.

이름: 1~32자의 영문 소문자, 숫자, 하이픈(-)으로 구성하며 영문자 또는 숫자로 시작하고 끝나야 합니다.
사용자 이름: 1~32자이며 영문 소문자 또는 _로 시작하고 소문자, 숫자, _, -만 사용할 수 있습니다.
비밀번호: 강도 검사를 통과해야 합니다.

가상 네트워크나 서브넷이 없으면 각 항목의 가상 네트워크 생성, 서브넷 생성으로 생성 화면을 벗어나지 않고 만들 수 있습니다.

생성을 요청하면 클러스터 상세 페이지 상단에 진행 중인 작업 카드가 표시되며, 컨트롤 플레인과 노드 풀이 모두 준비되면 사라집니다.

생성 후 변경할 수 없는 항목

이름, 서브넷, 노드 사양(인스턴스 타입·디스크), 노드 계정은 생성 후 변경할 수 없습니다. 노드 수는 설정 탭에서 변경할 수 있고, 쿠버네티스 버전은 버전 업그레이드로 올릴 수 있습니다.

컨트롤 플레인 노드 수

구성	특징
1대 · 단일	서버 장애 시 클러스터 조작이 중단되며, 실행 중인 워크로드는 유지됩니다
3대 · 고가용성	서버 3대를 로드밸런서로 묶어 1대에 장애가 생겨도 클러스터 조작이 유지됩니다

컨트롤 플레인 노드 수는 생성 후에도 설정 탭에서 1대와 3대 사이로 변경할 수 있습니다.

노드 풀 추가

클러스터에는 워크로드를 실행할 노드가 없으므로 노드 풀을 하나 이상 추가해야 합니다.

클러스터 상세 페이지에서 노드 풀 추가를 클릭합니다.
아래 항목을 입력하고 생성을 클릭합니다.

항목	설명
이름	노드 풀 이름. 클러스터 이름과 같은 규칙을 따릅니다
인스턴스 타입	노드 사양. GPU 노드가 필요하면 GPU 타입을 선택합니다
가격 유형	온디맨드 또는 예약
노드 수	1~64대
사용자 이름 / 비밀번호	노드의 운영체제 계정. 클러스터와 같은 규칙을 따릅니다

용도별로 노드 풀을 나누면 관리가 쉬워집니다. 예를 들어 서비스용 CPU 노드 풀과 학습용 GPU 노드 풀을 따로 구성할 수 있습니다.

kubectl로 연결

클러스터 상세 페이지 제목 아래의 연결하기를 클릭하면 연결 절차가 3단계로 안내됩니다.

kubectl 설치

kubectl이 없다면 쿠버네티스 공식 설치 안내에 따라 설치합니다. 클러스터 버전과 마이너 버전 차이가 1 이내인 kubectl을 사용합니다.

kubectl version --client

kubeconfig 발급

연결하기 창에서 만료 기간을 선택합니다. 30일, 90일, 6개월, 12개월 또는 사용자 지정 날짜를 선택할 수 있습니다.
발급을 클릭합니다.
다운로드를 클릭해 <클러스터 이름>-kubeconfig.yaml 파일을 저장합니다.

kubeconfig는 한 번만 표시됩니다

창을 닫으면 발급한 kubeconfig를 다시 볼 수 없습니다. 닫기 전에 다운로드하거나 복사하세요.
발급할 때마다 내 계정의 액세스 토큰이 새로 만들어져 kubeconfig에 포함됩니다. 이 토큰은 내 계정의 권한을 그대로 가지므로 비밀번호처럼 관리하세요.
kubeconfig로 접속한 사용자는 클러스터 안에서 클러스터 관리자 권한을 가집니다.
토큰은 특정 클러스터에 한정되지 않으며, 같은 조직에서 내가 접근할 수 있는 다른 클러스터에도 사용할 수 있습니다.
다른 사람과 공유하거나 저장소에 올리지 마세요.

연결 확인

kubeconfig를 저장한 폴더에서 아래 명령을 실행합니다. 운영체제와 셸에 관계없이 같은 명령을 사용합니다.

kubectl --kubeconfig <클러스터 이름>-kubeconfig.yaml get nodes

노드 목록이 표시되면 연결된 것입니다.

NAME           STATUS   ROLES           AGE   VERSION
cloud-joomev   Ready    control-plane   22m   v1.33.13

노드 풀을 추가하기 전에는 컨트롤 플레인 노드만 표시되며, 노드 풀의 노드는 ROLES가 <none>으로 표시됩니다.

kubeconfig의 클러스터와 컨텍스트 이름은 포털의 클러스터 이름이 아닌 cl-<짧은 ID> 형식입니다(예: cl-80zrrc). 여러 클러스터의 kubeconfig를 함께 사용할 때 참고하세요.

로드밸런서와 영구 볼륨 사용 설정

클러스터에서 LoadBalancer 타입 Service와 영구 볼륨(PVC)을 사용하려면, 클러스터 생성 후 액세스 토큰을 한 번 등록해야 합니다.

두 기능은 클러스터 안의 ECI 클라우드 컨트롤러와 블록 스토리지 드라이버가 사용자를 대신해 ECI 로드밸런서와 블록 스토리지를 관리하는 방식으로 제공되며, 이 구성 요소가 ECI API를 호출하는 데 액세스 토큰이 필요합니다. 토큰을 등록하기 전에는 LoadBalancer Service의 EXTERNAL-IP가 <pending>으로, PVC가 Pending으로 유지됩니다.

전용 액세스 토큰 발급

사용자 관리 > 사용자 액세스 토큰에서 이 클러스터 전용 토큰을 발급합니다. 다른 용도와 토큰을 함께 사용하는 것은 권장하지 않습니다.

액세스 토큰의 권한은 발급한 사용자의 현재 역할을 따르며, 역할이 바뀌면 이미 발급한 토큰의 권한도 함께 바뀝니다. 발급하는 사용자에게 아래 권한이 있어야 합니다.

리소스	필요 권한
로드밸런서	생성 · 조회 · 삭제
공인 IP	생성 · 조회 · 삭제
블록 스토리지	생성 · 조회 · 수정 · 삭제
네트워크 인터페이스	조회
서브넷	조회
가상머신	조회

권한을 최소화하려면 위 권한만 가진 역할을 만들어 이 용도의 사용자에게 부여하고, 그 사용자로 토큰을 발급하는 방식을 권장합니다. 역할 생성과 부여는 역할 기반 접근 제어를 참고하세요.

권한 코드 목록

로드밸런서: ACL.Resource.Network.LoadBalancer.CREATE, ACL.Resource.Network.LoadBalancer.READ, ACL.Resource.Network.LoadBalancer.DELETE
공인 IP: ACL.Resource.Network.PublicIp.CREATE, ACL.Resource.Network.PublicIp.READ, ACL.Resource.Network.PublicIp.DELETE
블록 스토리지: ACL.Resource.Storage.BlockStorage.CREATE, ACL.Resource.Storage.BlockStorage.READ, ACL.Resource.Storage.BlockStorage.UPDATE, ACL.Resource.Storage.BlockStorage.DELETE
네트워크 인터페이스: ACL.Resource.Network.NetworkInterface.READ
서브넷: ACL.Resource.Network.Subnet.READ
가상머신: ACL.Resource.Compute.VirtualMachine.READ

클러스터에 토큰 등록

발급한 토큰을 eci-system 네임스페이스에 eci-cloud-provider-credentials Secret으로 등록합니다. 키 이름은 반드시 ECI_API_TOKEN이어야 합니다.

kubectl -n eci-system create secret generic eci-cloud-provider-credentials \
  --from-literal=ECI_API_TOKEN=<발급한 액세스 토큰>

두 구성 요소는 시작할 때 토큰을 읽으므로, Secret을 등록하거나 변경한 뒤에는 재시작해야 반영됩니다.

kubectl -n eci-system rollout restart \
  ds/eci-cloud-controller-manager deploy/eci-block-csi-controller

재시작이 끝나면 대기 중이던 Service와 PVC가 자동으로 처리됩니다.

토큰 갱신

액세스 토큰에는 만료 기한이 있습니다. 만료 전에 새 토큰을 발급해 같은 방법으로 Secret을 교체하고 두 구성 요소를 재시작합니다.

kubectl -n eci-system create secret generic eci-cloud-provider-credentials \
  --from-literal=ECI_API_TOKEN=<새 액세스 토큰> \
  --dry-run=client -o yaml | kubectl apply -f -
kubectl -n eci-system rollout restart \
  ds/eci-cloud-controller-manager deploy/eci-block-csi-controller

토큰이 만료되어도 이미 만들어진 로드밸런서와 볼륨은 계속 동작하지만, 새 리소스 생성과 노드 변경 반영은 중단됩니다.

Secret 접근 관리

이 Secret은 클러스터 관리자 권한이 있는 사용자라면 누구나 조회할 수 있습니다. 클러스터 접근 권한을 신중하게 관리하세요.

클러스터 운영

클러스터 상태

상태	설명
요청됨	생성 요청이 접수되었습니다
생성 중	컨트롤 플레인 또는 노드를 만들고 있습니다
실행 중	클러스터를 사용할 수 있습니다
삭제 중	삭제가 진행 중입니다
삭제됨	삭제가 완료되었습니다

노드 수 변경과 버전 업그레이드 중에도 상태는 실행 중으로 유지되며, 진행 상황은 진행 중인 작업 카드에서 확인합니다.

상세 페이지 구성

탭	내용
기본 정보	클러스터 정보, 네트워크, 컨트롤 플레인, 노드 풀 요약
노드 풀	노드 풀 목록. 노드 풀을 선택하면 노드 풀 상세로 이동합니다
메트릭	노드별 CPU, 메모리, 네트워크, 스토리지, GPU 메트릭
설정	컨트롤 플레인 노드 수 변경, 버전 업그레이드, 클러스터 삭제

노드 풀 상세 페이지도 같은 구성이며, 설정 탭에서 노드 수(1~64대)를 변경합니다.

노드 수 변경

노드를 늘리려면 늘어나는 만큼의 할당량과 서브넷의 빈 IP가 필요합니다. 할당량이 부족하면 저장하기 전에 부족한 항목과 수량이 표시되고 저장이 비활성화됩니다. 노드를 줄일 때는 확인하지 않습니다.

버전 업그레이드

클러스터와 노드 풀의 쿠버네티스 버전은 각 상세 페이지의 설정 탭 > 버전 업그레이드에서 올립니다.

클러스터는 마이너 버전 한 단계씩만 올릴 수 있습니다(예: v1.33 → v1.34).
클러스터를 먼저 업그레이드한 뒤 노드 풀을 업그레이드합니다. 노드 풀은 클러스터 버전까지 한 번에 올릴 수 있으며, 클러스터보다 높은 버전으로는 올릴 수 없습니다.
클러스터와 노드 풀 모두 낮은 버전으로 되돌릴 수 없습니다.
클러스터를 업그레이드해도 기존 노드 풀은 자동으로 업그레이드되지 않습니다. 노드 풀은 클러스터보다 마이너 버전 세 단계까지 낮아도 정상 동작하지만, 그보다 낮은 노드 풀이 있으면 클러스터의 다음 업그레이드가 거부됩니다.
클러스터 업그레이드 후 새로 만드는 노드 풀은 클러스터 버전으로 생성됩니다.
생성이나 변경 작업이 진행 중일 때는 업그레이드를 시작할 수 없습니다.

선택할 수 없는 버전은 목록에 사유와 함께 비활성으로 표시됩니다. 클러스터의 다음 업그레이드를 막을 만큼 낮은 노드 풀은 노드 풀 표와 노드 풀 상세의 버전 항목에 경고 아이콘으로 표시됩니다.

액세스 토큰 관리

kubeconfig와 함께 만들어진 토큰은 사용자 관리 > 사용자 액세스 토큰에서 확인하며, 쿠버네티스 클러스터 컬럼에 토큰이 발급된 클러스터가 표시됩니다.

토큰이 만료되면 kubeconfig를 다시 발급합니다.
사용하지 않는 kubeconfig의 토큰은 이 메뉴에서 폐기합니다. 폐기한 토큰이 포함된 kubeconfig로는 접속할 수 없습니다.

자세한 내용은 액세스 토큰을 참고하세요.

쿠버네티스가 관리하는 리소스

클러스터가 만든 리소스를 포털에서 직접 변경하면 클러스터와 상태가 어긋날 수 있어 일부 조작이 제한됩니다.

노드 가상머신: 컴퓨트 > 가상머신의 쿠버네티스 노드 탭에 표시되며, 실행·중지·수정·삭제 버튼은 표시되지 않습니다. 컨트롤 플레인 가상머신은 목록에 표시되지 않습니다.
로드밸런서: LoadBalancer Service로 만들어진 로드밸런서는 클러스터에서 해당 Service를 삭제해 정리합니다.
블록 스토리지: PVC로 만들어진 볼륨은 블록 스토리지 드라이버가 관리하므로, 클러스터에서 PVC를 삭제해 정리합니다.

삭제

삭제는 되돌릴 수 없습니다. 노드 풀을 먼저 삭제한 뒤 클러스터를 삭제합니다.

노드 풀 상세의 설정 탭 하단에서 노드 풀을 삭제합니다. 소속 노드와 디스크가 함께 삭제되며 실행 중인 워크로드가 중단됩니다.
클러스터 상세의 설정 탭 하단에서 클러스터를 삭제합니다. 컨트롤 플레인 노드, 로드밸런서, 공인 IP가 함께 삭제됩니다.

문제 해결

연결되지 않을 때

오류 메시지	원인과 조치
`Unable to connect to the server`	엔드포인트에 연결할 수 없습니다. 클러스터 상세 네트워크 카드에서 방화벽 설정을 확인하세요
`x509: certificate ...`	kubeconfig가 손상됐거나 다른 클러스터의 파일입니다. kubeconfig를 다시 발급하세요
`Unauthorized`	토큰 만료·폐기, 권한 회수, 계정 차단, 조직 일시 중지 중 하나입니다. 권한과 계정 상태를 확인한 뒤 kubeconfig를 다시 발급하세요

로드밸런서나 볼륨이 만들어지지 않을 때

EXTERNAL-IP가 <pending>이거나 PVC가 Pending이면 액세스 토큰이 등록되지 않았거나 만료된 경우입니다. 로드밸런서와 영구 볼륨 사용 설정에 따라 토큰을 등록하거나 갱신하세요.

삭제할 수 없을 때

노드 풀이 남아 있는 클러스터: 노드 풀을 모두 삭제한 뒤 클러스터를 삭제합니다. 노드 풀이 삭제 중일 때도 삭제가 끝날 때까지 기다려야 합니다.
로드밸런서가 대상으로 사용 중인 노드 풀: 클러스터에서 LoadBalancer Service를 먼저 삭제합니다.
클러스터가 사용 중인 서브넷: 클러스터를 먼저 삭제합니다.

다음 단계

방화벽 — 클러스터 서브넷의 접근 규칙 설정
로드밸런서 — 로드밸런서 동작 방식
블록 스토리지 — PVC로 만들어지는 볼륨
액세스 토큰 — kubeconfig 토큰 확인과 폐기
역할 기반 접근 제어 — 쿠버네티스 권한 부여

개요​

구성 요소​

시작하기 전에​

필요 권한​

네트워크 요건​

요금​

클러스터 생성​

컨트롤 플레인 노드 수​

노드 풀 추가​

kubectl로 연결​

kubectl 설치​

kubeconfig 발급​

연결 확인​

로드밸런서와 영구 볼륨 사용 설정​

전용 액세스 토큰 발급​

클러스터에 토큰 등록​

토큰 갱신​

클러스터 운영​

클러스터 상태​

상세 페이지 구성​

노드 수 변경​

버전 업그레이드​

액세스 토큰 관리​

쿠버네티스가 관리하는 리소스​

삭제​

문제 해결​

연결되지 않을 때​

로드밸런서나 볼륨이 만들어지지 않을 때​

삭제할 수 없을 때​

다음 단계​

개요