# Kubesphere 클러스터 설치

##### **작업 환경**

💡 *RockyKVM에서 실습 진행 . 총 사용한 VM들의 목록과 사양은:*

<table border="1" class="align-center" id="bkmrk-%EB%85%B8%EB%93%9C-os-ip-cpu-memory-" style="border-collapse: collapse; width: 200%; height: 100%; border-width: 2px;"><colgroup><col style="width: 14.2091%;"></col><col style="width: 14.2091%;"></col><col style="width: 14.2091%;"></col><col style="width: 14.2091%;"></col><col style="width: 14.2091%;"></col><col style="width: 14.2091%;"></col><col style="width: 14.2091%;"></col></colgroup><tbody><tr><td style="border-width: 2px; padding: 1px;">노드</td><td style="border-width: 2px; padding: 1px;">OS</td><td style="border-width: 2px; padding: 1px;">IP</td><td style="border-width: 2px; padding: 1px;">CPU</td><td style="border-width: 2px; padding: 1px;">Memory</td><td style="border-width: 2px; padding: 1px;">Volume</td><td style="border-width: 2px; padding: 1px;">Extra Volume</td></tr><tr><td style="border-width: 2px; padding: 1px;">Ansible Node</td><td style="border-width: 2px; padding: 1px;">Rocky Linux 9.2</td><td style="border-width: 2px; padding: 1px;">192.168.122.103</td><td style="border-width: 2px; padding: 1px;">12</td><td style="border-width: 2px; padding: 1px;">16GiB</td><td style="border-width: 2px; padding: 1px;">100GiB</td><td style="border-width: 2px; padding: 1px;">30GiB + 30GiB</td></tr><tr><td style="border-width: 2px; padding: 1px;">Master Node</td><td style="border-width: 2px; padding: 1px;">Rocky Linux 9.2</td><td style="border-width: 2px; padding: 1px;">192.168.122.8</td><td style="border-width: 2px; padding: 1px;">12</td><td style="border-width: 2px; padding: 1px;">32GiB</td><td style="border-width: 2px; padding: 1px;">120GiB</td><td style="border-width: 2px; padding: 1px;">  
</td></tr><tr><td style="border-width: 2px; padding: 1px;">Worker Node1</td><td style="border-width: 2px; padding: 1px;">Rocky Linux 9.2</td><td style="border-width: 2px; padding: 1px;">192.168.122.52</td><td style="border-width: 2px; padding: 1px;">12</td><td style="border-width: 2px; padding: 1px;">32GiB</td><td style="border-width: 2px; padding: 1px;">120GiB</td><td style="border-width: 2px; padding: 1px;">  
</td></tr><tr><td style="border-width: 2px; padding: 1px;">Worker Node2</td><td style="border-width: 2px; padding: 1px;">Rocky Linux 9.2</td><td style="border-width: 2px; padding: 1px;">192.168.122.240</td><td style="border-width: 2px; padding: 1px;">12</td><td style="border-width: 2px; padding: 1px;">32GiB</td><td style="border-width: 2px; padding: 1px;">120GiB</td><td style="border-width: 2px; padding: 1px;">  
</td></tr></tbody></table>

##### **요구 사항**

- 현재 KubeSphere Major 버전은 3.3으로 Kubernetes 클러스터의 버전은 v1.20.x, v1.21.x, v1.22.x, v1.23.x, 또는 v1.24.x 이어야 한다

<p class="callout warning">쿠버네티스1.22 버전부터는 비호환성으로 인해 edge node의 일부 기능을 사용할 수 없다. 따라서 edge node를 사용하려면 Kubernetes v1.21.x 를 설치하는 것이 좋다.</p>

<p class="callout info">edge node는 클러스터 컴퓨팅에서 다른 노드와의 통신을 위한 최종 사용자 포털/게이트웨이 역할을 하는 노드이다.</p>

