本文档采用自动化机器翻译技术翻译。 尽管我们力求提供准确的译文，但不对翻译内容的完整性、准确性或可靠性作出任何保证。 若出现任何内容不一致情况，请以原始 英文 版本为准，且原始英文版本为权威文本。

升级 Cert-Manager

Rancher 兼容 API 版本 cert-manager.io/v1，并且最后一次测试的 cert-manager 版本是 v1.13.1。

Rancher 使用 cert-manager 自动生成和续订 Rancher 的 HA 部署的 TLS 证书。截至 2019 年秋季，cert-manager 将发生三项重要更改，如果您有 Rancher 的 HA 部署，您需要采取行动：

  1. Let’s Encrypt 将从 2019 年 11 月 1 日开始阻止低于 0.8.0 的 cert-manager 实例。

  2. Cert-manager 正在弃用并替换 certificate.spec.acme.solvers 字段。此更改没有确切的截止日期。

  3. Cert-manager 正在弃用 v1alpha1 API 并替换其 API 组

为了解决这些更改，本指南将做两件事：

  1. 记录升级 cert-manager 的过程

  2. 解释 cert-manager API 的更改，并链接到 cert-manager 的官方文档以迁移您的数据

重要说明：

如果您是从 1.5 之前的版本升级到最新版本的 cert-manager，请按照下面 选项 C 中的步骤进行。请注意，您无需重新安装 Rancher 即可执行此升级。

升级 Cert-Manager

这些说明中使用的名称空间取决于 cert-manager 当前安装的名称空间。如果它在 kube-system 中，请在下面的说明中使用该命名空间。您可以通过运行 kubectl get pods --all-namespaces 并检查 cert-manager-* pods 列出在哪个名称空间中来验证。请勿更改 cert-manager 运行的名称空间，否则可能会导致问题。

为了升级 cert-manager，请按照以下说明进行：

选项 A:使用互联网访问升级 cert-manager

点击展开

  1. 作为预防措施备份现有资源

     kubectl get -o yaml --all-namespaces \
 issuer,clusterissuer,certificates,certificaterequests > cert-manager-backup.yaml
    重要说明：

    如果您从版本低于 0.11.0 升级，请将所有备份资源的 apiVersion 从 certmanager.k8s.io/v1alpha1 更新为 cert-manager.io/v1alpha2。如果您在其他资源上使用了任何 cert-manager 注释，您需要更新它们以反映新的 API 组。有关详细信息，请参阅 附加注释更改的文档。

  2. 卸载现有部署

     helm uninstall cert-manager

    使用您安装的版本 vX.Y.Z 的链接删除 CustomResourceDefinition

     kubectl delete -f https://github.com/cert-manager/cert-manager/releases/download/vX.Y.Z/cert-manager.crds.yaml

  3. 单独安装 CustomResourceDefinition 资源

     kubectl apply --validate=false -f https://github.com/cert-manager/cert-manager/releases/download/vX.Y.Z/cert-manager.crds.yaml

    如果您正在运行 Kubernetes v1.15 或更低版本，您需要在上述 kubectl apply 命令中添加 --validate=false 标志。否则，您将收到与 cert-manager 的 CustomResourceDefinition 资源中的 x-kubernetes-preserve-unknown-fields 字段相关的验证错误。这是一个良性的错误，发生是由于 kubectl 执行资源验证的方式。

  4. 如有需要，为 cert-manager 创建名称空间。

     kubectl create namespace cert-manager

  5. 添加 Jetstack Helm 储存库

     helm repo add jetstack https://charts.jetstack.io

  6. 更新您的本地 Helm 图表仓库缓存

    helm repo update

  7. 安装新版本的 cert-manager

     helm install \
   cert-manager jetstack/cert-manager \
   --namespace cert-manager

  8. 恢复备份资源

     kubectl apply -f cert-manager-backup.yaml

选项 B：在隔离环境中升级 cert-manager

点击展开

=== 先决条件

在您执行升级之前，您必须通过将必要的容器镜像添加到您的私有注册表并下载或呈现所需的 Kubernetes 清单文件来准备您的隔离环境。

  1. 按照指南准备您的私有注册表所需的镜像进行升级。

  2. 从连接到互联网的系统中，将 cert-manager 储存库添加到 Helm。

     helm repo add jetstack https://charts.jetstack.io
 helm repo update

  3. 从 Helm chart 储存库获取最新的 cert-manager chart。

     helm fetch jetstack/cert-manager

  4. 使用您希望用于安装 chart 的选项渲染 cert manager 模板。请记得将选项设置为从您的私有注册表中拉取镜像。这将创建一个包含 Kubernetes 清单文件的目录。

    Helm 3 命令如下：

     helm template cert-manager ./cert-manager-v0.12.0.tgz --output-dir . \
 --namespace cert-manager \
 --set image.repository=<REGISTRY.YOURDOMAIN.COM:PORT>/quay.io/jetstack/cert-manager-controller
 --set webhook.image.repository=<REGISTRY.YOURDOMAIN.COM:PORT>/quay.io/jetstack/cert-manager-webhook
 --set cainjector.image.repository=<REGISTRY.YOURDOMAIN.COM:PORT>/quay.io/jetstack/cert-manager-cainjector

  5. 下载 cert-manager 所需的 CRD 文件（旧版和新版）。

     curl -L -o cert-manager-crd.yaml https://raw.githubusercontent.com/cert-manager/cert-manager/release-0.12/deploy/manifests/00-crds.yaml
 curl -L -o cert-manager/cert-manager-crd-old.yaml https://raw.githubusercontent.com/cert-manager/cert-manager/release-X.Y/deploy/manifests/00-crds.yaml

