# **QKS Kubernetes 설정**

QKS Kubernetes 배포를 위한 상세 설정을 설명합니다. 설치환경에 맞게 수정이 필요합니다.

설정파일 위치: `inventory/qks/group_vars/all/all-k8s.yaml`

```yaml
################################################################################
# QKS Kubernetes Environment ################################ BEGIN ###
################################################################################

# K8S 로드밸런서: 도메인
ext_lb_fqdn: "{{ qks_load_balancer_fqdn }}"
# K8S 로드밸런서: 주소
ext_lb_addr: "{{ qks_load_balancer_addr }}"
# K8S 로드밸런서: 포트
ext_lb_port: 8443

# K8S 서비스 : 버전
kube_version: 1.21.4
# K8S 서비스: POD CIDR
kube_pod_cidr: 10.0.0.0/16
# K8S 서비스: SVC CIDR
kube_svc_cidr: 10.1.0.0/16
# K8S 서비스: PROXY MODE
kube_proxy_mode: iptables

# K8S Master 노드 Tatint 여부
kube_master_node_taint: true

# Kubernetes Data Directory
kube_data_dir_cri:     /data/cri         # default: /var/lib/docker
kube_data_dir_kubelet: /data/k8s/kubelet # default: /var/lib/kubelet
kube_data_dir_etcd:    /data/k8s/etcd    # default: /var/lib/etcd

# Kubernetes admin users
kube_admin_users:
  - "{{ ansible_user }}"
  - "root"
  - "ec2-user" # for redhat on AWS
  - "ubuntu"   # for ubuntu on AWS

###############################
# QKS Kubernetes CNI #
###############################

# K8S CNI: 컨테이너 네트워크 선택
kube_cni: calico
# K8S CNI: Calico 버전
cni_calico_version: 3.17.1
# K8S CNI: Calico MTU
cni_calico_mtu: 0
# K8S CNI: Calico iptable 백엔드
cni_calico_iptablesbackend: Auto
cni_calico_cidr_autodetection_method: default


###############################
# QKS Kubernetes CRI #
###############################

# K8S CRI: 컨테이너 런타임 종류
kube_cri: containerd
# K8S CRI: 컨테이너 런타임 버전
kube_cri_version:
# K8S CRI 옵션: Cgroup 드라이버 선택
cri_cgroup_driver: systemd
# K8S CRI 옵션: Insecure 레지스트리
cri_insecure_registries:
  - "0.0.0.0/0"

kube_default_domain: qks.io

################################################################################
######################################################################## END ###
################################################################################

# QKS Offline Materials
qks_offline_enabled: true
qks_offline_source: "{{ inventory_dir }}/../../data/offline"
qks_offline_target: /data/qks/offline

# QKS Offline Registry Mirror
qks_offline_image_mirror: true

# QKS Service Materials
qks_service_source: "{{ inventory_dir }}/../../data/service"
qks_service_target: /data/qks/service

# QKS Menifess Location
qks_manifests_location: /etc/kubernetes/qks

# QKS Namespace
qks_system_namespace: qks-system
qks_service_namespace: qks
```

## Kubernetes 환경 설정

**`qks_offline_enabled`**

(true / **false**)

네트워크가 단절된 Air-gapped 환경에서 오프라인 설치여부를 설정합니다.

**`qks_offline_source`**

오프라인 설치시 사용될 데이터 소스 위치입니다. 기본값은 "`{{ inventory_dir }}/../../data/offline`" 입니다.

**`qks_offline_target`**

오프라인 설치시 사용될 데이터 타겟(리모트) 위치입니다. 기본값은 "`/data/qks/offline`" 입니다.
> 해당 노드의 역할에 맞게 필요한 데이터들이 복사되며, 배포 후에는 삭제해도 무방합니다.

**`qks_service_source`**

QKS 구동에 필요한 데이터 소스 위치입니다. 기본값은 "`{{ inventory_dir }}/../../data/service`" 입니다.

**`qks_service_target`**

QKS 구동에 필요한 데이터 타겟(리모트) 위치입니다. 기본값은 "`/data/qks/service`" 입니다.
> 해당 노드의 역할에 맞게 필요한 데이터들이 복사되며, 배포 후에는 삭제해도 무방합니다.

**`qks_manifests_location`**

Kubernetes 배포과정에서 생성된 Manifest 파일들이 저장될 위치입니다. 기본값은 "`/etc/kubernetes/qks`" 입니다. 배포된 시점의 설정값들을 참고할 수 있으며, 차후 특정 오브젝트의 재생성이 필요하면 사용할 수 있습니다.

**`qks_system_namespace`**

순수 Kubernetes 외에 추가된 컴포넌트들의 네임스페이스 입니다. 기본값은 "`qks-system`" 입니다. 순수 Kubernetes 의 컴포넌트들의 네임스페이스는 "`kube-system`" 입니다.

**`qks_service_namespace`**

QKS 서비스 (modeler, pipeline) 및 서비스를 위한 컴포넌트 (MariaDB, Keycloak)를 위한 네임스페이스를 지정합니다.

## Kubernetes 노드 설정

**`os_update`**

(true / **false**)

