跳至主要内容

k3s 证书

客户端和服务器证书​

K3s 客户端和服务器证书从颁发之日起有效期为 365 天。任何已过期或将在 90 天内过期的证书都会在每次 K3s 启动时自动续订。

轮换客户端和服务器证书​

要手动轮换客户端和服务器证书，请使用 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 启动时将使用新的证书和密钥。如果在验证证书和密钥时遇到问题，则会向系统日志报告错误，并且操作将取消，而不会进行任何更改。

版本门

从 2023-02 版本（v1.26.2+k3s1、v1.25.7+k3s1、v1.24.11+k3s1、v1.23.17+k3s1）开始，支持 k3s certificate rotate-ca 命令以及使用外部 CA 签名的 CA 证书的功能。

使用自定义 CA 证书​

如果在集群中第一个服务器的初始启动期间在正确的位置找到 CA 证书和密钥，则将绕过 CA 证书的自动生成。

在K3s 存储库的 contrib/util/generate-custom-ca-certs.sh中提供了一个用于预创建相应证书和密钥的示例脚本。此脚本应在首次启动 K3s 之前运行，并将创建由常用根和中间 CA 证书签名的完整的一组叶子 CA 证书。如果您有现有的根或中间 CA，则可以使用此脚本（或将其用作起点）来创建正确的 CA 证书，以使用根植于现有颁发机构的 PKI 来配置 K3s 集群。

自定义证书颁发机构文件必须放在 /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 证书应遵循以下拓扑结构

使用示例脚本​

重要

如果您想使用现有的根 CA 对集群 CA 证书进行签名，请在运行脚本之前将根和中间文件放置在目标目录中。如果文件不存在，脚本将创建新的根和中间 CA 证书。

如果您只想使用现有的根 CA 证书，请提供以下文件

  • root-ca.pem
  • root-ca.key

如果您想使用现有的根和中间 CA 证书，请提供以下文件

  • root-ca.pem
  • intermediate-ca.pem
  • intermediate-ca.key

要使用示例脚本在启动 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/master/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 选项，使用安全令牌加入的所有节点（包括服务器）都需要重新配置以使用新的令牌值，并且需要重新启动 pod 以信任新的根 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/master/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 选项绕过完整性检查，并且需要重新启动 pod 以信任新的根 CA。

默认 CA 拓扑​

默认的自签名 CA 证书具有以下拓扑结构

在轮换默认的自签名 CA 时，可以使用具有中间 CA 和由旧 CA 交叉签名的新的根 CA 的修改后的证书拓扑，以便在旧 CA 和新 CA 之间存在连续的信任链。

使用示例脚本​

在K3s 存储库的 contrib/util/rotate-default-ca-certs.sh中提供了一个用于创建由现有 CA 交叉签名的更新的 CA 证书和密钥的示例脚本。

要使用示例脚本生成由现有 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 | 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 私钥。在轮换服务账户颁发者密钥时，应至少保留一个旧密钥在文件中，以防止现有服务账户令牌失效。可以通过使用 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。无需重新启动代理或任何 Pod。