K3sのconfig

軽量kubernetesクラスタの k3sはPC1台から小規模構成を手軽に構築できます。

k3sクラスタの設定には、systemdユニットの起動時オプション指定と、 configファイルの2種類を利用できます。

複数の機器のセットアップやバックアップ・リストアを考えるとconfigファイルの方がポータブルです。

起動時オプション

公式サイトのスクリプトからインストールした場合、k3sはsystemdのサービスとしてセットアップされます。

/etc/systemd/system/k3s.serviceを編集することで 起動時オプションをカスタマイズできます。

公式ドキュメントの各オプションの解説は、このサーバー起動時に用いるフォーマットです。
後述のYAML形式は、オプションの書式が直感的でないものがあるため、動作しない場合には起動時オプションを直接指定する方法もとれます。

systemd標準の手順どおり、systemctl daemon-reloadsystemctl restart k3sにより再起動し、configを反映できます。

/etc/rancher/k3s/config.yaml

configファイルは、k3sの各サーバーのオプションをYAMLに変換したものです。

Linuxにセットアップした場合の一般的なconfigパスは/etc/rancher/k3s/config.yamlです。
最初はファイルが存在せず、カスタマイズの必要が発生した場合に作成します。

kubeletのconfig

k3sはkubeletを内包しているため、kubernetes標準の起動オプションもconfig.yamlに指定できますが、分かりにくいポイントがあります。

kubeletのようにネストした設定セットは、YAMLのマップではなく、次のようにコマンドライン引数のような文字列を配列指定します。

kubelet-arg:
  - "image-gc-high-threshold=99"
  - "image-gc-low-threshold=98"

この例は、ガベージコレクションの挙動を指定するものです。

kube-apiserveretcdなどのkubernetesプロセスにオプション指定するケースも同様でしょう。

ガベージコレクションによる動作不良例

上の設定は、ディスク逼迫に伴うコンテナevictionに対処する例です。
これはk3sに限らず、kubernetesの一般的なセットアップで多く報告されているトラブルです。

kubeletのガベージコレクションは、ディスク空き容量が少なくなった際にも動作します。
デフォルトでは92%消費した際(image-gc-high-threshold)に80%まで空きを回復(image-gc-low-threshold)させる、といった意図の設定になっています。

ハードがk3s専用ではないケースでは、この既定値が適切に機能しないことがあります。 たとえば、1TBのパーティションにインストールした場合、残り80GBを切った際にガベージコレクションが動作し、12GBを解放しようとします。

しかし、ディスクが他の用途で埋まっている場合、不要なコンテナイメージキャッシュを削除しても12GBまで解放できません。
この場合、kubernetesはディスク利用をあきらめ、ノードがダウンします。
このエラーは、journalctl -e -u k3skubectl describe nodesのイベントログで確認できます。

クライアントPC上にクラスタをセットアップするようなケースでは、ディスク枯渇の主要因がkubernetesでないことは多いので、ハード構成の実態に合わせてgcの動作を抑制することが有効です。

設定例

IPv6/IPv4デュアルスタック

起動時オプションによる設定は公式ドキュメント記載のとおりですが、YAML形式は次のとおりです。

cluster-cidr: "10.42.0.0/16,2001:cafe:42::/56"
service-cidr: "10.43.0.0/16,2001:cafe:43::/112"
flannel-ipv6-masq: true

--flannel-ipv6-masqのように機能をオンにするオプションはbool値を指定する形式になります。

nodePortにウェルノウンポートを指定する

kubernetesのデフォルトではServicenodePortは30000番台を利用しますが、--service-node-port-range=100-9999のように変更でき、ウェルノウンポートも使えます。
YAMLの書式は次のとおりです。

service-node-port-range: "100-9999"

PodhostPortと同様にホストのポートをlistenしますが、nodePortはk3sによるルートが加わるためバックエンドに複数のPodを置けます。一方で、Podに到達するリクエストはコンテナネットワークの内部IPから受信するため、ピアのIPを参照するアプリケーションでは支障があります。

Ingressを除去する

k3sはデフォルトのIngressとしてtraefikをkube-systemネームスペースにセットアップします。そのため、ホストの443番ポートは干渉します。
--disable-traefikオプションによりtraefikを除去できます。クラスタを再起動すると停止しますが、動き続けている場合には手動でリソースを削除します。

httpsの外部リクエストをうけつけるためにIngressではなく、WebサーバーやプロキシのPodを自前で動作させる場合にも、まずtraefikを無効化する必要があるでしょう。

YAMLの書式は次のとおりです。

disable: "traefik"

なお、disableオプションには複数の機能を指定する可能性がありますが、YAMLの配列ではなくカンマ区切り文字列で指定するようです(未検証)。

⁋ 2023/05/13↻ 2025/09/07
中馬崇尋
Chuma Takahiro