ほとんどの Kubernetes アドオンは、すでに機能しているクラスターにインストールします。Cilium は違います。CNI として、Cilium はまさにクラスターのネットワーキングそのものです。したがって、クラスターはその役割をすでに担っているデフォルトの CNI なしで作成する必要があります。そうしないと、Cilium が引き継ぐ対象がありません。このガイドでは、ローカルの kind クラスターを使ってその順序を説明し、その後 Helm で Cilium をインストールします。

ここで順序が重要な理由

Kubernetes クラスターは通常、Pod のネットワーキングを管理する何らかの CNI がすでにインストールされた状態で起動します。kind では kindnet、クラウドプロバイダーではそのプロバイダー独自のデフォルトです。すでに稼働している CNI の上に Cilium をインストールすると、同じ仕事を担おうとする 2 つのネットワークプラグインが存在することになり、動作しません。Cilium が唯一の CNI でなければなりません。つまり、Cilium をインストールした後ではなく、インストールする前に、その役割を担うはずのデフォルトを無効にする必要があります。

デフォルトの CNI を無効にしてクラスターを作成する

kind では、これは後から無効にするものではなく、クラスター設定の項目です。

# kind-config.yaml
kind: Cluster
apiVersion: kind.x-k8s.io/v1alpha4
networking:
  disableDefaultCNI: true
nodes:
  - role: control-plane
    extraPortMappings:
      - containerPort: 30080
        hostPort: 80
      - containerPort: 30443
        hostPort: 443
  - role: worker

kind create cluster --config kind-config.yaml
kubectl get nodes

すべてのノードが NotReady と表示されることを想定してください。これは失敗ではなく想定どおりの動作です。まだ CNI がインストールされていないため、ノードは Ready になれません。extraPortMappings は基本的なインストールには必須ではありません。kind には、ルーティング可能なアドレスを割り当てるクラウドのロードバランサーがないため、サービスを外部に公開する、このシリーズの後続のガイドのために、あらかじめ設定しているものです。

ローカルクラスターではなく、マネージドのクラウド Kubernetes サービスを使っている場合は、デフォルトの CNI なしでクラスターを作成する方法について、そのプロバイダーのドキュメントを確認してください。方法はプロバイダーごとに異なりますが、根本的な要件、つまり Cilium がインストールされる前に CNI がその役割を担っていてはならないという点は、どこでも同じです。

Gateway API を使う場合は、Cilium の前に CRD をインストールする

Cilium で Kubernetes Gateway API を使う予定がある場合（次のガイドで説明します）、Cilium 自体のインストールで Gateway API のサポートを有効にする前に、その CustomResourceDefinition をここでインストールしてください。Cilium の Gateway API コントローラーは、これらの CRD（GatewayClass、Gateway、HTTPRoute および関連する型）がすでにクラスターに存在することを前提としています。

kubectl apply -f https://github.com/kubernetes-sigs/gateway-api/releases/download/v1.4.1/standard-install.yaml

常に最新版を取得するのではなく、特定の Gateway API リリースに固定してください。Gateway API の進化は、すべての実装が追従できる速度を超えており、Cilium 自身のリリースノートには、各 Cilium リリースが実際にテストされた Gateway API のバージョンが記載されています。Cilium がサポートするより新しい CRD バージョンを使うと、ご自身の設定とは無関係の、分かりにくいエラーが発生する原因になりやすいです。

Helm で Cilium をインストールする

helm repo add cilium https://helm.cilium.io
helm repo update
helm show values cilium/cilium --version 1.19.0 > cilium-values.yaml

インストール前にデフォルトの values ファイル全体を確認する価値は、数分かかっても十分にあります。長いファイルですが、設定可能な項目の正式な一覧です。Gateway API も使うクラスターで、最も重要な設定は次のとおりです。

# cilium-values.yaml (関連する抜粋)
kubeProxyReplacement: true

gatewayAPI:
  enabled: true
  gatewayClass:
    create: false   # GatewayClass は自分で明示的に作成する（次のガイドで説明）

hubble:
  enabled: true
  relay:
    enabled: true
  ui:
    enabled: true

kubeProxyReplacement: true は、前のガイドで説明したとおり、kube-proxy と並行して動作するのではなく、Cilium が eBPF で Service のルーティングを完全に引き継ぎます。gatewayClass.create を false に設定するのは意図的な選択であり、守り続けなければならないデフォルトではありません。これにより、Helm チャートが暗黙的に作成するのではなく、GatewayClass リソースをご自身で作成して所有できます。Argo CD や Flux などの GitOps ツールで管理している場合、他の設定と同じように追跡できるので便利です。ここで Hubble とその UI を有効にすると、このシリーズ全体で参照される可観測性ツールが使えるようになりますが、Gateway API や BGP が単独で動作するために必須ではありません。

helm install cilium cilium/cilium \
  --version 1.19.0 \
  --namespace kube-system \
  -f cilium-values.yaml

インストールを確認する

kubectl get pods -n kube-system -l k8s-app=cilium
kubectl get nodes

Cilium の Pod が Running になり、そうなると、クラスター作成直後に NotReady だったノードがすぐに Ready に変わるはずです。この遷移のために他に必要なことはありません。各ノードで Cilium のエージェント自身が起動することが、それを可能にします。

後から安全に変更できるもの

kubeProxyReplacement や、どの CNI がインストールされているかといった設定は、インストール時に正しく決めるべきものです。稼働中のクラスターでこれらを変更するとサービスが中断するため、気軽に試すべきではありません。リソース制限、有効な機能、Hubble の設定など、他のほとんどの値は、同じ values ファイルに対する helm upgrade で後から調整できます。そのレベルの注意は必要ありません。