跳至主要内容

升級 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-* Pod 列在哪個命名空間來驗證。請勿更改 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 Chart 儲存庫快取

    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 範本。請記住設定 image.repository 選項以從您的私有註冊表拉取映像。這將建立一個包含 Kubernetes 清單檔案的 cert-manager 目錄。

    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
    Helm 2 已棄用

    Helm 2 不再受支援。請改用 Helm 3。

    Helm 2 指令如下：

    helm template ./cert-manager-v0.12.0.tgz --output-dir . \
    --name cert-manager --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. 使用安裝指南安裝 cmctl，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 版本。Chart 發布名稱為 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 Issuer 和 Certificate 資源更新為新格式。

有關變更和遷移說明的詳細資訊，請參閱 cert-manager v0.7 到 v0.8 升級說明。

v0.11 版本標誌著移除了在先前版本的 cert-manager 中使用的 v1alpha1 API，以及我們的 API 群組變更為 cert-manager.io 而不是 certmanager.k8s.io。

我們還移除了對 v0.8 版本中棄用的舊設定格式的支援。這意味著在升級到 v0.11 之前，您必須過渡到為您的 ACME 發行者使用新的解決器樣式設定格式。有關更多資訊，請參閱升級到 v0.8 指南。

有關變更和遷移說明的詳細資訊，請參閱 cert-manager v0.10 到 v0.11 升級說明。

有關 cert-manager 升級資訊的更多資訊。