この記事は MicroAd Advent Calendar 2024 と Kubernetes Advent Calendar 2024 の4日目の記事です。
今回は、K3dをProxy環境下で利用する際にハマったのでその解消法について、 CloudNative Days Winter 2024 では、Rancherの中の人と勘違いされてたやっさんから紹介します。
（´-`）.｡oO（ export HTTP_PROXY で終わりでは、、 ）
って思うやん？違うんです。。。
では始めていきます。
はじめに
K3dは、Dockerコンテナ内でKubernetesの軽量版のK3sのクラスタをシングルノードまたはマルチノードで動かすためのツールです。K3sでKubernetesクラスタを構成することもあって省スペース＆リソースで稼働するので、CIでシングルノードだけでなくマルチノードで構成したい際にオススメです（Helmチャートのテストとか）。
また、K3dで構築されるK3sクラスタにはローカルストレージプロバイダーが付属していてK3dコマンドを実行するノード時のローカルストレージをPVとして払い出してくれるPVCがデフォルトで付属するので非常に便利です1。
ネットワーク周りについては、K3d側にサービス公開用の機能として、traefik（とらふぃっく）を使ったIngressやNodePortが利用できるようになっています2。
K3d自体のインストールも簡単で、ローカル端末なら Homebrew 、Chocolatey、Scoop に対応しています。またサーバ用途ならインストールスクリプトも用意しているので以下で一発です3。
curl -s https://raw.githubusercontent.com/k3d-io/k3d/main/install.sh | bash または curl -s https://raw.githubusercontent.com/k3d-io/k3d/main/install.sh | TAG=v5.7.5 bash
インストールが完了すると、k3dコマンドが利用できるようになります。
❯ k3d --help https://k3d.io/ k3d is a wrapper CLI that helps you to easily create k3s clusters inside docker. Nodes of a k3d cluster are docker containers running a k3s image. All Nodes of a k3d cluster are part of the same docker network. Usage: k3d [flags] k3d [command] Available Commands: cluster Manage cluster(s) completion Generate completion scripts for [bash, zsh, fish, powershell | psh] config Work with config file(s) help Help about any command image Handle container images. kubeconfig Manage kubeconfig(s) node Manage node(s) registry Manage registry/registries version Show k3d and default k3s version Flags: -h, --help help for k3d --timestamps Enable Log timestamps --trace Enable super verbose output (trace logging) --verbose Enable verbose output (debug logging) --version Show k3d and default k3s version Use "k3d [command] --help" for more information about a command.
上記のヘルプにもあるように、completionにも対応してるので補完が効くのでとても便利です。
それでは本題のProxy環境下でのハマりポイントの解決の話の前に、、、、
K3sの紹介を軽く触れるので、「K3sの話はいいよ」って方は目次から飛んでください。
- はじめに
- K3s・K3dとは何か？
- 🙃ハマりポイント：クラスタ構築
- 🙃ハマりポイント：コンテキストが行方不明になる問題
- 🙃ハマりポイント：K3sクラスタノードにどうやってはいったらよいの？
- 最後に
- 補足
K3s・K3dとは何か？
K3sは、当時のRancher Labs（現SUSE）から2019年3月にGAしました。
軽量さを武器にエッジコンピューティング市場で注目を集め、Dockerベースでシンプルにデプロイ出来ることから開発環境向けにも重宝されています。
2020/8にはRancher LabsはK3sをCNCF（Cloud Native Computing Foundation）に寄贈しました。これにより、K3sはCNCF Sandboxプロジェクトの1つとなりました。
また、本番利用にも耐え、CNCF認定ディストリビューションとして合格しているプロダクトなので安心して利用できます。 Kubernetesクラスタ管理プラットフォーム RancherをインストールするためのKubernetesクラスタとしても利用できます4。
この記事書いてて初めて知ったのですが、、、巷ではK3sは『Kubernetesの短縮形が「K8s」で軽量化するためにそこから5つ抜いたので ８−５＝３なので、「K3s」だ』って話をよく耳にするのですが、、、
実はそれ間違ってて、 K3sのリポジトリのREADMEには、以下のように記載されてました。
What's with the name? We wanted an installation of Kubernetes that was half the size in terms of memory footprint. Kubernetes is a 10 letter word stylized as k8s. So something half as big as Kubernetes would be a 5 letter word stylized as K3s. A '3' is also an '8' cut in half vertically. There is neither a long-form of K3s nor official pronunciation.
つまり、、「リソース使用量を半分に削減する」という目標が名前の由来であり、Kubernetesの短縮形の「K8s」の「8」を縦に半分にした「3」を強調した比喩的な表現ということでした。。
ΩΩΩ<な、なんだってー!?
そして、軽量化の取り組みとして以下を行っています。
- 組み込み5のストレージドライバを削除6
- 組み込みのクラウドプロバイダーを削除7
- 複数のKubernetesコンポーネント（例: kube-apiserver、kube-controller-manager、kube-schedulerなど）を一部統合し、単一プロセス内で実行する仕組みに変更8
- etcdを組み込みのDB（SQLite）または外部データストアに対応9
一方、K3dについては、冒頭で述べた話に加え、K3sと異なるのは以下の通り、Rancherのプロダクトではなくコミュニティ駆動のプロダクトになっています。
https://k3d.io/v5.4.6/ より引用 Note: k3d is a community-driven project but it’s not an official Rancher (SUSE) product. Sponsoring: To spend any significant amount of time improving k3d, we rely on sponsorships:
🙃ハマりポイント：クラスタ構築
基本的にK3dでクラスタを構築するには、k3d cluster create を使います。
ただし、Proxy環境下に置いてはオプションが必要です。そのオプションは以下です。
-e, --env KEY[=VALUE][@NODEFILTER[;NODEFILTER...]]
なので、-e つければOKです。
ってことは、、 -e HTTP_PROXY=my.proxy.com でOK。
簡単でしょ？って思うやん？
違うんです。。。大事なのは [@NODEFILTER[;NODEFILTER...]] ここです。このK3d特有のコンセプトである「NODEFILTER」が肝になります。
NODEFILTERについては、K3dのコンセプトのページに説明があります。
上記のドキュメントにあるように環境変数のKey/Valueの後に @<group>:<subset>[:<suffix>] としてNodefilterを付けてやる必要があります。
| 項目 | 説明 |
|---|---|
<group> |
フィルタリング対象のノードグループを指定します。 使用可能な値: server, servers, agent, agents, loadbalancer, all⚠️ all はクラスター外部のサーバーロードバランサー（k3d-proxy コンテナ）も含む点に注意。 |
<subset> |
選択したグループ内でフラグを適用したいノードの範囲を指定します。 ▪️ワイルドカード *: グループ内のすべてのノード▪️インデックス（例: 0）: グループ内の最初のノード▪️リスト（例: 1,3,5）: グループ内の1番目、3番目、5番目のノード▪️範囲（例: 2-4）: グループ内の2番目から4番目のノード |
<suffix>（オプション） |
フラグ固有の追加設定を指定できます。 例: --port フラグでは、ポートの公開方法を設定するために direct や（デフォルトの）proxy を指定できます。 |
つまり以下のように、Proxyの環境変数の後に @all:* を付けてやればOK
（クラスタ名を mycluster とした場合）
$ k3d cluster create mycluster \ -e "HTTP_PROXY=my.proxy.com:8080@all:*" \ -e "HTTPS_PROXY=my.proxy.com:8080@all:*" \ -e "NO_PROXY=localhost,127.0.0.1,0.0.0.0,10.0.0.0/8,cattle-system.svc,.svc,.cluster.local,example.com,.localhost@all:*"
また、プライベートレジストリ（myregistry.localhost）が必要な場合は以下
$ k3d registry create myregistry.localhost --port 5000 $ k3d cluster create mycluster \ --servers 1 --agents 3 \ --registry-use k3d-myregistry.localhost:5000 \ -e "HTTP_PROXY=my.proxy.com:8080@all:*" \ -e "HTTPS_PROXY=my.proxy.com:8080@all:*" \ -e "NO_PROXY=localhost,127.0.0.1,0.0.0.0,10.0.0.0/8,cattle-system.svc,.svc,.cluster.local,example.com,.localhost@all:*"
補足： --servers 1 --agents 3 については、 アーキテクチャ | K3s を参照ください。
めでたくクラスタがスピンアップすると以下のようにK3sのNodeとしてコンテナが立ち上がっています
$ docker ps CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES 76021db57e20 ghcr.io/k3d-io/k3d-proxy:5.6.3 "/bin/sh -c nginx-pr…" 40 seconds ago Up 18 seconds 80/tcp, 0.0.0.0:40563->6443/tcp k3d-mycluster-serverlb 0a2ea4336562 rancher/k3s:v1.28.8-k3s1 "/bin/k3d-entrypoint…" 40 seconds ago Up 27 seconds k3d-mycluster-agent-2 c50d9460fe56 rancher/k3s:v1.28.8-k3s1 "/bin/k3d-entrypoint…" 40 seconds ago Up 27 seconds k3d-mycluster-agent-1 c11764231dd2 rancher/k3s:v1.28.8-k3s1 "/bin/k3d-entrypoint…" 40 seconds ago Up 27 seconds k3d-mycluster-agent-0 e49565784e52 rancher/k3s:v1.28.8-k3s1 "/bin/k3d-entrypoint…" 41 seconds ago Up 37 seconds k3d-mycluster-server-0 63744543efce registry:2 "/entrypoint.sh /etc…" 5 months ago Up 3 hours 0.0.0.0:5000->5000/tcp k3d-myregistry.localhost
🙃ハマりポイント：コンテキストが行方不明になる問題
Proxyとは関係ないのですが、複数クラスタを構築している際に kubectl config use-context hogeとしても接続したいクラスタに接続出来ない場合があります。そんな場合は、以下のコマンドを使うことで復活します。
$ k3d kubeconfig merge <接続したクラスタ> -d
🙃ハマりポイント：K3sクラスタノードにどうやってはいったらよいの？
これもProxyとは関係ないのですが、K3sノード内に入って中の状態を確認したい場合があります。そんな場合は、直接K3sノードコンテナに入ってやればいいです。
$ docker exec k3d-spark-server-0 crictl images --digests $ docker exec -ti k3d-spark-server-1 crictl pull k3d-myregistry.localhost:5000/scserver:3.5.1
💡 K3sノードにはデフォルトでcrictlコマンドが利用出来るようになってます（べんりー）
最後に
いかがだったでしょうか。
「ドキュメントちゃんと読もうや、にぃちゃん🔪」って言われたらそれまでなんですが、まぁ、目が滑るってあるよねって事で、、
これを機会にK3dやK3s始めてみたって方は是非、RancherJPで共有してみませんか！以下からお待ちしています！
（´-`）.｡oO（突然の運営からの宣伝）
2025/1頃にはオンライン、2025/2には東京でオフラインでMeetupやりたいなぁと考えてるので、グループに入っていただければ通知が飛んできますよっ！
X.comでは #rancherjp で発信してるのでそちらも是非ウォッチください！
（´-`:）.｡oO（圧が、、）
以上、MicroAd Advent Calendar 2024 と Kubernetes Advent Calendar 2024 の4日目の記事でした。
補足
-
K3dというよりはK3sの機能ですいが詳細はこちらを参照ください
docs.k3s.io↩ -
詳細は以下を参照ください
docs.k3s.io↩ -
詳細なインストール方法については、以下を参照ください
https://k3d.io/v5.7.5/#releases↩ - サポートマトリクスのRancher Managerにある表を参照↩
- 「インツリー（in-tree）」とも呼ばれます↩
- READMEまたはボリュームとストレージ | K3s を参照↩
- READMEネットワーキングサービス | K3s を参照↩
- K3sのアーキテクチャの図を参照するとコンポーネントが別れておらず点線でプロセスとして囲まれていることが分かります。↩
-
K3sのアーキテクチャの図を参照すると、クラスタ外部のPostgreSQL、MySQL、etcdに対応していることが分かります。詳細は以下を参照ください。
docs.k3s.io↩
