メインコンテンツまでスキップ

k3s トークン

K3s はトークンを使用してノードの参加プロセスを保護します。トークンはクラスターを参加ノードに認証し、ノードをクラスターに認証します。

トークン形式​

K3s トークンはセキュア形式またはショート形式で指定できます。セキュア形式が推奨されます。これは、クライアントが資格情報を送信する前に参加するクラスターのアイデンティティを認証できるためです。

セキュア​

セキュアトークン形式（「フル」トークンとも呼ばれることがあります）は、以下の部分で構成されます：

<prefix><cluster CA hash>::<credentials>

  • prefix: トークン形式を識別する固定の K10 プレフィックス
  • cluster CA hash: 参加ノードにサーバーを認証するために使用されるクラスターのサーバー CA 証明書のハッシュ。
    • 自己署名 CA 証明書の場合、これはディスクに保存されている PEM 形式の証明書の SHA256 サムです。
    • カスタム CA 証明書の場合、これはルート証明書の DER エンコーディングの SHA256 サムです。一般に証明書のフィンガープリントとして知られています。
  • credentials: クラスターに参加するノードを認証するために使用されるユーザー名とパスワード、またはベアラートークン。

TLS ブートストラッピング​

セキュアトークンが指定されている場合、参加ノードは資格情報を送信する前に接続したサーバーのアイデンティティを検証するために以下の手順を実行します：

  1. TLS 検証を無効にして、参加するサーバーの /cacerts から CA バンドルをダウンロードします。
  2. 上記の説明に従って CA 証明書の SHA256 ハッシュを計算します。
  3. 計算された SHA256 ハッシュをトークンのハッシュと比較します。
  4. ハッシュが一致する場合、サーバーが提示する証明書がサーバーの CA バンドルによって検証できることを確認します。
  5. サーバー証明書が有効である場合、トークンの種類に応じて基本認証またはベアラートークン認証を使用してクラスターに参加するための資格情報を提示します。

ショート​

ショートトークン形式には、クラスターに参加するノードを認証するために使用されるパスワードまたはベアラートークンのみが含まれます。

ショートトークンが使用される場合、参加ノードはサーバーが提示する CA バンドルを暗黙的に信頼します。TLS ブートストラッピングプロセスのステップ 2-4 はスキップされます。初回接続は中間者攻撃に対して脆弱である可能性があります。

トークンの種類​

K3s は 3 種類のトークンをサポートします。デフォルトではサーバートークンのみが利用可能で、追加のトークンタイプは管理者によって設定または作成される必要があります。

種類CLI オプション環境変数
サーバー--tokenK3S_TOKEN
エージェント--agent-tokenK3S_AGENT_TOKEN
ブートストラップn/an/a

サーバー​

クラスターの最初のサーバーを起動する際にトークンが提供されない場合、ランダムなパスワードでトークンが作成されます。サーバートークンは常にセキュア形式で /var/lib/rancher/k3s/server/token に書き込まれます。

サーバートークンは、サーバーノードとエージェントノードの両方をクラスターに参加させるために使用できます。一度クラスターが作成されると変更できず、サーバートークンにアクセスできる人はクラスターに対して完全な管理者アクセスを持つことになります。このトークンは慎重に保護する必要があります。

サーバートークンは、データストアに永続化される機密情報（シークレット暗号化設定、ワイヤーガードキー、クラスター CA 証明書およびサービスアカウントトークンの秘密鍵など）を暗号化するために使用されるキーの PBKDF2 パスフレーズとしても使用されます。このため、トークンはクラスターのデータストアと一緒にバックアップする必要があります。

警告

カスタム CA 証明書が使用されていない限り、クラスターの最初のサーバーを起動する際にはショート（パスワードのみ）トークン形式のみが使用できます。これは、サーバーが自己署名のクラスター CA 証明書を生成するまでクラスター CA ハッシュがわからないためです。

カスタム CA 証明書の使用に関する詳細は、k3s certificate ドキュメントを参照してください。
クラスターのバックアップに関する詳細は、バックアップとリストアドキュメントを参照してください。

エージェント​

デフォルトでは、エージェントトークンはサーバートークンと同じです。エージェントトークンは、クラスターが開始された後でも、すべてのサーバーの CLI オプションまたは環境変数を変更することで設定できます。エージェントトークンはサーバートークンと同様に静的に構成され、期限切れにはなりません。

エージェントトークンはセキュア形式で /var/lib/rancher/k3s/server/agent-token に書き込まれます。エージェントトークンが指定されていない場合、このファイルはサーバートークンへのリンクです。

ブートストラップ​

