v1.0 we’re putting a seal of trust on 3 years of development on the cert-manager project.
In these 3 years cert-manager has grown in functionality and stability, but mostly in the community.
Today we see many people using cert-manager to secure their Kubernetes clusters, as well as cert-manager
being integrated into many other parts in the ecosystem.
In the past 16 releases many bugs got fixed, and things that needed to be broken were broken.
Several iterations on the API improved the user experience.
We solved 1500 GitHub Issues with even more PRs by 253 contributors.
v1.0 we’re officially making a statement that cert-manager is a mature project now.
We will also be making a compatibility promise with our
A big thank you to everyone who helped to build cert-manager in the past 3 years!
v1.0 be the first of many big achievements!
v1.0 release is a stability release with a few focus areas:
kubectl cert-manager statuscommand to help with investigating issues
- Using new and stable Kubernetes APIs
- Improved logging
- ACME improvements
As usual, please read the upgrade notes before upgrading.
v0.16 we introduced the
v1beta1 API. This brought some structural changes as well as better documentation of the API fields.
v1.0 we build on this with the
v1 API. This API is our first “stable” API version, while our others were well used we had to already provide some compatibility guarantees with the
v1 API we promise compatibility for the API for years to come.
These are the changes made (for reference, our conversion will take care of everything for you):
emailSANsis now named
uriSANsis now named
This change makes these 2 SANs consistent with the other SANs as well as the Go API. Dropping the term SAN from our API.
If you’re using Kubernetes 1.16 or higher, conversion webhooks will allow you seamlessly interact with
v1 API versions at the same time. This allows you to use the new API version without having to modify or redeploy your older resources.
We highly recommend upgrading your manifests to the
v1 API as older versions will soon be deprecated.
Users of the
legacy version of cert-manager will still only have the
v1 API, migration steps can be found in the upgrade notes.
kubectl cert-manager status command
With the new improvements to our
kubectl plugin it is easier to investigate issues with certificates not being issued.
kubectl cert-manager status now displays a lot more information about what has been going on with your certificate and in which
stage of issuance it currently is in.
Once the plugin is installed, you can run
kubectl cert-manager status certificate <name-of-cert>. That will then look for the Certificate with the name
<name-of-cert> and any 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.
For example while debugging a not ready certificate:
$ kubectl cert-manager status certificate acme-certificate Name: acme-certificate Namespace: default Created at: 2020-08-21T16:44:13+02:00 Conditions: Ready: False, Reason: DoesNotExist, Message: Issuing certificate as Secret does not exist Issuing: True, Reason: DoesNotExist, Message: Issuing certificate as Secret does not exist DNS Names: - example.com Events: Type Reason Age From Message ---- ------ ---- ---- ------- Normal Issuing 18m cert-manager Issuing certificate as Secret does not exist Normal Generated 18m cert-manager Stored new private key in temporary Secret resource "acme-certificate-tr8b2" Normal Requested 18m cert-manager Created new CertificateRequest resource "acme-certificate-qp5dm" Issuer: Name: acme-issuer Kind: Issuer Conditions: Ready: True, Reason: ACMEAccountRegistered, Message: The ACME account was registered with the ACME server error when finding Secret "acme-tls": secrets "acme-tls" not found Not Before: <none> Not After: <none> Renewal Time: <none> CertificateRequest: Name: acme-certificate-qp5dm Namespace: default Conditions: Ready: False, Reason: Pending, Message: Waiting on certificate issuance from order default/acme-certificate-qp5dm-1319513028: "pending" Events: Type Reason Age From Message ---- ------ ---- ---- ------- Normal OrderCreated 18m cert-manager Created Order resource default/acme-certificate-qp5dm-1319513028 Order: Name: acme-certificate-qp5dm-1319513028 State: pending, Reason: Authorizations: URL: https://acme-staging-v02.api.letsencrypt.org/acme/authz-v3/97777571, Identifier: example.com, Initial State: pending, Wildcard: false Challenges: - Name: acme-certificate-qp5dm-1319513028-1825664779, Type: DNS-01, Token: J-lOZ39yNDQLZTtP_ZyrYojDqjutMAJOxCL1AkOEZWw, Key: U_W3gGV2KWgIUonlO2me3rvvEOTrfTb-L5s0V1TJMCw, State: pending, Reason: error getting clouddns service account: secret "clouddns-accoun" not found, Processing: true, Presented: false
The command also can help looking into what is inside an issued certificate. This example looks at an issuer Let’s Encrypt certificate in detail:
$ kubectl cert-manager status certificate example Name: example [...] Secret: Name: example Issuer Country: US Issuer Organisation: Let's Encrypt Issuer Common Name: Let's Encrypt Authority X3 Key Usage: Digital Signature, Key Encipherment Extended Key Usages: Server Authentication, Client Authentication Public Key Algorithm: RSA Signature Algorithm: SHA256-RSA Subject Key ID: 65081d98a9870764590829b88c53240571997862 Authority Key ID: a84a6a63047dddbae6d139b7a64565eff3a8eca1 Serial Number: 0462ffaa887ea17797e0057ca81d7ba2a6fb Events: <none> Not Before: 2020-06-02T04:29:56+02:00 Not After: 2020-08-31T04:29:56+02:00 Renewal Time: 2020-08-01T04:29:56+02:00 [...]
Using new and stable Kubernetes APIs
cert-manager has been an early adopter of the Kubernetes CRDs. That and us supporting Kubernetes versions as for back as
made us use the now deprecated
apiextensions.k8s.io/v1beta1 for our CRDs and
admissionregistration.k8s.io/v1beta1 for our webhooks.
These are now deprecated and to be removed in Kubernetes
v1.0 we now offer full support for
admissionregistration.k8s.io/v1 for Kubernetes
v1.16 (where this got added) and above.
For users of Kubernetes
v1.15 we keep offering support for the
v1beta1 Kubernetes APIs in our legacy version.
For this release we upgraded our logging library to
klog/v2 analog to Kubernetes
We also reviewed every log we write to assign it an appropriate log level.
We followed the (Kubernetes logging guidelines)[https://github.com/kubernetes/community/blob/master/contributors/devel/sig-instrumentation/logging.md]. To come up with 5 log levels ranging from
Error (level 0) which only prints important errors to
Trace (level 5) which can help you to know exactly what is gong on.
With this change we reduced the number of logs when you don’t need to have a debugging trace while running cert-manager.
Tip: My default cert-manager runs on level 2 (Info), you can set this using
global.logLevel in the Helm chart.
Note: Looking at the logs while troubleshooting cert-manager should be last resort behavior, for more info check out our troubleshooting guide
The most used use case of cert-manager is probably to issue certificates from Let’s Encrypt using ACME. In
v1.0 we took took feedback from the community to add two small but important improvements to our ACME issuer.
Disable Account Key Generation
If you deploy ACME issuer certs on a large scale you probably want to re-use your ACME account across multiple clusters
so your rate limit exceptions get applied everywhere.
While this was already possible in cert-manager by copying over the secret referenced in
However this process was quite error prone as cert-manager was trying to be helpful and was happy to create a new account key
for you if one was not found. This is why we added
disableAccountKeyGeneration to safe guard you against this behavior,
if set to true it will not create a key and warn you if no account key was given to it.
apiVersion: cert-manager.io/v1 kind: Issuer metadata: name: letsencrypt spec: acme: privateKeySecretRef: name: example-issuer-account-key disableAccountKeyGeneration: false
On September 29th Let’s Encrypt will change over to using its own
ISRG Root CA.
This will replace the cross-signed certificates by
Identrust. This change over needs no changes to your cert-manager configuration, any renewed or new certificates issued after this date will use the new CA root.
Let’s encrypt currently already signs certificates using this CA and offers them as “alternative certificate chain” via ACME.
In this release cert-manager adds support for accessing these alternative chains in the issuer config.
preferredChain option will allow you to specify a CA’s common name for the certificate to be issued by.
If there is a certificate available matching that request it will present you that certificate. Note that this is a Preferred option,
if none is found matching the request it will give you the default certificate as before. This makes sure you still get your certificate
renewed once the alternative chain gets removed on the ACME issuer side.
You can already today get certificates from the
ISRG Root by using:
apiVersion: cert-manager.io/v1 kind: Issuer metadata: name: letsencrypt spec: acme: server: https://acme-v02.api.letsencrypt.org/directory preferredChain: "ISRG Root X1"
If you prefer to keep the
IdenTrust chain you can do that by setting the option to
DST Root CA X3:
apiVersion: cert-manager.io/v1 kind: Issuer metadata: name: letsencrypt spec: acme: server: https://acme-v02.api.letsencrypt.org/directory preferredChain: "DST Root CA X3"
Note that this Root CA is expiring soon, Let’s Encrypt will keep this certificate chain active until September 29 2021.