Helm으로 Cilium 설치하기

Helm으로 Cilium 설치하기

이 가이드는 Helm을 사용해 Cilium을 설치하는 방법을 보여줘요. Cilium Quick Installation보다 몇 단계가 더 필요하고, 자신의 환경에 맞는 최적의 datapath와 IPAM 모드를 직접 골라야 해요.

출처: Installation using Helm

본문

Helm 설치 방법

Cilium은 Helm으로 두 가지 방법으로 설치할 수 있어요.

1. OCI 레지스트리 (권장) — Helm 저장소를 추가하지 않고 OCI 레지스트리에서 직접 설치
2. 전통적인 저장소 (Traditional Repository) — 기존 https://helm.cilium.io/ 저장소 사용

OCI 레지스트리 사용하기 (권장)

Cilium Helm 차트는 OCI 컨테이너 레지스트리에서 바로 제공되므로, 별도의 Helm 저장소가 필요 없어요.

팁

helm repo add는 필요 없어요! oci://quay.io/cilium/charts/cilium으로 차트를 직접 참조하면 됩니다.

왜 OCI 레지스트리인가요?

Helm 차트를 컨테이너 이미지와 함께 OCI 레지스트리에 저장하면 여러 장점이 있어요.

• 서명된 차트 (Signed charts) — 모든 차트가 검증을 위해 cosign으로 서명됨
• 간단한 설정 — 저장소 구성이 필요 없음
• Digest 고정 (Digest pinning) — 재현성을 위해 SHA로 정확한 차트 버전 참조
• 통합된 도구 — 이미지와 차트에 동일한 레지스트리 인프라 사용

OCI 빠른 시작:

helm install cilium oci://quay.io/cilium/charts/cilium \
  1.20.2 \
  --namespace kube-system

사용 가능한 버전 찾기:

OCI 레지스트리는 helm search를 지원하지 않아요. 사용 가능한 버전을 찾는 방법은 다음과 같아요.

중요

버전 형식이 중요해요: Helm 차트 버전은 "v" 접두사 없이 SemVer 2.0을 따릅니다(예: 1.15.0). 컨테이너 이미지 태그는 "v"를 포함합니다(예: v1.15.0). Helm 명령에서는 "v" 없는 버전을 쓰세요.

• 레지스트리 둘러보기: Quay.io tags
• CLI로 조회:

# Using crane
crane ls quay.io/cilium/charts/cilium

• 릴리스 확인: https://github.com/cilium/cilium/releases

차트 서명 검증:

모든 차트는 cosign으로 서명돼요. 설치 전에 검증해 보세요.

cosign verify \
  --certificate-identity-regexp='https://github.com/cilium/cilium/.*' \
  --certificate-oidc-issuer=https://token.actions.githubusercontent.com \
  quay.io/cilium/charts/cilium:<VERSION>

cosign 설치는 https://docs.sigstore.dev/cosign/installation/를 참고하세요.

Digest로 고정하기:

재현 가능한 배포를 위해 태그 대신 digest로 차트를 고정할 수 있어요.

# Get the digest
helm pull oci://quay.io/cilium/charts/cilium --version <VERSION>

# Install with digest
helm install cilium oci://quay.io/cilium/charts/cilium@sha256:<DIGEST> \
  --namespace kube-system

이렇게 하면 매번 정확히 동일한 차트를 쓸 수 있어요.

전통적인 Helm 저장소 사용하기

전통적인 Helm 저장소 방식으로도 Cilium을 설치할 수 있어요. 두 설치 방법 모두 완전히 지원됩니다.

Cilium 설치하기

Helm 저장소를 설정해요.

helm repo add cilium https://helm.cilium.io/

Cilium 차트는 OCI 레지스트리(Quay.io와 Docker Hub)에서도 사용할 수 있어요. 별도 설정 없이 oci:// URL로 바로 설치하면 됩니다.

차트 서명 검증과 digest 기반 설치는 OCI Registry 섹션을 참고하세요.

아래는 기본 설정 옵션을 사용해 Cilium을 어떤 Kubernetes 클러스터든 설치하는 일반적인 안내예요. 외부 탭에서는 특정 플랫폼에 이상적인 기본 설정도 함께 나열하는 배포판/플랫폼별 안내를 확인할 수 있어요.

기본 설정:

Datapath	IPAM	Datastore
Encapsulation	Cluster Pool	Kubernetes CRD

요구사항:

• Kubernetes가 CNI를 사용하도록 설정되어 있어야 함 (Network Plugin Requirements)
• Linux kernel >= 5.10

팁

시스템 요구사항에 대한 자세한 내용은 System Requirements를 참고하세요.

Cilium 설치:

