コンテナ・オーケストレーション | kubernetes管理 ...はじめに rancher...

はじめに

Rancherはアメリカ合衆国クパチーノに本社を置く Rancher Labs, Inc.が提供する Kubernetes管理プラットフォームです。データセンターからクラウド、エッジに至るまで、Rancher を使用すれば容易に Kubernetes-as-a-Service を構築できます。Rancher は本番環境でコンテナと Kubernetes を基盤として利用したいと考えている企業にとって、最優の選択肢になりました。この度 Rancher Labs, Inc.は、IoTやエッジコンピューティング向けに、新たに軽量かつ認定済みの

Kubernetes ディストリビューションである K3s を開発、GA させました。Kubernetes は、製造、輸送、発電、小売、銀行といった業界共通の市場におけるエッジコンピューティングのユースケースに対応するための最先端のソリューションです。Kubernetesを利用して複雑なワークロードを処理する代表的なエッジシステムには、エネルギーメータ、航空機エンジン、ガス&石油リグ、クルーズ船、高速列車、小売用スキャナ、風力タービン基地局、コネクテッドカー、ATMなどが想定されます。K3sは、その小さなシングルバイナリ、ネイティブ ARMサポート、および本番環境に適した高可用性アーキテクチャにより、エッジシステムでクラスターを自動初期化および維持する理想的な Kubernetesディストリビューションです。すべての K3sクラスターは、Rancherのマルチクラスター機能を使用して、IT運用チームが簡単にインストール、監視、および管理が可能となります。本書は Rancher K3s 公式ドキュメントより、K3s マニュアルを翻訳、日本語版を制作いたしました。本書をきっかけに開発環境での利用のみならず、本番環境において K3sを活用したエッジシステムの開発、運用にチャレンジしてみてください。本書が読者の皆様のお役に立てることを願っております。本書制作にあたり、翻訳を中心的に進めてくださいました株式会社スタイルズ矢野哲朗様、制作編集

にご尽力いただきましたテッキーメディア様およびご協力いただきました皆様に感謝いたします。

Rancher Labs, Inc. 西原順二

3

目次

はじめに 3

第 1章 K3s - K8sとの 5つの違い 7最適な用途 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

1.1 K3sとはどういうものか . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

第 2章アーキテクチャ 92.1 組み込み DBでのシングルサーバーのセットアップ . . . . . . . . . . . . . . . . . . . 92.2 外部データベースを使った HA構成の K3sサーバー . . . . . . . . . . . . . . . . . . . 10

エージェントノード用の登録用固定 IPアドレス . . . . . . . . . . . . . . . . . . . . . 112.3 エージェントノードが登録されるときの動作 . . . . . . . . . . . . . . . . . . . . . . . 12

第 3章クイックスタートガイド 133.1 インストールスクリプト . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

インストール後 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

第 4章インストール 15アンインストール . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

4.1 ノード要件 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15前提条件 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15オペレーティングシステム . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16ハードウェア要件 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16ネットワーク . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16

4.2 インストールオプション . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17インストールスクリプトのオプション . . . . . . . . . . . . . . . . . . . . . . . . . . 17K3sをバイナリでインストールする方法 . . . . . . . . . . . . . . . . . . . . . . . . . 18K3sサーバー起動オプション . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19K3sエージェント起動オプション . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22

4.3 ネットワークオプション . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23Flannelオプション . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23カスタム CNI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24

4.4 外部データベースを使った HA構成 . . . . . . . . . . . . . . . . . . . . . . . . . . . 25

5

目次

インストールの概要 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 264.5 組み込み DB（試験実装）による HA構成 . . . . . . . . . . . . . . . . . . . . . . . . 274.6 クラスターデータストアオプション . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28

外部データストア構成パラメータ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29データストアのエンドポイントの形式と機能 . . . . . . . . . . . . . . . . . . . . . . . 29HA構成組み込み DQLite（試験実装） . . . . . . . . . . . . . . . . . . . . . . . . . 31

4.7 インターネット隔離環境でのインストール . . . . . . . . . . . . . . . . . . . . . . . . 31インストールの概要 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31

第 5章アップグレード 355.1 インストールスクリプトでアップグレードする . . . . . . . . . . . . . . . . . . . . . . 355.2 バイナリを使って手動でアップグレードする . . . . . . . . . . . . . . . . . . . . . . . 355.3 K3sの再起動 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36

第 6章ボリュームとストレージ 376.1 ローカルストレージプロバイダー . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 376.2 Longhornをセットアップする . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39

第 7章ネットワーク 417.1 オープンポート . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 417.2 CoreDNS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 417.3 Traefik イングレスコントローラー . . . . . . . . . . . . . . . . . . . . . . . . . . . . 417.4 サービスロードバランサー . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42

第 8章構成設定と詳細オプション 438.1 マニフェストの自動配布 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 438.2 Helm CRDを利用する . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 448.3 kubectlを使って外部からクラスターへアクセスする . . . . . . . . . . . . . . . . . . 458.4 コンテナランタイムに Dockerを使用する . . . . . . . . . . . . . . . . . . . . . . . . 458.5 RootlessKitで K3sを動かす（試験実装） . . . . . . . . . . . . . . . . . . . . . . . . 46

RootlessKitの既知の課題 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46Rootlessでサーバーとエージェントを起動する . . . . . . . . . . . . . . . . . . . . . 47

8.6 ノードのラベルと taint . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 478.7 インストールスクリプトでのサーバーの起動 . . . . . . . . . . . . . . . . . . . . . . . 478.8 Alpine Linuxで設定するときの追加セットアップ . . . . . . . . . . . . . . . . . . . . 488.9 K3d（Dockerで動く K3s）を docker-composeで動かす . . . . . . . . . . . . . . . . 49

付録 A FAQと既知の問題 51A.1 FAQ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51A.2 既知の問題 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51

6

第 1章

K3s - K8sとの 5つの違い

軽量 Kubernetes。簡単にインストールでき、メモリ使用量も半分、バイナリサイズも 50MB未満。

最適な用途

• Edge• IoT• CI• ARM

1.1 K3sとはどういうものかK3sは Kubernetesに完全に準拠したディストリビューションで次のような拡張が行われています。

• デフォルトのデータストアの etcd を組み込み型データベースの SQLite に置き換えました。PostgreSQL、MySQL、etcdなどの外部データストアもサポートしています。

• ローカルストレージプロバイダー、ロードバランサーサービス、Helm コントローラー、およびTraefikイングレスコントローラーなど、シンプルながら強力な機能が“組み込まれて”います。

• Kubernetesのコントロールプレーンが動くために必要なコンポーネントが、単一のバイナリとプロセスにカプセル化されています。これにより、証明書の配布などの複雑なクラスター操作を K3sでは簡単に管理、自動化できます。

• ソースコード内のクラウドプロバイダーとストレージプラグインは削除されました。• 外部環境への依存が必要最小限に抑えられています（必要なのは最新のカーネルと cgroupマウントです）。以下の依存しているパッケージが K3sに含まれています。

– containerd– Flannel– CoreDNS– ホストユーティリティー（iptables, socat, etc）

7

第 2章

アーキテクチャ

本項目では、HA 構成の K3s サーバークラスターのアーキテクチャとシングルノードのサーバークラスターとの違いについて説明します。また、エージェントノードが K3sサーバーに登録されるときの動作についても説明します。まず、サーバーノードを k3s serverコマンドを実行するマシン（ベアメタルや仮想マシン）と定義し

ます。ワーカーノードを、k3s agentコマンドを動かすマシンと定義します。以下のトピックについて取り上げます。

• 組み込み DBでのシングルサーバーのセットアップ• 外部データベースを使った HA構成の K3sサーバー

– エージェントノード用の登録用固定 IPアドレス• エージェントノードが登録されるときの動作

2.1 組み込み DBでのシングルサーバーのセットアップ次ページの図は、組み込み SQLiteデータベースを使ったシングルノードのK3sサーバーのクラスター

の例です。この構成では、各エージェントノードが同じ 1つのサーバーに登録されます。K3sのユーザーは、サーバーノード上で K3s APIを呼び出すことにより Kubernetesリソースを操作できます。

9

第 2章アーキテクチャ 2.2 外部データベースを使った HA構成の K3sサーバー

図 2.1: シングルノードのアーキテクチャ

2.2 外部データベースを使った HA構成の K3sサーバーシングルサーバーのクラスターでさまざまなユースケースに対応できますが、Kubernetes のコントロールプレーンの稼働時間が重要である場合、HA構成で K3sを実行できます。HA構成の K3sクラスターは次のもので構成されます。

• Kubernetes API サービスとその他のコントロールプレーンサービスが動く 2 つ以上のサーバーノード

• 外部のデータストア*1（データベース）

*1 シングルサーバーで使用される組み込み SQLite データベースではない。

