kubectl apply

了解如何使用 kubectl 和靜態清單安裝 cert-manager。

先決條件

安裝 kubectl 版本 >= v1.19.0。(否則，更新 CRD 時會發生問題 - 請參閱v0.16 升級注意事項)
安裝支援的 Kubernetes 或 OpenShift 版本。
如果您在雲端平台上使用 Kubernetes，請閱讀與 Kubernetes 平台供應商的相容性。

步驟

1. 從 cert-manager 發行清單安裝

所有資源（CustomResourceDefinitions 以及 cert-manager、cainjector 和 webhook 元件）都包含在單一 YAML 清單檔案中

安裝所有 cert-manager 元件

kubectl apply -f https://github.com/cert-manager/cert-manager/releases/download/v1.16.1/cert-manager.yaml

依預設，cert-manager 將會安裝到 cert-manager 命名空間中。也可以在不同的命名空間中執行 cert-manager，不過您需要修改部署清單。

安裝 cert-manager 後，您可以檢查 cert-manager 命名空間是否有正在執行的 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、cert-manager-cainjector 和 cert-manager-webhook pod 處於 Running 狀態。Webhook 可能需要比其他元件多一點時間才能成功佈建。

如果遇到問題，請先查看常見問題。

2. (選用) 等待 cert-manager webhook 準備就緒

webhook 元件可能需要一些時間才能啟動，並使 Kubernetes API 伺服器信任 webhook 的憑證。

首先，請確認已安裝 cmctl。

cmctl 會針對 Kubernetes 叢集執行憑證建立的預先執行檢查。如果成功，將會顯示訊息 The cert-manager API is ready。

$ cmctl check api
The cert-manager API is ready

該命令也可以用來等待檢查成功。以下是在安裝 cert-manager 的同時執行該命令的輸出範例

$ cmctl check api --wait=2m
Not ready: the cert-manager CRDs are not yet installed on the Kubernetes API server
Not ready: the cert-manager CRDs are not yet installed on the Kubernetes API server
Not ready: the cert-manager webhook deployment is not ready yet
Not ready: the cert-manager webhook deployment is not ready yet
Not ready: the cert-manager webhook deployment is not ready yet
Not ready: the cert-manager webhook deployment is not ready yet
The cert-manager API is ready

2. (選用) 端對端驗證安裝

完整驗證安裝的最佳方法是發出測試憑證。為此，我們將在測試命名空間中建立一個自我簽署的簽發者和憑證資源。

cat <<EOF > test-resources.yaml
apiVersion: v1
kind: Namespace
metadata:
  name: cert-manager-test
---
apiVersion: cert-manager.io/v1
kind: Issuer
metadata:
  name: test-selfsigned
  namespace: cert-manager-test
spec:
  selfSigned: {}
---
apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
  name: selfsigned-cert
  namespace: cert-manager-test
spec:
  dnsNames:
    - example.com
  secretName: selfsigned-cert-tls
  issuerRef:
    name: test-selfsigned
EOF

建立測試資源。

kubectl apply -f test-resources.yaml

檢查新建立的憑證狀態。您可能需要等待幾秒鐘，cert-manager 才會處理憑證請求。

$ kubectl describe certificate -n cert-manager-test

...
Spec:
  Common Name:  example.com
  Issuer Ref:
    Name:       test-selfsigned
  Secret Name:  selfsigned-cert-tls
Status:
  Conditions:
    Last Transition Time:  2019-01-29T17:34:30Z
    Message:               Certificate is up to date and has not expired
    Reason:                Ready
    Status:                True
    Type:                  Ready
  Not After:               2019-04-29T17:34:29Z
Events:
  Type    Reason      Age   From          Message
  ----    ------      ----  ----          -------
  Normal  CertIssued  4s    cert-manager  Certificate issued successfully

清除測試資源。

kubectl delete -f test-resources.yaml

如果上述所有步驟都已完成且沒有錯誤，表示您已準備就緒！

解除安裝

警告：若要解除安裝 cert-manager，您應該始終使用與安裝相同的流程，但反向執行。無論 cert-manager 是從靜態清單還是 Helm 安裝，偏離以下流程都可能導致問題和潛在的損壞狀態。請務必在解除安裝時遵循以下步驟，以避免發生這種情況。

在繼續之前，請確保已刪除使用者建立的未經請求的 cert-manager 資源。您可以使用以下命令檢查是否有任何現有的資源

kubectl get Issuers,ClusterIssuers,Certificates,CertificateRequests,Orders,Challenges --all-namespaces

建議您在解除安裝 cert-manager 之前刪除所有這些資源。如果您計畫稍後重新安裝且不想遺失某些自訂資源，您可以保留它們。但是，這可能會導致終結器出現問題。有些資源（例如 Challenges）應該刪除，以避免停留在擱置狀態。

刪除不需要的資源後，您就可以使用您安裝時所決定的程序來解除安裝 cert-manager。

警告：解除安裝 cert-manager 或僅刪除 Certificate 資源可能會導致 TLS Secret 因為它們的 metadata.ownerReferences 是由 cert-manager 設定而被刪除。您可以使用 --enable-certificate-owner-ref 控制器旗標來控制是否將擁有者參考新增至 Secret。依預設，此旗標設定為 false，這表示不會新增任何擁有者參考。但是，在 cert-manager v1.8 及更舊的版本中，將旗標的值從 true 變更為 false 不會導致移除現有的擁有者參考。此行為已在 cert-manager v1.8 中修正。請檢查擁有者參考以確認它們是否確實已移除。

使用一般清單解除安裝

從使用一般清單的安裝解除安裝，是使用 kubectl 的 delete 命令，反向執行安裝流程。

使用連結到您目前執行版本的 vX.Y.Z，刪除安裝清單，如下所示

警告：此命令也會移除已安裝的 cert-manager CRD。所有 cert-manager 資源（例如 certificates.cert-manager.io 資源）都將由 Kubernetes 的垃圾收集器移除。如果您刪除 CustomResourceDefinition，則無法保留任何自訂資源。如果您想保留資源，則應該個別管理 CustomResourceDefinition。

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

命名空間停留在終止狀態

如果命名空間已標記為刪除，但沒有先刪除 cert-manager 安裝，則命名空間可能會停留在終止狀態。這通常是因為 APIService 資源仍然存在，但 webhook 不再執行，因此無法存取。若要解決此問題，請確保您已正確執行上述命令，如果仍然遇到問題，請執行

kubectl delete apiservice v1beta1.webhook.cert-manager.io

刪除擱置中的挑戰

當終結器無法完成且 Kubernetes 等待 cert-manager 控制器完成時，Challenge 會停留在擱置狀態。當控制器不再執行以移除旗標時，且資源被定義為需要等待時，就會發生這種情況。您可以使用控制器手動執行的動作來修正此問題。

首先，刪除現有的 cert-manager webhook 設定 (如果有的話)

kubectl delete mutatingwebhookconfigurations cert-manager-webhook
kubectl delete validatingwebhookconfigurations cert-manager-webhook

然後，編輯挑戰資源，將 .metadata.finalizers 欄位變更為空白清單

kubectl edit challenge <the-challenge>