Helm으로 Cilium 릴리스를 배포해요.

helm install cilium cilium/cilium --version 1.20.2 \
   --namespace kube-system

helm install cilium oci://quay.io/cilium/charts/cilium 1.20.2 \
   --namespace kube-system

Google Kubernetes Engine (GKE)에 Cilium을 설치하려면 다음 단계를 수행해요.

기본 설정:

Datapath	IPAM	Datastore
Direct Routing	Kubernetes PodCIDR	Kubernetes CRD

요구사항:

• 클러스터는 --node-taints 옵션으로 node.cilium.io/agent-not-ready=true:NoExecute taint를 사용해 생성해야 해요. 다만 다른 옵션도 있어요. taint 영향과 unmanaged pod 문서 페이지를 반드시 읽고 이해하세요.

Cilium 설치:

네이티브 라우팅을 활성화하려면 Cluster CIDR을 추출해요.

NATIVE_CIDR="$(gcloud container clusters describe "${NAME}" --zone "${ZONE}" --format 'value(clusterIpv4Cidr)')"
echo $NATIVE_CIDR

Helm으로 Cilium 릴리스를 배포해요.

helm install cilium cilium/cilium --version 1.20.2 \
   --namespace kube-system \
   --set nodeinit.enabled=true \
   --set nodeinit.reconfigureKubelet=true \
   --set nodeinit.removeCbrBridge=true \
   --set cni.binPath=/home/kubernetes/bin \
   --set gke.enabled=true \
   --set ipam.mode=kubernetes \
   --set ipv4NativeRoutingCIDR=$NATIVE_CIDR

helm install cilium oci://quay.io/cilium/charts/cilium 1.20.2 \
   --namespace kube-system \
   --set nodeinit.enabled=true \
   --set nodeinit.reconfigureKubelet=true \
   --set nodeinit.removeCbrBridge=true \
   --set cni.binPath=/home/kubernetes/bin \
   --set gke.enabled=true \
   --set ipam.mode=kubernetes \
   --set ipv4NativeRoutingCIDR=$NATIVE_CIDR

NodeInit DaemonSet은 노드가 클러스터에 추가될 때 GKE 노드들을 준비하는 데 필요해요. NodeInit DaemonSet은 다음 작업을 수행해요.

• kubelet을 CNI 모드로 실행하도록 재구성
• eBPF 파일시스템 마운트

설정:

Datapath	IPAM	Datastore
Encapsulation	Cluster Pool	Kubernetes CRD

요구사항:

참고

AKS에서는 Cilium을 관리자가 Bring your own CNI 방식으로 수동 설치하거나, AKS가 Azure CNI Powered by Cilium 방식으로 자동 설치할 수 있어요. Bring your own CNI는 관리자가 설치를 완전히 통제하므로 유연성과 커스터마이징이 더 좋지만, Azure 네트워크 스택과 네이티브 통합이 되지 않고 Cilium 업그레이드를 관리자가 직접 처리해야 해요. Azure CNI Powered by Cilium은 Azure 네트워크 스택과 네이티브 통합되고 업그레이드는 AKS가 처리하지만, AKS가 통제하므로 유연성과 커스터마이징이 덜해요. 아래 설명은 Bring your own CNI를 전제로 해요. Azure CNI Powered by Cilium에 대해서는 전용 안내 Installation using Azure CNI Powered by Cilium in AKS를 참고하세요.

• AKS 클러스터는 --network-plugin none으로 생성해야 해요. BYOCNI 전제조건/영향에 대한 자세한 내용은 Bring your own CNI 문서를 참고하세요.
• AKS의 기본 서비스 CIDR과 겹치지 않는 Cluster Pool IPAM pod CIDR을 설정하세요. 예를 들어 --helm-set ipam.operator.clusterPoolIPv4PodCIDRList=192.168.0.0/16을 사용하면 돼요.

Cilium 설치:

Helm으로 Cilium 릴리스를 배포해요.

helm install cilium cilium/cilium --version 1.20.2 \
   --namespace kube-system \
   --set aksbyocni.enabled=true

helm install cilium oci://quay.io/cilium/charts/cilium 1.20.2 \
   --namespace kube-system \
   --set aksbyocni.enabled=true

참고

Helm을 통한 Cilium 설치는 AKS BYOCNI 클러스터에서만 지원되고, Azure CNI Powered by Cilium 클러스터에서는 지원되지 않아요.

Amazon Elastic Kubernetes Service (EKS)에 Cilium을 설치하려면 다음 단계를 수행해요.

기본 설정:

Datapath	IPAM	Datastore
Direct Routing (ENI)	AWS ENI	Kubernetes CRD

