[Editor’s note: This post was written by Haoxiang Zhou who was a work placement student at our company for the past four months. We are grateful to Haoxiang for adding this very useful feature, and all his other contributions, and wish him all the best with his final year of study.]
This post will explore the newest addition to the kubectl plugin of cert-manager, kubectl cert-manager status certificate, a command designed to make the troubleshooting experience of cert-manager problems easier. The command was hugely improved in the recent v1 release. Jump to the bottom for more information on how to get involved and start contributing!
Why do we need this kubectl command?
Troubleshooting cert-manager has always been a recurring topic in the community, that is why the cert-manager team has created the Troubleshooting guide along with extra help for ACME Certificates to assist users to identify the most common causes of errors. Even if the user is unable to find the solution themselves, these guides enable them to narrow down the problem and make seeking help more effective.
We have received a lot of positive feedback from users saying that the guides were very helpful. As a small bonus point, it made our team members’ lives easier as well. But we wanted to take it a step further.
The usual advice that we give users and which is documented in the Troubleshooting guides is to use kubectl describe on various resources in order to pinpoint where the error is happening.
For example, to find out why an ACME Certificate is not ready, in the worst case, the user has to run kubectl describe on the Certificate resource, copy the name of the CertificateRequest then kubectl describe on the CertificateRequest. Then copy the name of the Issuer to do kubectl describe on the Issuer. Then again for the Order, and again for the Challenges. In the example below I omitted parts of the actual output for the sake of readability.
While it helps us achieve what we want, speaking out of personal experience, that can quickly become tedious. That is why when the team discussed building a command-line tool that outputs all the information needed for troubleshooting as an addition to our kubectl CLI plugin, I gladly took over the task.
What does this kubectl command do?
To run the command, you need to have the cert-manager kubectl CLI plugin installed. You can either follow these steps in the cert-manager docs, or use krew, the package manager for kubectl plugins, to install the plugin.
Once the plugin is ready, you can run kubectl cert-manager status certificate <name-of-cert>. That will then look for the Certificate with the name <name-of-cert> in the specified/default namespace and any related resources like CertificateRequest, Secret, Issuer, as well as Order and Challenges if it is an 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.
Taking the example from above:
Conclusion
With the command, the user can just dump all the information about a Certificate resource if something is not going well, making it much simpler to find out what is causing trouble. It also makes it easier for others to help spot any issues, e.g. when seeking advice on Slack, the output of the status certificate command is a great starting point for others to assist in the troubleshooting process, rather than just “My certificate is stuck in pending state” or pasting a page of logs which are usually far too verbose to be useful in this context, especially in production environments.
Finally, I encourage everybody to use this command as well as other commands of the plugin. Feedback, bug reports, feature requests or even PRs are very much welcome - not only for the cert-manager kubectl plugin, but to anything cert-manager related!
