Merge pull request #82 from btat/sync-pr357

Sync PR #357 (Add useful information for tokens) from Community docs
rancher · Dec 11, 2024 · a265336 · a265336
2 parents faf0378 + cc073d0
commit a265336
Show file tree

Hide file tree

Showing 4 changed files with 112 additions and 30 deletions.
diff --git a/versions/latest/modules/en/pages/cli/token.adoc b/versions/latest/modules/en/pages/cli/token.adoc
@@ -1,6 +1,6 @@
 = k3s token
 
-K3s uses tokens to secure the node join process. Tokens authenticate the cluster to the joining node, and the node to the cluster.
+K3s uses tokens to secure the node join process and to encrypt confidential information that is persisted to the datastore. Tokens authenticate the cluster to the joining node, and the node to the cluster.
 
 == Token Format
 
@@ -58,9 +58,9 @@ K3s supports three types of tokens. Only the server token is available by defaul
 
 If no token is provided when starting the first server in the cluster, one is created with a random password. The server token is always written to `/var/lib/rancher/k3s/server/token`, in secure format.
 
-The server token can be used to join both server and agent nodes to the cluster. It cannot be changed once the cluster has been created, and anyone with access to the server token essentially has full administrator access to the cluster. This token should be guarded carefully.
+The server token can be used to join both server and agent nodes to the cluster. Anyone with access to the server token essentially has full administrator access to the cluster. This token should be guarded carefully.
 
-The server token is also used as the https://en.wikipedia.org/wiki/PBKDF2[PBKDF2] passphrase for the key used to encrypt confidential information that is persisted to the datastore, such as the secrets-encryption configuration, wireguard keys, and private keys for cluster CA certificates and service-account tokens. For this reason, the token must be backed up alongside the cluster datastore itself.
+The server token is also used as the https://en.wikipedia.org/wiki/PBKDF2[PBKDF2] passphrase to encrypt confidential information that is persisted to the datastore known as bootstrap data. Bootstrap data is essential to set up new server nodes or restore from a snapshot. For this reason, the token must be backed up alongside the cluster datastore itself.
 
 [CAUTION]
 ====
@@ -85,8 +85,7 @@ The agent token is written to `/var/lib/rancher/k3s/server/agent-token`, in secu
 Support for the `k3s token` command and the ability to join nodes with bootstrap tokens is available starting with the 2023-02 releases (v1.26.2+k3s1, v1.25.7+k3s1, v1.24.11+k3s1, v1.23.17+k3s1).
 ====
 
-
-K3s supports dynamically generated, automatically expiring agent bootstrap tokens. Bootstrap tokens can only be used to join agents.
+K3s supports dynamically generated, automatically expiring agent https://kubernetes.io/docs/reference/access-authn-authz/bootstrap-tokens/[bootstrap tokens].
 
 == k3s token
 
