k3s

k3sは軽量にリパックしたkubernetesです。一般的なx64 PCのほか、Raspberry Piもサポートしています。 Rancher Desktopのランタイムとしても使われています。

サイトのスクリプトを実行するとインストールできます。

$ curl -sfL https://get.k3s.io | sh -

この過程でsystemd設定も完了し、システム起動時にk3sが自動起動します。

事前準備

ドキュメント類には記載されていないものの、kubernetesはホストが固定IPであることを暗に前提としています。
デュアルスタックの場合には、IPv4/IPv6の両方を固定IPに設定しておくことが必要です。

ノード1台構成で運用中にホストIPが変わってしまった場合、systemdのk3s.serviceが最初のノードとの通信エラーで異常終了し、再起動を繰り返すものの回復しない挙動となります。

この状態に陥った場合の手軽な回復方法は、再インストールです。ノードのIP設定を変更する方法はありません。
また、クラスタ上で動作しているリソース一式にもアクセスできないため、稼動中のコンテナセットのバックアップも難しい状況に陥ります。

Raspberry Piのcgroup有効化

Raspberry Piはcgroupの一部機能を無効化しているケースがあり、その場合、ブート時のカーネルオプションに次のようなパラメータを追加して、cgroupの機能を有効にしておく必要があります。

cgroup_enable=memory

Ubuntuのcmdline.txtは/boot/firmware/cmdline.txtです。リブートすると有効になります。
現在のカーネルのコマンドパラメータは/proc/cmdlineで確認できます。

kubernetes動作にはcpusetやmemoryなどのcgroupアクセスが必要です。cgroup v2の機能は/sys/ファイルシステムを通じて確認できます。

$ cat /sys/fs/cgroup/cgroup.controllers
cpuset cpu io memory hugetlb pids rdma misc dmem

似て非なるcgroup v1(/proc/cgroups)は廃止されつつあるため不要です。

IPv6対応クラスタ

IPv6デュアルスタックをサポートするにはクラスタ構築時にオプションを追加します。

$ curl -sfL https://get.k3s.io | sh -s - --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

インストール時オプションについては、 Configuratonに解説があります。
--flannel-ipv6-masqを付けないと コンテナから外部通信できない構成になるため、ほぼ必須でしょう。

/etc/rancher/k3s/config.yamlをあらかじめ作成しておくとインストール時のオプションを追加しなくても参照されます。インストールの再現性を必要とするケースでは、ワークするconfig.yamlを確保しておく方法が適しています。

また、デフォルトではIPv4をリッスンする構成となり、IPv6のNodePortはlocalhostにバインドしていないようです。サービスオブジェクトは異常なく作成できますが、ホストから::1宛てに接続するとコネクションが切れます。

アップグレード

Upgrade k3sのとおり、インストールと同じスクリプト実行でアップグレードできます。

context

/etc/rancher/k3s/k3s.yamlにkubeconfigが生成され、既存のconfigとマージするとkubectl configサブコマンドによるcontext切り替えでローカルk3sクラスタを操作できます。

# 一般ユーザーからアクセス可能に
$ sudo cp /etc/rancher/k3s/k3s.yaml ~/.kube/
$ sudo chown $USER:$USER ~/.kube/k3s.yaml

# context名をk3sに変更（任意）
$ sed -i -e 's/default/k3s/g' k3s.yaml

$ KUBECONFIG=~/.kube/config:~/.kube/k3s.yaml kubectl config view --flatten > ~/.kube/merged
# mergedの内容が問題なければ、configを置き換え
$ mv ~/.kube/merged ~/.kube/config

プライベートレジストリの認証

コンテナイメージを外部から取得する際の認証は、 プライベートレジストリへのアクセス権を設定の手順で設定できます。
ただし、ServiceAccountはネームスペースごとに作成されるオブジェクトであることに注意が必要です。コンテナを起動するネームスペースのデフォルトServiceAccountにsecretをアタッチする必要があります。

