k3s

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

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

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

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

アップグレード

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する際には、ディレクトリパーミッションのエラーが起きがちであるため、コンテナ起動時の設定が必要でしょう。

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秒待たされます。

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の接続エラー

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のパスを指定します。