=== 安装 cert-manager。

  1. 作为预防措施备份现有资源。

     kubectl get -o yaml --all-namespaces \
 issuer,clusterissuer,certificates,certificaterequests > cert-manager-backup.yaml
    重要说明：

    如果您从版本低于 0.11.0 升级，请将所有备份资源的 apiVersion 从 certmanager.k8s.io/v1alpha1 更新为 cert-manager.io/v1alpha2。如果您在其他资源上使用了任何 cert-manager 注释，您需要更新它们以反映新的 API 组。有关详细信息，请参阅 附加注释更改的文档。

  2. 删除现有的 cert-manager 安装。

     kubectl -n cert-manager \
 delete deployment,sa,clusterrole,clusterrolebinding \
 -l 'app=cert-manager' -l 'chart=cert-manager-v0.5.2'

    使用您安装的 vX.Y 版本的链接删除 CustomResourceDefinition。

     kubectl delete -f cert-manager/cert-manager-crd-old.yaml

  3. 单独安装 CustomResourceDefinition 资源

     kubectl apply -f cert-manager/cert-manager-crd.yaml
    重要说明：

    如果您正在运行 Kubernetes v1.15 或更低版本，您需要在上述 kubectl apply 命令中添加 --validate=false 标志。否则，您将收到与 cert-manager 的 CustomResourceDefinition 资源中的 x-kubernetes-preserve-unknown-fields 字段相关的验证错误。这是一个良性的错误，发生是由于 kubectl 执行资源验证的方式。

  4. 为 cert-manager 创建名称空间。

     kubectl create namespace cert-manager

  5. 安装 cert-manager。

     kubectl -n cert-manager apply -R -f ./cert-manager

  6. 恢复备份资源

     kubectl apply -f cert-manager-backup.yaml

选项 C：从版本 1.5 及以下升级 cert-manager。

点击展开

之前，为了从旧版本升级 cert-manager，建议卸载并重新安装 Rancher。使用以下方法，您可以在不进行额外步骤的情况下升级 cert-manager，以更好地保护您的生产环境：

  1. 使用安装指南安装 cert-manager CLI 工具。

  2. 确保任何可能已存储在过时 API 版本的 etcd 中的 cert-manager 自定义资源迁移到 v1：

     cmctl upgrade migrate-api-version

    有关更多信息，请参阅 API 版本迁移文档。如有需要，请参阅 文档以从 1.5 升级到 1.6 和 文档以从 1.6 升级到 1.7。

  3. 使用正常的 helm upgrade 升级 cert-manager 到 v1.7.1。如果需要，您可以直接从版本 1.5 升级到 1.7。

  4. 按照 Helm 教程 更新发布清单的 API 版本。图表发布名称为 release_name=rancher，发布名称空间为 release_namespace=cattle-system。

  5. 在解码的文件中，搜索 cert-manager.io/v1beta1 并 将其替换 为 cert-manager.io/v1。

  6. 正常使用 helm upgrade 升级 Rancher。

验证部署

安装 cert-manager 后，您可以通过检查 kube-system 命名空间中的运行中的 pod 来验证其是否正确部署：

kubectl get pods --namespace cert-manager

NAME                                       READY   STATUS    RESTARTS   AGE
cert-manager-5c6866597-zw7kh               1/1     Running   0          2m
cert-manager-cainjector-577f6d9fd7-tr77l   1/1     Running   0          2m
cert-manager-webhook-787858fcdb-nlzsq      1/1     Running   0          2m

Cert-Manager API 更改和数据迁移

Rancher 现在支持 cert-manager 版本 1.6.2 和 1.7.1。我们推荐使用 v1.7.x，因为 v1.6.x 将于 2022 年 3 月 30 日终止服务。要了解更多信息，请参阅 cert-manager 文档。有关从版本 1.5 升级 cert-manager 到 1.6 的说明，请参阅上游 cert-manager 文档 在这里。有关从版本 1.6 升级 cert-manager 到 1.7 的说明，请参阅上游 cert-manager 文档 在这里。

Cert-manager 已弃用 certificate.spec.acme.solvers 字段的使用，并将在即将发布的版本中完全停止支持。

根据 cert-manager 文档，v0.8 引入了配置 ACME 证书资源的新格式。具体来说，挑战求解器配置字段已被移动。自 v0.9 起，旧格式和新格式均受支持，但旧格式的支持将在 cert-manager 的即将发布版本中被取消。cert-manager 文档强烈建议在升级后更新您的 ACME 发行者和证书资源为新格式。

有关更改和迁移说明的详细信息可以在 cert-manager v0.7到v0.8的升级说明中找到。

v0.11版本标志着v1alpha1 API的移除，该API在之前的cert-manager版本中使用，同时我们的API组也更改为cert-manager.io，而不是certmanager.k8s.io。

我们还移除了在v0.8版本中被弃用的旧配置格式的支持。这意味着在升级到v0.11之前，您必须过渡到使用新的求解器样式配置格式来配置您的ACME发行者。有关更多信息，请参见 升级到v0.8的指南。

有关更改和迁移说明的详细信息可以在 cert-manager v0.10到v0.11的升级说明中找到。

有关 cert-manager升级信息的更多信息。