Cilium 빠른 설치

Cilium 빠른 설치 (Cilium Quick Installation)

Cilium을 기본 설정으로 빠르게 설치하는 가이드예요. 사용 중인 Kubernetes 배포판에 가장 적합한 구성을 자동으로 감지해 적용하며, 모든 상태는 Kubernetes 커스텀 리소스 정의(CRD)로 저장돼요. 대부분의 환경에서 가장 좋은 설치 방법이에요.

출처: Cilium Quick Installation

본문

이 가이드는 기본 빠른 설치를 안내할게요. 사용 중인 Kubernetes 배포판에 가장 적합한 구성을 자동으로 감지해 적용해요. 모든 상태는 Kubernetes 커스텀 리소스 정의(CRD)로 저장돼요.

이 방법은 대부분의 사용 사례에 가장 좋은 설치 방법이에요. 대규모 환경(500 노드 초과)이거나 특정 데이터패스 모드를 실행하고 싶다면 Getting Started 가이드를 참고하세요.

설치 중 문제가 발생하면 Troubleshooting 섹션을 참고하거나 Cilium Slack에서 도움을 구하세요.

클러스터 생성 (Create the Cluster)

아직 Kubernetes 클러스터가 없다면, 아래 지침으로 로컬 또는 관리형 Kubernetes 서비스로 클러스터를 만들 수 있어요. (GKE / AKS / EKS / kind / minikube / Kubespray / Rancher Desktop / Alibaba ACK)

다음 명령은 Google Kubernetes Engine으로 Kubernetes 클러스터를 생성해요. gcloud 설치와 계정 준비 방법은 Installing Google Cloud SDK를 참고하세요.

export NAME="$(whoami)-$RANDOM"
# Create the node pool with the following taint to guarantee that
# Pods are only scheduled/executed in the node when Cilium is ready.
# Alternatively, see the note below.
gcloud container clusters create "${NAME}" \
 --node-taints node.cilium.io/agent-not-ready=true:NoExecute \
 --zone us-west2-a
gcloud container clusters get-credentials "${NAME}" --zone us-west2-a

참고: taint 효과와 비관리 파드(unmanaged pods)에 관한 문서 페이지를 읽고 이해해 주세요.

다음 명령은 CNI 플러그인이 미리 설치되지 않은(BYOCNI) Azure Kubernetes Service로 Kubernetes 클러스터를 생성해요. az 설치와 계정 준비는 Azure Cloud CLI를, BYOCNI 사전 요구사항/영향에 대한 자세한 내용은 Bring your own CNI 문서를 참고하세요.

export NAME="$(whoami)-$RANDOM"
export AZURE_RESOURCE_GROUP="${NAME}-group"
az group create --name "${AZURE_RESOURCE_GROUP}" -l westus2

# Create AKS cluster
az aks create \
  --resource-group "${AZURE_RESOURCE_GROUP}" \
  --name "${NAME}" \
  --network-plugin none \
  --generate-ssh-keys

# Get the credentials to access the cluster with kubectl
az aks get-credentials --resource-group "${AZURE_RESOURCE_GROUP}" --name "${NAME}"

다음 명령은 eksctl로 Amazon Elastic Kubernetes Service를 사용해 Kubernetes 클러스터를 생성해요. eksctl 설치와 계정 준비는 eksctl Installation을 참고하세요.

export NAME="$(whoami)-$RANDOM"
cat <<EOF >eks-config.yaml
apiVersion: eksctl.io/v1alpha5
kind: ClusterConfig

metadata:
  name: ${NAME}
  region: eu-west-1

managedNodeGroups:
- name: ng-1
  desiredCapacity: 2
  privateNetworking: true
  # taint nodes so that application pods are
  # not scheduled/executed until Cilium is deployed.
  # Alternatively, see the note below.
  taints:
   - key: "node.cilium.io/agent-not-ready"
     value: "true"
     effect: "NoExecute"
EOF
eksctl create cluster -f ./eks-config.yaml

참고: taint 효과와 비관리 파드에 관한 문서 페이지를 읽고 이해해 주세요.

kind 문서(Installation and Usage)에 따라 kind >= v0.7.0을 설치하세요.

curl -LO https://raw.githubusercontent.com/cilium/cilium/1.20.2/Documentation/installation/kind-config.yaml
kind create cluster --config=kind-config.yaml