AWS ENI 모드에 대한 자세한 내용은 AWS ENI를 참고하세요.

팁

AWS CNI 위에 Cilium을 체이닝하려면 AWS VPC CNI plugin을 참고하세요.

EKS에서는 Single-Region, Multi-Region, Multi-AZ 환경에서도 Cilium을 띄울 수 있어요.

요구사항:

• EKS Managed Nodegroups에 애플리케이션 Pod가 Cilium에 의해 올바르게 관리되도록 적절한 taint가 설정돼야 해요. managedNodeGroups는 애플리케이션 Pod가 Cilium이 관리할 준비가 되기 전엔 스케줄되지 않도록 node.cilium.io/agent-not-ready=true:NoExecute로 taint 해야 해요. 다만 다른 옵션도 있어요. taint 영향과 unmanaged pod에 대한 문서 페이지를 반드시 읽고 이해하세요. 아래는 ClusterConfig 파일을 사용해 클러스터를 생성하는 예시예요.

apiVersion: eksctl.io/v1alpha5
kind: ClusterConfig
# ...
managedNodeGroups:
- name: ng-1
  # ...
  #
  # taint nodes so that application pods are
  # not scheduled/executed until Cilium is deployed.
  # Alternatively, see the note above regarding taint effects.
  taints:
   - key: "node.cilium.io/agent-not-ready"
     value: "true"
     effect: "NoExecute"

제한사항:

• Cilium의 AWS ENI 통합은 현재 IPv4에서만 활성화돼요. IPv6를 쓰려면 ENI가 아닌 datapath/IPAM 모드를 사용하세요.

VPC CNI 패치 (aws-node DaemonSet)

Cilium이 VPC CNI 대신 ENI를 관리하므로, 충돌 동작을 막기 위해 aws-node DaemonSet을 패치해야 해요.

kubectl -n kube-system patch daemonset aws-node --type='strategic' -p='{"spec":{"template":{"spec":{"nodeSelector":{"io.cilium/aws-node-enabled":"true"}}}}}'

Cilium 설치:

Helm으로 Cilium 릴리스를 배포해요.

helm install cilium cilium/cilium --version 1.20.2 \
   --namespace kube-system \
   --set eni.enabled=true

helm install cilium oci://quay.io/cilium/charts/cilium 1.20.2 \
   --namespace kube-system \
   --set eni.enabled=true

참고

이 helm 명령은 eni.enabled=true를 설정해서, Amazon VPC CNI plugin의 동작과 비슷하게 각 Pod에 완전히 라우팅 가능한 AWS ENI IP 주소를 Cilium이 할당하도록 해요.

이 모드는 EC2 API의 Required Privileges 집합에 의존해요.

Cilium은 EKS에서 Pod에 VPC 라우팅이 불가능한 IP를 주는 overlay 모드로도 실행할 수 있어요. 이렇게 하면 ENI 한도보다 더 많은 Pod를 Kubernetes 워커 노드당 실행할 수 있지만 다음 주의사항이 있어요.

1. 클러스터 밖(VPC 안의 VM이나 AWS 관리 서비스 등)으로 가는 Pod 연결은 Cilium이 Kubernetes 워커 노드의 VPC IP를 사용하도록 마스커레이딩(즉, SNAT)해요.
2. EKS API 서버는 overlay 네트워크로 패킷을 라우팅할 수 없어요. 이는 접근해야 하는 webhook은 호스트 네트워크로 실행되거나 서비스나 인그레스를 통해 노출돼야 한다는 뜻이에요.

Cilium overlay 모드를 설정하려면 다음 단계를 따르세요.

1. helm 명령에서 eni.enabled=true 줄을 빼면 Cilium이 overlay 라우팅 모드(helm 기본값)를 사용하도록 설정돼요.
2. VPC CNI가 추가한 iptables 규칙을 비워요.

iptables -t nat -F AWS-SNAT-CHAIN-0 \
   && iptables -t nat -F AWS-SNAT-CHAIN-1 \
   && iptables -t nat -F AWS-CONNMARK-CHAIN-0 \
   && iptables -t nat -F AWS-CONNMARK-CHAIN-1

OpenShift에 Cilium을 설치하려면 다음 단계를 수행해요.

기본 설정:

Datapath	IPAM	Datastore
Encapsulation	Cluster Pool	Kubernetes CRD

요구사항:

• OpenShift 4.x

Cilium 설치:

Cilium은 Certified OpenShift CNI Plugin이며 OpenShift 설치 프로그램으로 클러스터를 만들 때 설치하는 것이 가장 좋아요. 자세한 내용은 Installation on OpenShift OKD를 참고하세요.