@@ -199,7 +198,7 @@ Available as of the October 2023 releases (v1.28.2+k3s1, v1.27.7+k3s1, v1.26.10+
 ====
 
 
-Rotate original server token with a new bootstrap token. After running this command, all servers and any agents that originally joined with the old token must be restarted with the new token.
+Rotate original server token with a new server token. After running this command, all servers and any agents that originally joined with the old token must be restarted with the new token.
 
 If you do not specify a new token, one will be generated for you.
 
@@ -221,3 +220,8 @@ If you do not specify a new token, one will be generated for you.
 | `--new-token` value
 | New token that replaces existing token
 |===
+
+[WARNING]
+====
+Snapshots taken before the rotation will require the old server token when restoring the cluster.
+====
diff --git a/versions/latest/modules/ja/pages/cli/token.adoc b/versions/latest/modules/ja/pages/cli/token.adoc
@@ -1,6 +1,6 @@
 = k3s トークン
 
-K3s はトークンを使用してノードの参加プロセスを保護します。トークンはクラスターを参加ノードに認証し、ノードをクラスターに認証します。
+K3s uses tokens to secure the node join process and to encrypt confidential information that is persisted to the datastore。トークンはクラスターを参加ノードに認証し、ノードをクラスターに認証します。
 
 == トークン形式
 
@@ -58,9 +58,9 @@ K3s は 3 種類のトークンをサポートします。デフォルトでは
 
 クラスターの最初のサーバーを起動する際にトークンが提供されない場合、ランダムなパスワードでトークンが作成されます。サーバートークンは常にセキュア形式で `/var/lib/rancher/k3s/server/token` に書き込まれます。
 
-サーバートークンは、サーバーノードとエージェントノードの両方をクラスターに参加させるために使用できます。一度クラスターが作成されると変更できず、サーバートークンにアクセスできる人はクラスターに対して完全な管理者アクセスを持つことになります。このトークンは慎重に保護する必要があります。
+The server token can be used to join both server and agent nodes to the cluster. Anyone with access to the server token essentially has full administrator access to the cluster. This token should be guarded carefully.
 
-サーバートークンは、データストアに永続化される機密情報（シークレット暗号化設定、ワイヤーガードキー、クラスター CA 証明書およびサービスアカウントトークンの秘密鍵など）を暗号化するために使用されるキーの https://en.wikipedia.org/wiki/PBKDF2[PBKDF2] パスフレーズとしても使用されます。このため、トークンはクラスターのデータストアと一緒にバックアップする必要があります。
+The server token is also used as the https://en.wikipedia.org/wiki/PBKDF2[PBKDF2] passphrase to encrypt confidential information that is persisted to the datastore known as bootstrap data. Bootstrap data is essential to set up new server nodes or restore from a snapshot. For this reason, the token must be backed up alongside the cluster datastore itself.
 
 [CAUTION]
 ====
@@ -85,8 +85,7 @@ K3s は 3 種類のトークンをサポートします。デフォルトでは
 `k3s token` コマンドのサポートとブートストラップトークンを使用してノードに参加する機能は、2023-02 リリース（v1.26.2+k3s1、v1.25.7+k3s1、v1.24.11+k3s1、v1.23.17+k3s1）から利用可能です。
 ====
 
-
-K3s は動的に生成され、自動的に期限切れになるエージェントブートストラップトークンをサポートします。ブートストラップトークンはエージェントの参加にのみ使用できます。
+K3s supports dynamically generated, automatically expiring agent https://kubernetes.io/docs/reference/access-authn-authz/bootstrap-tokens/[bootstrap tokens].
 
 == k3s トークン
 
@@ -193,7 +192,7 @@ OPTIONS:
 2023年10月のリリース（v1.28.2+k3s1、v1.27.7+k3s1、v1.26.10+k3s1、v1.25.15+k3s1）から利用可能です。
 ====
 
-
+Rotate original server token with a new server token.
 元のサーバートークンを新しいブートストラップトークンにローテートします。このコマンドを実行した後、すべてのサーバーおよび元のトークンで参加したエージェントは新しいトークンで再起動する必要があります。
 
 新しいトークンを指定しない場合、1 つが生成されます。
@@ -216,3 +215,8 @@ OPTIONS:
 | `--new-token` 値
 | 既存のトークンを置き換える新しいトークン
 |===
+
+[WARNING]
+====
+Snapshots taken before the rotation will require the old server token when restoring the cluster.
+====
diff --git a/versions/latest/modules/ko/pages/cli/token.adoc b/versions/latest/modules/ko/pages/cli/token.adoc
@@ -1,6 +1,6 @@
 = k3s token
 
-K3s uses tokens to secure the node join process. Tokens authenticate the cluster to the joining node, and the node to the cluster.
+K3s uses tokens to secure the node join process and to encrypt confidential information that is persisted to the datastore. Tokens authenticate the cluster to the joining node, and the node to the cluster.
 
 == Token Format
 
@@ -58,9 +58,9 @@ K3s supports three types of tokens. Only the server token is available by defaul
 
 If no token is provided when starting the first server in the cluster, one is created with a random password. The server token is always written to `/var/lib/rancher/k3s/server/token`, in secure format.
 
-The server token can be used to join both server and agent nodes to the cluster. It cannot be changed once the cluster has been created, and anyone with access to the server token essentially has full administrator access to the cluster. This token should be guarded carefully.
+The server token can be used to join both server and agent nodes to the cluster. Anyone with access to the server token essentially has full administrator access to the cluster. This token should be guarded carefully.
 
-The server token is also used as the https://en.wikipedia.org/wiki/PBKDF2[PBKDF2] passphrase for the key used to encrypt confidential information that is persisted to the datastore, such as the secrets-encryption configuration, wireguard keys, and private keys for cluster CA certificates and service-account tokens. For this reason, the token must be backed up alongside the cluster datastore itself.
+The server token is also used as the https://en.wikipedia.org/wiki/PBKDF2[PBKDF2] passphrase to encrypt confidential information that is persisted to the datastore known as bootstrap data. Bootstrap data is essential to set up new server nodes or restore from a snapshot. For this reason, the token must be backed up alongside the cluster datastore itself.
 
 [CAUTION]
 ====
@@ -85,8 +85,7 @@ The agent token is written to `/var/lib/rancher/k3s/server/agent-token`, in secu
 Support for the `k3s token` command and the ability to join nodes with bootstrap tokens is available starting with the 2023-02 releases (v1.26.2+k3s1, v1.25.7+k3s1, v1.24.11+k3s1, v1.23.17+k3s1).
 ====
 
-
-K3s supports dynamically generated, automatically expiring agent bootstrap tokens. Bootstrap tokens can only be used to join agents.
+K3s supports dynamically generated, automatically expiring agent https://kubernetes.io/docs/reference/access-authn-authz/bootstrap-tokens/[bootstrap tokens].
 
 == k3s token
 
@@ -104,6 +103,7 @@ COMMANDS:
    delete    Delete bootstrap tokens on the server
    generate  Generate and print a bootstrap token, but do not create it on the server
    list      List bootstrap tokens on the server
+   rotate    Rotate original server token with a new bootstrap token
 
 OPTIONS:
    --help, -h  show help
@@ -120,10 +120,10 @@ A token in secure format, including the cluster CA hash, will be written to stdo
 | Flag | Description
 
 | `--data-dir` value
-| (data) Folder to hold state default /var/lib/rancher/k3s or $\{HOME}/.rancher/k3s if not root
+| Folder to hold state (default: /var/lib/rancher/k3s or $\{HOME}/.rancher/k3s if not root)
 
 | `--kubeconfig` value
-| (cluster) Server to connect to [$KUBECONFIG]
+| Server to connect to [$KUBECONFIG]
 
 | `--description` value
 | A human friendly description of how this token is used
@@ -147,10 +147,10 @@ Delete one or more tokens. The full token can be provided, or just the token ID.
 | Flag | Description
 
 | `--data-dir` value
-| (data) Folder to hold state default /var/lib/rancher/k3s or $\{HOME}/.rancher/k3s if not root
+| Folder to hold state (default: /var/lib/rancher/k3s or $\{HOME}/.rancher/k3s if not root)
 
 | `--kubeconfig` value
-| (cluster) Server to connect to [$KUBECONFIG]
+| Server to connect to [$KUBECONFIG]
 |===
 
 [discrete]
@@ -164,10 +164,10 @@ You don't have to use this command in order to generate a token. You can do so y
 | Flag | Description
 
 | `--data-dir` value
-| (data) Folder to hold state default /var/lib/rancher/k3s or $\{HOME}/.rancher/k3s if not root
+| Folder to hold state (default: /var/lib/rancher/k3s or $\{HOME}/.rancher/k3s if not root)
 
 | `--kubeconfig` value
-| (cluster) Server to connect to [$KUBECONFIG]
+| Server to connect to [$KUBECONFIG]
 |===
 
 [discrete]
@@ -179,11 +179,49 @@ List bootstrap tokens, showing their ID, description, and remaining time-to-live
 | Flag | Description
 
 | `--data-dir` value
-| (data) Folder to hold state default /var/lib/rancher/k3s or $\{HOME}/.rancher/k3s if not root
+| Folder to hold state (default: /var/lib/rancher/k3s or $\{HOME}/.rancher/k3s if not root)
 
 | `--kubeconfig` value
-| (cluster) Server to connect to [$KUBECONFIG]
+| Server to connect to [$KUBECONFIG]
 
 | `--output` value
 | Output format. Valid options: text, json (default: "text")
 |===
+
+[discrete]
+==== `k3s token rotate`
+
+[IMPORTANT]
+.Version Gate
+====
+Available as of the October 2023 releases (v1.28.2+k3s1, v1.27.7+k3s1, v1.26.10+k3s1, v1.25.15+k3s1).
+====
+
+
+Rotate original server token with a new server token. After running this command, all servers and any agents that originally joined with the old token must be restarted with the new token.
+
+If you do not specify a new token, one will be generated for you.
+
+|===
+| Flag | Description
+
+| `--data-dir` value
+| Folder to hold state (default: /var/lib/rancher/k3s or $\{HOME}/.rancher/k3s if not root)
+
+| `--kubeconfig` value
+| Server to connect to [$KUBECONFIG]
+
+| `--server` value
+| Server to connect to (default: "https://127.0.0.1:6443") [$K3S_URL]
+
+| `--token` value
+| Existing token used to join a server or agent to a cluster [$K3S_TOKEN]
+
+| `--new-token` value
+| New token that replaces existing token
+|===
+
+[WARNING]
+====
+Snapshots taken before the rotation will require the old server token when restoring the cluster.
+====
diff --git a/versions/latest/modules/zh/pages/cli/token.adoc b/versions/latest/modules/zh/pages/cli/token.adoc
@@ -1,6 +1,6 @@
 = k3s token
 
-K3s 使用 Token 来保护加入节点的过程。Token 用于验证加入的节点和集群。
+K3s 使用 Token 来保护加入节点的过程 and to encrypt confidential information that is persisted to the datastore。Token 用于验证加入的节点和集群。
 
 == Token 格式
 
@@ -58,9 +58,9 @@ K3s 支持三种类型的 Token。默认情况下只有 Server Token 可用，
 
 如果在启动集群中的第一个 Server 时未提供 Token，则会使用随机密码创建。Server Token 始终以安全格式写入 `/var/lib/rancher/k3s/server/token`。
 
-Server Token 可用于将 Server 和 Agent 节点加入集群。一旦创建了集群，它就无法更改，任何有权访问 Server Token 的用户基本上都拥有集群的完全管理员访问权限。因此，你需要小心保管 Token。
+The server token can be used to join both server and agent nodes to the cluster. Anyone with access to the server token essentially has full administrator access to the cluster. This token should be guarded carefully.
 
-Server Token 还用作密钥的 https://en.wikipedia.org/wiki/PBKDF2[PBKDF2] 密码，该密钥用于加密持久保存到数据存储的机密信息，例如 Secret 加密配置、wireguard 密钥，集群 CA 证书的私钥以及 service-account Token。因此，Token 必须与集群数据存储一起备份。
+The server token is also used as the https://en.wikipedia.org/wiki/PBKDF2[PBKDF2] passphrase to encrypt confidential information that is persisted to the datastore known as bootstrap data. Bootstrap data is essential to set up new server nodes or restore from a snapshot. For this reason, the token must be backed up alongside the cluster datastore itself.
 
 [CAUTION]
 ====
@@ -85,8 +85,7 @@ Agent Token 以安全格式写入 `/var/lib/rancher/k3s/server/agent-token`。
 从 2023-02 版本（v1.26.2+k3s1、v1.25.7+k3s1、v1.24.11+k3s1、v1.23.17+k3s1）开始，支持 `k3s token` 命令以及使用 Bootstrap Token 加入节点。
 ====
 
-
-K3s 支持动态生成、自动过期的 agent bootstrap token。Bootstrap Token 只能用于加入 Agent。
+K3s supports dynamically generated, automatically expiring agent https://kubernetes.io/docs/reference/access-authn-authz/bootstrap-tokens/[bootstrap tokens].
 
 == k3s token
 
@@ -187,3 +186,40 @@ OPTIONS:
 | `--output` value
 | 输出格式。可选值：text、json（默认值：`text`）
 |===
+
+==== `k3s token rotate`
+
+[IMPORTANT]
+.Version Gate
+====
+Available as of the October 2023 releases (v1.28.2+k3s1, v1.27.7+k3s1, v1.26.10+k3s1, v1.25.15+k3s1).
+====
+
+
+Rotate original server token with a new server token. After running this command, all servers and any agents that originally joined with the old token must be restarted with the new token.
+
+If you do not specify a new token, one will be generated for you.
+
+|===
+| Flag | Description
+
+| `--data-dir` value
+| Folder to hold state (default: /var/lib/rancher/k3s or $\{HOME}/.rancher/k3s if not root)
+
+| `--kubeconfig` value
+| Server to connect to [$KUBECONFIG]
+
+| `--server` value
+| Server to connect to (default: "https://127.0.0.1:6443") [$K3S_URL]
+
+| `--token` value
+| Existing token used to join a server or agent to a cluster [$K3S_TOKEN]
+
+| `--new-token` value
+| New token that replaces existing token
+|===
+
+[WARNING]
+====
+Snapshots taken before the rotation will require the old server token when restoring the cluster.
+====