k3s

k3sは軽量にリパックしたkubernetesです。 Rancher Desktopのランタイムとしても使われています。

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

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

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

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

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

また、現時点でIPv6ではNodePortをサポートしていないようです。サービスオブジェクトは異常なく作成できますが、ホストから::1宛てに接続するとコネクションが切れます。

アップグレード

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

context

/etc/rancher/k3s/k3s.yamlにkubeconfigが生成され、既存のconfigとマージするとkube 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をアタッチする必要があります。

ローカルディレクトリの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用設定を書きかえます。

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