독립(standalone) Rancher Kubernetes Engine 1 (RKE1) 또는 Rancher Kubernetes Engine 2 (RKE2) 클러스터 위에 Cilium을 설치하려면, 전용 가이드 Installation using Rancher Kubernetes Engine의 설치 안내를 따르세요.

RKE1/2 클러스터가 Rancher에 의해 관리되는(non-standalone) 경우에는 Installation using Rancher 가이드를 대신 따르세요.

k3s에 Cilium을 설치하려면 다음 단계를 수행해요.

기본 설정:

Datapath	IPAM	Datastore
Encapsulation	Cluster Pool	Kubernetes CRD

요구사항:

• 평소처럼 k3s 클러스터를 설치하되, 기본 CNI 플러그인과 내장 네트워크 정책 enforcement 기능을 비활성화해서 그 위에 Cilium을 설치할 수 있게 해요.

curl -sfL https://get.k3s.io | INSTALL_K3S_EXEC='--flannel-backend=none --disable-network-policy' sh -

• 이후 단계에서 Cilium CLI가 클러스터에 접근하려면 KUBECONFIG 환경 변수를 설정해 /etc/rancher/k3s/k3s.yaml에 저장된 kubeconfig 파일을 사용해야 해요.

export KUBECONFIG=/etc/rancher/k3s/k3s.yaml

Cilium 설치:

helm install cilium cilium/cilium --version 1.20.2 \
   --namespace $CILIUM_NAMESPACE \
   --set operator.replicas=1

helm install cilium oci://quay.io/cilium/charts/cilium 1.20.2 \
   --namespace $CILIUM_NAMESPACE \
   --set operator.replicas=1

Rancher Desktop 구성:

Rancher Desktop에 Cilium을 설치하려면 다음 단계를 수행해요.

Rancher Desktop은 YAML 구성 파일로 설정해요. 기본 CNI를 비활성화하고 Cilium으로 교체하려면 이 단계가 필요해요.

다음으로 Rancher Desktop을 containerd로 시작하고 override.yaml을 생성해요.

env:
  # needed for cilium
  INSTALL_K3S_EXEC: '--flannel-backend=none --disable-network-policy'
provision:
  # needs root to mount
  - mode: system
    script: |
      #!/bin/sh
      set -e

      # needed for cilium
      mount bpffs -t bpf /sys/fs/bpf
      mount --make-shared /sys/fs/bpf

      mkdir -p /run/cilium/cgroupv2
      mount -t cgroup2 none /run/cilium/cgroupv2
      mount --make-shared /run/cilium/cgroupv2/

파일을 만든 뒤 Rancher Desktop의 lima/_config 디렉터리로 옮겨요.

cp override.yaml ~/.local/share/rancher-desktop/lima/_config/override.yaml

cp override.yaml ~/Library/Application\ Support/rancher-desktop/lima/_config/override.yaml

마지막으로 Rancher Desktop UI를 열고 Troubleshooting 패널로 가서 "Reset Kubernetes"를 클릭해요.

몇 분 후 Rancher Desktop이 Cilium 설치 준비 상태로 다시 시작될 거예요.

Cilium 설치:

helm install cilium cilium/cilium --version 1.20.2 \
   --namespace $CILIUM_NAMESPACE \
   --set operator.replicas=1 \
   --set cni.binPath=/usr/libexec/cni

helm install cilium oci://quay.io/cilium/charts/cilium 1.20.2 \
   --namespace $CILIUM_NAMESPACE \
   --set operator.replicas=1 \
   --set cni.binPath=/usr/libexec/cni

Talos Linux에 Cilium을 설치하려면 다음 단계를 수행해요.

전제조건 / 제한사항

• Cilium의 Talos Linux 지원은 Talos 버전 >=1.5.0에서만 테스트했어요.
• Talos는 Kubernetes 워크로드가 커널 모듈 로딩을 허용하지 않기 때문에, Cilium 기본 capability 목록에서 SYS_MODULE을 제거해야 해요.
• Talos Linux의 Forwarding kube-dns to Host DNS(Talos 1.8 이후 기본 활성화)는 Cilium의 eBPF Host-Routing과 함께 동작하지 않아요. 동작시키려면 bpf.hostLegacyRouting을 true로 설정해야 해요. 그렇지 않으면 DNS가 동작하지 않아요.

참고

공식 Talos Linux 문서는 이미 Deploying Cilium CNI guide 안에서 다양한 Cilium 배포 옵션을 다루고 있어요. 그래서 이 가이드는 Cilium 관점에서 가장 권장되는 배포 옵션에만 집중할게요.

