cilium-kubernetes

このAnsibleロールは、KubernetesクラスターにCiliumネットワークをインストールします。内部では、公式のHelmチャートを使用しています。現在、Ciliumのデプロイメントのインストール、アップグレード、および削除などの手順がサポートされています。

バージョン

すべてのリリースにタグを付けており、セマンティックバージョニングに従うようにしています。このロールを使用する場合は、最新のタグをチェックアウトすることをお勧めします。マスターブランチは基本的に開発のためのものであり、タグは安定したリリースを示します。ただし、一般的にマスターも良好な状態に保つように努力しています。タグ 13.0.0+1.15.3 は、このロールのリリース 13.0.0 であり、Ciliumチャートのバージョン 1.15.3 を含んでいることを意味します。ロール自体が変更されると、 X.Y.Z の部分が増加します。また、Ciliumチャートのバージョンが変更されると、 + の後の X.Y.Z も増加します。これにより、特定のCiliumリリースの開発が続いている間でも、バグ修正や新しいメジャーバージョンのタグ付けが可能になります。

要件

ansible-playbook が実行されるホスト、またはプレイブックが委任されたホスト（例：cilium_delegate_to 変数を使用）には、Helm 3のバイナリがインストールされている必要があります。以下のいずれかを使用できます。

• ディストリビューションのリポジトリに helm が含まれている場合は、お好きなパッケージマネージャーを使用します（Archlinuxの場合、sudo pacman -S helm など）。
• Ansibleの Helm ロール（例：helm）のうちの一つを使用します（このロールを使用する場合、ansible-galaxy role install -vr requirements.yml でインストールされます）。
• または、Helmのリリースからバイナリを直接ダウンロードし、 /usr/local/bin/ ディレクトリに配置します。

適切に設定された KUBECONFIG も必要です（デフォルトでは ${HOME}/.kube/config にあります）。通常、kubectl がクラスターで動作する場合、その点については問題ありません。

さらに、Ansibleの kubernetes.core コレクションをインストールする必要があります。これは、このロールに含まれている collections.yml ファイルを使って次のように実行できます： ansible-galaxy install -r collections.yml。

もちろん、Kubernetesクラスターも必要です ;-)

インストール

• GitHubから直接ダウンロードします（クローンする前にAnsibleロールディレクトリに移動してください。ロールパスは ansible-config dump | grep DEFAULT_ROLES_PATH コマンドで確認できます）： git clone https://github.com/githubixx/ansible-role-cilium-kubernetes.git githubixx.cilium_kubernetes

• ansible-galaxy コマンドを介して、Ansible Galaxyから直接ダウンロードします： ansible-galaxy install role githubixx.cilium_kubernetes

• 次の内容で requirements.yml ファイルを作成し（これによりGitHubからロールがダウンロードされます）、 ansible-galaxy role install -r requirements.yml でインストールします（必要に応じて version を変更してください）：

---
roles:
  - name: githubixx.cilium_kubernetes
    src: https://github.com/githubixx/ansible-role-cilium-kubernetes.git
    version: 13.0.0+1.15.3

変更履歴

変更履歴:

完全なCHANGELOG.mdをご覧ください。

最近の変更:

13.0.0+1.15.3

破壊的変更

• templates/cilium_values_default.yml.j2 に変更：
  • kubeProxyReplacement、nodePort、および socketLB を追加しました（これはBPFマスカレードがNodePortを必要とするためです）。

更新

• Cilium v1.15.3 にアップグレードしました。

Molecule

• Vagrant generic/ubuntu2204 ボックスを alvistack/ubuntu-22.04 に置き換えました。

12.0.0+1.15.0

• Cilium v1.15.0 にアップグレードしました。
• Molecule設定をリファクタリングしました。
• cilium_chart_values_directory 変数を導入しました。

ロール変数

# Helmチャートバージョン
cilium_chart_version: "1.15.3"

# Helmチャート名
cilium_chart_name: "cilium"

# HelmチャートURL
cilium_chart_url: "https://helm.cilium.io/"

