CNI 네트워크 설치

Cilium(기본), Calico, Flannel, Multus(선택) 등 컨테이너 간 통신을 위한 CNI 네트워크를 설치합니다.

기본 CNI 선택 (택 1)

ubuntu.yaml의 kube_cni 값에 따라 아래 3개 중 하나만 골라 설치됩니다(셋을 동시에 설치할 수 없음).

ubuntu.yaml에서 하나를 고른 뒤, 아래 A/B/C 중 그 옵션에 해당하는 섹션만 읽고 진행하면 됩니다. 세 섹션을 순서대로 다 하는 게 아닙니다.

플레이북 실행 (A/B/C/D 공통)

신규 설치(다른 3개 항목과 함께):

./install.sh ubuntu k8s.yaml

CNI만 다시 적용:

./install.sh ubuntu plays/qks-cni.yaml

A. Cilium (기본)

설정값

ubuntu.yaml:

kube_cni: "cilium"          # 생략 가능(기본값)
cni_cilium_version: "1.19.4"   # 생략 시 compatible-matrix.yaml의 cni_cilium_matrix[kube_version]에서 자동 결정

세부 배포 옵션(kube-proxy 대체 여부, Hubble, BGP 등)은 roles/qks-kubernetes/cni/cilium/tasks/main.yaml의 Helm set_values 목록과, inventory/qks/group_vars/all/all-k8s.yaml의 cni_cilium_* 변수들(예: cni_cilium_kube_proxy_replaced, cni_cilium_ipam_mode)에서 조정합니다.

설치 흐름

1. NetworkManager가 cilium_*/lxc* 인터페이스를 건드리지 않도록 설정
2. kube-system 네임스페이스 확인(Cilium은 kube-system에 설치됨)
3. (kube_proxy 대체 모드인 경우) kube-proxy DaemonSet 제거
4. Helm 저장소 'cilium' 등록
5. Helm으로 Cilium 배포 (release: cilium, namespace: kube-system)
   - kube-proxy 대체, Hubble(관측성 UI), BGP 컨트롤 플레인 등 다수 옵션 포함
6. 마스터 노드 수만큼 cilium 파드가 Running 될 때까지 대기
7. (멀티클러스터 clustermesh 사용 시) CoreDNS 서비스 NodePort 패치
8. CoreDNS 재시작(드물게 배포 직후 응답이 멈추는 경우 대응)

설치 확인

kubectl get pods -n kube-system | grep cilium
helm list -n kube-system | grep cilium

cilium/cilium-operator/hubble-relay/hubble-ui 파드가 Running, Helm 릴리즈가 deployed 상태인지 확인합니다.

cilium status --wait   # cilium-cli 설치되어 있는 경우

B. Calico

설정값

ubuntu.yaml:

kube_cni: "calico"
# cni_calico_version: "3.26.1"   # 생략 시 compatible-matrix.yaml의 cni_calico_matrix[kube_version]에서 자동 결정

버전을 지정하면 그 마이너 버전(예: 3.26.x)에 대응하는 매니페스트 템플릿이 자동 선택됩니다 — 템플릿 파일 목록: roles/qks-kubernetes/cni/calico/templates/calico-3.{17,23,25,26,32}.x.yaml.j2. 해당 마이너 버전용 템플릿이 없으면 새로 추가해야 합니다(기존 파일을 복사해 이미지 태그만 새 버전으로 교체).

설치 흐름

1. NetworkManager가 cali*/tunl*/vxlan.calico 인터페이스를 건드리지 않도록 설정
2. 각 노드의 기본 네트워크 인터페이스 CIDR 자동 감지
3. kube-cni 네임스페이스 생성(Calico는 kube-system이 아니라 별도 네임스페이스에 설치됨)
4. Calico 매니페스트 템플릿 렌더링
   - cni_calico_version의 마이너 버전(예: 3.26)에 맞는 템플릿 파일을 자동 선택
     (roles/qks-kubernetes/cni/calico/templates/calico-3.26.x.yaml.j2 등)
5. 매니페스트 적용(kubectl apply 방식)
6. (선택) 복합 CIDR 자동감지 모드인 경우 추가 매니페스트 적용
7. (오프라인 아니고 dockerio 계정 사용 시) calico-node/calico-kube-controllers에 imagePullSecrets 패치
8. 마스터 노드 수만큼 calico-node 파드가 Running 될 때까지 대기
9. CoreDNS 재시작

설치 확인

kubectl get pods -n kube-cni

calico-node(DaemonSet, 전 노드) / calico-kube-controllers가 Running인지 확인합니다. (Cilium과 달리 kube-system이 아니라 kube-cni 네임스페이스입니다.)

calicoctl node status   # calicoctl 설치되어 있는 경우

C. Flannel

설정값

ubuntu.yaml:

kube_cni: "flannel"
# cni_flannel_version: "0.21.0"   # 생략 시 compatible-matrix.yaml의 cni_flannel_matrix[kube_version]에서 자동 결정

템플릿 파일: roles/qks-kubernetes/cni/flannel/templates/flannel-{마이너버전}.x.yaml.j2.

설치 흐름

1. kube-cni 네임스페이스 생성
2. Flannel 매니페스트 템플릿 렌더링
   - cni_flannel_version의 마이너 버전에 맞는 템플릿 파일을 자동 선택
3. 매니페스트 적용
4. 마스터 노드 수만큼 kube-flannel 파드가 Running 될 때까지 대기
5. CoreDNS 재시작

설치 확인

kubectl get pods -n kube-cni | grep flannel

kube-flannel-ds 파드(DaemonSet, 전 노드)가 전부 Running인지 확인합니다.

D. Multus (추가 옵션, A/B/C 중 하나 위에 얹음)

설정값

ubuntu.yaml:

kube_cni_multus_enabled: true

템플릿 파일: roles/qks-kubernetes/cni/multus/templates/{multus-ds,multus-nad,multus-pod,whereabouts}.yaml.j2. DaemonSet 설정(CNI 바이너리 경로 등)을 바꾸려면 multus-ds.yaml.j2를, IPAM 대역을 바꾸려면 multus-nad.yaml.j2/whereabouts.yaml.j2를 수정합니다.

설치 흐름 (코드 기준)

1. Multus 매니페스트 템플릿 렌더링(multus-ds.yaml, multus-nad.yaml, multus-pod.yaml, whereabouts.yaml)
2. multus-ds.yaml(DaemonSet) 적용
3. 마스터 노드 수만큼 multus 파드가 Running 될 때까지 대기
4. whereabouts.yaml(IPAM), multus-nad.yaml(NetworkAttachmentDefinition) 적용

설치 확인

kubectl get pods -n kube-cni | grep multus

설치 후 공통 확인

kubectl get nodes -o wide

전 노드가 Ready인지, CONTAINER-RUNTIME/KERNEL-VERSION 컬럼이 선택한 옵션과 일치하는지 확인합니다(CNI 설치가 끝나면 워커 조인 전이라도 마스터 노드가 Ready로 바뀝니다).

kubectl get pods -A | grep -vE "Running|Completed"

k8s.yaml 전체 실행이 끝난 뒤 클러스터 전역에서 비정상 파드가 없는지 최종 확인합니다. 아무것도 안 나오면(빈 결과) 정상입니다.

다음 단계