cmctl
cmctl
is a CLI tool that can help you to manage cert-manager resources inside
your cluster.
While also available as a kubectl plugin, it is recommended to use as a stand alone binary as this allows the use of command auto-completion.
Installation
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
the name cmctl
in your $PATH
.
Run the following commands to set up the CLI. Replace OS and ARCH with your
systems equivalents:
OS=$(go env GOOS); ARCH=$(go env GOARCH); curl -sSL -o cmctl.tar.gz https://github.com/cert-manager/cert-manager/releases/download/v1.7.2/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.
Commands
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
--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'
Convert
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 --output-version
flag.
The default output will be printed to stdout in YAML format. One can use the
option -o
to change the output destination.
For example, this will output cert.yaml
in the latest API version:
cmctl convert -f cert.yaml
Create
cmctl create
can be used to create cert-manager resources manually.
Sub-commands are available to create different resources:
CertificateRequest
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 --from-certificate-file
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 --output-key-file
flag.
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 my-certificate.yaml
while
storing the private key and X.509 certificate in my-cr.key
and my-cr.crt
respectively.
cmctl create certificaterequest my-cr --from-certificate-file my-certificate.yaml --fetch-certificate --timeout 20m
Renew
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 --all
flag:
For example, you can renew the certificate example-com-tls
:
$ 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:
--all
renew all Certificates in the given Namespace, or all namespaces when combined with--all-namespaces
-A
or--all-namespaces
mark Certificates across namespaces for renewal-l
--selector
allows set a label query to filter on as well askubectl
like global flags like--context
and--namespace
.
Status Certificate
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
a Certificate.
The command takes in one argument specifying the name of the Certificate
resource and the namespace can be specified as usual with the -n
or
--namespace
flag.
This example queries the status of the Certificate named my-certificate
in
namespace my-namespace
.
cmctl status certificate my-certificate -n my-namespace
Completion
cmctl
supports auto-completion for both subcommands as well as suggestions for
runtime objects.
$ 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
Experimental
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.
Create
cmctl x create
can be used to create cert-manager resources manually.
Sub-commands are available to create different resources:
CertificateSigningRequest
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 <name>.key
, or
specified by -k, --output-key-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
the flag -w, --fetch-certificate
. Once signed it will write the resulting
signed certificate to the local file <name>.crt
, or specified by -c, --output-certificate-file
.
$ cmctl x create csr -f my-cert.yaml my-req -w
Upgrade
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
before cert-manager 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