10

第 2章アーキテクチャ 2.2 外部データベースを使った HA構成の K3sサーバー

図 2.2: クラスター構成のアーキテクチャ

エージェントノード用の登録用固定 IPアドレス

HA構成では次の図 2.3に示すとおり、各ノードが Kubernetes APIに登録するときに固定 IPアドレスが必要です。登録後、エージェントノードは固定 IP アドレス経由ではなくサーバーノードのひとつに直接接続します。

11

第 2章アーキテクチャ 2.3 エージェントノードが登録されるときの動作

図 2.3: K3s HA構成図

2.3 エージェントノードが登録されるときの動作エージェントノードは、k3s agentプロセスが開始したWebsocket接続によって登録され、エージェントプロセスの一部として実行されているクライアント側のロードバランサーにより接続が維持されます。エージェントは、ランダムに生成されたノード用のパスワードを/etc/rancher/node/passwordに保

存し、それをノードクラスターのシークレットとして使用してサーバーに登録します。サーバーにはノードごとの個別のパスワードが/var/lib/rancher/k3s/server/cred/node-passwd に保存されています。それ以降のノードからサーバーへの接続では、同じパスワードを使用する必要があります。エージェントの/etc/rancher/nodeディレクトリが削除された場合、エージェントのパスワードファ

イルを再作成するか、サーバーからエントリを削除する必要があります。--with-node-idフラグを使用して K3sサーバーまたはエージェントを起動することにより、ノード

ごとの一意のノード IDをホスト名に追加できます。

12

第 3章

クイックスタートガイド

本項目では、デフォルトオプションを使用してクラスターをすばやく起動する方法について説明します。K3sの設定方法については、第 4章「インストール」で詳しく説明しています。

K3sのそれぞれのコンポーネントがどのように連携するかについては、第 2章「アーキテクチャ」を参照してください。

Kubernetesについての理解が足りない場合、Kubernetesの基本的なことを概説した素晴らしい公式ドキュメント*1のチュートリアルを参照してください。

3.1 インストールスクリプトK3sには便利なインストールスクリプトがあり、それを使って systemdや openrcベースのシステム

にサービスとしてインストールできます。https://get.k3s.ioからこのスクリプトをダウンロードできます。インストールスクリプトを使って K3sをインストールする場合、次のように実行します。

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

インストール後

• ノードの再起動時、プロセスがクラッシュまたは強制終了した場合に自動的に K3s サービスが起動するようになります。

• kubectl、crictl、ctr、k3s-killall と k3s-uninstall.sh などのユーティリティがインストールされます。

• kubeconfig ファイルは/etc/rancher/k3s/k3s.yaml に保存され、K3s でインストールされたkubectlで自動的に利用されるようになります。

*1 https://kubernetes.io/docs/tutorials/kubernetes-basics/

13

第 3章クイックスタートガイド 3.1 インストールスクリプト

ワーカーノードに K3sをインストールして、クラスターに追加するには、K3S_URLおよび K3S_TOKENの環境変数を設定してインストールスクリプトを実行します。ワーカーノードを追加するコマンドは以下のとおりです。

curl -sfL https://get.k3s.io | K3S_URL=https://myserver:6443 K3S_TOKEN=mynodetoken sh -

K3S_URL パラメータが設定されていると、K3s がワーカーモードで実行されます。ワーカーモードのK3sエージェントは、指定された URLの K3sサーバーに登録されます。K3S_TOKENの値は、サーバーノードの/var/lib/rancher/k3s/server/node-tokenに格納されています。� �注意：各マシンのホスト名は一意である必要があります。マシンのホスト名が一意でない場合は、各ノードで一意のホスト名として有効な値を K3S_NODE_NAME環境変数に指定します。� �

14

第 4章

インストール

本項目では、さまざまな環境で K3sをインストールする手順について説明します。K3sをインストールする前に、「ノード要件」を満たしているかどうかを確認してください。「インストールオプション」の節では、K3sのインストール時に使用できるオプションについて説明します。「外部データベースを使った HA構成」では、MySQL、PostgreSQL、etcdなどの外部データストアを利用した HA構成の K3sクラスターのセットアップ方法について説明します。「組み込み DB（試験実装）による HA構成」では、組み込みの分散データベースを利用する HA構成の K3sクラスターのセットアップ方法について説明します。「インターネット隔離環境でのインストール」では、インターネットに直接アクセスできない環境で

K3sをセットアップする方法について説明します。

アンインストール

install.sh スクリプトを使って K3s をインストールした場合、インストール時にアンインストールスクリプトが同時に作成されます。アンインストールスクリプトは、ノードの/usr/local/bin/k3s-uninstall.sh（エージェントの場合は、k3s-agent-uninstall.sh）に作成されます。

4.1 ノード要件K3sは非常に軽量ですが、次に示すような最小限の必要要件がいくつかあります。K3s クラスターを単一ノード構成または HA 構成のいずれで構成する場合でも、K3s を実行する各ノードは次の最小要件を満たす必要があります。必要に応じて、より多くのリソースが必要になります。

前提条件

• ノードごとに別のホスト名である必要があります。すべてのノードが同じホスト名である場合は、各ノードをクラスターに追加するときに--node-nameオプションを指定するか、$K3S_NODE_NAMEに一意の名前を指定します。

15

第 4章インストール 4.1 ノード要件

オペレーティングシステム

K3sは基本的にどんな種類の Linuxでも動きますが、次のオペレーティングシステムとそのマイナーバージョンのリリースで K3sはテストされています。

• Ubuntu 16.04（AMD64）• Ubuntu 18.04（AMD64）• Raspbian Buster（armhf）

Alpine Linuxを利用する場合、追加作業（第 8章「構成設定と詳細オプション」の「Alpine Linuxで設定するときの追加セットアップ」）を実施してください。

ハードウェア要件

ハードウェア要件は、デプロイするサイズにより増減します。推奨最小構成は次のとおりです。

• RAM: 最小 512MB• CPU: 最低 1CPU

ディスクK3s のパフォーマンスは、データベースのパフォーマンスに依存します。最適なスピードを実現するには、可能な限り SSD を使用することをお勧めします。ARM デバイスで使われている SD カードやeMMCによってディスクのパフォーマンスは違ってきます。

ネットワーク

K3sサーバーは、ノード側の 6443ポートにアクセスできる必要があります。ノード同士は UDPポート 8472（Flannel VXLAN）を介してほかのノードに到達できる必要があります。Flannel を使用せずに独自の CNIを利用する場合は、8472ポートではないかもしれません。ノードでその他のポートがオープンしていてはいけません。K3sはリバーストンネリングを使用して、ノードがサーバーへのアウトバンド接続を行い、すべての kubeletトラフィックはそのトンネルを通過するようになっています。� �重要：ノードの VXLANポートが公開されていると、ネットワークを通してクラスターに誰でもアクセスできるようになるため、そのまま外部に公開しないでください。ファイアウォールやセキュリティグループで 8472番ポートへの接続を遮断した内側でノードを実行してください。� �メトリックサーバーを使用する場合は、各ノードで 10250ポートを開く必要があります。

16

第 4章インストール 4.2 インストールオプション

4.2 インストールオプション本項目では、K3sを最初にセットアップするときに使うオプションについて説明します。

• インストールスクリプトのオプション• K3sをバイナリでインストールする方法• K3sサーバー起動オプション• K3sエージェント起動オプション

より詳細なオプションについての内容は、第 8章「構成設定と詳細オプション」を参照してください。

インストールスクリプトのオプション

第 3章「クイックスタートガイド」に書かれているように、https://get.k3s.ioからダウンロードしたインストールスクリプトを利用すれば、systemdや openrcベースのシステムで K3sをサービスとしてインストールできます。シンプルに次のコマンドを実行します。


この方法で K3s をインストールする場合は、インストールオプションとして次の環境変数を指定できます。

INSTALL K3S SKIP DOWNLOADtrueに設定すると、K3sのハッシュまたはバイナリはダウンロードされません。

INSTALL K3S SYMLINKskipに設定するとシンボリックリンクを作成せず、forceでは上書きします。コマンドがパスに存在しない場合、通常はシンボリックリンクを作ります。

INSTALL K3S SKIP STARTtrueに設定すると、K3sサービスを開始しません。

INSTALL K3S VERSIONGitHub からダウンロードする K3s のバージョンを指定します。指定されていない場合は、最新バージョンをダウンロードします。

INSTALL K3S BIN DIRK3sバイナリ、リンク、およびアンインストールスクリプトをインストールするディレクトリを指定します。指定しない場合、デフォルトでは/usr/local/binになります。

INSTALL K3S BIN DIR READ ONLYtrueに設定すると、ファイルを INSTALL_K3S_BIN_DIRに書き込みません。強制的に INSTALL_K3S_SKIP_DOWNLOAD=trueに設定されます。

