QKS Kubernetes 설정

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

설정파일 위치: inventory/qks/group_vars/all/all-k8s.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 드라이버를 선택합니다. 기본값은 “systemd” 입니다.

참고: 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

cri_cgroup_driver

(systemd /cgroupfs)

cgroup 드라이버를 선택합니다. 기본값은 “systemd” 입니다.

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

참고: Cgroup drivers

cri_insecure_registries

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

참고: Insecure Registry

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

kube_cni

컨테이너 네트워크 플러그인을 지정합니다. 현재는 calico 만 사용할 수 있습니다.

cni_calico_mtu

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

참고: Configure MTU to maximize network performance

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” 로 설정합니다.