# CiliumリソースをインストールするKubernetesネームスペース
cilium_namespace: "cilium"

# Helmチャートの値ファイルが含まれるディレクトリ。Ansibleは指定されたディレクトリ内で
# "values.yml.j2"または "values.yaml.j2" というファイルを探します
# （".j2" は通常のJinja2テンプレート記法を使用できるため）。
# 見つからない場合は、デフォルトの "templates/cilium_values_default.yml.j2" が
# 使用されます（これはテンプレートとしても使用できます）。このファイルの内容は
# "helm install/template" コマンドの値ファイルとして提供されます。
cilium_chart_values_directory: "/tmp/cilium/helm"

# etcd設定。"cilium_etcd_enabled" 変数が定義され、"true" に設定されている場合、
# Ciliumのetcd設定が生成されてデプロイされます。そうでない場合は、すべての
# "cilium_etcd_*" 設定は無視されます。
cilium_etcd_enabled: "true"

# etcdデーモンがリッスンしているインターフェース。もしetcdデーモンが
# WireGuardインターフェースにバインドされている場合、この設定は
# "wg0"（デフォルト）になるべきです。例えば。
# もし私のetcdロールを使っている場合、"{{ etcd_interface }}" のような
# 変数を使用することもできます（詳細は
# https://github.com/githubixx/ansible-role-etcd）
cilium_etcd_interface: "eth0"

# etcdデーモンがリッスンしているポート
cilium_etcd_client_port: 2379

# Ansibleのetcdホストグループ。これは "templates/cilium_values_default.yml.j2" 
# テンプレートで、etcdデーモンがリッスンしているホストのIPアドレスを
# 判断するために使用されます。
cilium_etcd_nodes_group: "k8s_etcd"

# この変数が定義されると、"cilium_etcd_cafile"、"cilium_etcd_certfile"、
# "cilium_etcd_keyfile" で定義された証明書ファイルを含むKubernetesシークレットが
# インストールされます。
# これにより、etcdにセキュアな接続（https）が確立されます。
# もちろん、これはetcdがSSL/TLSを使用するように設定されている必要があります。
# この値が定義されていない場合（例：コメントアウトされた場合）、残りの
# "cilium_etcd_*" 設定は無視され、etcdには非セキュアな "http" 経由で接続されます。
cilium_etcd_secrets_name: "cilium-etcd-secrets"

# 定義された証明書ファイルの場所。私のKubernetes証明書認証機関ロールを使用している場合
# （https://github.com/githubixx/ansible-role-kubernetes-ca）、すでに
# "k8s_ca_conf_directory" 変数が定義されているかもしれます。
# このロールは、以下の変数で使用できる証明書ファイルも生成します。
# デフォルトでは、これは "ansible-playbook" コマンドを実行するユーザーの
# "$HOME/k8s/certs" になります。
cilium_etcd_cert_directory: "{{ '~/k8s/certs' | expanduser }}"

# etcd証明書認証機関ファイル（ファイルは "cilium_etcd_cert_directory" から取得されます）
cilium_etcd_cafile: "ca-etcd.pem"

# etcd証明書ファイル（ファイルは "cilium_etcd_cert_directory" から取得されます）
# 証明書には、etcdデーモンがリッスンしているインターフェースの
# "Subject Alternative Name" (SAN) にIPアドレスが含まれていることを
# 確保してください（これが "cilium_etcd_interface" で定義されたインターフェースの
# IPアドレスです）。この処理は、私のKubernetes証明書認証機関ロールが行います。
cilium_etcd_certfile: "cert-cilium.pem"

# etcd証明書キー文件（ファイルは "cilium_etcd_cert_directory" から取得されます）
cilium_etcd_keyfile: "cert-cilium-key.pem"

# デフォルトでは、Kubernetesクラスタと通信する必要のあるすべてのタスクが
# ローカルホスト（127.0.0.1）で実行されます。しかし、そこがこのクラスタに直接
# 接続できない場合、または他の場所で実行する必要がある場合は、
# この変数を適宜変更できます。
cilium_delegate_to: 127.0.0.1