17


INSTALL K3S SYSTEMD DIRsystemd サービスおよび環境ファイルをインストールするディレクトリ。指定しない場合、通常は/etc/systemd/systemです。

INSTALL K3S EXECK3s がサービスで起動されるときに指定される起動コマンドとフラグです。コマンドが指定されていない場合、K3S_URLが設定されていれば“agent”として起動し、設定されていなければ“server”で動くようにデフォルトでセットされます。最終的に systemdでのコマンドは、この環境変数とスクリプト引数の組み合わせを統合します。つまり、次のコマンドはすべて Flannelを除外した起動オプションをサーバーに登録するという同じ動作になります。

curl ... | INSTALL_K3S_EXEC="--no-flannel" sh -s -curl ... | INSTALL_K3S_EXEC="server --no-flannel" sh -s -curl ... | INSTALL_K3S_EXEC="server" sh -s - --no-flannelcurl ... | sh -s - server --no-flannelcurl ... | sh -s - --no-flannel}

INSTALL K3S NAMEsystemd に登録されるときのサービス名を指定します。指定しない場合は、K3s 実行コマンドがデフォルトで設定されます。指定すると、その名前の先頭に“k3s-”が付きます。

INSTALL K3S TYPEsystemd に登録されるサービスのタイプ。指定しない場合は、K3s 実行コマンドがデフォルトで設定されます。

K3S_で始まる環境変数は、systemdおよび openrcサービスにより設定されます。K3S_URLが起動時に明示的に設定されていないと、デフォルトでは“agent”として起動します。このエージェントとして実行するときには、K3S_TOKENも設定する必要があります。

K3sをバイナリでインストールする方法

前述のように、インストールスクリプトは基本的に K3sをサービスとして起動するように設定します。このスクリプトを使用しない場合は、リリースページからバイナリのみダウンロードし、パスに配置して実行するだけで K3sを起動できます。K3sバイナリは、次のコマンドオプションをサポートしています。

18


表 4.1: K3sバイナリがサポートするコマンド

コマンドオプション詳細k3s server K3s マネージメントサーバーを起動します。このサーバーは、API サーバー、コントロー

ラーマネージャー、スケジューラなどの Kubernetesコントロールプレーンコンポーネントが起動されます。

k3s agent K3sノードエージェントを起動します。これにより、K3sはワーカーノードとして動作し、kubeletと kube-proxyの Kubernetesノードのサービスが起動されます。

k3s kubectl 組み込みの kubectl CLIを実行します。K3sサーバーノードで実行するときに KUBECONFIG 環境変数が設定されていないと、/etc/rancher/k3s/k3s.yamlに作成された設定ファイルを自動的に参照します。

k3s crictl 組み込みの crictl を実行します。これは Kubernetes のコンテナランタイムインターフェース（CRI）とやりとりするための CLIです。デバッグに便利です。

k3s ctr 組み込みの ctr を実行します。これは、K3s が使用するコンテナデーモン containerd のCLIです。デバッグに便利です。

k3s help コマンドの一覧または 1つのコマンドのヘルプを表示します。

k3s server および k3s agent コマンドのその他の設定オプションは、k3s server --help またはk3s agent --helpで見られます。ヘルプテキストを掲載します。

K3sサーバー起動オプション

NAME:k3s server - Run management server

USAGE:k3s server [OPTIONS]

OPTIONS:-v value (logging) Number for the log level verbosity (

default: 0)--vmodule value (logging) Comma-separated list of pattern=N se

ttings for file-filtered logging--log value, -l value (logging) Log to file--alsologtostderr (logging) Log to standard error as well as fil

e (if set)--bind-address value (listener) k3s bind address (default: 0.0.0.0)--https-listen-port value (listener) HTTPS listen port (default: 6443)--advertise-address value (listener) IP address that apiserver uses to a

dvertise to members of the cluster (default: node-external-ip/node-ip)

--advertise-port value (listener) Port that apiserver uses to advertise to members of the cluster (default: listen-

19


port) (default: 0)--tls-san value (listener) Add additional hostname or IP as a

Subject Alternative Name in the TLS cert--data-dir value, -d value (data) Folder to hold state default /var/lib/r

ancher/k3s or ${HOME}/.rancher/k3s if not root--cluster-cidr value (networking) Network CIDR to use for pod IPs (

default: "10.42.0.0/16")--service-cidr value (networking) Network CIDR to use for services

IPs (default: "10.43.0.0/16")--cluster-dns value (networking) Cluster IP for coredns service. S

hould be in your service-cidr range (default:10.43.0.10)

--cluster-domain value (networking) Cluster Domain (default: "cluster.local")

--flannel-backend value (networking) One of ’none’, ’vxlan’, ’ipsec’,or ’flannel’ (default: "vxlan")

--token value, -t value (cluster) Shared secret used to join a serveror agent to a cluster [$K3S_TOKEN]

--token-file value (cluster) File containing the cluster-secret/token [$K3S_TOKEN_FILE]

--write-kubeconfig value, -o value (client) Write kubeconfig for admin client tothis file [$K3S_KUBECONFIG_OUTPUT]

--write-kubeconfig-mode value (client) Write kubeconfig with this mode [$K3S_KUBECONFIG_MODE]

--kube-apiserver-arg value (flags) Customized flag for kube-apiserver process

--kube-scheduler-arg value (flags) Customized flag for kube-scheduler process

--kube-controller-manager-arg value (flags) Customized flag for kube-controller-manager process

--kube-cloud-controller-manager-arg value (flags) Customized flag for kube-cloud-controller-manager process

--datastore-endpoint value (db) Specify etcd, Mysql, Postgres, or Sqlite(default) data source name [$K3S_DATASTORE_ENDPOINT]

--datastore-cafile value (db) TLS Certificate Authority file used to secure datastore backend communication [$K3S_DATASTORE_CAFILE]

--datastore-certfile value (db) TLS certification file used to secure datastore backend communication [$K3S_DATASTORE_CERTFILE]

--datastore-keyfile value (db) TLS key file used to secure datastore backend communication [$K3S_DATASTORE_KEYFILE]

--default-local-storage-path value (storage) Default local storage path for localprovisioner storage class

--no-deploy value (components) Do not deploy packaged components(valid items: coredns, servicelb, traefik, lo

cal-storage, metrics-server)--disable-scheduler (components) Disable Kubernetes default schedu

ler

20


--disable-cloud-controller (components) Disable k3s default cloud controller manager

--disable-network-policy (components) Disable k3s default network policy controller

--node-name value (agent/node) Node name [$K3S_NODE_NAME]--with-node-id (agent/node) Append id to node name--node-label value (agent/node) Registering kubelet with set of l

abels--node-taint value (agent/node) Registering kubelet with set of t

aints--docker (agent/runtime) Use docker instead of containe

rd--container-runtime-endpoint value (agent/runtime) Disable embedded containerd an

d use alternative CRI implementation--pause-image value (agent/runtime) Customized pause image for con

tainerd sandbox--private-registry value (agent/runtime) Private registry configuration

file (default: "/etc/rancher/k3s/registries.yaml")

--node-ip value, -i value (agent/networking) IP address to advertise fornode

--node-external-ip value (agent/networking) External IP address to advertise for node

--resolv-conf value (agent/networking) Kubelet resolv.conf file [$K3S_RESOLV_CONF]

--flannel-iface value (agent/networking) Override default flannel interface

--flannel-conf value (agent/networking) Override default flannel config file

--kubelet-arg value (agent/flags) Customized flag for kubelet process

--kube-proxy-arg value (agent/flags) Customized flag for kube-proxy process

--rootless (experimental) Run rootless--agent-token value (experimental/cluster) Shared secret used to j

oin agents to the cluster, but not servers [$K3S_AGENT_TOKEN]

--agent-token-file value (experimental/cluster) File containing the agent secret [$K3S_AGENT_TOKEN_FILE]

--server value, -s value (experimental/cluster) Server to connect to, used to join a cluster [$K3S_URL]

--cluster-init (experimental/cluster) Initialize new clustermaster [$K3S_CLUSTER_INIT]

--cluster-reset (experimental/cluster) Forget all peers and become a single cluster new cluster master [$K3S_CLUSTER_RESET]

--no-flannel (deprecated) use --flannel-backend=none--cluster-secret value (deprecated) use --token [$K3S_CLUSTER_SECRET]

21


K3sエージェント起動オプション

NAME:k3s agent - Run node agent

USAGE:k3s agent [OPTIONS]

OPTIONS:-v value (logging) Number for the log level verbosity (default

: 0)--vmodule value (logging) Comma-separated list of pattern=N settings

