cert-manager 命令列工具 (cmctl)

cmctl 是一個命令列工具，可協助您管理 cert-manager 及其叢集內的資源。

📢 cert-manager CLI 正在移至新的 GitHub 儲存庫

cert-manager 團隊已決定將 cmctl 程式碼移至新的 GitHub 儲存庫。這將使我們能夠獨立於 cert-manager 發布 cmctl 的新功能和錯誤修復。它將簡化 cert-manager 的 Go 套件相依性，因此 cert-manager 的安全性修補程式版本應該會減少。這將使我們更容易擴展 cmctl 的功能，以管理 trust-manager 和 approver-policy。這也將使我們能夠為 cmctl 撰寫更多 E2E 測試，而不會進一步減慢 cert-manager 的測試套件速度。

⚠️ cert-manager 1.14 是最後一個仍包含 cert-manager-ctl 容器映像檔、go 套件和 GitHub 發行二進位檔的版本。

請造訪 GitHub 上的新 cmctl 儲存庫以瞭解更多資訊。

安裝

Homebrew

如果您在 Mac 或 Linux 上安裝了 Homebrew，您可以使用以下命令安裝 cmctl

brew install cmctl

這也會安裝 shell 完成。

手動安裝

您需要您所使用平台的 cmctl 檔案，這些檔案可以在我們的 cmctl GitHub 發行頁面上找到。為了使用 cmctl，您需要其二進位檔在您的 $PATH 中以 cmctl 的名稱存取。請執行下列命令來設定 CLI。請將 OS 和 ARCH 替換為您系統的對等項目

OS=$(go env GOOS); ARCH=$(go env GOARCH); curl -fsSL -o cmctl https://github.com/cert-manager/cmctl/releases/latest/download/cmctl_${OS}_${ARCH}
chmod +x cmctl
sudo mv cmctl /usr/local/bin

或者，您可以使用 go 安裝 cmctl

go install github.com/cert-manager/cmctl/v2@latest

您可以執行 cmctl help 來測試 CLI 是否已正確設定

$ cmctl help

cmctl is a CLI tool manage and configure cert-manager resources for Kubernetes

Usage: cmctl [command]

Available Commands:
  approve      Approve a CertificateRequest
  check        Check cert-manager components
  completion   Generate completion scripts for the cert-manager CLI
  convert      Convert cert-manager config files between different API versions
  create       Create cert-manager resources
  deny         Deny a CertificateRequest
  experimental Interact with experimental features
  help         Help about any command
  inspect      Get details on certificate related resources
  renew        Mark a Certificate for manual renewal
  status       Get details on current status of cert-manager resources
  upgrade      Tools that assist in upgrading cert-manager
  version      Print the cert-manager CLI version and the deployed cert-manager version

Flags:
  -h, --help                           help for cmctl
      --log-flush-frequency duration   Maximum number of seconds between log flushes (default 5s)

Use "cmctl [command] --help" for more information about a command.

還有一個舊版 kubectl 外掛程式，但不建議使用，因為獨立的 cmctl 二進位檔提供更好的自動完成。

命令

核准與拒絕 CertificateRequests (憑證請求)

可以使用它們各自的 cmctl 命令核准或拒絕 CertificateRequests。

注意：除非使用 cert-manager-controller 上的旗標 --controllers=*,-certificaterequests-approver 停用，否則內部 cert-manager 核准者可能會自動核准所有 CertificateRequests。

$ cmctl approve -n istio-system mesh-ca --reason "pki-team" --message "this certificate is valid"
Approved CertificateRequest 'istio-system/mesh-ca'

$ cmctl deny -n my-app my-app --reason "example.com" --message "violates policy"
Denied CertificateRequest 'my-app/my-app'

轉換

cmctl convert 可用於在不同的 API 版本之間轉換 cert-manager 資訊清單檔案。接受 YAML 和 JSON 格式。此命令接受檔案名稱、目錄路徑或 URL 作為輸入。內容會轉換為 cert-manager 已知的最新 API 版本格式，或由 --output-version 旗標指定的格式。

預設輸出將以 YAML 格式列印到標準輸出。可以使用選項 -o 來變更輸出目的地。

例如，這將以最新的 API 版本輸出 cert.yaml