# タスクがHelmを使用してリソースをインストール、更新/アップグレード、
# または削除する場合に実行された "helm" コマンドを表示します。
cilium_helm_show_commands: false

# "cilium_action" 変数が定義されていない場合、このロールはインストールまたは
# アップグレードされるすべてのリソースを含むYAMLファイルをただ生成します。
# 生成されたリソースのファイルは "template.yml" と呼ばれ、
# 下記の指定されたディレクトリに配置されます。
cilium_template_output_directory: "{{ '~/cilium/template' | expanduser }}"

使用方法

最初に行うべきことは、templates/cilium_values_default.yml.j2 を確認することです。このファイルには、デフォルト値（こちらにあります）とは異なるCilium Helmチャートの値/設定が含まれています。このAnsibleロールのデフォルト値は、TLSが有効化された etcd クラスターを使用しています。自己ホスト型のKubernetesクラスターの場合、Kubernetes APIサーバーのためにすでに実行されている etcd クラスターが存在する可能性が高いです。私は自分のAnsible etcdロールを使用して、そのような etcd クラスターをインストールしており、私の Kubernetes Certificate Authorityロールを使用して証明書を生成しています。したがって、私のロールを使用した場合、このCiliumロールを基本的にそのまま利用できます。

templates/cilium_values_default.yml.j2 テンプレートには、TLSが有効でないetcdクラスタを使用するためのいくつかの if 条件も含まれています。どの値を変更できるかは、 defaults/main.yml を確認してください。独自の変数を導入することもできます。独自の値を使用するには、values.yml.j2 または values.yaml.j2 というファイルを作成して、cilium_chart_values_directory で指定されたディレクトリに配置してください。すると、このロールはそのファイルを使用してHelmの値を生成します。

値ファイルが準備でき、defaults/main.yml の値が確認できたら、ロールをインストールできます。このロールのタスクのほとんどはデフォルトでローカルで実行されるため、Kubernetes APIサーバーと通信する必要があるタスクやHelmコマンドを実行するためのタスクがいくつかあります。しかし、 cilium_delegate_to 変数を使用することにより、この種のタスクを別のホストに委任できます（上記参照）。委任されたホストにはKubernetes APIサーバーへの接続があり、ユーザーが有効な KUBECONFIG ファイルを持っていることを確認してください。

デフォルトアクションは、すべてのJinja2変数とそのほかの部分を置き換えた後にKubernetesリソースのYAMLファイルを単に生成することです。以下の「Example Playbook」セクションには、Example 2 (assign tag to role)があります。ロール githubixx.cilium_kubernetes には、role-cilium-kubernetes というタグが付いています。Helmチャートの値を生成することを想定しています（この場合、インストールは行われません）、プレイブックが k8s.yml であると仮定して、次のコマンドを実行します：

ansible-playbook --tags=role-cilium-kubernetes k8s.yml

テンプレートを別のディレクトリに生成するには、cilium_template_output_directory 変数を使用します。例えば：

ansible-playbook --tags=role-cilium-kubernetes --extra-vars cilium_template_output_directory="/tmp/cilium" k8s.yml

実行された helm コマンドとパラメータをログに表示したい場合は、--extra-vars cilium_helm_show_commands=true を指定することもできます。

最終タスクの一つは、TASK [githubixx.cilium_kubernetes : Write templates to file] と呼ばれています。これは、生成されたリソースを含むテンプレートを cilium_template_output_directory で指定されたディレクトリに書き込むものです。ファイルは template.yml と呼ばれ、あなたのローカルマシンに配置されて、検査できるようになります。

生成された出力に必要なものがすべて含まれている場合、ロールをインストールすることでCiliumがデプロイされます：

ansible-playbook --tags=role-cilium-kubernetes --extra-vars cilium_action=install k8s.yml

すべてがデプロイされたか確認するためには、通常の kubectl コマンド（例： kubectl -n <cilium_namespace> get pods -o wide）を使用します。