また、ローカルネットワークにミラーレジストリを構築するケースについては、 /etc/rancher/k3s/registries.yamlの設定で参照できます。

ローカルディレクトリのmount

hostPathボリュームを用いてコンテナ内からローカルディレクトリにもアクセスできます。
Directoryボリュームをmountする際には、ディレクトリパーミッションのエラーが起きがちであるため、コンテナ起動時の設定が必要でしょう。

トラブルシュート

k3s serverの起動エラー

k3sをインストールするとsystemd経由で起動する設定が追加されます。k3sじたいの起動エラーはdmesgに出力しますが、systemdのエラー出力は簡素で切り分けに使えないことがあります。

/etc/systemd/system/k3s.serviceの末尾のExecStartのコマンドを実行すると、k3s serverのエラーを直接確認できます。
実際に遭遇した例として、 トークン破損が起きたことがあります。/var/lib/rancher/k3s/server/tokenを削除して再起動することで回復しました。

kube-systemの起動エラー

稀にkube-systemのコンテナが起動失敗していることがあり、この場合、コンテナがネットワーク通信不能になります。
以下のようなコマンドで再起動できます。

    kubectl rollout restart -nkube-system deploy/coredns
    kubectl rollout restart -nkube-system deploy/local-path-provisioner
    kubectl rollout restart -nkube-system deploy/metrics-server

コンテナネットワーク不調

コンテナは動作していてkubectl経由の操作は可能なものの、別のコンテナやNodePortからアクセスできない場合、k3sのネットワーク設定のトラブルが考えられます。
k3sのネットワークconfigは、おそらくsystemdの起動スクリプトで直接指定されています。Linuxディストリビューションのネットワーク設定は階層構造になっている場合があり、別レイヤの設定と干渉することがあり得ます。

実際に遭遇した例として、UbuntuのNetplanにcni0インターフェースの設定が存在する場合、コンテナネットワークが不通になる事象がありました。このケースでは/etc/netplan/内のcni設定を削除して再起動すると適切に動作しました。

shutdown不良

systemd-shutdown hangs on containerd-shim when k3s-agent running #2400というissueのとおり、k3sインストール後に電源断やリブートが鈍くなることがあります。

本質的にはコンテナプロセスのクリーンアップをシャットダウン時に的確に行う必要がある問題ですが、/etc/systemd/system.confのDefaultTimeoutStopSecを短くすることでsystemdに強制終了させるワークアラウンドがあります。

ところが、Ubuntu20.04のsystemdにはこの configを読まないバグがあるため、完全終了まで90秒待たされます。

kubectlの接続エラー

kubectlがUnauthorizedエラーを返すケースがあります。
多くの場合~/.kube/configに接続情報が設定されており、user.client-certificate-dataやuser.client-key-dataが破損していると認証に失敗します。

また、このcertificateは期限切れを迎えます。k3sをアップグレードしても各ユーザーのconfigまでは更新しないからです。 kubectl実行時に次のようなエラーに遭遇します。

E0210 17:25:42.675689   10896 memcache.go:265] couldn't get current server API group list: the server has asked for the client to provide credentials
error: You must be logged in to the server (the server has asked for the client to provide credentials)

/etc/rancher/k3s/k3s.yamlに現在のシステムのクレデンシャルがあり、この設定を引きうつすことで回復しました。certificateはbase64エンコードされたpemであり、デコードのうえopenssl x509コマンドで有効期限を確認できます。
~/.kube/configには他のクラスタのクレデンシャルも含まれているため、userセクションのk3s用設定を書きかえます。

kubectl実行時に~/.kube/configを参照しない場合には、.bashrcなどの設定にexport KUBECONFIG=~/.kube/configを指定して、アクセスできるconfigのパスを指定します。

まとめ

Linux上のk3sはVMがないためRancher Desktopより安定しています。
設定については、 k3s configを参照してください。