cmctl convert -f cert.yaml

建立

cmctl create 可用於手動建立 cert-manager 資源。有子命令可用於建立不同的資源

CertificateRequest

若要建立 cert-manager CertificateRequest，請使用 cmctl create certificaterequest。此命令會接收要建立的 CertificateRequest 名稱，並根據 --from-certificate-file 旗標指定的憑證資源 YAML 資訊清單建立新的 CertificateRequest 資源，方法是在本機產生私密金鑰，並建立要提交至 cert-manager Issuer 的「憑證簽署請求」。私密金鑰將寫入本機檔案，預設值為 <cr_name>.key，或者可以使用 --output-key-file 旗標指定。

如果您希望等待 CertificateRequest 簽署並將 X.509 憑證儲存在檔案中，您可以設定 --fetch-certificate 旗標。等待憑證簽發的預設逾時為 5 分鐘，但可以使用 --timeout 旗標指定。儲存 X.509 憑證的檔案的預設名稱為 <cr_name>.crt，您可以使用 --output-certificate-file 旗標指定其他名稱。

請注意，私密金鑰和 X.509 憑證都會寫入檔案，而不會儲存在 Kubernetes 內。

例如，這將基於 my-certificate.yaml 中描述的 cert-manager 憑證建立名稱為「my-cr」的 CertificateRequest 資源，同時將私密金鑰和 X.509 憑證分別儲存在 my-cr.key 和 my-cr.crt 中。

cmctl create certificaterequest my-cr --from-certificate-file my-certificate.yaml --fetch-certificate --timeout 20m

更新

cmctl 允許您手動觸發特定憑證的更新。這可以一次更新一個憑證，使用標籤選擇器（-l app=example），或使用 --all 標誌。

例如，您可以更新憑證 example-com-tls。

$ kubectl get certificate
NAME                       READY   SECRET               AGE
example-com-tls            True    example-com-tls      1d

$ cmctl renew example-com-tls
Manually triggered issuance of Certificate default/example-com-tls

$ kubectl get certificaterequest
NAME                              READY   AGE
example-com-tls-tls-8rbv2         False    10s

您也可以更新給定命名空間中的所有憑證。

$ cmctl renew --namespace=app --all

更新命令允許指定多個選項。

--all 更新給定命名空間中的所有憑證，或與 --all-namespaces 結合使用時，更新所有命名空間中的憑證。
-A 或 --all-namespaces 標記跨命名空間的憑證以進行更新。
-l --selector 允許設定標籤查詢以進行篩選，以及類似 kubectl 的全域標誌，例如 --context 和 --namespace。

憑證狀態

cmctl status certificate 輸出憑證資源及其相關資源（例如 CertificateRequest、Secret、Issuer）的目前狀態詳細資訊，如果它是 ACME 憑證，則還會輸出 Order 和 Challenges 的資訊。該命令會輸出有關資源的資訊，包括條件（Conditions）、事件（Events）以及特定於資源的欄位，例如 Secret 的金鑰用途（Key Usages）和擴展金鑰用途（Extended Key Usages），或 Order 的授權（Authorizations）。這對於疑難排解憑證會很有幫助。

該命令接受一個參數，用於指定憑證資源的名稱，並且可以使用 -n 或 --namespace 標誌指定命名空間。

此範例查詢命名空間 my-namespace 中名為 my-certificate 的憑證的狀態。

cmctl status certificate my-certificate -n my-namespace

補全

cmctl 支援子命令的自動補全，以及執行階段物件的建議。

$ cmctl approve -n <TAB> <TAB>
default             kube-node-lease     kube-public         kube-system         local-path-storage

您可以依照您正在使用的 shell 的指示，為您的環境安裝補全功能。目前支援 bash、fish、zsh 和 powershell。

$ cmctl completion help

實驗性功能

cmctl x 具有實驗性的子命令，用於目前正在評估是否要納入 cert-manager 本身的運算。這些命令的行為和介面可能會在未來版本中變更或移除。

建立

cmctl x create 可以用來手動建立 cert-manager 資源。子命令可用來建立不同的資源。

CertificateSigningRequest

若要建立 CertificateSigningRequest，請使用

cmctl x create csr