참고: Cilium은 에이전트 파드 중 하나 이상에서 열려 있는 파일이 너무 많아 배포에 실패할 수도 있어요. 이런 오류가 보이면 호스트 머신의 inotify 리소스 한도를 늘려 보세요 (즉, "too many open files"로 인한 파드 오류 참고).

minikube 문서(Install Minikube)에 따라 minikube ≥ v1.28.0을 설치하세요. 다음 명령은 cilium 설치를 위해 준비된 단일 노드 minikube 클러스터를 기동해요.

minikube start --cni=cilium

참고: (참고 사항)

Kubespray는 최신 버전에서 Python ≥ 3.10이 필요해요. 환경 설정과 의존성 설치에 대해서는 Kubespray Ansible 문서를 참고하세요.

클러스터 구성:

# Enter the already cloned kubespray directory
cd kubespray/

# Copy sample inventory
cp -rfp inventory/sample inventory/mycluster

# Configure your inventory
vi inventory/mycluster/inventory.ini

# Configure Kubernetes networking:
# Use CNI without any network plugin
sed -e 's/^kube_network_plugin:.*$/kube_network_plugin: cni/' \
    -e 's/^kube_owner:.*$/kube_owner: root/' \
    inventory/mycluster/group_vars/k8s_cluster/k8s-cluster.yml > k8s-cluster.tmp
mv k8s-cluster.tmp inventory/mycluster/group_vars/k8s_cluster/k8s-cluster.yml

kube_network_plugin: cni로 설정하면 클러스터가 네트워크 플러그인 없이 배포되어, 이후 Cilium을 별도로 설치할 수 있게 해줘요.

클러스터 배포:

ansible-playbook -i inventory/mycluster/inventory.ini cluster.yml -b -v \
  --private-key=~/.ssh/private_key

(개인 SSH 키 경로를 조정하세요.)

참고: 더 자세한 구성 옵션은 Kubespray 문서를 참고하세요.

Rancher Desktop 문서(Install Rancher Desktop)에 따라 Rancher Desktop >= v1.1.0을 설치하세요.

다음으로, 내장 CNI를 비활성화해 Cilium을 설치할 수 있도록 Rancher Desktop을 구성해야 해요.

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

다음으로 containerd로 Rancher Desktop을 시작하고 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 디렉터리로 옮기세요.

Linux

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

macOS

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

마지막으로 Rancher Desktop UI를 열고 Troubleshooting 패널로 가서 "Reset Kubernetes"를 클릭하세요. 몇 분 후 Rancher Desktop이 Cilium 설치 준비된 상태로 다시 시작돼요.

참고: 이 기능은 베타 기능이에요. 문제가 생기면 피드백을 남겨 주시고 GitHub 이슈를 올려주세요.

참고: Cilium과의 AlibabaCloud ENI 통합에는 다음과 같은 제한 사항이 적용돼요.

AlibabaCloud에 Kubernetes를 설정하세요. 어떤 방식이든 선호하는 방법을 쓸 수 있어요. 가장 빠른 방법은 ACK(Alibaba Cloud Container Service for Kubernetes) 클러스터를 만들고 CNI 플러그인을 Cilium으로 교체하는 거예요. ACK 클러스터 설정 방법에 대한 자세한 내용은 공식 문서를 따라 주세요.

Cilium CLI 설치 (Install the Cilium CLI)

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

Linux

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}

macOS

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 CLI에 대해 더 알고 싶다면 eCHO 에피소드 8: Exploring the Cilium CLI을 확인하세요.

Cilium 설치 (Install Cilium)

어떤 Kubernetes 클러스터에도 Cilium을 설치할 수 있어요. 아래 옵션 중 하나를 선택하세요. (Generic / GKE / AKS / EKS / OpenShift / RKE / k3s / Alibaba ACK)

Generic

이것은 어떤 Kubernetes 클러스터에도 Cilium을 설치하는 일반적인 지침이에요. 설치 도구가 최적의 구성 옵션을 자동으로 선택하려고 할 거예요. 특정 플랫폼에 이상적인 기본 구성을 나열한 다른 탭들도 참고하세요.

요구사항:

• Kubernetes가 CNI를 사용하도록 구성되어 있어야 함 (Network Plugin Requirements 참고)