• 공식 Cilium Helm chart를 통한 배포
• Cilium Kube-Proxy replacement 활성화
• Talos가 이미 제공하는 cgroupv2 마운트 재사용
• Talos가 기본적으로 v1.Node 리소스에 PodCIDR을 할당하므로 Kubernetes Host Scope IPAM 모드 사용

Talos Linux 구성하기

Cilium을 설치하기 전에 조정해야 할 Talos Linux Kubernetes 구성이 두 가지 있어요.

1. cluster.network.cni.name: none으로 다른 CNI가 배포되지 않도록 보장
2. cluster.proxy.disabled: true로 Kube-Proxy 배포 비활성화

patch.yaml 파일을 준비해요.

cluster:
  network:
    cni:
      name: none
  proxy:
    disabled: true

다음으로 talosctl gen config 명령으로 Talos 클러스터의 구성 파일을 생성해요.

talosctl gen config \
  my-cluster https://mycluster.local:6443 \
  --config-patch @patch.yaml

Cilium 설치

Kube-Proxy replacement를 활성화하고 Cilium을 실행하려면 k8sServiceHost와 k8sServicePort를 설정해 Kubernetes API를 가리키게 해야 해요. 다행히 Talos Linux는 외부 로드밸런서 없이 호스트 네트워킹만으로 Kubernetes API에 편리하게 접근할 수 있는 KubePrism을 제공해요. 이 KubePrism 엔드포인트는 모든 Talos Linux 노드에서 localhost:7445로 접근할 수 있어요.

helm install cilium cilium/cilium --version 1.20.2 \
   --namespace $CILIUM_NAMESPACE \
   --set ipam.mode=kubernetes \
   --set kubeProxyReplacement=true \
   --set securityContext.capabilities.ciliumAgent="{CHOWN,KILL,NET_ADMIN,NET_RAW,IPC_LOCK,SYS_ADMIN,SYS_RESOURCE,DAC_OVERRIDE,FOWNER,SETGID,SETUID}" \
   --set securityContext.capabilities.cleanCiliumState="{NET_ADMIN,SYS_ADMIN,SYS_RESOURCE}" \
   --set cgroup.autoMount.enabled=false \
   --set cgroup.hostRoot=/sys/fs/cgroup \
   --set k8sServiceHost=localhost \
   --set k8sServicePort=7445

helm install cilium oci://quay.io/cilium/charts/cilium 1.20.2 \
   --namespace $CILIUM_NAMESPACE \
   --set ipam.mode=kubernetes \
   --set kubeProxyReplacement=true \
   --set securityContext.capabilities.ciliumAgent="{CHOWN,KILL,NET_ADMIN,NET_RAW,IPC_LOCK,SYS_ADMIN,SYS_RESOURCE,DAC_OVERRIDE,FOWNER,SETGID,SETUID}" \
   --set securityContext.capabilities.cleanCiliumState="{NET_ADMIN,SYS_ADMIN,SYS_RESOURCE}" \
   --set cgroup.autoMount.enabled=false \
   --set cgroup.hostRoot=/sys/fs/cgroup \
   --set k8sServiceHost=localhost \
   --set k8sServicePort=7445

ACK (Alibaba Cloud Container Service for Kubernetes)에 Cilium을 설치하려면 다음 단계를 수행해요.

ACK CNI 비활성화 (ACK 전용):

ACK 클러스터를 실행 중이라면 ACK CNI를 삭제해야 해요.

Cilium이 ACK CNI 대신 ENI를 관리하므로, 충돌을 막기 위해 아래 목록의 실행 중인 DaemonSet을 삭제해야 해요.

• kube-flannel-ds
• terway
• terway-eni
• terway-eniip

참고

Flannel(DaemonSet kube-flannel-ds)과 함께 ACK를 사용한다면 Cloud Controller Manager (CCM)가 VPC에 경로(Pod CIDR)를 생성해요. Managed Kubernetes 클러스터라면 이 동작을 비활성화할 수 없어요. 새 클러스터 생성을 고려하세요.

kubectl -n kube-system delete daemonset <terway>

다음 단계로 terway* CNI가 생성한 아래 CRD들을 삭제해요.

kubectl delete crd \
    ciliumclusterwidenetworkpolicies.cilium.io \
    ciliumendpoints.cilium.io \
    ciliumidentities.cilium.io \
    ciliumnetworkpolicies.cilium.io \
    ciliumnodes.cilium.io \
    bgpconfigurations.crd.projectcalico.org \
    clusterinformations.crd.projectcalico.org \
    felixconfigurations.crd.projectcalico.org \
    globalnetworkpolicies.crd.projectcalico.org \
    globalnetworksets.crd.projectcalico.org \
    hostendpoints.crd.projectcalico.org \
    ippools.crd.projectcalico.org \
    networkpolicies.crd.projectcalico.org