Kubernetes 노드의 운영체제를 최신으로 업데이트할 것인지 설정합니다. 기본값은 "`false`" 입니다.

**`os_timezone`**

Kubernetes 노드의 타임존을 설정합니다. 기본값은 "`Asia/Seoul`" 입니다.

> 노드의 운영체제 타임존을 변경하는 것이며, Kubernetes 이벤트나 로그에 표시되는 시간, 컨테이너 내부의 시간은 변경되지 않습니다.

## Kubernetes 기본 설정

**`kube_version`**

사용할 Kubernetes 버전을 설정합니다. 지원되는 버전은 1.27.x / 1.28.x / 1.29.x / 1.30.x / 1.31.x 입니다. 

**`kube_pod_cidr`**

Kubernetes POD들이 사용할 서브 네트워크 범위를 설정합니다. 기본값은 "`10.0.0.0/16`" 입니다.

> 사설 네트워크의 범위와 중복되지 않고 라우팅에 문제가 없는 범위를 지정해야합니다.

**`kube_svc_cidr`**

Kubernetes Service가 사용할 서브 네트워크 범위를 설정합니다. 기본값은 "`10.1.0.0/16`" 입니다.

> 사설 네트워크의 범위와 중복되지 않고 라우팅에 문제가 없는 범위를 지정해야합니다.

**`kube_proxy_mode`**

(**iptables** / ipvs)

Kubernetes의 내부 트래픽의 라우팅을 담당하는 kube_proxy의 작동 모드를 설정합니다. 기본값은 "`iptables`" 입니다.

**`kube_master_node_taint`**

(**true** / false)

K8S Master 노드의 전용여부를 설정합니다. 기본값은 "`true`" 입니다. K8S Master 컴포넌트 (etcd, apiserver, controller, schedule) 외의 비지니스 워크로드를 수용하려면 반드시 "`false`" 로 설정해야 합니다.

> 대부분의 고객사는 고사양 머신을 제공하기에 `false` 로 설정하여 K8S Master 노드가 일반 K8S Worker 노드의 역할도 수행하게 설정합니다. 가능하면 K8S Master 는 적정사양의 작은 머신을 전용으로 사용하는 것이 안정성 측면에서 권장됩니다.

**`kube_data_dir_cri`**

(**/data/cri**)

컨테이너 런타임이 사용할 스토리지(이미지 및 컨테이너 임시파일 저장) 위치를 지정합니다.

| 런타임     | 기본 스토리지 위치  |
| ---------- | ------------------- |
| containerd | /var/lib/containerd |
| cri-o      | /var/lib/containers |

> 파일시스템 구성 요구조건을 간소화하고, 유연한 공간 사용을 위해 K8S, ETCD, CRI 의 공간을 통합합니다.

**`kube_data_dir_kubelet`**

(**/data/k8s/kubelet**)

K8S에서 사용할 스토리지(컨테이너 임시파일 및 원격 스토리지 마운트) 위치를 지정합니다. 기본값은 "`/var/lib/kubelet`" 입니다.
> 파일시스템 구성 요구조건을 간소화하고, 유연한 공간 사용을 위해 K8S, ETCD, CRI 의 공간을 통합합니다.

**`kube_data_dir_etcd`**

(**/data/k8s/etcd**)

K8S 메타정보를 저장하는 ETCD가 사용할 스토리지 위치를 저정합니다. 기본값은 "`/var/lib/etcd`" 입니다.
> 파일시스템 구성 요구조건을 간소화하고, 유연한 공간 사용을 위해 K8S, ETCD, CRI 의 공간을 통합합니다.

**`kube_admin_users`**

쿠버네티스 및 컨테이너 런타임을 관리할 사용자를 지정합니다. 기본값은 "`{{ ansible_user }}`" 입니다.
지정된 사용자는 쿠버네티스 관리자 권한으로 kubectl 명령 및 컨테이너 툴(docker, ctr, podman) 명령 사용이 가능한 권한으로 설정됩니다. K8S Master 노드에만 적용됩니다.

> 나열된 사용자는 실제 시스템상에 계정이 있을 경우만 설정되며, 존재하지 않는 계정은 무시됩니다.

> 특정 고객사의 경우, 배포 시에는 root 사용자 권한을 제공하지만 운영 환경으로 전환 시 root 사용자 권한을 제한합니다. 일반 사용자로 쿠버네티스 및 컨테이너를 관리해야 한다면, 해당 사용자를 나열하면 됩니다. 

**`[DEPRECATED: cri_cgroup_driver 와 통합] kube_cgroup_driver`**

(**systemd** / cgroupfs)

