|
この文書は自動機械翻訳技術を使用して翻訳されています。 正確な翻訳を提供するように努めておりますが、翻訳された内容の完全性、正確性、信頼性については一切保証いたしません。 相違がある場合は、元の英語版 英語 が優先され、正式なテキストとなります。 |
k3s証明書
クライアントおよびサーバー証明書
K3sのクライアントおよびサーバー証明書は、発行日から365日間有効です。
期限切れまたは期限切れまで120日以内の証明書は、K3sが起動するたびに自動的に更新されます。
この更新は既存のキーを再利用し、既存の証明書の有効期限を延長します。
既存の証明書の有効期限を延長するのではなく、新しい証明書とキーを生成したい場合は、以下に文書化されているrotateサブコマンドを使用してください。
証明書が期限切れまで120日以内の場合、証明書を使用しているノードに関連する`reason: CertificateExpirationWarning`を持つKubernetes警告イベントが作成されます。
2025年5月のリリース（v1.33.1+k3s1、v1.32.5+k3s1、v1.31.9+k3s1、v1.30.13+k3s1）以前は、アラートとローテーションは120日ではなく90日でトリガーされていました。
有効期限の確認
|
バージョンゲート
出力形式は2025年1月のリリースから設定可能です：v1.32.0+k3s1、v1.31.5+k3s1、v1.30.9+k3s1、v1.30.13+k3s1。 2025年5月のリリースから、より多くの情報を含む新しい形式が利用可能です：v1.33.1+k3s1、v1.32.5+k3s1、v1.31.9+k3s1、v1.29.13+k3s1。 |
ノード証明書とその有効期限を確認するには、`k3s certificate check --output table`を使用してください：
FILENAME SUBJECT USAGES EXPIRES RESIDUAL TIME STATUS
-------- ------- ------ ------- ------------- ------
client-kube-proxy.crt system:kube-proxy ClientAuth Jun 09, 2026 10:17 UTC 1 year OK
client-kube-proxy.crt k3s-client-ca@1749464211 CertSign Jun 07, 2035 10:16 UTC 10 years OK
client-kubelet.crt system:node:ip-10-11-0-14 ClientAuth Jun 09, 2026 10:17 UTC 1 year OK
client-kubelet.crt k3s-client-ca@1749464211 CertSign Jun 07, 2035 10:16 UTC 10 years OK
serving-kubelet.crt ip-10-11-0-14 ServerAuth Jun 09, 2026 10:17 UTC 1 year OK
serving-kubelet.crt k3s-server-ca@1749464211 CertSign Jun 07, 2035 10:16 UTC 10 years OK
client-k3s-controller.crt system:k3s-controller ClientAuth Jun 09, 2026 10:17 UTC 1 year OK
client-k3s-controller.crt k3s-client-ca@1749464211 CertSign Jun 07, 2035 10:16 UTC 10 years OK|
同じ証明書を2回
各証明書ファイル（`FILENAME `列）には、少なくとも2つの証明書が含まれています - リーフ（またはエンドエンティティ）クライアント/サーバー証明書、中間認証局証明書、およびルート認証局証明書。 |
予期しない出力がある場合は、--data-dir`フラグを使用して正しいデータディレクトリを指定していることを確認してください（カスタムデータディレクトリを使用している場合）、または--debug`フラグを使用してチェックプロセスから追加の出力を取得してください。
クライアントおよびサーバー証明書のローテーション
クライアントおよびサーバー証明書を手動でローテーションするには、`k3s certificate rotate`サブコマンドを使用してください：
# Stop K3s
systemctl stop k3s
# Rotate certificates
k3s certificate rotate
# Start K3s
systemctl start k3s個別の証明書または証明書のリストは、証明書名を指定することでローテーションできます：
k3s certificate rotate --service <SERVICE>,<SERVICE>次の証明書はローテーションできます: admin, api-server, controller-manager, scheduler, k3s-controller, k3s-server, cloud-controller, etcd, auth-proxy, kubelet, kube-proxy。
認証局 (CA) 証明書
Kubernetes は適切な操作のためにいくつかの CA 証明書を必要とします。Kubernetes が CA 証明書をどのように使用するかについての詳細は、Kubernetes PKI 証明書と要件 ドキュメントを参照してください。
デフォルトでは、K3s は最初のサーバーノードの起動時に自己署名の CA 証明書を生成します。これらの CA 証明書は発行日から 10 年間有効であり、自動的には更新されません。
権威ある CA 証明書とキーは、データストアの起動キー内に保存され、サーバートークン を PBKDF2 パスフレーズとして使用して AES256-GCM と HMAC-SHA1 で暗号化されます。 CA 証明書とキーのコピーは、K3s サーバーの起動時にディスクに抽出されます。 任意のサーバーは、ノードがクラスターに参加する際にリーフ証明書を生成でき、Kubernetes 証明書 API コントローラーはランタイム中に追加の証明書を発行することがあります。
CA 証明書とキーをローテーションするには、k3s certificate rotate-ca コマンドを使用してください。
このコマンドは、更新された証明書とキーが使用可能であることを確認するために整合性チェックを実行します。
更新されたデータが受け入れ可能な場合、データストアの暗号化されたブートストラップキーが更新され、新しい証明書とキーは次回 K3s が起動する際に使用されます。
証明書とキーの検証中に問題が発生した場合、エラーがシステムログに報告され、操作は変更なしでキャンセルされます。
|
バージョンゲート
|
カスタム CA 証明書の使用
CA 再利用に関する注意
|
ルートまたは中間 CA を複数のクラスターで共有したり、既存のプライベート CA をクラスター CA として使用することは推奨されません。 |
複数のクラスターが共通の信頼のルートを共有する場合、1 つのクラスターによって発行されたクライアントまたはサーバー証明書は、すべての他のクラスターでも信頼されます。すべての証明書は同じ信頼のアンカー - 共通の [Root] 証明書機関にチェーンされます。 これは、1 つのクラスターに対して有効なクライアント証明書 (または kubeconfig) を持つユーザーが、他のクラスターにも認証できることを意味します。また、クライアントのユーザーまたはグループに一致する RBAC は、他のクラスターでも適用されます。 同様に、1 つのクラスターによって発行されたサーバー証明書も、すべての他のクラスターおよびそのルート CA を信頼するすべての他のインフラストラクチャやクライアントで信頼されます。
Kubernetesは証明書取り消しリストの使用をサポートしていません。 証明書を取り消す必要がある場合（たとえば、管理者のkubeconfigが侵害された場合など）、証明書の信頼を無効にするために、クラスターの証明書認証局を完全に置き換える必要があります。
カスタム CA 証明書の使用
クラスター内の最初のサーバーの初期起動時にCA証明書とキーが正しい場所に見つかった場合、CA証明書の自動生成はスキップされます。
適切な証明書とキーを事前に作成するための例のスクリプトは、https://github.com/k3s-io/k3s/blob/main/contrib/util/generate-custom-ca-certs.sh[K3sリポジトリの`contrib/util/generate-custom-ca-certs.sh`]にあります。 このスクリプトはK3sを初めて起動する前に実行する必要があり、一般的なルートおよび中間CA証明書によって署名された完全なセットのリーフCA証明書を作成します。 既存のルートまたは中間CAがある場合、このスクリプトを使用して（または出発点として使用して）既存の権限に基づいてPKIでK3sクラスターをプロビジョニングするための正しいCA証明書を作成できます。
カスタム証明書認証局ファイルは`/var/lib/rancher/k3s/server/tls`に配置する必要があります。次のファイルが必要です：
-
server-ca.crt -
server-ca.key -
client-ca.crt -
client-ca.key -
request-header-ca.crt -
request-header-ca.key
// 注意：埋め込まれたetcdが使用されていなくても、etcdファイルは必要です。 -
etcd/peer-ca.crt -
etcd/peer-ca.key -
etcd/server-ca.crt -
etcd/server-ca.key
// 注意：これはサービスアカウントトークンに署名するために使用される秘密鍵です。対応する証明書はありません。 -
service.key
カスタムCAトポロジー
例のスクリプトによって生成されたカスタムCA証明書は、次のトポロジーを持っています：
(control-plane and kubelet listeners)"]] kube-client-certs[["Kubernetes clients
(apiserver and kubelet clients)"]] request-header-certs[["Kubernetes API aggregation
(apiserver proxy client)"]] etcd-peer-certs[["etcd peer client/server
(etcd replication)"]] etcd-server-certs[["etcd client/server certificates
(Kubernetes <-> etcd)"]] root -.-|SHA256| root-hash root ---> intermediate intermediate --> server-ca ==> kube-server-certs intermediate --> client-ca ==> kube-client-certs intermediate --> request-header-ca ==> request-header-certs intermediate --> etcd-peer-ca ==> etcd-peer-certs intermediate --> etcd-server-ca ==> etcd-server-certs
例のスクリプトを使用する
|
重要
例のスクリプトを使用して既存のルートCAでクラスターCA証明書に署名したい場合、スクリプトを実行する前にターゲットディレクトリにルートおよび中間ファイルを配置する必要があります。 ファイルが存在しない場合、スクリプトは新しいルートおよび中間CA証明書を作成します。 |
既存のルートCA証明書のみを使用したい場合、次のファイルを提供してください：
-
root-ca.pem -
root-ca.key
既存のルートおよび中間CA証明書を使用する場合は、次のファイルを提供してください：
-
root-ca.pem -
intermediate-ca.pem -
intermediate-ca.key
例のスクリプトは、提供されたCAをすべてのクラスターCAバンドルのルートとして使用します - サーバー、クライアント、API集約、およびetcdピア/サーバー。 提供されたCAを特定のバンドルのみに使用する場合や、異なるバンドルに異なるCAを使用する場合などの高度な使用ケースでは、例のスクリプトを組織の特定のニーズに合わせて修正する必要があります。
K3sを開始する前にカスタム証明書とキーを生成するために例のスクリプトを使用するには、次のコマンドを実行してください：
# Create the target directory for cert generation.
mkdir -p /var/lib/rancher/k3s/server/tls
# Copy your root CA cert and intermediate CA cert+key into the correct location for the script.
# For the purposes of this example, we assume you have existing root and intermediate CA files in /etc/ssl.
# If you do not have an existing root and/or intermediate CA, the script will generate them for you.
cp /etc/ssl/certs/root-ca.pem /etc/ssl/certs/intermediate-ca.pem /etc/ssl/private/intermediate-ca.key /var/lib/rancher/k3s/server/tls
# Generate custom CA certs and keys.
curl -sL https://github.com/k3s-io/k3s/raw/main/contrib/util/generate-custom-ca-certs.sh | bash -コマンドが正常に完了した場合、初めてK3sをインストールおよび/または開始できます。 スクリプトがルートおよび/または中間CAファイルを生成した場合、後日CA証明書をローテーションする必要が生じた際に再利用できるよう、これらのファイルをバックアップする必要があります。
カスタムCA証明書のローテーション
カスタムCA証明書をローテーションするには、`k3s certificate rotate-ca`サブコマンドを使用してください。 更新されたファイルは一時ディレクトリにステージングされ、データストアにロードされ、更新された証明書を使用するためにすべてのノードでk3sを再起動する必要があります。
|
現在使用中のデータを`/var/lib/rancher/k3s/server/tls`に上書きしてはいけません。 |
カスタムCA証明書で開始されたクラスターは、同じルートCAが使用されている限り、CA証明書とキーを非破壊的に更新またはローテーションすることができます。
新しいルートCAが必要な場合、ローテーションは破壊的になります。`k3s certificate rotate-ca --force`オプションを使用する必要があり、セキュアトークンで参加したすべてのノード（サーバーを含む）は、新しいトークン値を使用するように再構成する必要があり、ポッドは新しいルートCAを信頼するために再起動する必要があります。
例のスクリプトを使用する
上記の例の`generate-custom-ca-certs.sh`スクリプトも、新しい一時ディレクトリで更新された証明書を生成するために使用でき、ファイルを正しい場所にコピーし、`DATA_DIR`環境変数を設定します。 更新された証明書とキーを生成するために例のスクリプトを使用するには、次のコマンドを実行してください：
# Create a temporary directory for cert generation.
mkdir -p /opt/k3s/server/tls
# Copy your root CA cert and intermediate CA cert+key into the correct location for the script.
# Non-disruptive rotation requires the same root CA that was used to generate the original certificates.
# If the original files are still in the data directory, you can just run:
cp /var/lib/rancher/k3s/server/tls/root-ca.* /var/lib/rancher/k3s/server/tls/intermediate-ca.* /opt/k3s/server/tls
# Copy the current service-account signing key, so that existing service-account tokens are not invalidated.
cp /var/lib/rancher/k3s/server/tls/service.key /opt/k3s/server/tls
# Generate updated custom CA certs and keys.
curl -sL https://github.com/k3s-io/k3s/raw/main/contrib/util/generate-custom-ca-certs.sh | DATA_DIR=/opt/k3s bash -
# Load the updated CA certs and keys into the datastore.
k3s certificate rotate-ca --path=/opt/k3s/server`rotate-ca`コマンドがエラーを返した場合は、サービスログでエラーを確認してください。 コマンドが正常に完了した場合、クラスター内のすべてのノードでK3sを再起動します - まずサーバー、その後エージェント。
--force`オプションを使用した場合やルートCAを変更した場合は、セキュアトークンで参加したノードが、再起動する前に新しいトークン値を使用するように再構成されていることを確認してください。
トークンは、ノードが初期インストール中にどのように構成されたかに応じて、.env`ファイル、systemdユニット、またはconfig.yamlに保存される場合があります。
自己署名CA証明書のローテーション
K3sによって生成された自己署名CA証明書をローテーションするには、`k3s certificate rotate-ca`サブコマンドを使用します。 更新されたファイルは一時ディレクトリにステージングされ、データストアにロードされ、更新された証明書を使用するためにすべてのノードでk3sを再起動する必要があります。
|
現在使用中のデータを`/var/lib/rancher/k3s/server/tls`に上書きしてはいけません。 |
クラスターがデフォルトの自己署名CA証明書で起動された場合、ローテーションは破壊的になります。セキュアトークンで参加したすべてのノードは、新しいCAハッシュを信頼するように再構成する必要があります。 新しいCA証明書が古いCA証明書によってクロスサインされていない場合、整合性チェックをバイパスするために`--force`オプションを使用する必要があり、ポッドは新しいルートCAを信頼するために再起動する必要があります。
デフォルトCAトポロジー
デフォルトの自己署名CA証明書は、以下のトポロジーを持っています：
(control-plane and kubelet listeners)"]] kube-client-certs[["Kubernetes clients
(apiserver and kubelet clients)"]] request-header-certs[["Kubernetes API aggregation
(apiserver proxy client)"]] etcd-peer-certs[["etcd peer client/server
(etcd replication)"]] etcd-server-certs[["etcd client/server certificates
(Kubernetes <-> etcd)"]] server-ca -.-|SHA256| root-hash server-ca ===> kube-server-certs client-ca ===> kube-client-certs request-header-ca ===> request-header-certs etcd-peer-ca ===> etcd-peer-certs etcd-server-ca ===> etcd-server-certs
デフォルトの自己署名CAをローテーションする際には、中間CAと古いCAによってクロスサインされた新しいルートCAを持つ修正された証明書トポロジーを使用することができ、古いCAと新しいCAの間に信頼の連続したチェーンがあります：
(古い)") + client-ca-old("クライアントCA
(古い)") + request-header-ca-old("API集約CA
(古い)") + etcd-peer-ca-old("etcdピアCA
(古い)") + etcd-server-ca-old("etcdサーバーCA
(古い)") root-hash>"Join token CA hash"] server-ca-xsigned("サーバーCA
(クロスサイン済み)") + client-ca-xsigned("クライアントCA
(クロスサイン済み)") + request-header-ca-xsigned("API集約CA
(クロスサイン済み)") + etcd-peer-ca-xsigned("etcdピアCA
(クロスサイン済み)") + etcd-server-ca-xsigned("etcdサーバーCA
(クロスサイン済み)") server-ca-ssigned("Server CA
(self-signed)") client-ca-ssigned("Client CA
(self-signed)") request-header-ca-ssigned("API Aggregation CA
(self-signed)") etcd-peer-ca-ssigned("etcd Peer CA
(self-signed)") etcd-server-ca-ssigned("etcd Server CA
(self-signed)") server-ca("中間
サーバーCA") + client-ca("中間
クライアントCA") + request-header-ca("中間
API集約CA") + etcd-peer-ca("中間
etcdピアCA") + etcd-server-ca("中間
etcdサーバーCA") kube-server-certs[["Kubernetes servers
(control-plane and kubelet listeners)"]] kube-client-certs[["Kubernetes clients
(apiserver and kubelet clients)"]] request-header-certs[["Kubernetes API aggregation
(apiserver proxy client)"]] etcd-peer-certs[["etcd peer client/server
(etcd replication)"]] etcd-server-certs[["etcd client/server certificates
(Kubernetes <-> etcd)"]] server-ca-ssigned -.-|SHA256| root-hash + server-ca-ssigned --> server-ca ==> kube-server-certs + server-ca-old --> server-ca-xsigned --> server-ca + client-ca-ssigned --> client-ca ==> kube-client-certs + client-ca-old --> client-ca-xsigned --> client-ca + request-header-ca-ssigned --> request-header-ca ==> request-header-certs + request-header-ca-old --> request-header-ca-xsigned --> request-header-ca + etcd-peer-ca-ssigned --> etcd-peer-ca ==> etcd-peer-certs + etcd-peer-ca-old --> etcd-peer-ca-xsigned --> etcd-peer-ca + etcd-server-ca-ssigned --> etcd-server-ca ==> etcd-server-certs + etcd-server-ca-old --> etcd-server-ca-xsigned --> etcd-server-ca
例のスクリプトを使用する
既存のCAによってクロスサインされた更新済みのCA証明書とキーを作成するための例のスクリプトがhttps://github.com/k3s-io/k3s/blob/main/contrib/util/rotate-default-ca-certs.sh[K3sリポジトリの`contrib/util/rotate-default-ca-certs.sh`]にあります。
例のスクリプトを使用して、既存のCAによってクロスサインされた更新済みの自己署名証明書を生成するには、以下のコマンドを実行します。
# Create updated CA certs and keys, cross-signed by the current CAs.
# This script will create a new temporary directory containing the updated certs, and output the new token values.
curl -sL https://github.com/k3s-io/k3s/raw/main/contrib/util/rotate-default-ca-certs.sh | bash -
# Load the updated certs into the datastore; see the script output for the updated token values.
k3s certificate rotate-ca --path=/var/lib/rancher/k3s/server/rotate-ca`rotate-ca`コマンドがエラーを返した場合は、サービスログでエラーを確認してください。 コマンドが正常に完了した場合、クラスター内のすべてのノードでK3sを再起動します - まずサーバー、その後エージェント。
すべてのノード（他のサーバーノードを含む）で、セキュアトークンを使って参加した場合は、再起動する前に新しいトークン値を使用するように再構成してください。 トークンは、ノードが初期インストール中にどのように構成されたかに応じて、`.env`ファイル、systemdユニット、またはconfig.yamlに保存される場合があります。
サービスアカウント発行者キーのローテーション
サービスアカウント発行者キーは、サービスアカウントトークンに署名するために使用されるRSA秘密鍵です。 サービスアカウント発行者キーを回転させる際には、既存のサービスアカウントトークンが無効にならないよう、少なくとも1つの古いキーをファイルに保持しておく必要があります。 新旧のキーの両方を含む更新された`k3s certificate rotate-ca`ファイルのみをインストールするために、`service.key`を使用してクラスターCAとは独立して回転させることができます。
|
現在使用中のデータを`/var/lib/rancher/k3s/server/tls`に上書きしてはいけません。 |
例えば、サービスアカウント発行者キーのみを回転させるには、以下のコマンドを実行します：
# Create a temporary directory for cert generation
mkdir -p /opt/k3s/server/tls
# Check OpenSSL version
openssl version | grep -qF 'OpenSSL 3' && OPENSSL_GENRSA_FLAGS=-traditional
# Generate a new key
openssl genrsa ${OPENSSL_GENRSA_FLAGS:-} -out /opt/k3s/server/tls/service.key 2048
# Append the existing key to avoid invalidating current tokens
cat /var/lib/rancher/k3s/server/tls/service.key >> /opt/k3s/server/tls/service.key
# Load the updated key into the datastore
k3s certificate rotate-ca --path=/opt/k3s/server更新されていないファイルに対して警告が表示されるのは正常です。`rotate-ca`コマンドがエラーを返した場合は、サービスログでエラーを確認してください。 コマンドが正常に完了した場合、クラスター内のすべてのサーバーでK3sを再起動します。エージェントを再起動したり、ポッドを再起動したりする必要はありません。