• Linux 커널 >= 5.10

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

현재 kubectl 컨텍스트가 가리키는 Kubernetes 클러스터에 Cilium을 설치해요.

cilium install 1.20.2

GKE

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 효과와 비관리 파드에 관한 문서 페이지를 읽고 이해해 주세요.

Cilium 설치: GKE 클러스터에 Cilium을 설치해요.

cilium install 1.20.2

AKS

구성:

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과 겹치지 않는 클러스터 풀 IPAM 파드 CIDR을 설정하세요. 예를 들어 --helm-set ipam.operator.clusterPoolIPv4PodCIDRList=192.168.0.0/16을 사용할 수 있어요.

Cilium 설치: AKS 클러스터에 Cilium을 설치해요.

cilium install 1.20.2 --set azure.resourceGroup="${AZURE_RESOURCE_GROUP}"

EKS

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가 제대로 테인트되어 애플리케이션 파드가 Cilium에 의해 적절히 관리되도록 해야 해요.

• managedNodeGroups는 애플리케이션 파드가 Cilium이 관리할 준비가 된 후에만 스케줄링되도록 node.cilium.io/agent-not-ready=true:NoExecute로 테인트되어야 해요. 하지만 다른 옵션도 있어요. taint 효과와 비관리 파드에 관한 문서 페이지를 읽고 이해해 주세요.

아래는 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가 아닌 데이터패스/IPAM 모드를 사용하세요.

Cilium 설치: EKS 클러스터에 Cilium을 설치해요.

cilium install 1.20.2
cilium status --wait

참고: Cilium을 제거했다가 나중에 다시 설치해야 한다면, aws-node DaemonSet이 Linux 라우팅 테이블을 플러시해서 연결성 문제가 생길 수 있어요. 문제는 모든 파드를 재시작하면 해결되며, 그런 문제를 피하려면 Cilium 설치 전에 aws-node DaemonSet을 삭제할 수 있어요.

OpenShift

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

기본 구성:

Datapath	IPAM	Datastore
Encapsulation	Cluster Pool	Kubernetes CRD

요구사항:

• OpenShift 4.x

Cilium 설치: Cilium은 Certified OpenShift CNI Plugin이며, OpenShift 설치 도구로 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로 관리된다면(비-단독형), 대신 Installation using Rancher 가이드를 따르세요.

Cilium 설치:

새로 만든 RKE 클러스터에 Cilium을 설치해요.

cilium install 1.20.2

k3s

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

기본 구성:

Datapath	IPAM	Datastore
Encapsulation	Cluster Pool	Kubernetes CRD

요구사항:

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

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

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

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

Cilium 설치:

새로 만든 Kubernetes 클러스터에 Cilium을 설치해요.

cilium install 1.20.2

Alibaba ACK

Alibaba ACK에 Helm으로 Cilium을 설치할 수 있어요. 자세한 내용은 Installation using Helm을 참고하세요.

설치가 어떤 이유로 실패하면 cilium status를 실행해 Cilium 배포의 전반적인 상태를 확인하고, 배포에 실패하는 파드들의 로그를 검사해 보세요.

팁: cilium install이 대략 다음과 같은 내용을 출력하는 걸 볼 수 있을 거예요. 이는 Cilium이 배포되기 전에 클러스터에 이미 실행 중이던 파드가 있었고, 설치 도구가 모든 파드가 Cilium이 제공하는 네트워킹을 받도록 자동으로 재시작했음을 나타내요.

설치 검증 (Validate the Installation)

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)

참고: 연결성 테스트는 일부 파드에서 열려 있는 파일이 너무 많아 배포에 실패할 수도 있어요. 이런 오류가 보이면 호스트 머신의 inotify 리소스 한도를 늘려 보세요 (즉, "too many open files"로 인한 파드 오류 참고).

축하해요! 이제 Cilium이 완전히 동작하는 Kubernetes 클러스터를 갖추셨어요. 🎉

다음 단계 (Next Steps)

• Hubble Observability 설정

• CLI로 네트워크 플로우 검사

• Service Map과 Hubble UI

• Identity-Aware 및 HTTP-Aware 정책 강제

• Cluster Mesh 설정

더 알아보기 (Learn more)

• 설치 상태 확인
• 연결성 테스트
• Cilium CLI 설치
• Getting Started 가이드