バージョンゲート

k3s token コマンドのサポートとブートストラップトークンを使用してノードに参加する機能は、2023-02 リリース（v1.26.2+k3s1、v1.25.7+k3s1、v1.24.11+k3s1、v1.23.17+k3s1）から利用可能です。

K3s は動的に生成され、自動的に期限切れになるエージェントブートストラップトークンをサポートします。ブートストラップトークンはエージェントの参加にのみ使用できます。

k3s トークン​

K3s ブートストラップトークンは kubeadm token ブートストラップトークンと同じ生成および検証コードを使用し、k3s token CLI も類似しています。

NAME:
   k3s token - ブートストラップトークンを管理する

USAGE:
   k3s token command [command options] [arguments...]

COMMANDS:
   create    サーバー上でブートストラップトークンを作成する
   delete    サーバー上のブートストラップトークンを削除する
   generate  ブートストラップトークンを生成して表示するが、サーバー上には作成しない
   list      サーバー上のブートストラップトークンを一覧表示する
   rotate    元のサーバートークンを新しいブートストラップトークンにローテートする

OPTIONS:
   --help, -h  ヘルプを表示する

k3s token create [token]​

新しいトークンを作成します。[token] は k3s token generate によって生成された実際のトークンです。トークンが指定されていない場合、ランダムなトークンが生成されます。

クラスター CA ハッシュを含むセキュア形式のトークンが標準出力に書き込まれます。このコマンドの出力は保存する必要があります。トークンの秘密部分は再度表示できません。

フラグ説明
--data-dir 値状態を保持するフォルダー（デフォルト: /var/lib/rancher/k3s または root でない場合は ${HOME}/.rancher/k3s）
--kubeconfig 値接続するサーバー [$KUBECONFIG]
--description 値このトークンの使用方法に関する人間に優しい説明
--groups 値認証に使用されるときにこのトークンが認証する追加のグループ。（デフォルト: "system:bootstrappers:k3s:default-node-token"）
--ttl 値トークンが自動的に削除されるまでの期間（例: 1s, 2m, 3h）。'0' に設定すると、トークンは期限切れになりません（デフォルト: 24h0m0s）
--usages 値このトークンが使用できる方法を説明します。（デフォルト: "signing,authentication"）

k3s token delete​

1 つ以上のトークンを削除します。完全なトークンまたはトークン ID のみを提供できます。

フラグ説明
--data-dir 値状態を保持するフォルダー（デフォルト: /var/lib/rancher/k3s または root でない場合は ${HOME}/.rancher/k3s）
--kubeconfig 値接続するサーバー [$KUBECONFIG]

k3s token generate​

ランダムに生成されたブートストラップトークンを生成します。

トークンを生成するためにこのコマンドを使用する必要はありません。トークン ID が "[a-z0-9]6.[a-z0-9]16" の形式であり、最初の部分がトークン ID、2 番目の部分が秘密である限り、自分で生成することもできます。

フラグ説明
--data-dir 値状態を保持するフォルダー（デフォルト: /var/lib/rancher/k3s または root でない場合は ${HOME}/.rancher/k3s）
--kubeconfig 値接続するサーバー [$KUBECONFIG]

k3s token list​

ブートストラップトークンを一覧表示し、その ID、説明、および残りの有効期間を表示します。

フラグ説明
--data-dir 値状態を保持するフォルダー（デフォルト: /var/lib/rancher/k3s または root でない場合は ${HOME}/.rancher/k3s）
--kubeconfig 値接続するサーバー [$KUBECONFIG]
--output 値出力形式。 有効なオプション: text, json（デフォルト: "text"）

k3s token rotate​

バージョンゲート

2023-10 リリース（v1.28.2+k3s1、v1.27.7+k3s1、v1.26.10+k3s1、v1.25.15+k3s1）から利用可能です。

元のサーバートークンを新しいブートストラップトークンにローテートします。このコマンドを実行した後、すべてのサーバーおよび元のトークンで参加したエージェントは新しいトークンで再起動する必要があります。

新しいトークンを指定しない場合、1 つが生成されます。

フラグ説明
--data-dir 値状態を保持するフォルダー（デフォルト: /var/lib/rancher/k3s または root でない場合は ${HOME}/.rancher/k3s）
--kubeconfig 値接続するサーバー [$KUBECONFIG]
--server 値接続するサーバー(デフォルト: "https://127.0.0.1:6443") [$K3S_URL]
--token 値サーバーまたはエージェントをクラスターに参加させるために使用される既存のトークン [$K3S_TOKEN]
--new-token 値既存のトークンを置き換える新しいトークン