此命令接受要建立的 CertificateSigningRequest 的名稱，以及包含憑證資訊清單的檔案（-f, --from-certificate-file）。此命令將根據憑證的選項產生私鑰，並將其寫入本機檔案 <name>.key，或由 -k, --output-key-file 指定的檔案。

$ cmctl x create csr -f my-cert.yaml my-req

cert-manager 不會自動批准 CertificateSigningRequests。如果您未在叢集中執行自訂批准者，則可能需要手動批准 CertificateSigningRequest。

$ kubectl certificate approve <name>

此命令也可以使用標誌 -w, --fetch-certificate 等待 CertificateSigningRequest 被簽署。簽署後，它會將產生的已簽署憑證寫入本機檔案 <name>.crt，或由 -c, --output-certificate-file 指定的檔案。

$ cmctl x create csr -f my-cert.yaml my-req -w

安裝

cmctl x install

此命令確保已安裝所需的 CustomResourceDefinitions 以及 cert-manager、cainjector 和 webhook 元件。在底層，會使用類似於 Helm 安裝程序的程序。

您也可以使用 cmctl x install 自訂 cert-manager 的安裝。

以下範例示範如何透過覆寫預設 Helm 值來調整 cert-manager 的安裝。

cmctl x install \
    --set prometheus.enabled=false \  # Example: disabling prometheus using a Helm parameter
    --set webhook.timeoutSeconds=4s   # Example: changing the wehbook timeout using a Helm parameter

您可以在 cert-manager 的 ArtifactHub 頁面上找到安裝參數的完整清單。這些參數與使用 Helm chart 時可用的參數相同。部署 cert-manager 後，您可以驗證安裝。

CLI 也允許使用者將範本化的資訊清單輸出到 stdout，而不是將資訊清單安裝到叢集上。

cmctl x install --dry-run > cert-manager.custom.yaml

解除安裝

cmctl x uninstall

此命令會解除安裝 cert-manager 的任何 Helm 管理版本。

從 cmctl v2.0.0 開始，解除安裝命令是安全的，預設情況下不會刪除 CRD，即使它們是在 v1.15.0 之前使用 cert-manager Helm chart 安裝的（使用選項 --set installCRDs=true）。從 cert-manager v1.15.0 開始，使用 Helm 解除安裝 Helm chart 時，預設情況下不會移除 CRD。

🕐 在 v2.0.0 之前，如果 CRD 是使用 Helm chart 安裝的，cmctl 會移除這些 CRD（類似於 Helm 的行為）。

此命令也支援 helm uninstall 支援的大部分功能。

以下是一些使用範例

cmctl x uninstall

cmctl x uninstall --namespace my-cert-manager

cmctl x uninstall --dry-run

升級

協助升級 cert-manager 的工具。

$ cmctl upgrade --help

遷移 API 版本

此命令可用於準備在 cert-manager v1 之前建立的 cert-manager 安裝，以便升級到 cert-manager 版本 v1.6 或更高版本。它確保任何可能以已棄用的 API 版本儲存在 etcd 中的 cert-manager 自訂資源都會遷移到 v1。如需更多背景資訊，請參閱遷移已棄用的 API 資源。

$ cmctl upgrade migrate-api-version --qps 5 --burst 10

Kubectl 插件

自 kubectl 1.26 起，kubectl 插件支援自動完成，這表示您將擁有與獨立 cmctl 二進位檔和 kubectl 插件相同的體驗。

若要安裝插件，您需要適用於您所使用平台的 kubectl_cert-manager 檔案，這些檔案可以在我們的cmctl GitHub 發行頁面上找到。為了使用 kubectl 插件，您需要其二進位檔在您的 $PATH 中以 kubectl-cert_manager 的名稱存取。

您可以執行 kubectl cert-manager help 來測試是否正確設定了插件。

使用 kubectl 外掛程式自動完成

從 kubectl 1.26 版本開始，可以為外掛程式啟用自動完成功能。假設您已將 kubectl_cert-manager 安裝在 /usr/local/bin 中，您可以執行以下命令來設定自動完成功能

cat >kubectl_complete-cert_manager <<'EOF'
#!/usr/bin/env sh
kubectl cert-manager __complete "$@"
EOF
sudo install kubectl_complete-cert_manager /usr/local/bin