証明書管理

クライアントおよびサーバー証明書

RKE2のクライアントおよびサーバー証明書は、発行日から365日間有効です。 期限切れまたは期限切れまで120日以内の証明書は、RKE2が起動するたびに自動的に更新されます。

この更新は既存のキーを再利用し、既存の証明書の有効期限を延長します。

既存の証明書の有効期限を延長するのではなく、新しい証明書とキーを生成したい場合は、以下に記載されているrotateサブコマンドを使用してください。

証明書が期限切れまで120日以内の場合、理由: CertificateExpirationWarning のKubernetes警告イベントが作成されます。

有効期限の確認

有効期限の確認

バージョンゲート

出力形式は、2025年1月のリリースから設定可能です：v1.32.0+rke2r1、v1.31.5+rke2r1、v1.30.9+rke2r1、v1.29.13+rke2r1。

2025年5月のリリースから、より多くの情報を含む新しい形式が利用可能です：v1.33.1+rke2r1、v1.32.5+rke2r1、v1.31.9+rke2r1、v1.30.13+rke2r1。

ノード証明書とその有効期限を確認するには、rke2 certificate check --output table を使用してください：

FILENAME                     SUBJECT                     USAGES       EXPIRES                  RESIDUAL TIME   STATUS
--------                     -------                     ------       -------                  -------------   ------
client-kube-proxy.crt        system:kube-proxy           ClientAuth   Jun 12, 2026 11:12 UTC   1 year          OK
client-kube-proxy.crt        rke2-client-ca@1749726675   CertSign     Jun 10, 2035 11:11 UTC   10 years        OK
client-kubelet.crt           system:node:ip-10-11-0-14   ClientAuth   Jun 12, 2026 11:12 UTC   1 year          OK
client-kubelet.crt           rke2-client-ca@1749726675   CertSign     Jun 10, 2035 11:11 UTC   10 years        OK
serving-kubelet.crt          ip-10-11-0-14               ServerAuth   Jun 12, 2026 11:12 UTC   1 year          OK
serving-kubelet.crt          rke2-server-ca@1749726675   CertSign     Jun 10, 2035 11:11 UTC   10 years        OK
client-rke2-controller.crt   system:rke2-controller      ClientAuth   Jun 12, 2026 11:12 UTC   1 year          OK
client-rke2-controller.crt   rke2-client-ca@1749726675   CertSign     Jun 10, 2035 11:11 UTC   10 years        OK
同じ証明書を2回

各証明書ファイル（FILENAME列）には、少なくとも2つの証明書が含まれています - リーフ（またはエンドエンティティ）クライアント/サーバー証明書、中間認証局証明書、およびルート認証局証明書。

予期しない出力がある場合は、--data-dir`フラグを使用して正しいデータディレクトリを指定していることを確認してください（カスタムデータディレクトリを使用している場合）、または--debug`フラグを使用してチェックプロセスから追加の出力を取得してください。

クライアントおよびサーバー証明書を手動でローテーションするには、サブコマンドを使用してください：

クライアントおよびサーバー証明書を手動でローテーションするには、`rke2 certificate rotate`サブコマンドを使用してください：

# Stop RKE2
systemctl stop rke2-server

# Rotate certificates
rke2 certificate rotate

# Start RKE2
systemctl start rke2-server

個別の証明書または証明書のリストは、証明書名を指定することでローテーションできます：

rke2 certificate rotate --service <SERVICE>,<SERVICE>

次の証明書をローテーションできます：admin, api-server, controller-manager, scheduler, rke2-controller, rke2-server, cloud-controller, etcd, auth-proxy, kubelet, kube-proxy。

バージョンゲート

2025年1月以前のリリース（v1.32.0+rke2r1、v1.31.5+rke2r1、v1.30.9+rke2r1、v1.30.13+rke2r1）では、証明書のローテーションは次の順序で行う必要があります：etcdサーバー、コントロールプレーンサーバー、エージェント。

認証局 (CA) 証明書

Kubernetes は適切な操作のためにいくつかの CA 証明書を必要とします。Kubernetes が CA 証明書をどのように使用するかについての詳細は、Kubernetes PKI 証明書と要件 ドキュメントを参照してください。

デフォルトでは、RKE2は最初のサーバーノードの起動時に自己署名のCA証明書を生成します。これらの CA 証明書は発行日から 10 年間有効であり、自動的には更新されません。

権威あるCA証明書とキーは、データストアの起動用キー内に保存され、サーバートークンをPBKDF2パスフレーズとしてAES256-GCMおよびHMAC-SHA1で暗号化されます。CA証明書とキーのコピーは、RKE2サーバーの起動時にディスクに抽出されます。任意のサーバーは、ノードがクラスターに参加する際にリーフ証明書を生成でき、Kubernetes 証明書 API コントローラーはランタイム中に追加の証明書を発行することがあります。

CA証明書のローテーション