AlibabaCloud 시크릿 생성:

Cilium을 설치하기 전에 AlibabaCloud 토큰으로 새 Kubernetes Secret을 클러스터에 추가해야 해요. 이 Secret으로 Cilium이 ToGroups 정책 구현에 필요한 정보를 AlibabaCloud API에서 가져올 수 있어요.

AlibabaCloud Access Keys:

새 액세스 토큰을 만들려면 다음 가이드를 사용할 수 있어요. 이 키들은 특정 RAM Permissions을 가져야 해요.

{
  "Version": "1",
  "Statement": [{
      "Action": [
        "ecs:CreateNetworkInterface",
        "ecs:DescribeNetworkInterfaces",
        "ecs:AttachNetworkInterface",
        "ecs:DetachNetworkInterface",
        "ecs:DeleteNetworkInterface",
        "ecs:DescribeInstanceAttribute",
        "ecs:DescribeInstanceTypes",
        "ecs:AssignPrivateIpAddresses",
        "ecs:UnassignPrivateIpAddresses",
        "ecs:DescribeInstances",
        "ecs:DescribeSecurityGroups",
        "ecs:ListTagResources"
      ],
      "Resource": [
        "*"
      ],
      "Effect": "Allow"
    },
    {
      "Action": [
        "vpc:DescribeVSwitches",
        "vpc:ListTagResources",
        "vpc:DescribeVpcs"
      ],
      "Resource": [
        "*"
      ],
      "Effect": "Allow"
    }
  ]
}

액세스 토큰을 확보하면 다음 시크릿을 추가해야 해요. 각 빈 문자열은 base64로 인코딩된 해당 값으로 바꿔요.

apiVersion: v1
kind: Secret
metadata:
  name: cilium-alibabacloud
  namespace: kube-system
type: Opaque
data:
  ALIBABA_CLOUD_ACCESS_KEY_ID: ""
  ALIBABA_CLOUD_ACCESS_KEY_SECRET: ""

base64 명령줄 도구로 각 값을 생성할 수 있어요. 예를 들면:

$ echo -n "access_key" | base64
YWNjZXNzX2tleQ==

이 시크릿은 AlibabaCloud API에 연결하는 데 사용할 AlibabaCloud 자격 증명을 저장해요.

$ kubectl create -f cilium-secret.yaml

Cilium 설치:

Helm으로 Cilium 릴리스를 설치해요.

helm install cilium cilium/cilium --version 1.20.2 \
   --namespace kube-system \
   --set alibabacloud.enabled=true \
   --set ipam.mode=alibabacloud \
   --set enableIPv4Masquerade=false \
   --set routingMode=native

helm install cilium oci://quay.io/cilium/charts/cilium 1.20.2 \
   --namespace kube-system \
   --set alibabacloud.enabled=true \
   --set ipam.mode=alibabacloud \
   --set enableIPv4Masquerade=false \
   --set routingMode=native

참고

ENI(eth1, eth2, …)와 연결된 보안 그룹이 VPC 밖으로 나가는 egress 트래픽을 허용해야 해요. 기본적으로 pod ENI의 보안 그룹은 기본 ENI(eth0)에서 파생돼요.

영상

Cilium Helm values에 대해 더 알아보고 싶다면 eCHO episode 117: A Tour of the Cilium Helm Values를 확인해 보세요.

업그레이드

OCI 레지스트리 사용하기

helm upgrade cilium oci://quay.io/cilium/charts/cilium \
  1.20.2 \
  --namespace kube-system

전통적인 저장소에서 OCI로 마이그레이션