Cilium は数週間/月ごとにアップデート/アップグレードを行うため、ロールでもアップグレードが可能です。ロールは基本的にCiliumアップグレードガイドに記載されている内容を実行します。つまり、Ciliumの事前チェックがインストールされ、実際にアップデートが行われる前にいくつかのチェックが実行されます。アップデートの前後に何が起こるかを見るには、tasks/upgrade.yml を確認してください。もちろん、アップグレードの前にCiliumアップグレードガイドを参照し、主な変更事項を確認してください。また、アップグレードノートも確認してください！

アップグレードが成功しなかった場合、ロールバックは基本的に cilium_chart_version 変数を変更するだけで開始できます。しかし、Ciliumのロールバックガイドを必ず読んでください。マイナーリリース間の切り替えは通常問題ありませんが、メジャーリリースの切り替えはあまり簡単でないことがあります。

また、templates/cilium_values_default_pre_flight_check.yml.j2 を確認してください。事前チェック用の値を調整する必要がある場合は、そのファイルを変更するか、独自の値で templates/cilium_values_user_pre_flight_check.yml.j2 というファイルを作成できます。

アップグレードを行う前に、基本的には cilium_chart_version 変数を 1.13.4 から 1.14.5 に変更するだけで、 1.13.4 から 1.14.5 にアップグレードできます。アップデートを行うには、次のコマンドを実行します：

ansible-playbook --tags=role-cilium-kubernetes --extra-vars cilium_action=upgrade k8s.yml

すでに述べたように、ロールにはアップグレードがスムーズに進むようにするためのいくつかのチェックが含まれていますが、アップグレード後にすべてが期待通りに動作するかを再度 kubectl で確認してください。

最後に、Ciliumを削除したい場合は、すべてのリソースを再度削除できます：

ansible-playbook --tags=role-cilium-kubernetes --extra-vars cilium_action=delete k8s.yml

CNIプラグインが構成されていない場合、これによりKubernetesワーカーノードの kubelet プロセスが時折CNIエラーを発行します。なぜなら、もはやCNIに関連するものがないためであり、もちろん異なるホスト上のポッド間の接続性も失われ、ネットワークポリシーなどが除外されることになります。

例プレイブック

例1（ロールタグなし）：

- hosts: k8s_worker
  roles:
    - githubixx.cilium_kubernetes

例2（ロールにタグを割り当てる）：

-
  hosts: k8s_worker
  roles:
    -
      role: githubixx.cilium_kubernetes
      tags: role-cilium-kubernetes

テスト

このロールには、小さなテストセットアップがあり、Molecule、libvirt (vagrant-libvirt)、およびQEMU/KVMを使用して作成されています。テストのセットアップ方法については、私のブログ記事 Testing Ansible roles with Molecule, libvirt (vagrant-libvirt) and QEMU/KVM を参照してください。テスト設定はこちらです。

その後、moleculeを実行できます。次のコマンドは基本的なセットアップを行い、生成されるリソースのテンプレートを作成します（デフォルトアクションを参照）：

molecule converge

Ciliumと必要なリソースをインストールします。これにより、いくつかの仮想マシン（VM）が設定され、Kubernetesクラスターがインストールされます。このセットアップを使ってこのロールを使用して Cilium をインストールします。

molecule converge -- --extra-vars cilium_action=install

次のコマンドは、KubernetesのDNS関連の作業のためにCoreDNSをインストールし、Ciliumポッドのみを実行するようにコントロールノードに汚染を加えます：

molecule converge -- --extra-vars cilium_setup_networking=install

Ciliumのアップグレードやパラメータの変更：

molecule converge -- --extra-vars cilium_action=upgrade

Ciliumとそのリソースを削除：

molecule converge -- --extra-vars cilium_action=delete

いくつかのテストを実行するには、以下のコマンドを使用します（必要に応じて -v を追加して詳細な出力を得ることができます）：

molecule verify

クリーンアップを行うには、次のコマンドを実行します：

molecule destroy

ライセンス

GNU一般公衆ライセンスバージョン3

作者情報

http://www.tauceti.blog