CA証明書とキーをローテーションするには、`rke2 certificate rotate-ca`コマンドを使用してください。 このコマンドは、更新された証明書とキーが使用可能であることを確認するために整合性チェックを実行します。更新されたデータが受け入れ可能な場合、データストアの暗号化されたブートストラップキーが更新され、新しい証明書とキーは次回RKE2が起動する際に使用されます。証明書とキーの検証中に問題が発生した場合、エラーがシステムログに報告され、操作は変更なしでキャンセルされます。

カスタム CA 証明書の使用

CA 再利用に関する注意

ルートまたは中間 CA を複数のクラスターで共有したり、既存のプライベート CA をクラスター CA として使用することは推奨されません。

複数のクラスターが共通の信頼のルートを共有する場合、1 つのクラスターによって発行されたクライアントまたはサーバー証明書は、すべての他のクラスターでも信頼されます。すべての証明書は同じ信頼のアンカー - 共通の [Root] 証明書機関にチェーンされます。

これは、1つのクラスターに対して有効なクライアント証明書（またはkubeconfig）を持つユーザーが、他のクラスターにも認証できることを意味します。また、クライアントのユーザーまたはグループに一致するRBACは、他のクラスターでも適用されます。

同様に、1つのクラスターによって発行されたサーバー証明書も、すべての他のクラスターおよびそのルートCAを信頼するすべての他のインフラストラクチャやクライアントで信頼されます。

Kubernetesは証明書取り消しリストの使用をサポートしていません。

証明書を取り消す必要がある場合（たとえば、管理者のkubeconfigが侵害された場合など）、証明書の信頼を無効にするために、クラスターの証明書認証局を完全に置き換える必要があります。

カスタム CA 証明書の使用

クラスター内の最初のサーバーの初期起動時にCA証明書とキーが正しい場所に見つかった場合、CA証明書の自動生成はスキップされます。

適切な証明書とキーを事前に作成するための例のスクリプトは、 K3sリポジトリの`contrib/util/generate-custom-ca-certs.sh`にあります。このスクリプトはRKE2を初めて起動する前に実行する必要があり、一般的なルートおよび中間CA証明書によって署名された完全なセットのリーフCA証明書を作成します。既存のルートまたは中間CAがある場合、このスクリプトを使用して（または出発点として使用して）既存の権限に基づいてPKIでRKE2クラスターをプロビジョニングするための正しいCA証明書を作成できます。

カスタム証明書認証局ファイルは`/var/lib/rancher/rke2/server/tls`に配置する必要があります。次のファイルが必要です：

  • server-ca.crt

  • server-ca.key

  • client-ca.crt

  • client-ca.key

  • request-header-ca.crt

  • request-header-ca.key

  • etcd/peer-ca.crt

  • etcd/peer-ca.key

  • etcd/server-ca.crt

  • etcd/server-ca.key（これはサービスアカウントトークンに署名するために使用される秘密鍵です。対応する証明書はありません。）

  • service.key

カスタムCAトポロジー

例のスクリプトによって生成されたカスタムCA証明書は、次のトポロジーを持っています：

graph TD root("ルートCA") intermediate("中間CA") server-ca("サーバーCA") client-ca("クライアントCA") request-header-ca("API集約CA") etcd-peer-ca("etcdピアCA") etcd-server-ca("etcdサーバーCA") root-hash>"Join token CA hash"] 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)"]] 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を使用する場合などの高度な使用ケースでは、例のスクリプトを組織の特定のニーズに合わせて修正する必要があります。

RKE2を開始する前にカスタム証明書とキーを生成するために例のスクリプトを使用するには、次のコマンドを実行してください：

# Create the target directory for cert generation.
mkdir -p /var/lib/rancher/rke2/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/rke2/server/tls

# Generate custom CA certs and keys.
curl -sL https://github.com/k3s-io/k3s/raw/master/contrib/util/generate-custom-ca-certs.sh | PRODUCT=rke2 bash -

コマンドが正常に完了した場合、初めてRKE2をインストールおよび/または開始できます。スクリプトがルートおよび/または中間CAファイルを生成した場合、後日CA証明書をローテーションする必要が生じた際に再利用できるよう、これらのファイルをバックアップする必要があります。

カスタムCA証明書のローテーション

カスタムCA証明書をローテーションするには、`rke2 certificate rotate-ca`サブコマンドを使用してください。更新されたファイルは一時ディレクトリにステージングされ、データストアにロードされ、更新された証明書を使用するためにすべてのノードでRKE2を再起動する必要があります。

現在使用中のデータを`/var/lib/rancher/rke2/server/tls`に上書きしてはいけません。更新された証明書とキーを別のディレクトリにステージングしてください。

カスタムCA証明書で開始されたクラスターは、同じルートCAが使用されている限り、CA証明書とキーを非破壊的に更新またはローテーションすることができます。

新しいルートCAが必要な場合、ローテーションは破壊的になります。`rke2 certificate rotate-ca --force`オプションを使用する必要があり、すべてのノード（サーバーとエージェント）は新しいトークン値を使用するように再構成する必要があり、ポッドは新しいルートCAを信頼できるように再起動する必要があります。

例のスクリプトを使用する

上記の例の`generate-custom-ca-certs.sh`スクリプトも、新しい一時ディレクトリで更新された証明書を生成するために使用でき、ファイルを正しい場所にコピーし、`DATA_DIR`環境変数を設定します。更新された証明書とキーを生成するために例のスクリプトを使用するには、次のコマンドを実行してください：