전통적인 저장소(https://helm.cilium.io/)를 사용 중이라면 차트가 동일하기 때문에 OCI로 전환하는 것은 간단해요.

helm upgrade cilium oci://quay.io/cilium/charts/cilium \
  1.20.2 \
  --namespace kube-system \
  --reuse-values

--reuse-values 플래그는 기존 구성을 보존해요.

OCI vs 전통적인 저장소

Feature	OCI Registry	Traditional Repository
Setup	None	helm repo add
Chart signing	Yes (cosign)	No
Digest pinning	Yes	Limited
Air-gapped install	Standard OCI mirror tools	Separate chart mirror

두 방법 모두 완전히 지원돼요.

문제 해결

"failed to authorize: failed to fetch anonymous token"

보통 네트워크 또는 레지스트리 연결 문제를 의미해요. 접근을 테스트해 보세요.

curl https://quay.io/v2/

"chart not found"

버전 번호를 다시 확인하세요. Helm 버전에는 "v" 접두사가 없다는 점을 기억하세요.

unmanaged Pod 재시작

노드를 node.cilium.io/agent-not-ready taint로 만들지 않은 클러스터라면 unmanaged pod를 수동으로 재시작해야 해요. Cilium이 관리하기 시작하도록 호스트 네트워킹 모드로 실행 중이 아닌 이미 실행 중인 모든 Pod를 재시작해요. 이는 Cilium 배포 전에 실행 중이던 모든 Pod가 Cilium이 제공하는 네트워크 연결을 갖고 NetworkPolicy가 적용되도록 하는 데 필요해요.

$ kubectl get pods --all-namespaces -o custom-columns=NAMESPACE:.metadata.namespace,NAME:.metadata.name,HOSTNETWORK:.spec.hostNetwork --no-headers=true | grep '<none>' | awk '{print "-n "$1" "$2}' | xargs -L 1 -r kubectl delete pod
pod "event-exporter-v0.2.3-f9c896d75-cbvcz" deleted
pod "fluentd-gcp-scaler-69d79984cb-nfwwk" deleted
pod "heapster-v1.6.0-beta.1-56d5d5d87f-qw8pv" deleted
pod "kube-dns-5f8689dbc9-2nzft" deleted
pod "kube-dns-5f8689dbc9-j7x5f" deleted
pod "kube-dns-autoscaler-76fcd5f658-22r72" deleted
pod "kube-state-metrics-7d9774bbd5-n6m5k" deleted
pod "l7-default-backend-6f8697844f-d2rq2" deleted
pod "metrics-server-v0.3.1-54699c9cc8-7l5w2" deleted

참고

macOS에서는 xargs가 -r을 지원하지 않아 이 명령이 오류를 낼 수 있어요. 이 경우 -r 없이 명령을 실행해도 안전하며, 재시작할 Pod가 없으면 명령이 멈추는 증상이 생겨요. ctrl-c로 중단할 수 있어요.

설치 검증하기

최신 버전의 Cilium CLI를 설치해요. Cilium CLI는 Cilium 설치, 설치 상태 점검, 다양한 기능(예: clustermesh, Hubble) 활성화/비활성화에 사용할 수 있어요.

CILIUM_CLI_VERSION=$(curl -s https://raw.githubusercontent.com/cilium/cilium-cli/main/stable.txt)
CLI_ARCH=amd64
if [ "$(uname -m)" = "aarch64" ]; then CLI_ARCH=arm64; fi
curl -L --fail --remote-name-all https://github.com/cilium/cilium-cli/releases/download/${CILIUM_CLI_VERSION}/cilium-linux-${CLI_ARCH}.tar.gz{,.sha256sum}
sha256sum --check cilium-linux-${CLI_ARCH}.tar.gz.sha256sum
sudo tar xzvfC cilium-linux-${CLI_ARCH}.tar.gz /usr/local/bin
rm cilium-linux-${CLI_ARCH}.tar.gz{,.sha256sum}

CILIUM_CLI_VERSION=$(curl -s https://raw.githubusercontent.com/cilium/cilium-cli/main/stable.txt)
CLI_ARCH=amd64
if [ "$(uname -m)" = "arm64" ]; then CLI_ARCH=arm64; fi
curl -L --fail --remote-name-all https://github.com/cilium/cilium-cli/releases/download/${CILIUM_CLI_VERSION}/cilium-darwin-${CLI_ARCH}.tar.gz{,.sha256sum}
shasum -a 256 -c cilium-darwin-${CLI_ARCH}.tar.gz.sha256sum
sudo tar xzvfC cilium-darwin-${CLI_ARCH}.tar.gz /usr/local/bin
rm cilium-darwin-${CLI_ARCH}.tar.gz{,.sha256sum}

전체 releases 페이지를 참고하세요.

Cilium이 제대로 설치됐는지 확인하려면 다음을 실행해요.

$ cilium status --wait
   /¯\
/¯\__/¯\    Cilium:         OK
\__/¯\__/    Operator:       OK
/¯\__/¯\    Hubble:         disabled
\__/¯\__/    ClusterMesh:    disabled
   \__/

DaemonSet         cilium             Desired: 2, Ready: 2/2, Available: 2/2
Deployment        cilium-operator    Desired: 2, Ready: 2/2, Available: 2/2
Containers:       cilium-operator    Running: 2
                  cilium             Running: 2
Image versions    cilium             quay.io/cilium/cilium:v1.9.5: 2
                  cilium-operator    quay.io/cilium/operator-generic:v1.9.5: 2

클러스터가 올바른 네트워크 연결을 갖췄는지 확인하려면 다음 명령을 실행해요.

$ cilium connectivity test
ℹ️  Monitor aggregation detected, will skip some flow validation steps
✨ [k8s-cluster] Creating namespace for connectivity check...
(...)
---------------------------------------------------------------------------------------------------------------------
📋 Test Report
---------------------------------------------------------------------------------------------------------------------
✅ 69/69 tests successful (0 warnings)

참고

연결성 테스트는 Pod 중 하나에 열린 파일이 너무 많아 배포에 실패할 수 있어요. 이런 오류가 보이면 호스트 머신의 inotify 리소스 한도를 늘리세요 (Pod errors due to "too many open files").

축하해요! 이제 Cilium이 동작하는 완전한 Kubernetes 클러스터가 갖춰졌어요. 🎉

Cilium과 필요한 컴포넌트들이 설치되는 과정을 다음과 같이 모니터링할 수 있어요.

$ kubectl -n kube-system get pods --watch
NAME                                    READY   STATUS              RESTARTS   AGE
cilium-operator-cb4578bc5-q52qk         0/1     Pending             0          8s
cilium-s8w5m                            0/1     PodInitializing     0          7s
coredns-86c58d9df4-4g7dd                0/1     ContainerCreating   0          8m57s
coredns-86c58d9df4-4l6b2                0/1     ContainerCreating   0          8m57s

모든 컴포넌트가 뜨기까지 몇 분이 걸릴 수 있어요.

cilium-operator-cb4578bc5-q52qk         1/1     Running   0          4m13s
cilium-s8w5m                            1/1     Running   0          4m12s
coredns-86c58d9df4-4g7dd                1/1     Running   0          13m
coredns-86c58d9df4-4l6b2                1/1     Running   0          13m

Pod 사이의 연결을 테스트하려면 "connectivity-check"를 배포할 수 있어요. 이를 위해 별도 네임스페이스를 만드는 것을 권장해요.

kubectl create ns cilium-test

다음 명령으로 체크를 배포해요.

kubectl apply -n cilium-test -f https://raw.githubusercontent.com/cilium/cilium/1.20.2/examples/kubernetes/connectivity-check/connectivity-check.yaml

이 단계는 다양한 연결 경로를 사용해 서로 연결되는 일련의 deployment들을 배포해요. 연결 경로에는 서비스 로드밸런싱 유무와 다양한 네트워크 정책 조합이 포함돼요. Pod 이름은 연결 변형(variant)을 나타내고, readiness와 liveness 게이트는 테스트의 성공 여부를 나타내요.

$ kubectl get pods -n cilium-test
NAME                                                     READY   STATUS    RESTARTS   AGE
echo-a-76c5d9bd76-q8d99                                  1/1     Running   0          66s
echo-b-795c4b4f76-9wrrx                                  1/1     Running   0          66s
echo-b-host-6b7fc94b7c-xtsff                             1/1     Running   0          66s
host-to-b-multi-node-clusterip-85476cd779-bpg4b          1/1     Running   0          66s
host-to-b-multi-node-headless-dc6c44cb5-8jdz8            1/1     Running   0          65s
pod-to-a-79546bc469-rl2qq                                1/1     Running   0          66s
pod-to-a-allowed-cnp-58b7f7fb8f-lkq7p                    1/1     Running   0          66s
pod-to-a-denied-cnp-6967cb6f7f-7h9fn                     1/1     Running   0          66s
pod-to-b-intra-node-nodeport-9b487cf89-6ptrt             1/1     Running   0          65s
pod-to-b-multi-node-clusterip-7db5dfdcf7-jkjpw           1/1     Running   0          66s
pod-to-b-multi-node-headless-7d44b85d69-mtscc            1/1     Running   0          66s
pod-to-b-multi-node-nodeport-7ffc76db7c-rrw82            1/1     Running   0          65s
pod-to-external-1111-d56f47579-d79dz                     1/1     Running   0          66s
pod-to-external-fqdn-allow-google-cnp-78986f4bcf-btjn7   1/1     Running   0          66s

참고

단일 노드 클러스터에 연결성 체크를 배포하면 멀티노드 기능을 확인하는 Pod들은 Pending 상태로 남아요. 이는 해당 Pod들이 성공적으로 스케줄되려면 노드가 최소 2개 필요하기 때문이에요. 정상적인 현상이에요.

테스트가 끝나면 cilium-test 네임스페이스를 삭제해요.

kubectl delete ns cilium-test

다음 단계

• Setting up Hubble Observability
• Inspecting Network Flows with the CLI
• Service Map & Hubble UI
• Identity-Aware and HTTP-Aware Policy Enforcement
• Setting up Cluster Mesh

더 알아보기 (Learn more)

• Cilium Quick Installation
• Cilium 설치 요구사항
• 설치 검증하기