> For the complete documentation index, see [llms.txt](https://ia-cloud.gitbook.io/cloudia-manual/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://ia-cloud.gitbook.io/cloudia-manual/user-guide/quickstarts/06-configure-kubernetes-cluster.md).

# 쿠버네티스 클러스터 구성하기

이 문서는 네트워크 준비부터 클러스터(컨트롤 플레인) 생성, 워커 노드 추가까지의 절차를 안내합니다.

## 사전 준비

* 프로젝트 리소스 여유
  * 예: vCPU 10 이상, RAM 20GB 이상
* VPC, 서브넷 준비
  * 클러스터에 사용할 VPC와 서브넷 1개
* (선택) CA 파일 준비
  * 직접 준비한 CA를 사용하려면 `ca.crt`(CA 인증서)와 `ca.key`(개인 키)를 함께 준비합니다.
  * 첨부하지 않으면 시스템이 CA를 자동으로 생성합니다.

> 💡 **참고:** CA 파일을 직접 준비하려면 `openssl`로 개인 키와 자체 서명 인증서를 생성할 수 있습니다. 자세한 내용은 [클러스터](https://github.com/iAcloud-inc/CloudiA-manual/blob/main/docs/project/kubernetes/cluster/cluster.md#ca-파일-설정) 문서를 참고하세요.

## 개요

1. [클러스터(컨트롤 플레인) 생성](#step-1)
2. [클러스터 실행 상태 확인](#step-2)
3. [워커 노드 추가](#step-3)
4. [워커 노드 READY 상태 확인](#step-4)

## 1단계: 클러스터(컨트롤 플레인) 생성

**수행 계정/화면:** `project-owner 계정` / `프로젝트 페이지`

### 절차

1. `쿠버네티스 > 클러스터`로 이동한 뒤 `생성` 버튼을 클릭합니다.
2. 클러스터 기본 정보(클러스터 이름)를 입력합니다.
3. VPC와 서브넷을 선택합니다. 필요하면 추가 보안그룹을 선택합니다.
4. 컨트롤 플레인 설정에서 인스턴스 구성, 버전, 컨트롤 플레인 수를 선택합니다. 버전을 선택하면 고급 옵션에서 디스크 크기와 스토리지 도메인(선택)을 설정할 수 있습니다.
5. 사용자 계정(사용자 이름)과 인증 방식(비밀번호 또는 SSH 키)을 입력합니다.
6. (선택) CA 파일 설정에서 `등록` 버튼을 클릭하고, 열린 모달에서 `ca.crt`와 `ca.key`를 함께 첨부합니다.
7. `생성` 버튼을 클릭합니다.

### 입력 예시

| 항목          | 값                     |
| ----------- | --------------------- |
| 클러스터 이름     | `example-cluster-001` |
| VPC         | `example-vpc`         |
| 서브넷         | `example-subnet`      |
| 인스턴스 구성     | `t2.medium`           |
| 버전          | `1.35`                |
| 컨트롤 플레인 수   | `3`                   |
| 사용자 이름      | `cloudia`             |
| 비밀번호        | `cloudia`             |
| CA 인증서 (선택) | `ca.crt`              |
| 개인 키 (선택)   | `ca.key`              |

> ⚠️ **주의:** CA 인증서와 개인 키는 둘 다 첨부하거나 둘 다 첨부하지 않아야 합니다. 하나만 첨부할 수 없습니다.

### 확인

* 클러스터가 목록에 `생성 중` 상태로 표시됩니다.

## 2단계: 클러스터 실행 상태 확인

**수행 계정/화면:** `project-owner 계정` / `프로젝트 페이지`

### 절차

1. 클러스터 목록에서 생성한 클러스터 상태를 확인합니다.
2. 상태 전환이 완료될 때까지 대기 후 재조회합니다.

### 확인

* 클러스터 상태가 `실행 중`으로 전환됩니다.
* 컨트롤 플레인 수가 `3/3`으로 표시됩니다.

## 3단계: 워커 노드 추가

**수행 계정/화면:** `project-owner 계정` / `프로젝트 페이지`

### 절차

1. 대상 클러스터 상세 화면으로 이동합니다.
2. `컴퓨트` 탭을 선택합니다.
3. `워커 노드 추가` 버튼을 클릭합니다.
4. 워커 노드 구성(인스턴스 구성, 워커 노드 수, 디스크 크기 등)과 사용자 계정 정보를 입력합니다.
5. `생성` 버튼을 클릭합니다.

> 💡 **참고:** `워커 노드 추가` 버튼은 클러스터 상태가 `UP`일 때만 활성화됩니다.

### 입력 예시

| 항목      | 값                     |
| ------- | --------------------- |
| 대상 클러스터 | `example-cluster-001` |
| 워커 노드 수 | `2`                   |
| 인스턴스 구성 | `t2.medium`           |
| 사용자 이름  | `cloudia`             |
| 비밀번호    | `cloudia`             |

### 확인

* 컴퓨트 탭 노드 목록에 신규 워커 노드가 추가됩니다.
* 초기 상태가 `생성 중`으로 표시될 수 있습니다.

## 4단계: 워커 노드 READY 상태 확인

**수행 계정/화면:** `project-owner 계정` / `프로젝트 페이지`

### 절차

1. 컴퓨트 탭 노드 목록을 재조회합니다.
2. 신규 워커 노드의 상태와 역할을 확인합니다.

### 확인

* 역할이 `워커 노드`로 표시됩니다.
* 상태가 `실행 중`으로 전환됩니다.