[cgroup](https://en.wikipedia.org/wiki/Cgroups) 드라이버를 선택합니다. 기본값은 "`systemd`" 입니다.

> 참고: [Cgroup drivers](https://kubernetes.io/docs/setup/production-environment/container-runtimes/#cgroup-drivers)

**`ext_lb_fqdn`**

HA로 구성된 Kubernetes API Server 앞단의 로드밸런서 도메인을 지정합니다. 기본값은 "`{{ qks_load_balancer_fqdn }}`" 으로 내부 소프트웨어 로드밸런서의 도메인 `k8s.qks.io` 입니다.

> 하드웨어 로드밸런서가 있다면, 해당 정보를 지정합니다. 안정적인 성능을 위해 하드웨어 로드밸런서가 권장됩니다.

> 지정한 도메인은 API Server의 자체 서명 인증서(Self-Signed Certificate) 생성 시 서버 정보에 추가됩니다.

**`ext_lb_addr`**

HA로 구성된 Kubernetes API Server 앞단의 로드밸러서 주소를 지정합니다. 기본값은  "`{{ qks_load_balancer_addr }}`"으로 내부 소프트웨어 로드밸런서의 주소입니다.

> 하드웨어 로드밸런서가 있다면, 해당 정보를 지정합니다. 안정적인 성능을 위해 하드웨어 로드밸런서가 권장됩니다.

> 지정한 주소는 API Server의 자체 서명 인증서(Self-Signed Certificate) 생성 시 서버 정보에 추가됩니다.

**`ext_lb_port`**

HA로 구성된 Kubernetes API Server 앞단의 로드밸런서 포트를 지정합니다. 기본값은 "`6443`" 입니다.

## Kubernetes 컨테이너 런타임 설정

**`kube_cri`**

(**containerd** / cri-o)

컨테이너 런타임을 설정합니다. 기본값은 "`containerd`" 입니다.

**`kube_cri_version`**

`kube_cri` 에 지정한 컨테이너 런타임의 버전을 설정합니다. 설정을 생략하면 `kube_version` 값으로 설정된 Kubernetes 버전에서 권장하는 런타임 버전으로 자동 설치됩니다.

| kube_version | containerd | cri-o |
| ------------ | ---------- | ----- |
| 1.31         | 1.6.31     | 1.28  |
| 1.30         | 1.6.31     | 1.28  |
| 1.29         | 1.6.28     | 1.28  |
| 1.28         | 1.6.24     | 1.28  |

> 자세한 버전 호환성은 `inventory/qks/group_vars/all/compatible-matrix.yaml` 파일을 참고합니다.

**`[DEPRECATED: 자동 설정으로 변경] kube_cri_sock`**

Kubelet이 컨테이너 런타밍과 통신하기 위한 유닉스 도메인 소켓 위치를 지정합니다.

| 런타임     | 유닉스 도메인 소켓              |
| ---------- | ------------------------------- |
| docker     | /var/run/dockershim.sock        |
| containerd | /run/containerd/containerd.sock |
| cri-o      | /var/run/crio/crio.sock         |

> 참고: [Runtime Unix Domain Socket](https://kubernetes.io/docs/setup/production-environment/tools/kubeadm/install-kubeadm/#installing-runtime)

**`cri_cgroup_driver`**

(**systemd** /cgroupfs)

[cgroup](https://en.wikipedia.org/wiki/Cgroups) 드라이버를 선택합니다. 기본값은 "`systemd`" 입니다.

> Kubernetes / Container Runtime 모두 동일한 값으로 설정됩니다.

> 참고: [Cgroup drivers](https://kubernetes.io/docs/setup/production-environment/container-runtimes/#cgroup-drivers)

**`cri_insecure_registries`**

컨테이너 런타임에서 접근을 허용할 HTTP (Insecure) 저장소를 나열합니다. 기본값은 "`{{ qks_registry_fqdn }}`"이며 내부 이미지 저장소의 도메인입니다. "`0.0.0.0/0`"을 설정하면  모든 HTTP (Insecure) 저장소가 허용됩니다.

> 참고: [Insecure Registry](https://docs.docker.com/registry/insecure/#deploy-a-plain-http-registry)

## Kubernetes 컨테이너 네트워크 설정

**`kube_cni`**

컨테이너 네트워크 플러그인을 지정합니다. 현재는 [calico](https://www.projectcalico.org/) 만 사용할 수 있습니다.

**`cni_calico_mtu`**

컨테이너 네트워크 플러그인에서 사용할 [MTU](https://en.wikipedia.org/wiki/Maximum_transmission_unit)값을 설정합니다. 기본값은 `1440` 이며, 네트워크 환경(물리머신, 가상머신, GCE, AWS)에 맞게 설정하면 네트워크 성능이 향상됩니다.

> 참고: [Configure MTU to maximize network performance](https://docs.projectcalico.org/networking/mtu)

**`cni_calico_version`**

Calico 컨테이너 네트워크 플러그인 버전을 설정합니다. 온라인 모드에서는 모든 버전이 가능하며, 오프라인 모드에서는 `3.15.2` 만 선택 가능합니다.

**`cni_calico_iptablesbackend`**

(Legacy / NFT / **Auto**)

Calico 컨테이너 네트워크 플러그인에서 사용할 iptables 모드를 설정합니다. 기본값은 "`Auto`" 입니다. 최근의 Linux 배포본(RHEL 8 / CentOS 8)에 포함된 iptables v1.8 부터는 내부로직이 변경되어 현시점에서 정상 작동하는 CNI는 Calico 뿐입니다. Linux 배포본 버전간의 호환을 위해 반드시 "`Auto`" 로 설정합니다.