for file-filtered logging--log value, -l value (logging) Log to file--alsologtostderr (logging) Log to standard error as well as file (if s

et)--token value, -t value (cluster) Token to use for authentication [$K3S_TOKEN]--token-file value (cluster) Token file to use for authentication [$K3S_

TOKEN_FILE]--server value, -s value (cluster) Server to connect to [$K3S_URL]--data-dir value, -d value (agent/data) Folder to hold state (default: "/var/lib

/rancher/k3s")--node-name value (agent/node) Node name [$K3S_NODE_NAME]--with-node-id (agent/node) Append id to node name--node-label value (agent/node) Registering kubelet with set of labels--node-taint value (agent/node) Registering kubelet with set of taints--docker (agent/runtime) Use docker instead of containerd--container-runtime-endpoint value (agent/runtime) Disable embedded containerd and use a

lternative CRI implementation--pause-image value (agent/runtime) Customized pause image for containerd

sandbox--private-registry value (agent/runtime) Private registry configuration file (

default: "/etc/rancher/k3s/registries.yaml")--node-ip value, -i value (agent/networking) IP address to advertise f

or node--node-external-ip value (agent/networking) External IP address to advertise f

or node--resolv-conf value (agent/networking) Kubelet resolv.conf file [$K3S_RES

OLV_CONF]--flannel-iface value (agent/networking) Override default flannel interface--flannel-conf value (agent/networking) Override default flannel config fi

le--kubelet-arg value (agent/flags) Customized flag for kubelet process--kube-proxy-arg value (agent/flags) Customized flag for kube-proxy process--rootless (experimental) Run rootless--no-flannel (deprecated) use --flannel-backend=none--cluster-secret value (deprecated) use --token [$K3S_CLUSTER_SECRET]

22

第 4章インストール 4.3 ネットワークオプション

エージェントノードに付与するノードラベルと taintK3sエージェントには、kubeletにノードラベルと taintを追加するオプション--node-labelと--n

ode-taintがあります。この 2つのオプションは、ノードラベルまたは taint（あるいはその両方）を起動時に追加するのみで、K3sを起動してラベルを追加したあとは変更できません。次の例は、ラベルと taintを追加する方法です。

--node-label foo=bar \--node-label hello=world \--node-taint key1=value1:NoExecute

ノードの登録後にノードのラベルや taintを変更したい場合は kubectlを使う必要があります。taintsを追加する方法*1やノードラベルの変更*2は Kubernetesの公式ドキュメントを参照してください。

4.3 ネットワークオプション

� �注意：CoreDNS、Traefik、およびサービスロードバランサーについては、第 7章「ネットワーク」を参照してください。� �K3sはデフォルトで CNIとして Flannelを使用し、バックエンドとしてデフォルトで VXLANを使用します。CNIを変更するには、「カスタム CNI」の項を参照してください。Flannelバックエンドを変更するには、次の「Flannelオプション」の項を参照してください。

Flannelオプション

Flannel のデフォルトのバックエンドは VXLAN です。暗号化を有効にするには、IPSec（インターネットプロトコルセキュリティ）を利用するか、または以下のWireGuardオプションを使用します。

Flannel のバックエンドとして WireGuard を使う場合、追加のカーネルモジュールが必要になります。詳しくは「WireGuard インストールガイド」*3をご覧ください。WireGuard のインストールガイドで、利用中のオペレーティングシステムに対応したカーネルモジュールがインストールされます。WireGuardと Flannelのバックエンドオプションを利用する前に、サーバーとエージェントの両方のすべてのノードにWireGuardをインストールする必要があります。

*1 https://kubernetes.io/docs/concepts/configuration/taint-and-toleration/*2 https://kubernetes.io/docs/tasks/configure-pod-container/assign-pods-nodes/#add-a-label-to-a-node*3 https://www.wireguard.com/install/

23

第 4章インストール 4.3 ネットワークオプション

表 4.2: Flannelオプション

CLIフラグと値詳細--flannel-backend=vxlan VXLANをバックエンドとして使用（デフォルト）--flannel-backend=ipsec ネットワークトラフィックを暗号化する IPsecバックエンドを使用--flannel-backend=wireguard ネットワークトラフィックを暗号化するWireGuardバックエンドを使用。

追加のカーネルモジュールと設定が必要になります。

カスタム CNI

--flannel-backend=none を指定して K3sを実行し、希望の CNIをインストールします。CanalとCalicoでは IP Forwardingを有効にする必要があります。次の手順を参照してください。

Canalを利用する場合「プロジェクト Calico」*4のドキュメントを参照してください。Canal をインストールするには以下の手順に従います。container_settings セクションで IP フォワードができるように Canal YAML を変更します。次に例を示します。

"container_settings": {"allow_ip_forwarding": true

}

Canal YAMLを適用します。ホストで次のコマンドを実行して、設定が適用されていることを確認します。

cat /etc/cni/net.d/10-canal.conflist

IP forwardingが trueに設定されていることを確認します。

Calicoを利用する場合「Calico CNI プラグインガイド」*5に従ってください。container_settings セクションで IP フォワードができるように Calico YAMLを変更します。次に例を示します。

*4 https://docs.projectcalico.org/*5 https://docs.projectcalico.org/master/reference/cni-plugin/configuration

24

第 4章インストール 4.4 外部データベースを使った HA構成

"container_settings": {"allow_ip_forwarding": true

}

Calico YAMLを適用します。ホストで次のコマンドを実行して、設定が適用されていることを確認します。

cat /etc/cni/net.d/10-calico.conflist

IP forwardingが trueに設定されていることを確認します。

4.4 外部データベースを使った HA構成

� �注意：HA構成は、リリース v1.0.0で公式にサポートされました。� �本項目では、外部データベースを利用した HA構成の K3sクラスターのインストール方法について解

説します。シングルサーバーのクラスターはさまざまなユースケースに対応できますが、Kubernetesコントロールプレーンの稼働率が重要な環境では、HA構成で K3sを実行します。HAの K3sクラスターは、次のコンポーネントで構成されています。

• Kubernetes API サービスとその他のコントロールプレーンサービスが動く 2 つ以上のサーバーノード

• 外部のデータストア*6（データベース）• ワーカーノードをクラスターに登録できるようにサーバーノードのフロントには登録用の固定 IPアドレスがあること

これらのコンポーネントがどのように連携しているかは、第 2 章「アーキテクチャ」を参照してください。ワーカーは登録用の固定 IPアドレスを使用して登録されますが、登録後はサーバーノードのひとつに直接接続します。これは、 k3s agent プロセスによって開始されるWebソケット接続で、エージェントプロセスの一部として実行されているクライアント側のロードバランサーによって維持されます。

*6 シングルサーバーで使用される組み込み SQLite データベースではない。

25

第 4章インストール 4.4 外部データベースを使った HA構成

インストールの概要

HAクラスターをセットアップするには、次の手順で実行します。

1. 外部データストアの作成2. サーバーノードの起動3. 登録用の固定 IPアドレスを設定4. ワーカーノードを追加

1. 外部データストアの作成最初に、クラスターの外部データストアを作成する必要があります。詳細については、「クラスターデータストアオプション」の項を参照してください。

2. サーバーノードの起動HA構成の K3sでは、2つ以上のサーバーノードが必要です。ノードの最小要件については、「ノード要件」の項を参照してください。

k3s serverコマンドを実行するノードは、K3sが外部データストアへの接続方法を識別できるようにdatastore-endpointパラメータを設定する必要があります。このパラメータの構成については、「外部データストア構成パラメータ」の項を参照してください。� �注意：HA構成のインストールでも、シングルサーバーのインストールと同じインストールオプションを利用します。インストールオプションの詳細については、「4.2 インストールオプション」の節を参照してください。� �デフォルトでは、サーバーノードにユーザーのワークロードをスケジューリングできる設定のため、そ

の上でワークロードを動かせます。ユーザーのワークロードを実行しない専用のコントロールプレーンにしたい場合は、taintを指定してください。--node-taintオプションパラメータを使用するとノードをtaintに設定できます。例えば、 --node-taint k3s-controlplane=true:NoExecuteのように設定します。すべてのサーバーノードで k3s server プロセスを起動したら、k3s kubectl get nodes を使用し

て、ノードを確認します。すべてのノードがレディ（ready）になっていればクラスターが正しく起動しています。

3. 登録の固定 IPアドレスを設定ワーカーノードを動かすときに登録するため、サーバー URLが必要です。サーバーノードの IPまた

は任意のホスト名を指定できますが、これらは時間の経過とともに変わることがよくあります。たとえば、スケールアウトをできるクラウド上でクラスターを実行している場合、時間の経過とともにサーバー

26

第 4章インストール 4.5 組み込み DB（試験実装）による HA構成

のノードグループが拡大または縮小されると、ノードが作成されたり破棄されるため、サーバーノードの初期セットアップ時とは異なる IPアドレスを持つことになります。したがって、サーバーノードのフロントには、時間が経っても変化しない安定したエンドポイントが必要です。このようなエンドポイントを構成する方法には、次のような方法があります。

• L4（TCP）ロードバランサー• ラウンドロビン DNS• 仮想 IPアドレスまたは Elastic IPアドレス

このエンドポイントは、Kubernetes APIへのアクセスにも使用できます。例えば、これにより kubeconfigファイル*7の接続先を特定のノードではなくエンドポイントを指すように変更できます。

4. ワーカーノードを追加シングルサーバークラスターのワーカーノードと同じように、HA構成クラスターにワーカーノードを

追加します。登録する URLとクラスターのトークンをエージェントに指定します。

K3S_TOKEN=SECRET k3s agent --server https://fixed-registration-address:6443

4.5 組み込み DB（試験実装）による HA構成v1.0.0 から、K3s で外部データベースを使用しない HA 構成のコントロールプレーンを試験的にサ

ポートしています。つまり信頼性の必要な本番レベルの環境を構築するために、外部 etcd や SQL データストアの管理は必要ありません。この機能は現在試験的なものですが、将来的には HA構成の K3sクラスターを動かすための主要なアーキテクチャになると考えています。このアーキテクチャでは、K3s サーバープロセスに組み込まれている DQLite データベースを使用し

ます。DQLiteは“分散 SQLite”の略で、https://dqlite.ioによると“IoTデバイスや Edgeデバイスを堅牢にするのに最適な Raft のコンセンサスによる高速で組み込み型の永続的 SQL データベース”です。K3sでの利用に適しています。このモードで K3sを実行するには、奇数のサーバーノードが必要です。3つのノードから開始することをお勧めします。まず、クラスター化を有効にする cluster-init フラグを付け、サーバーをクラスターに追加すると

きの共有シークレットキーとして必要なトークンを定義した状態でサーバーノードを起動します。

K3S_TOKEN=SECRET k3s server --cluster-init

*7 https://kubernetes.io/docs/concepts/configuration/organize-cluster-access-kubeconfig/

27

第 4章インストール 4.6 クラスターデータストアオプション

最初のサーバーを起動したあと、共有シークレットキーを使用して 2 番目と 3 番目のサーバーをクラスターに参加させます。

K3S_TOKEN=SECRET k3s server --server https://<1台目のサーバーのIPアドレスかホスト名>:6443

これで、高可用性のコントロールプレーンができました。あとは単一サーバークラスターと同じ手順でワーカーノードをクラスターに追加します。

4.6 クラスターデータストアオプションほかの Kubernetesディストリビューションと K3sが大きく違うところは、etcd以外のデータストアを使って Kubernetes を実行する機能です。この機能により Kubernetes の柔軟な運用ができるようになりました。さまざまなデータストアを使えることによりユースケースに最適なデータストアを選ぶことができます。例を挙げると、

• チームに etcdの操作に関する専門知識がない場合は、MySQLや PostgreSQLなどのエンタープライズグレードの SQLデータベースを利用できます。

• CI/CD 環境でシンプルな生存期間の短いクラスターを実行する必要がある場合は、組み込みSQLiteデータベースを使用できます。

• エッジ環境に Kubernetesをデプロイし、高可用性ソリューションを必要としているが、エッジでデータベースを管理する運用上のオーバーヘッドを許容できない場合、DQLiteで構築された K3sの組み込み HAデータストアを使用できます（現在、試験実装）。

K3sは、オプションとして以下のデータストアをサポートします。

• 組み込み SQLite*8

• PostgreSQL*9（認定されているバージョンは 10.7および 11.5）• MySQL*10（認定されているバージョンは 5.7）• etcd*11（認定されているバージョンは 3.3.15）• HA構成組み込み DQLite*12（試験実装）

*8 https://www.sqlite.org/index.html*9 https://www.postgresql.org/

*10 https://www.mysql.com/*11 https://etcd.io/*12 https://dqlite.io/

28


外部データストア構成パラメータ

PostgreSQL、MySQL、etcdなどの外部データストアを使用する場合は、K3sが接続方法を識別できるように datastore-endpoint パラメータを設定する必要があります。パラメータを指定して、接続ときの認証と暗号化をすることもできます。次の表は、CLIフラグまたは環境変数として渡すことができるパラメータをまとめたものです。

表 4.3: 外部データストア構成パラメータ

CLI フラグ環境変数詳細--datastore-endpoint K3S_DATASTORE_ENDPOINT PostgresSQL、MySQL、または etcd接続文字列

を指定します。これは、データストアへの接続を記述するために使用される文字列です。この文字列の構造は各バックエンドに固有で、詳細については次項に示します。

--datastore-cafile K3S_DATASTORE_CAFILE データストアとのセキュリティ保護に役立つ TLSCertificate Authority(CA)ファイル。データストアが、カスタム認証局によって署名された証明書を使用して TLS 経由で要求を処理する場合、K3s クライアントが証明書を正しく検証できるように、このパラメータを使用して CA を指定できます。

--datastore-certfile K3S_DATASTORE_CERTFILE データストアへのクライアント証明書認証に使用される TLS 証明書ファイル。この機能を使用するには、クライアント証明書認証をサポートするようにデータストアを構成する必要があります。このパラメータを指定する場合は、datastore-keyfileパラメータも指定する必要があります。

--datastore-keyfile K3S_DATASTORE_KEYFILE データストアへのクライアント証明書認証に使用される TLSキーファイル。詳細については、前述の datastore-certfile パラメータを参照してください。

データベース資格情報やその他の機密情報がプロセス情報の一部として公開されないように、これらのパラメータをコマンドライン引数ではなく環境変数として設定することをお勧めします。

データストアのエンドポイントの形式と機能

前述のように、datastore-endpoint パラメータに渡される値の形式は、データストアバックエンドにより違います。次に、それぞれサポートされている外部データストアの形式と機能の詳細を示します。

29


PostgreSQLPostgreSQLの datastore-endpointパラメータの最も一般的な形式は次のとおりです。

postgres://username:password@hostname:port/database-name

さらに高度な設定パラメータを使用できます。詳細については、https://godoc.org/github.com/lib/pqを参照してください。指定したデータベース名が存在しない場合、サーバーはそのデータベースを作成しようとします。エンドポイントとして postgres:// のみを指定すると、K3sは以下のことを実行しようとします。

• ユーザー名とパスワードに“postgres”を使用して localhostに接続します。• kubernetes という名前のデータベースを作成します。

MySQLMySQLの datastore-endpointパラメータの最も一般的な形式は以下のとおりです。

mysql://username:password@tcp(hostname:3306)/database-name

さらに高度な設定パラメータを使用できます。詳細については、https://github.com/go-sql-driver/mysql#dsn-data-source-nameを参照してください。

K3sの既知の問題のため、tlsパラメータを指定できません。これにより、TLSとの通信はサポートされますが、このパラメータに“skip-verify”を設定して、K3sで証明書の検証をスキップするといったことができません。指定したデータベース名が存在しない場合、サーバーはそのデータベースを作成しようとします。エンドポイントとして mysql://のみを指定すると、K3sは以下のことを実行しようとします。

• MySQL ソケット/var/run/mysqld/mysqld.sock に接続します。root ユーザーを使用し、パスワードを使用しません。

• kubernetes という名前のデータベースを作成します。

etcdetcdの datastore-endpointパラメータの最も一般的な形式は以下のとおりです。

https://etcd-host-1:2379,https://etcd-host-2:2379,https://etcd-host-3:2379

上記は、典型的な 3ノードの etcdクラスターを想定しています。パラメータには、1つ以上のカンマ区切りの etcd URLを指定できます。　これらを踏まえて、次のようなコマンドを使用すると k3sという名前の PostgresSQLデータベースに接続するサーバーインスタンスを起動することができます。

30

第 4章インストール 4.7 インターネット隔離環境でのインストール

K3S_DATASTORE_ENDPOINT=’postgres://username:password@hostname:5432/k3s’ k3s server

次の例ではクライアント証明書を使用してMySQLデータベースに接続します。

K3S_DATASTORE_ENDPOINT=’mysql://username:password@tcp(hostname:3306)/k3s’ \K3S_DATASTORE_CERTFILE=’/path/to/client.crt’ \K3S_DATASTORE_KEYFILE=’/path/to/client.key’ \k3s server

HA構成組み込み DQLite（試験実装）

K3s で利用される DQLite の使い方は SQLite と似ています。セットアップと操作方法は簡単です。そのため、このオプションを使用するための外部設定や追加手順は不要です。このオプションを使用してを実行する方法については、「組み込み DB（試験実装）による HA構成」の項を参照してください。

4.7 インターネット隔離環境でのインストールこの章ではインターネットに接続されていない環境にノードがあり、インターネットに接続している

踏み台サーバー上にセキュアな Docker プライベートレジストリが用意されていることを前提としています。

インストールの概要

1. イメージディレクトリの準備2. レジストリ YAMLの作成3. K3sのインストール

イメージディレクトリの準備実行したいバージョンの K3sのリリースページ*13から、利用するアーキテクチャのイメージ tarファイルを入手します。

K3s を起動する前に、各ノードの images ディレクトリに tar ファイルを配置します。次の例のようにします。

*13 https://github.com/rancher/k3s/releases

31


sudo mkdir -p /var/lib/rancher/k3s/agent/images/sudo cp ./k3s-airgap-images-$ARCH.tar /var/lib/rancher/k3s/agent/images/

レジストリ YAMLの作成registries.yamlファイルを/etc/rancher/k3s/registries.yamlに作成します。ここに K3sが

プライベートレジストリに接続するための必要な詳細情報を設定します。接続する前に必要な情報の registries.yamlファイルは次のようになります。

------mirrors:

customreg:endpoint:

- "https://ip-to-server:5000"configs:

customreg:auth:

username: xxxxxx # this is the registry usernamepassword: xxxxxx # this is the registry password

tls:cert_file: <path to the cert file used in the registry>key_file: <path to the key file used in the registry>ca_file: <path to the ca file used in the registry>

� �注意：現時点では、セキュアレジストリ（独自 CAの SSL）のみ K3sでサポートします。� �

K3sのインストールリリースページからインターネットに接続されていない環境用としてダウンロードした tar と同じ

バージョンの K3sバイナリを取得します。同じように https://get.k3s.ioから K3sインストールスクリプトをダウンロードします。バイナリをそれぞれのノードの/usr/local/bin に配置します。インストールスクリプトをそれぞれ

のノードに配置して、ファイル名を install.shにします。各サーバーに K3sをインストールします。

32


INSTALL_K3S_SKIP_DOWNLOAD=true ./install.sh

それぞれエージェントをインストールします。

INSTALL_K3S_SKIP_DOWNLOAD=true \K3S_URL=https://myserver:6443 K3S_TOKEN=mynodetoken ./install.sh

注意点は、myserver をサーバーの IP または有効な DNS に置き換えること、mynodetoken をサーバーからのノードトークンに置き換えることです。サーバーのノードトークンは、/var/lib/rancher/k3s/server/node-tokenに保存されています。� �注意: K3s には kubelets のために--resolv-conf フラグも用意しています。これを使うとインターネットに接続されていない環境で DNSを設定するのに便利です。� �

アップグレードインターネットに接続されていない環境の場合、以下の方法でアップグレードします。

1. リリースページから、アップグレードしたいバージョンの K3s のインターネットに接続されていない環境用イメージ（tarファイル）をダウンロードします。すべてのノードの/var/lib/rancher/k3s/agent/images/に保存して、古い tarファイルは削除します。

2. すべてのノードの/usr/local/binにある古い K3sバイナリをコピーして置き換えて、https://get.k3s.ioから（できるだけ新しい最新の）インストールスクリプトをダウンロードして上書きします。そうして、旧環境と同じ環境変数をインストール時に指定した状態で、スクリプトを再度実行してください。

3. K3sサービスを再起動（インストーラーで再起動しなかった場合）してください。

33

第 5章

アップグレード

インストールスクリプトで K3s をアップグレードすることができます。もしくは、指定のバージョンのバイナリを手動でインストールすることもできます。� �注意：アップグレード時には、まずサーバーノードをひとつずつアップグレードしてから、ワーカーノードをアップグレードします。� �5.1 インストールスクリプトでアップグレードする

K3sを古いバージョンからアップグレードするには、同じフラグを使用してインストールスクリプトを再実行します。次に例を示します。


特定のバージョンにアップグレードする場合は、次のようにコマンドを実行します。

curl -sfL https://get.k3s.io | INSTALL_K3S_VERSION=vX.Y.Z-rc1 sh -

5.2 バイナリを使って手動でアップグレードするまたは、K3sを手動でアップグレードします。

35

第 5章アップグレード 5.3 K3sの再起動

1. 必要なバージョンの K3sをリリースページ*1からダウンロードします。2. 適切な場所にインストールします（通常は /usr/local/bin/k3s）。3. 古いバージョンを停止4. 新しいバージョンを起動

5.3 K3sの再起動K3sを再起動する方法は、インストールスクリプトにより systemdや openrcに設定されています。s

ystemdの場合、手動で再起動するには、次のコマンドを使用します。

sudo systemctl restart k3s

openrcの場合、手動で再起動するには、次のコマンドを使用します。

sudo service k3s restart

*1 https://github.com/rancher/k3s/releases

36

第 6章

ボリュームとストレージ

データを保持するアプリケーションを導入する場合は、永続ストレージを作成する必要があります。永続ストレージを使用すると、アプリケーションを実行する Pod の外部にアプリケーションのデータを格納できます。アプリケーションの Podに障害が発生した場合でも、永続ストレージを使用してアプリケーションのデータが維持されます。パーシステントボリューム（PV）は、Kubernetesクラスターで使用するストレージのひとつで、パー

システントボリュームクレームのリクエストによりストレージから切り出されるものです。PVと PVCがどのような挙動をするかについて、詳しくは公式の Kubernetesのストレージのドキュメント*1を参照してください。こちらのページでは、ローカルストレージプロバイダーか、Longhorn を使ってパーシステントスト

レージをセットアップする方法を解説します。

6.1 ローカルストレージプロバイダーK3sには Rancherの Local Path Provisionerが付属していて、最初から各ノードのローカルストレー

ジを使用して永続ボリュームクレームを作成できるようになっています。以下に簡単な例を示します。詳細については、公式ドキュメントを参照してください。まず、hostPathによってバックアップされた永続ボリュームクレームとそれを使用する Podを作成し

ます。

pvc.yaml

apiVersion: v1kind: PersistentVolumeClaimmetadata:

name: local-path-pvcnamespace: default

spec:accessModes:

*1 https://kubernetes.io/docs/concepts/storage/volumes/

37

第 6章ボリュームとストレージ 6.1 ローカルストレージプロバイダー

- ReadWriteOncestorageClassName: local-pathresources:

requests:storage: 2Gi

pod.yaml

apiVersion: v1kind: Podmetadata:

name: volume-testnamespace: default

spec:containers:- name: volume-test

image: nginx:stable-alpineimagePullPolicy: IfNotPresentvolumeMounts:- name: volv

mountPath: /dataports:- containerPort: 80

volumes:- name: volv

persistentVolumeClaim:claimName: local-path-pvc

yamlファイルを適用します。

kubectl create -f pvc.yamlkubectl create -f pod.yaml

PV と PVC が作られたのを確認します。

kubectl get pvkubectl get pvc

それぞれステータスが、Boundになっているか確認してください。

38

第 6章ボリュームとストレージ 6.2 Longhornをセットアップする

6.2 Longhornをセットアップする

� �注意：現時点では、Longhornは AMD64のみをサポートしています。� �K3sは Longhorn（https://github.com/longhorn/longhorn）をサポートします。Longhornは、

Kubernetes向けのオープンソース分散ブロックストレージです。以下に簡単な例を示します。詳細については、公式ドキュメント*2を参照してください。longhorn.yamlを適用して Longhornをインストールします。

kubectl apply \-f https://raw.githubusercontent.com/longhorn/longhorn/master/deploy/longhorn.yaml

Longhornは longhorn-system という名前空間にインストールされます。PVCを作成する前に、この yamlを使用して Longhorn用のストレージクラスを作成します。

kubectl create \-f https://raw.githubusercontent.com/longhorn/longhorn/master/examples/storageclass.yaml

yamlを適用して PVCと Podを作成します。

kubectl create -f pvc.yamlkubectl create -f pod.yaml

pvc.yaml

apiVersion: v1kind: PersistentVolumeClaimmetadata:

name: longhorn-volv-pvc

*2 https://github.com/longhorn/longhorn/blob/master/README.md

39

第 6章ボリュームとストレージ 6.2 Longhornをセットアップする

spec:accessModes:

- ReadWriteOncestorageClassName: longhornresources:

requests:storage: 2Gi

pod.yaml

apiVersion: v1kind: Podmetadata:

name: volume-testnamespace: default

spec:containers:- name: volume-test

image: nginx:stable-alpineimagePullPolicy: IfNotPresentvolumeMounts:- name: volv

mountPath: /dataports:- containerPort: 80

volumes:- name: volv

persistentVolumeClaim:claimName: longhorn-volv-pvc

PVと PVCが作成されていることを確認します。

kubectl get pvkubectl get pvc

それぞれステータスが、Boundになっているか確認してください。

40

第 7章

ネットワーク

� �注意：CNIオプションの詳細については、第 4章「インストール」の「ネットワークオプション」の節を参照してください。Flannel とさまざまな Flannel バックエンドオプションの詳細や、独自のCNIの設定方法についても同章を参照してください。� �7.1 オープンポートポート情報については、第 4章「インストール」の「ノード要件」の節を参照してください。

7.2 CoreDNSCoreDNSはエージェントの起動時にデプロイされます。無効にする場合は、--no-deploy coredns

オプションを付けて実行します。CoreDNSをインストールしない場合は、クラスターに DNSプロバイダーを自分でインストールする

必要があります。

7.3 Traefik イングレスコントローラーTraefik*1は簡単にマイクロサービスをデプロイすることができるロードバランサーでモダンな HTTP

リバースプロキシーです。これによりアプリケーションの設計、導入、および実行時のネットワークの複雑さが軽減されます。

Traefikは、サーバーの起動時にデフォルトでデプロイされます。詳細については、第 8章「構成設定と詳細オプション」の「マニフェストの自動配布」の節を参照してください。デフォルトの設定ファイルは /var/lib/rancher/k3s/server/manifests/traefik.yaml にあります。このファイルに加えられ

*1 https://traefik.io/

41

第 7章ネットワーク 7.4 サービスロードバランサー

た変更は kubectl apply と同じように自動的に Kubernetesに展開されます。Traefikイングレスコントローラーは、ホストのポート 80、ポート 443およびポート 8080を使用します（つまり、このポートは HostPortまたは NodePortでは使用できません）。用途に応じて、traefik.yamlファイルにオプションを設定することで traefikを調整できます。詳細

については、公式の Traefikの Helm設定パラメータ*2の readmeを参照してください。これを無効にするには、--no-deploy traefikオプションを指定して各サーバーを起動します。

7.4 サービスロードバランサーK3s には、利用可能な hostPort を使用する基本的なサービスロードバランサーが組み込まれていま

す。例えば、80ポートでリッスンするロードバランサーを作成しようとすると、クラスター内で 80ポートが空いているホストを見つけようとします。使用可能なポートがない場合、ロードバランサーは保留中になります。組み込みロードバランサーを無効にするには、--no-deploy servicelb オプションを指定してサー

バーを起動します。MetalLBなどの別のロードバランサーを実行する場合に使用してください。

*2 https://github.com/helm/charts/tree/master/stable/traefik#configuration

42

第 8章

構成設定と詳細オプション

本項目では、K3sを実行および管理するさまざまな方法について詳しく説明します。

• マニフェストの自動配布• Helm CRDを利用する• kubectlを使って外部からクラスターへアクセスする• コンテナランタイムに Dockerを使用する• RootlessKitで K3sを動かす（試験実装）• ノードのラベルと taint• インストールスクリプトでのサーバーの起動• Alpine Linuxで設定するときの追加セットアップ• K3d（Dockerで動く K3s）を docker-composeで動かす

8.1 マニフェストの自動配布/var/lib/rancher/k3s/server/manifestsに置かれたすべてのファイルは、kubectl applyが常

に適用されて自動的に Kubernetesに展開されます。HelmChartをデプロイすることもできます。K3sでは、チャートをインストールするための CRDコ

ントローラーが動いています。デプロイされる YAML ファイルは次のような仕様になります（以下は、/var/lib/rancher/k3s/server/manifests/traefik.yaml から取った例です）。

apiVersion: helm.cattle.io/v1kind: HelmChartmetadata:

name: traefiknamespace: kube-system

spec:chart: stable/traefikset:

rbac.enabled: "true"

43

第 8章構成設定と詳細オプション 8.2 Helm CRDを利用する

ssl.enabled: "true"

注意していただきたいのは、HelmChartのリソースのメタデータセクションの namespaceは常に kube-systemにする必要がある点です。というのも K3sデプロイコントローラーは新しくデプロイされたHelmChartのリソースでこの名前空間名を常に監視するように設定されているためです。実際のヘルムリリースでネームスペースを指定するには、以下の設定サンプルのように specセクションディレクティブで、targetNamespaceキーを使用します。もうひとつの注意点としては、setのほかに、specディレクティブの配下で values Contentを使用することもできます。また、両方を使っても問題ありません。


name: grafananamespace: kube-system

spec:chart: stable/grafanatargetNamespace: monitoringset:

adminPassword: "NotVerySafePassword"valuesContent: |-

image:tag: master

env:GF_EXPLORE_ENABLED: true

adminUser: adminsidecar:

datasources:enabled: true

K3sのバージョン 0.5.0以下では HelmChartの APIグループは、k3s.cattle.ioを使用していました。以降のバージョンは helm.cattle.ioに変更されました。

8.2 Helm CRDを利用する以下のサンプルのようにするとサードパーティの HelmChartを配布できます。


44

第 8章構成設定と詳細オプション 8.3 kubectlを使って外部からクラスターへアクセスする

name: nginxnamespace: kube-system

spec:chart: nginxrepo: https://charts.bitnami.com/bitnamitargetNamespace: default

次のサンプルのようにすると特定のバージョンの HelmChartをインストールできます。


name: stable/nginx-ingressnamespace: kube-system

spec:chart: nginx-ingressversion: 1.24.4targetNamespace: default

8.3 kubectlを使って外部からクラスターへアクセスする/etc/rancher/k3s/k3s.yaml をコピーしてクラスターの外側にあるマシンの~/.kube/config に保存します。そのファイルの“localhost”を K3sサーバーの IPまたは名前に置換します。kubectl でK3sクラスターを外部から管理できるようになります。

8.4 コンテナランタイムに Dockerを使用するK3sには業界標準の containerd*1が含まれ、デフォルトに設定されています。containerdの代わりに

Dockerを使用したい場合は、--dockerフラグを付けてエージェントを実行してください。K3sは containerdの config.toml設定を生成し、/var/lib/rancher/k3s/agent/etc/containe

rd/config.tomlに保存します。このファイルを詳細にカスタマイズするには、同じディレクトリに config.toml.tmplという別のファイルを作成すると代わりにこちらが使用されます。

config.toml.tmplは Go言語のテンプレートファイルとなっていて、config.Nodeの構成がテンプレートになっています。以下は設定ファイルの構成をカスタマイズする方法の例です。

https://github.com/rancher/k3s/blob/master/pkg/agent/templates/templates.go#L16-L32

*1 https://containerd.io/

45

第 8章構成設定と詳細オプション 8.5 RootlessKitで K3sを動かす（試験実装）

8.5 RootlessKitで K3sを動かす（試験実装）

� �注意：この機能は、試験実装です� �RootlessKitは Linuxネイティブの“root偽装” ユーティリティの一種で、主に特権を持たないユーザーで Dockerと Kubernetesを実行するために作られ*2、潜在的なコンテナ侵入攻撃からホスト上の実際の rootを保護します。

rootlessの初期サポートが実装されていますが、その影響によりユーザビリティーにいくつかの重要な課題があります。本実装は rootless に取り組みたい人たちのための初期実装です。将来的にコントリビューターがこの

ユーザビリティを改善してくれることを期待しています。利用するためには、ユーザーの名前空間が適切に設定され、サポートされていることを確認します。手順については、RootlessKit の要件セクション*3を参照してください。簡単に言うと Rootlessを動かす一番簡単な方法は最新の Ubuntuを使うことです。

RootlessKitの既知の課題

ポートRootless を実行すると、新しいネットワークネームスペースが作成されます。これは、K3s インスタンスがホストからまったく切り離されたネットワークで実行されていることを意味します。そうするとホストから K3sのサービスに接続する唯一の方法は、K3s ネットワークネームスペースにポートフォワードするしかありません。そのため、ホストに 6443を自動的にバインドし、1024未満のポートに 10000 を足してホストにバインドするコントローラーがあります。つまり、ホストのサービスポート 80は 10080になりますが、8080は足されることなしに 8080になります。現在、自動的にバインドされるのは LoadBalancerサービスのみです。

DaemonライフサイクルK3sを killしてから K3sの新しいインスタンスを起動すると、新しいネットワークネームスペースが作成されますが、古いポッドは killされません。そうすると壊れた状態で残ります。これは現在のところ、ネットワークネームスペースをどのように扱うかという大きな問題です。この課題はhttps://github.com/rootless-containers/rootlesskit/issues/65で検討されています。

CgroupsCgroupsはサポートされていません。

*2 https://github.com/rootless-containers/usernetes*3 https://github.com/rootless-containers/rootlesskit#setup

46

第 8章構成設定と詳細オプション 8.6 ノードのラベルと taint

Rootlessでサーバーとエージェントを起動する

必要なのは、サーバーかエージェントのどちらでも--rootless フラグを追加することだけです。まず、k3s server --rootless を実行して、Wrote kubeconfig [SOME PATH] というメッセージを見つけてクラスターにアクセスするための kubeconfigがどこにあるかを調べてください。注意してほしい点は、-oオプションを使って kubeconfigを別のディレクトリに書き込んでいる場合、

おそらく動作しないことです。これは、K3sインスタンスが異なるマウントネームスペースで実行されているためです。

8.6 ノードのラベルと taintK3sエージェントは、kubeletにラベルと taintを追加するオプション--node-labelと--node-tai

ntで設定できます。この 2つのオプションは、登録時（第 4章「インストール」の「エージェントノードに付与するノードラベルと taint」を参照）にラベルまたは taint（あるいはその両方）を追加するだけなので、K3sをラベルを追加して一度実行したあとは変更できません。ノードの登録後にノードラベルや属性を変更したい場合は kubectlを使用してください。ノードラベ

ルと taintを追加する方法は、それぞれ公式ドキュメントを参照してください。

8.7 インストールスクリプトでのサーバーの起動インストールスクリプトは、OS が systemd または openrc を使用しているかどうかを自動的に検出し、サービスを起動します。ログは openrcの場合は /var/log/k3s.log に出力されます。

systemdの場合は、/var/log/syslog に出力されます。journalctl -u k3sを使用して表示することもできます。

インストールスクリプトを使用したインストールと自動起動の例


サーバーを手動で実行すると、次のような出力が表示されます。

$ k3s serverINFO[2019-01-22T15:16:19.908493986-07:00] Starting k3s devINFO[2019-01-22T15:16:19.908934479-07:00] Running kube-apiserver --allow-privileged=true --authorization-mode Node,RBAC --service-account-signing-key-file /var/lib/rancher/k3s/server/tls/service.key --service-cluster-ip-range 10.43.0.0/16 --advertise-port 6445 --advertise-address 127.0.0.1 --insecure-port 0 --secure-port 6444 --bind-address 127.0.0.1 --tls-cert-file

47

第 8章構成設定と詳細オプション 8.8 Alpine Linuxで設定するときの追加セットアップ

/var/lib/rancher/k3s/server/tls/localhost.crt --tls-private-key-file /var/lib/rancher/k3s/server/tls/localhost.key --service-account-key-file /var/lib/rancher/k3s/server/tls/service.key --service-account-issuer k3s --api-audiences unknown --basic-auth-file /var/lib/rancher/k3s/server/cred/passwd --kubelet-client-certificate /var/lib/rancher/k3s/server/tls/token-node.crt --kubelet-client-key /var/lib/rancher/k3s/server/tls/token-node.keyFlag --insecure-port has been deprecated, This flag will be removed in a future version.INFO[2019-01-22T15:16:20.196766005-07:00] Running kube-scheduler --kubeconfig /var/lib/rancher/k3s/server/cred/kubeconfig-system.yaml --port 0 --secure-port 0 --leader-elect=falseINFO[2019-01-22T15:16:20.196880841-07:00] Running kube-controller-manager --kubeconfig /var/lib/rancher/k3s/server/cred/kubeconfig-system.yaml --service-account-private-key-file /var/lib/rancher/k3s/server/tls/service.key --allocate-node-cidrs --cluster-cidr 10.42.0.0/16 --root-ca-file /var/lib/rancher/k3s/server/tls/token-ca.crt --port 0 --secure-port 0 --leader-elect=falseFlag --port has been deprecated, see --secure-port instead.INFO[2019-01-22T15:16:20.273441984-07:00] Listening on :6443INFO[2019-01-22T15:16:20.278383446-07:00] Writing manifest: /var/lib/rancher/k3s/server/manifests/coredns.yamlINFO[2019-01-22T15:16:20.474454524-07:00] Node token is available at /var/lib/rancher/k3s/server/node-tokenINFO[2019-01-22T15:16:20.474471391-07:00] To join node to cluster: k3s agent -s https://10.20.0.3:6443 -t ${NODE_TOKEN}INFO[2019-01-22T15:16:20.541027133-07:00] Wrote kubeconfig /etc/rancher/k3s/k3s.yamlINFO[2019-01-22T15:16:20.541049100-07:00] Run: k3s kubectl

エージェントが大量のログを生成するため、出力はかなり長くなります。デフォルトでは、サーバー自身をノードとして登録します（エージェントを実行します）。

8.8 Alpine Linuxで設定するときの追加セットアップAlpine Linuxでセットアップするには事前に次のステップを実行する必要があります。

echo "cgroup /sys/fs/cgroup cgroup defaults 0 0" >> /etc/fstab

cat >> /etc/cgconfig.conf <<EOFmount {cpuacct = /cgroup/cpuacct;memory = /cgroup/memory;devices = /cgroup/devices;freezer = /cgroup/freezer;net_cls = /cgroup/net_cls;blkio = /cgroup/blkio;cpuset = /cgroup/cpuset;cpu = /cgroup/cpu;}EOF

48

第 8章構成設定と詳細オプション 8.9 K3d（Dockerで動く K3s）を docker-composeで動かす

それから /etc/update-extlinux を修正して以下を追加します。

default_kernel_opts="... cgroup_enable=cpuset cgroup_memory=1 cgroup_enable=memory"

設定を更新したら再起動します。

update-extlinuxreboot

再起動後は以下を実行します。

• k3s を /usr/local/bin/k3s へダウンロード• /etc/init.d に openrcファイルを作成

8.9 K3d（Dockerで動く K3s）を docker-composeで動かすK3dは Docker上で K3sを簡単に実行できるように設計されたユーティリティです。このユーティリティは、MacOSの場合は brewユーティリティを使用してインストールできます。

brew install k3d

rancher/k3sイメージは Dockerで K3sサーバーとエージェントを実行するためにも利用できます。K3s リポジトリのルートにある docker-compose.yml を使って Docker で K3s を実行する例です。

このレポジトリの docker-composeから起動するには次のようにします。

docker-compose up --scale node=3# kubeconfig はカレントディレクトリに書かれます

kubectl --kubeconfig kubeconfig.yaml get node

NAME STATUS ROLES AGE VERSION497278a2d6a2 Ready <none> 11s v1.13.2-k3s2d54c8b17c055 Ready <none> 11s v1.13.2-k3s2db7a5a5a5bdd Ready <none> 12s v1.13.2-k3s2

49

第 8章構成設定と詳細オプション 8.9 K3d（Dockerで動く K3s）を docker-composeで動かす

Dockerでエージェントのみ実行するには、docker-compose up nodeとします。もしくは、docker runコマンドで起動することもできます。

sudo docker run \-d --tmpfs /run \--tmpfs /var/run \-e K3S_URL=${SERVER_URL} \-e K3S_TOKEN=${NODE_TOKEN} \--privileged rancher/k3s:vX.Y.Z

50

付録 A

FAQと既知の問題A.1 FAQ

FAQは定期的に更新されており、K3sについて最もよく尋ねられる質問に回答しています。

K3sは K8sの代替に最適ですか?K3sでは K8sのほとんどすべての機能が利用可能です。K8sのより軽量なバージョンと思っていただいて構いません。詳細については、K3sのドキュメントページ*1を参照してください。

Traefikの代わりに自前の Ingressを使うにはどうすればいいですか？シンプルに--no-deploy=traefikで K3sサーバーを起動し、Ingressをデプロイしてください。

K3sは Windowsをサポートしていますか？現時点では、K3sはWindowsをネイティブにサポートしていませんが、このようなリクエストをオープンに受け入れています。

ソースからビルドする方法は？K3sのビルドについては、ビルド方法のページ*2を参照してください。

A.2 既知の問題「既知の問題」は定期的に更新されており、次のリリースではすぐに対処されないと考えられる課題について情報共有しています。

Snap DockerSnapでインストーラされた Dockerで K3sを使おうとしても、K3sの実行時に問題が発生すること分かっているため、Snapパッケージを使用しての Dockerのインストールはお勧めしません。

Iptables古いモードではなく、nftablesモードで iptablesを実行している場合、問題が発生する可能性があります。問題を回避するために、新しい iptables（1.6.1以降など）の使用をお勧めします。

RootlessKitK3sを RootlessKit上で動かす機能は、試験的に実装されているものですので、いくつか既知の問題（第 8章「構成設定と詳細オプション」の「RootlessKitの既知の課題」を参照）があります。

*1 https://rancher.com/docs/k3s/latest/en/*2 https://github.com/rancher/k3s/blob/master/BUILDING.md

51

日本語版K3sマニュアル（電子書籍版）― Rancher K3s公式ドキュメントより ―

2020年 3月 25日　初版第 1刷　発行翻　訳矢野哲朗協　力 Rancher Labs, Inc./株式会社スタイルズ編集制作株式会社テッキーメディア

コンテナ・オーケストレーション | kubernetes管理 ...はじめに rancher...

Documents