- x86\_64 CPU만 지원되며, ARM CPU는 현재 완전히 지원되지 않는다
- CPU자원은 최소 1코어 그리고 메모리는 최소 2GiB 이어야 한다
- Kubernetes 클러스터에 기본 StorageClass가 구성되어 있어야 한다. `kubectl get sc`명령어를 사용하여 클러스터의 StorageClass 상태를 확인한다. 추가로 StorageClass는 **Default** class에 속 해야 한다.

<p class="callout info">Storage Class는 PV(Persistent Volume)을 동적으로 프로비저닝하기 위한 스토리지 유형과 해당 속성을 정의하는 구성.  
</p>

더 자세한 요구 사항들은 KubeSphere 공식 문서에서 확인 가능 하다.

[Prerequisites for KubeSphere 바로가기](https://www.kubesphere.io/docs/v3.3/installing-on-kubernetes/introduction/prerequisites/)

##### **KubeSphere 설치를 위한 준비 작업**

쿠버네티스 클러스터 생성 작업은 이미 수동과 자동 방법으로 Wiki에 추가 되어있다.

바로가기:

[쿠버네티스 클러스터 수동 (Kubeadm) 설치](http://138.2.116.150/books/kubernetes/page/kubeadm)

[쿠버네티스 클러스터 자동 (Kubespray) 설치](http://138.2.116.150/books/kubernetes/page/kubespray)

<p class="callout warning">Kubernetes v1.24 이상이면 특정 Kubesphere 서비스가 실행 되지 않으니 주의 할 것!</p>

이번 KubeSphere 설치를 하기 위해 Kubespray를 통해 쿠버네티스 클러스터 v1.24.6버전을 설치 하였다.

```bash
kubectl get nodes
NAME    STATUS   ROLES           AGE    VERSION
node1   Ready    control-plane   3d3h   v1.24.6
node2   Ready    <none>          3d3h   v1.24.6
node3   Ready    <none>          3d3h   v1.24.6
```

쿠버네티스 클러스터가 준비 된 후, 클러스터의 기본 StorageClass 및 PersistentVolume을 구성해야 한다.

그러기 위해 먼저 NFS를 Ansible 노드에서 설정을 하여 2개의 워커노드들이 각각 PV를 사용 할 수 있게 설정 해주는 작업을 실행 한다. 이미 Ansible 노드에 추가로 2개의 디스크를 추가 하였다.

```bash
lsblk
NAME           MAJ:MIN RM  SIZE RO TYPE MOUNTPOINTS
sr0             11:0    1 1024M  0 rom
vda            252:0    0  100G  0 disk
├─vda1         252:1    0   99M  0 part /boot/efi
├─vda2         252:2    0 1000M  0 part /boot
├─vda3         252:3    0    4M  0 part
├─vda4         252:4    0    1M  0 part
└─vda5         252:5    0 98.9G  0 part
  └─rocky-root 253:0    0 98.9G  0 lvm  /
vdb            252:16   0   30G  0 disk  		# 추가 디스크 1
vdc            252:32   0   30G  0 disk 		# 추가 디스크 2
```

<div id="bkmrk--22"></div><div id="bkmrk--0"></div><div id="bkmrk--1"></div><div id="bkmrk--23">제일 먼저 filesystem 포멧 작업을 진행 한다</div><div id="bkmrk--2"></div><div id="bkmrk--25"></div>```bash
# xfs 파일 시스템으로 포멧
mkfs.xfs /dev/vdb
mkfs.xfs /dev/vdc

# HDD 구성정보 확인 및 XFS 파일시스템 구성 ( 포맷 )
blkid | grep /dev/vdb && blkid | grep /dev/vdc
/dev/vdb: UUID="d77478e3-b832-4117-a470-a868e6dd3eab" TYPE="xfs"
/dev/vdc: UUID="451acf45-b067-49ef-b6fb-49d4c7b44e10" TYPE="xfs"
```

<div id="bkmrk-%23-mkfs.xfs-%2Fdev%2Fsdb"></div><div id="bkmrk-%ED%8C%8C%ED%8B%B0%EC%85%98-%EA%B5%AC%EC%84%B1-%EC%97%86%EC%9D%B4-%ED%95%B4%EB%8B%B9-%EB%94%94%EC%8A%A4%ED%81%AC-%ED%95%98%EB%82%98%EB%A5%BC">파티션 구성 없이 해당 디스크 하나를 단일 파티션으로 사용했다</div><div id="bkmrk-%2Fdev%2Fsdc%3A-uuid%3D%22ab75"></div><div id="bkmrk--27">  
</div><div id="bkmrk--3"></div><div id="bkmrk--4"></div><div id="bkmrk--28">공유 할 디렉터리 생성 및 마운트 작업을 진행 한다</div><div id="bkmrk--5"></div><div id="bkmrk--6"></div>```bash
# 공유 디렉터리로 사용 할 마운트 포인트 생성 및 오토 마운트 설정
mkdir /k8s_data
mkdir /k8s_data2

# 오토 마운트 설정
vi /etc/fstab
/dev/vdb        /k8s_data           xfs     defaults        0 0
/dev/vdc        /k8s_data2           xfs     defaults        0 0

# 마운트 작업 실행
mount -a

# 마운트 상태 확인
df -h

Filesystem              Size  Used Avail Use% Mounted on
devtmpfs                4.0M     0  4.0M   0% /dev
tmpfs                   7.7G     0  7.7G   0% /dev/shm
tmpfs                   3.1G   20M  3.1G   1% /run
/dev/mapper/rocky-root   99G  2.4G   97G   3% /
/dev/vdb                 30G  540M   30G   2% /k8s_data
/dev/vdc                 30G  541M   30G   2% /k8s_data2
```

<div id="bkmrk-%23-mkdir-%2Fnfs_volume_"></div><p class="callout info">참고 : 디스크 파티션 및 파일 시스템을 잘못 구성하였을 경우 초기화 작업 진행  
wipefs -a /dev/vdb  
wipefs -a /dev/vdc</p>

<div id="bkmrk-%23-wipefs--a-%2Fdev%2Fsdc"></div><div id="bkmrk--34"></div><div id="bkmrk--7"></div><div id="bkmrk--8"></div><div id="bkmrk--9"></div><div id="bkmrk--10"></div><div id="bkmrk-%E2%96%A3-%5B-nfs-%EC%84%9C%EB%B9%84%EC%8A%A4-%EC%84%A4%EC%B9%98-%EB%B0%8F-%EC%84%9C%EB%B2%84-">이제 Ansible노드가 NFS 역할을 수행 하기 위해 NFS 패키지를 설치 해줘야 한다</div><div id="bkmrk--11"></div>```bash
# nfs 패키지 설치
dnf -y install nfs*

# exports 파일속 공유할 디렉터리 지정 및 접근 가능 호스트 Mapping 계정등을 설정
#  Worker Node에서 접근하므로 Worker Node의 Network 대역대를 설정
vi /etc/exports
/k8s_data   192.168.122.0/24(rw,all_squash,sync) 
/k8s_data   192.168.122.0/24(rw,all_squash,sync)


# NFS 연결 시 Mapping 계정은 nfs_nobody로 연결되도록 설정
# NFS 공유 디렉터리의 소유그룹 및 허가권 변경작업을 진행
# nfsnobody 그룹 접근 시 쓰기 작업 허용
chown .nfsnobody /k8s_data*
chmod 775 /k8s_data*


# NFS와 rpcbind 서비스들 시작
systemctl start rpcbind
systemctl start nfs-server
systemctl enable rpcbind
systemctl enable nfs-server


# export 상태 확인
exportfs -v
/k8s_data       192.168.122.0/24(sync,wdelay,hide,no_subtree_check,sec=sys,rw,secure,root_squash,all_squash)
/k8s_data2      192.168.122.0/24(sync,wdelay,hide,no_subtree_check,sec=sys,rw,secure,root_squash,all_squash)
```

<div id="bkmrk-%23-yum--y-install-nfs"></div><div id="bkmrk--45"></div><p class="callout info">Firewall은 기본적으로 disabled 상태이어서 'nfs' 와 'rpc-bind' 서비스들을 firewall에 추가 하는 작업은 생략 한다</p>

NFS까지 준비가 되었으면 이제 쿠버네티스 클러스터에서 PV및 StorageClass 작업을 진행 한다

StorageClass를 지정하기 위한 Yaml 파일을 생성 한다

```bash
# Storage관련 YAML파일들을 분리 하기 위해 새로운 디렉터리 생성
mkdir Volume && cd Volume

# storageclass 생성을 위해 YAML 파일
vi storage.yml

apiVersion: storage.k8s.io/v1
kind: StorageClass
metadata:
  name: my-storage-class
  annotations:
    storageclass.kubernetes.io/is-default-class: "true"       # 기본 StorageClass이라고 지정
provisioner: kubernetes.io/no-provisioner
volumeBindingMode: WaitForFirstConsumer

# StorageClass 적용
kubectl apply -f storage.yml
storageclass.storage.k8s.io/my-storage-class created

# 적용 확인
kubectl get sc
NAME						PROVISIONER						RECLAIMPOLICY		VOLUMEBINDINGMODE		ALLOWVOLUMEEXPANSION		AGE
my-storage-class (default)	kubernetes.io/no-provisioner	Delete				WaitForFirstConsumer	false						10m
```

StorageClass를 적용 후 KubeSphere용 PV를 생성 해 줘야 한다.

```bash
# 첫 번째 pv 적용을 위해 YAML 파일
vi pv.yml

apiVersion: v1
kind: PersistentVolume
metadata:
  name: my-pv
spec:
  capacity:
    storage: 30Gi
  accessModes:
    - ReadWriteOnce
  persistentVolumeReclaimPolicy: Retain
  storageClassName: my-storage-class
  nfs:
    path: /k8s_data						
    server: 192.168.122.103				# NFS server의 주소
   

# 두 번째 pv 적용을 위해 YAML 파일
vi pv2.yml

apiVersion: v1
kind: PersistentVolume
metadata:
  name: my-pv2
spec:
  capacity:
    storage: 30Gi
  accessModes:
    - ReadWriteOnce
  persistentVolumeReclaimPolicy: Retain
  storageClassName: my-storage-class
  nfs:
    path: /k8s_data2						
    server: 192.168.122.103				# NFS server의 주소
    
    
# PV YAML 적용
kubectl apply -f pv.yml
kubectl apply -f pv2.yml
persistentvolume/my-pv created
persistentvolume/my-pv2 created

# PV 적용 상태 확인 명령어
kubectl get pv
NAME    CAPACITY   ACCESS MODES   RECLAIM POLICY   STATUS      CLAIM   STORAGECLASS       REASON   AGE
my-pv   30Gi       RWO            Retain           Available           my-storage-class            3s
my-pv2	30Gi	   RWO			  Retain		   Available		   my-storage-class			   3s
```

PV 적용 까지 완료 되었으면, KubeSphere를 설치 하기 위한 모든 준비 작업들은 완료 되었다.

#####   


##### **KubeSphere 설치(온라인)**

KubeSphere 설치를 위한 설치 Manifest 파일들을 다운로드 받는다

```
VER=$( curl --silent "https://api.github.com/repos/kubesphere/ks-installer/releases/latest"| grep '"tag_name"'|sed -E 's/.*"([^"]+)".*/\1/')
wget https://github.com/kubesphere/ks-installer/releases/download/$VER/kubesphere-installer.yaml
wget https://github.com/kubesphere/ks-installer/releases/download/$VER/cluster-configuration.yaml
```

KubeSphere 설치용 Manifest 파일들을 다운로드 받은 후 적용 시킨다

```bash
kubectl apply -f kubesphere-installer.yaml
customresourcedefinition.apiextensions.k8s.io/clusterconfigurations.installer.kubesphere.io created
namespace/kubesphere-system created
serviceaccount/ks-installer created
clusterrole.rbac.authorization.k8s.io/ks-installer created
clusterrolebinding.rbac.authorization.k8s.io/ks-installer created
deployment.apps/ks-installer created

kubectl apply -f cluster-configuration.yaml
clusterconfiguration.installer.kubesphere.io/ks-installer created
```

위 명령어를 실행하면 네임스페이스 kubesphere-system이 생성되고 다른 여러 리소스가 시작된다

다음 명령을 사용하여 배포 지행 현황을 볼 수 있다

```
kubectl logs -n kubesphere-system $(kubectl get pod -n kubesphere-system -l 'app in (ks-install, ks-installer)' -o jsonpath='{.items[0].metadata.name}') -f
```

설치 작업이 완료 되면 아래와 같은 화면을 확인 할 수 있다

[![Screenshot_20230630_131635_Termius.jpg](http://138.2.116.150/uploads/images/gallery/2023-06/scaled-1680-/screenshot-20230630-131635-termius.jpg)](http://138.2.116.150/uploads/images/gallery/2023-06/screenshot-20230630-131635-termius.jpg)

콘솔 접속 확인을 위해 위 IP주소 및 포트 번호로 접속을 하면,

[![image.png](http://138.2.116.150/uploads/images/gallery/2023-06/scaled-1680-/K0Vimage.png)](http://138.2.116.150/uploads/images/gallery/2023-06/K0Vimage.png)

초기 비밀번호와 계정 ID는 설치 완료시 기본적으로 받은 정보로 통해 최초 로그인을 실행 한다.

로그인 시 바로 새로운 패스워드를 입력 하라는 창이 나온다

[![image.png](http://138.2.116.150/uploads/images/gallery/2023-06/scaled-1680-/uRRimage.png)](http://138.2.116.150/uploads/images/gallery/2023-06/uRRimage.png)

패스워드 변경 후 아래와 같은 화면을 볼 수 있다.

[![image.png](http://138.2.116.150/uploads/images/gallery/2023-06/scaled-1680-/uXSimage.png)](http://138.2.116.150/uploads/images/gallery/2023-06/uXSimage.png)

여기서 좌측 상단에 있는 'Platform'을 선택 하여 'Cluster Management' 메뉴를 클릭 시 현재 쿠버네티스 클러스터의 현황을 볼 수 있다.

[![image.png](http://138.2.116.150/uploads/images/gallery/2023-06/scaled-1680-/3DBimage.png)](http://138.2.116.150/uploads/images/gallery/2023-06/3DBimage.png)

[![image.png](http://138.2.116.150/uploads/images/gallery/2023-06/scaled-1680-/ldximage.png)](http://138.2.116.150/uploads/images/gallery/2023-06/ldximage.png)


###   


클러스터의 모든 노드의 정보도 확인 가능 하다

[![image.png](http://138.2.116.150/uploads/images/gallery/2023-06/scaled-1680-/IfFimage.png)](http://138.2.116.150/uploads/images/gallery/2023-06/IfFimage.png)

###   


그 외 파드들의 작동 여부도 확인 가능 하다

[![image.png](http://138.2.116.150/uploads/images/gallery/2023-06/scaled-1680-/5Acimage.png)](http://138.2.116.150/uploads/images/gallery/2023-06/5Acimage.png)

초반에 생성한 StorageClass와 연관된 PVC들의 정보도 볼 수 있다

[![image.png](http://138.2.116.150/uploads/images/gallery/2023-06/scaled-1680-/LNXimage.png)](http://138.2.116.150/uploads/images/gallery/2023-06/LNXimage.png)

Prometheus 파드들이 각 PV를 claim하고 있는 것을 확인 할 수 있다

[![image.png](http://138.2.116.150/uploads/images/gallery/2023-06/scaled-1680-/X2Kimage.png)](http://138.2.116.150/uploads/images/gallery/2023-06/X2Kimage.png)

###   


그 외 KubeSphere 데시보드상 간단한 Monitoring과 로깅 정보도 볼 수 있다

[![image.png](http://138.2.116.150/uploads/images/gallery/2023-06/scaled-1680-/b6Oimage.png)](http://138.2.116.150/uploads/images/gallery/2023-06/b6Oimage.png)

###   


###   


##### **KubeSphere 설치 도중 발생한 ERROR 과 조치**

**1. 버전 호환성 문제**

KubeSphere는 현재 쿠버네티스 버전 1.24 까지 호환 가능 하며, 초반에 Kubesphere를 설치 한 클러스터는 v1.26이였기 때문에 'monitoring task status'는 매번 'failed'이라고 나왔다 [![image.png](http://138.2.116.150/uploads/images/gallery/2023-06/scaled-1680-/Qfmimage.png)](http://138.2.116.150/uploads/images/gallery/2023-06/Qfmimage.png)

 KubeSphere 설치는 완료 되지만 Prometheus 파드들은 계속 Pending 상태에 존재 한다![image.png](http://138.2.116.150/uploads/images/gallery/2023-06/scaled-1680-/t7dimage.png)

이 문제를 해결 하기 위해 Kubernetes 클러스터를 v1.24.6버전으로 맞춰서 실행 하였다.

**2. Prometheus 'CreateContainerConfigError'**

  
모든 설정 및 KubeSphere까지 설치 진행 후 Kubesphere monitoring의 파드들을 확인 한 결과

```
kubectl get pods -n kubesphere-monitoring-system
NAME                                               READY   STATUS                       RESTARTS   AGE
alertmanager-main-0                                2/2     Running                      0          20m
kube-state-metrics-6f6ffbf895-c28hf                3/3     Running                      0          20m
node-exporter-22fdn                                2/2     Running                      0          20m
node-exporter-96gmd                                2/2     Running                      0          20m
notification-manager-deployment-77d5b49896-9lt48   2/2     Running                      0          18m
notification-manager-operator-66c6967d78-bj2ms     2/2     Running                      0          19m
prometheus-k8s-0                                   1/2     CreateContainerConfigError   0          20m
prometheus-operator-b56bb98c4-l4cvp                2/2     Running                      0          20m
kubectl get pods -n kubesphere-monitoring-system
NAME                                               READY   STATUS                       RESTARTS   AGE
alertmanager-main-0                                2/2     Running                      0          20m
kube-state-metrics-6f6ffbf895-c28hf                3/3     Running                      0          20m
node-exporter-22fdn                                2/2     Running                      0          20m
node-exporter-96gmd                                2/2     Running                      0          20m
notification-manager-deployment-77d5b49896-9lt48   2/2     Running                      0          18m
notification-manager-operator-66c6967d78-bj2ms     2/2     Running                      0          19m
prometheus-k8s-0                                   1/2     CreateContainerConfigError   0          20m
prometheus-operator-b56bb98c4-l4cvp                2/2     Running                      0          20m
```

'CreateContainerConfigError'가 발생 하였다. 애러 로그 확인 시 **PV설정 한 경로를 못 찾겠다**는 애러 메시지를 발견 하였다.

이 문제의 원인은 초반에 KubeSphere 설치 전 pv.yml을 통해 PV 설정 할때, Master노드의 로컬 스토리지를 PV로 지정 하였기 때문이다.

<p class="callout info">예: Master 노드상 로컬 스토리지에 /mnt/data 디렉터리 생성 후 pv.yml 파일에 지정</p>

Kubesphere의 Prometheus 파드는 워커 노드에 생성 되고, PV.yml에 지정한 경로를 워커 노드에서 찾고 있었다. 하지만 워커 노드에서는 그 pv를 지정한 경로를 못 찾았기 때문에 계속 ContainerConfigError 가 발생 하였다

위 애러를 해결 하기 위해 각 워커 노드의 로컬 스토리지상 새로운 디렉터리를 생성하여 pv.yml로 지정 하거나, 로컬 스토리지를 사용하지 않고 공유 스토리지를 사용 하고 싶다면, NFS 서버를 통해 pv를 지정 하면 된다

그 후 KubeSphere 관련 모든 파드들의 상태를 확인:

[![image.png](http://138.2.116.150/uploads/images/gallery/2023-06/scaled-1680-/QQKimage.png)](http://138.2.116.150/uploads/images/gallery/2023-06/QQKimage.png)