The cert-manager Command Line Tool (cmctl)
cmctl is a command line tool that can help you manage cert-manager and its resources inside your cluster.
On Mac or Linux if you have Homebrew installed, you can
brew install cmctl
This will also install shell completion.
You need the
cmctl.tar.gz file for the platform you're using, these can be
found on our
GitHub releases page.
In order to use
cmctl you need its binary to be accessible under
cmctl in your
Run the following commands to set up the CLI. Replace OS and ARCH with your
OS=$(go env GOOS); ARCH=$(go env GOARCH); curl -fsSL -o cmctl.tar.gz https://github.com/cert-manager/cert-manager/releases/latest/download/cmctl-$OS-$ARCH.tar.gztar xzf cmctl.tar.gzsudo mv cmctl /usr/local/bin
You can run
cmctl help to test the CLI is set up properly:
$ cmctl helpcmctl is a CLI tool manage and configure cert-manager resources for KubernetesUsage: cmctl [command]Available Commands:approve Approve a CertificateRequestcheck Check cert-manager componentscompletion Generate completion scripts for the cert-manager CLIconvert Convert cert-manager config files between different API versionscreate Create cert-manager resourcesdeny Deny a CertificateRequestexperimental Interact with experimental featureshelp Help about any commandinspect Get details on certificate related resourcesrenew Mark a Certificate for manual renewalstatus Get details on current status of cert-manager resourcesupgrade Tools that assist in upgrading cert-managerversion Print the cert-manager CLI version and the deployed cert-manager versionFlags:-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.
There is also a legacy kubectl plugin, but it is no longer recommended because the standalone
cmctlbinary provides better auto-completion.
Approve and Deny CertificateRequests
CertificateRequests can be approved or denied using their respective cmctl commands:
Note: The internal cert-manager approver may automatically approve all CertificateRequests unless disabled with the flag on the cert-manager-controller
$ 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 can be used to convert cert-manager manifest files between
different API versions. Both YAML and JSON formats are accepted. The command
either takes a file name, directory path, or a URL as input. The contents is
converted into the format of the latest API version known to cert-manager, or
the one specified by
The default output will be printed to stdout in YAML format. One can use the
-o to change the output destination.
For example, this will output
cert.yaml in the latest API version:
cmctl convert -f cert.yaml
cmctl create can be used to create cert-manager resources manually.
Sub-commands are available to create different resources:
To create a cert-manager CertificateRequest, use
cmctl create certificaterequest. The command takes in the name of the CertificateRequest to
be created, and creates a new CertificateRequest resource based on the YAML
manifest of a Certificate resource as specified by
flag, by generating a private key locally and creating a 'certificate signing
request' to be submitted to a cert-manager Issuer. The private key will be
written to a local file, where the default is
<name_of_cr>.key, or it can be
specified using the
If you wish to wait for the CertificateRequest to be signed and store the X.509
certificate in a file, you can set the
--fetch-certificate flag. The default
timeout when waiting for the issuance of the certificate is 5 minutes, but can
be specified with the
--timeout flag. The default name of the file storing the
X.509 certificate is
<name_of_cr>.crt, you can use the
--output-certificate-file flag to specify otherwise.
Note that the private key and the X.509 certificate are both written to file, and are not stored inside Kubernetes.
For example this will create a CertificateRequest resource with the name "my-cr"
based on the cert-manager Certificate described in
storing the private key and X.509 certificate in
cmctl create certificaterequest my-cr --from-certificate-file my-certificate.yaml --fetch-certificate --timeout 20m
cmctl allows you to manually trigger a renewal of a specific certificate.
This can be done either one certificate at a time, using label selectors (
-l app=example), or with the
For example, you can renew the certificate
$ kubectl get certificateNAME READY SECRET AGEexample-com-tls True example-com-tls 1d$ cmctl renew example-com-tlsManually triggered issuance of Certificate default/example-com-tls$ kubectl get certificaterequestNAME READY AGEexample-com-tls-tls-8rbv2 False 10s
You can also renew all certificates in a given namespace:
$ cmctl renew --namespace=app --all
The renew command allows several options to be specified:
--allrenew all Certificates in the given Namespace, or all namespaces when combined with
--all-namespacesmark Certificates across namespaces for renewal
--selectorallows set a label query to filter on as well as
kubectllike global flags like
cmctl status certificate outputs the details of the current status of a
Certificate resource and related resources like CertificateRequest, Secret,
Issuer, as well as Order and Challenges if it is a ACME Certificate. The
command outputs information about the resources, including Conditions, Events
and resource specific fields like Key Usages and Extended Key Usages of the
Secret or Authorizations of the Order. This will be helpful for troubleshooting
The command takes in one argument specifying the name of the Certificate
resource and the namespace can be specified as usual with the
This example queries the status of the Certificate named
cmctl status certificate my-certificate -n my-namespace
cmctl supports auto-completion for both subcommands as well as suggestions for
$ cmctl approve -n <TAB> <TAB>default kube-node-lease kube-public kube-system local-path-storage
Completion can be installed for your environment by following the instructions for the shell you are using. It currently supports bash, fish, zsh, and powershell.
$ cmctl completion help
cmctl x has experimental sub-commands for operations which are currently under
evaluation to be included into cert-manager proper. The behavior and interface
of these commands are subject to change or removal in future releases.
cmctl x create can be used to create cert-manager resources manually.
Sub-commands are available to create different resources:
To create a CertificateSigningRequest, use
cmctl x create csr
This command takes the name of the CertificateSigningRequest to be created, as
well as a file containing a Certificate manifest (
-f, --from-certificate-file). This command will generate a private key, based on
the options of the Certificate, and write it to the local file
$ cmctl x create csr -f my-cert.yaml my-req
cert-manager will not automatically approve CertificateSigningRequests. If you are not running a custom approver in your cluster, you will likely need to manually approve the CertificateSigningRequest:
$ kubectl certificate approve <name>
This command can also wait for the CertificateSigningRequest to be signed using
-w, --fetch-certificate. Once signed it will write the resulting
signed certificate to the local file
<name>.crt, or specified by
$ cmctl x create csr -f my-cert.yaml my-req -w
cmctl x install
This command makes sure that the required
CustomResourceDefinitions are installed together with the cert-manager, cainjector and webhook components.
Under the hood, a procedure similar to the Helm install procedure is used.
You can also use
cmctl x install to customize the installation of cert-manager.
The example below shows how to tune the cert-manager installation by overriding the default Helm values:
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
You can find a full list of the install parameters on cert-manager's ArtifactHub page. These are the same parameters that are available when using the Helm chart. Once you have deployed cert-manager, you can verify the installation.
The CLI also allows the user to output the templated manifest to
stdout, instead of installing the manifest on the cluster.
cmctl x install --dry-run > cert-manager.custom.yaml
cmctl x uninstall
This command uninstalls any Helm-managed release of cert-manager.
The CRDs will be deleted if you installed cert-manager with the option
Most of the features supported by
helm uninstall are also supported by this command.
Some example uses:
cmctl x uninstallcmctl x uninstall --namespace my-cert-managercmctl x uninstall --dry-runcmctl x uninstall --no-hooks
Tools that assist in upgrading cert-manager
$ cmctl upgrade --help
Migrate API version
This command can be used to prepare a cert-manager installation that was created
v1 for upgrading to a cert-manager version
v1.6 or later.
It ensures that any cert-manager custom resources that may have been stored in etcd at
a deprecated API version get migrated to
v1. See Migrating Deprecated API
Resources for more context.
$ cmctl upgrade migrate-api-version --qps 5 --burst 10
Legacy kubectl plugin
While the kubectl plugin is supported, it is recommended to use
cmctl as this enables a better experience via tab auto-completion.
To install the plugin you need the
kubectl-cert-manager.tar.gz file for the platform you're using,
these can be found on our GitHub releases page.
In order to use the kubectl plugin you need its binary to be accessible under the name
kubectl-cert_manager in your
You can run
kubectl cert-manager help to test that the plugin is set up properly.