# Create a temporary directory for cert generation.
mkdir -p /opt/rke2/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/rke2/server/tls/root-ca.* /var/lib/rancher/rke2/server/tls/intermediate-ca.* /opt/rke2/server/tls

# Copy the current service-account signing key, so that existing service-account tokens are not invalidated.
cp /var/lib/rancher/rke2/server/tls/service.key /opt/rke2/server/tls

# Generate updated custom CA certs and keys.
curl -sL https://github.com/k3s-io/k3s/raw/master/contrib/util/generate-custom-ca-certs.sh | DATA_DIR=/opt/rke2 PRODUCT=rke2 bash -

# Load the updated CA certs and keys into the datastore.
rke2 certificate rotate-ca --path=/opt/rke2/server

`rotate-ca`コマンドがエラーを返した場合は、サービスログでエラーを確認してください。コマンドが正常に完了した場合、クラスター内のすべてのノードでRKE2を再起動します - まずサーバー、その後エージェント。

--force`オプションを使用した場合やルートCAを変更した場合は、セキュアトークンで参加したノードが再起動する前に新しいトークン値を使用するように再構成されていることを確認してください。トークンは、ノードが初期インストール中にどのように構成されたかに応じて、.env`ファイル、systemdユニット、またはconfig.yamlに保存される場合があります。

自己署名CA証明書のローテーション

RKE2によって生成された自己署名CA証明書をローテーションするには、`rke2 certificate rotate-ca`サブコマンドを使用します。 更新されたファイルは一時ディレクトリにステージングされ、データストアにロードされ、更新された証明書を使用するためにすべてのノードでRKE2を再起動する必要があります。

現在使用中のデータを`/var/lib/rancher/rke2/server/tls`に上書きしてはいけません。更新された証明書とキーを別のディレクトリにステージングしてください。

クラスターがデフォルトの自己署名CA証明書で起動された場合、ローテーションは破壊的になります。セキュアトークンで参加したすべてのノードは、新しいCAハッシュを信頼するように再構成する必要があります。 新しいCA証明書が古いCA証明書によってクロスサインされていない場合、整合性チェックをバイパスするために`--force`オプションを使用する必要があり、ポッドは新しいルートCAを信頼するために再起動する必要があります。

デフォルトCAトポロジー

デフォルトの自己署名CA証明書は、以下のトポロジーを持っています：

graph TD + server-ca("サーバーCA") + client-ca("クライアントCA") + request-header-ca("API集約CA") + etcd-peer-ca("etcdピアCA") + etcd-server-ca("etcdサーバーCA") root-hash>"Join token CA hash"] 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 -.-|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の間に信頼の連続したチェーンがあります：

graph TD + server-ca-old("サーバー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証明書とキーを作成するための例のスクリプトが 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/master/contrib/util/rotate-default-ca-certs.sh | PRODUCT=rke2 bash -

# Load the updated certs into the datastore; see the script output for the updated token values.
rke2 certificate rotate-ca --path=/var/lib/rancher/rke2/server/rotate-ca

`rotate-ca`コマンドがエラーを返した場合は、サービスログでエラーを確認してください。コマンドが正常に完了した場合、クラスター内のすべてのノードでRKE2を再起動します - まずサーバー、その後エージェント。

セキュアトークンで参加したノード（他のサーバーノードを含む）は、再起動する前に新しいトークン値を使用するように再構成してください。トークンは、ノードが初期インストール中にどのように構成されたかに応じて、`.env`ファイル、systemdユニット、またはconfig.yamlに保存される場合があります。

サービスアカウント発行者キーのローテーション

サービスアカウント発行者キーは、サービスアカウントトークンに署名するために使用されるRSA秘密鍵です。サービスアカウント発行者キーを回転させる際には、既存のサービスアカウントトークンが無効にならないよう、少なくとも1つの古いキーをファイルに保持しておく必要があります。`rke2 certificate rotate-ca`を使用して、新旧のキーの両方を含む更新された`service.key`ファイルのみをインストールすることで、クラスターCAとは独立してローテーションできます。

現在使用中のデータを`/var/lib/rancher/rke2/server/tls`に上書きしてはいけません。更新されたキーを別のディレクトリに配置します。

例えば、サービスアカウント発行者キーのみを回転させるには、以下のコマンドを実行します：

# Create a temporary directory for cert generation
mkdir -p /opt/rke2/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/rke2/server/tls/service.key 2048

# Append the existing key to avoid invalidating current tokens
cat /var/lib/rancher/rke2/server/tls/service.key >> /opt/rke2/server/tls/service.key

# Load the updated key into the datastore
rke2 certificate rotate-ca --path=/opt/rke2/server

更新されていないファイルに対して警告が表示されるのは正常です。`rotate-ca`コマンドがエラーを返した場合は、サービスログでエラーを確認してください。コマンドが正常に完了した場合、クラスター内のすべてのサーバーでRKE2を再起動します。エージェントを再起動したり、ポッドを再起動したりする必要はありません。