最新：在推特和Mastodon

证书管理器命令行工具 (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

CertificateRequests 可以使用其相应的 cmctl 命令 批准或拒绝

注意：内部 cert-manager 批准者可能会自动批准所有 CertificateRequests，除非使用 cert-manager-controller 上的标志禁用 --controllers=*,-certificaterequests-approver

$ 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 可用于将 cert-manager 清单文件在不同的 API 版本之间进行转换。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 标志指定的 Certificate 资源的 YAML 清单创建一个新的 CertificateRequest 资源，方法是本地生成一个私钥并创建一个“证书签名请求”以提交给 cert-manager Issuer。私钥将写入本地文件，默认情况下为 <name_of_cr>.key，也可以使用 --output-key-file 标志指定。

如果您希望等待 CertificateRequest 被签名并将 X.509 证书存储到文件中，您可以设置 --fetch-certificate 标志。等待证书颁发时的默认超时时间为 5 分钟，但可以使用 --timeout 标志指定。存储 X.509 证书的文件的默认名称为 <name_of_cr>.crt，您可以使用 --output-certificate-file 标志来指定其他名称。

请注意，私钥和 X.509 证书都写入文件，并且 **不会** 存储在 Kubernetes 中。

例如，这将基于 my-certificate.yaml 中描述的 cert-manager Certificate 创建一个名为“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 输出证书资源当前状态的详细信息，以及相关资源，如证书请求、密钥、颁发者，以及如果是 ACME 证书的订单和挑战。该命令输出有关资源的信息，包括条件、事件和特定于资源的字段，如密钥的用途和扩展密钥用途或订单的授权。这将有助于对证书进行故障排除。

该命令接受一个参数，指定证书资源的名称，命名空间可以像往常一样使用 -n 或 --namespace 标志指定。

此示例查询名为 my-certificate 的证书的状态，该证书位于命名空间 my-namespace 中。

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 资源。子命令可用于创建不同的资源。

证书签名请求

要创建 证书签名请求，请使用

cmctl x create csr

该命令接受要创建的证书签名请求的名称，以及包含证书清单的文件 (-f, --from-certificate-file)。该命令将根据证书的选项生成一个私钥，并将其写入本地文件 <name>.key，或者由 -k, --output-key-file 指定。

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

cert-manager **不会** 自动批准证书签名请求。如果您没有在集群中运行自定义批准程序，则可能需要手动批准证书签名请求。

$ kubectl certificate approve <name>

该命令还可以使用标志 -w, --fetch-certificate 等待证书签名请求被签名。签名后，它会将生成的已签名证书写入本地文件 <name>.crt，或者由 -c, --output-certificate-file 指定。

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

安装

cmctl x install

该命令确保与 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 图表时可用的参数相同。部署 cert-manager 后，您可以 验证 安装。

CLI 还允许用户将模板化的清单输出到 stdout，而不是在集群上安装清单。

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

卸载

cmctl x uninstall

该命令卸载任何 Helm 管理的 cert-manager 版本。

从 cmctl v2.0.0 开始，卸载命令是安全的，默认情况下不会删除 CRD，即使它们是使用 cert-manager Helm 图表在 v1.15.0 之前安装的（使用选项 --set installCRDs=true）。从 cert-manager v1.15.0 开始，默认情况下，使用 Helm 卸载 Helm 图表时不会删除 CRD。

🕐 在 v2.0.0 之前，如果 CRD 是使用 Helm 图表安装的，则 cmctl 会删除它们（类似于 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