If you ask an experienced, wise engineer what they think about cert-manager and why everyone uses it, they will sigh, embrace you confidentially, and wearily say: "Everyone uses it because there are no reasonable alternatives. Our mice cry, are pricked, but continue to live with this cactus. Why do we love it? Because it works. Why don't we love it? Because new versions constantly come out that use new features. Therefore, we have to update the cluster time and again. Old versions stop working because there is a conspiracy and great mysterious shamanism."
But developers assure us that with cert-manager 1.0 everything will change.
Should we believe it?
Cert-manager is the "native" certificate management controller for Kubernetes. It allows issuing certificates from various sources: Let’s Encrypt, HashiCorp Vault, Venafi, key pairs for signing, and self-signed certificates. It also helps keep keys up to date and attempts to automatically renew certificates in a timely manner before they expire. Cert-manager is based on kube-lego and also incorporates techniques from other similar projects, such as kube-cert-manager.
Release Notes
With version 1.0, we place a mark of trust after three years of developing the cert-manager project. During this time, it has significantly evolved in functionality and stability, but most importantly — in the community. Today, we see many people using it to protect their Kubernetes clusters and implementing it across various parts of the ecosystem. In the last 16 releases, numerous bugs have been fixed. And what needed to be broken has been broken. Several approaches to working with the API have improved its interaction with users. We resolved 1500 issues on GitHub, with even more merge requests from 253 community contributors.
By releasing 1.0, we officially state that cert-manager is a mature project. We also promise to maintain the compatibility of our API v1.
A huge thank you to everyone who helped us make cert-manager over these three years! May version 1.0 serve as the first of many future major achievements.
Release 1.0 is a stable release with several priority areas:
v1API;The command
kubectl cert-manager status, to assist in problem analysis;Using the latest stable Kubernetes APIs;
Improved logging;
ACME enhancements.
Before updating, please read the release notes.
API v1
Version v0.16 worked with the API v1beta1. This introduced some structural changes, as well as improved documentation for API fields. Version 1.0 relies on all of this through the API v1. This API is our first stable version, while we have already provided compatibility guarantees, but with the API v1 we promise to maintain compatibility for years to come.
Changes made (note: our conversion tools will take care of everything for you):
Certificate:
emailSANsis now calledemailAddressesuriSANs—uris
These changes add compatibility with other SANs (subject alt names, translator's note), as well as with the Go API. We are removing this term from our API.
Upgrade
If you're using Kubernetes 1.16+ — the conversion webhooks will allow you to seamlessly operate with API versions v1alpha2, v1alpha3, v1beta1 and v1. With them, you will be able to use the new version of the API without altering or redeploying your old resources. We strongly recommend updating your manifests to the API v1, as previous versions will soon be declared deprecated. Users legacy of the cert-manager version will still only have access to v1, upgrade steps can be found .
Command kubectl cert-manager status
With new improvements in our extension to kubectl it has become easier to investigate issues related to certificate issuance. kubectl cert-manager status now provides much more information about what's happening with certificates and also shows the certification issuance stage.
After installing the extension, you can run kubectl cert-manager status certificate, which will search for the certificate with the specified name and any related resources, such as CertificateRequest, Secret, Issuer, as well as Order and Challenges if using ACME certificates.
Example of debugging a certificate that is not yet ready:
$ 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:
Not After:
Renewal Time:
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 can also help to learn more about the certificate's contents. An example detail for a certificate issued by Letsencrypt:
$ 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:
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 the latest stable Kubernetes APIs
Cert-manager was one of the first to implement Kubernetes CRDs. This, along with our support for Kubernetes versions up to 1.11, led us to maintain deprecated apiextensions.k8s.io/v1beta1 for our CRDs, as well as admissionregistration.k8s.io/v1beta1 for our webhooks. They are now deprecated and will be removed in Kubernetes from version 1.22. With our 1.0, we now provide full support apiextensions.k8s.io/v1 and admissionregistration.k8s.io/v1 for Kubernetes 1.16 (where they were added) and newer versions. For users of previous versions, we continue to offer support. v1beta1 in our legacy version.
Enhanced logging
In this version, we upgraded the logging library to klog/v2, which is used in Kubernetes 1.19. We also check each log we write to assign it the appropriate level. We were guided by . There are five (actually six, translator's note) logging levels, starting with Error (level 0), which outputs only critical errors, and ending with Trace (level 5), which helps you understand exactly what is happening. This change reduces the number of logs if you don't need debug information while working with cert-manager.
Tip: by default, cert-manager operates at level 2 (Info), you can override this using global.logLevel in Helm chart.
Note: viewing logs is a last resort in troubleshooting. For more information, check our .
N.B. editor: To learn more about how this all works under the hood of Kubernetes, gain valuable insights from practitioner instructors, and receive quality technical support, you can participate in online intensives , which will take place from September 28-30, and , which will take place from October 14-16.
ACME Improvements
The most common use case for cert-manager is likely associated with issuing certificates from Let's Encrypt using ACME. Version 1.0 is notable for incorporating community feedback to add two small but significant improvements to our ACME issuer.
Disabling account key creation
If you are using ACME certificates in large volumes, you are likely using the same account across multiple clusters, so your certificate issuance limits will apply to all of them. This was already possible in cert-manager by copying the secret specified in privateKeySecretRef. This use case was quite buggy, as cert-manager would try to be helpful and happily create a new account key if it didn't find one. That's why we added disableAccountKeyGeneration, to protect you from such behavior; when this option is set to true — cert-manager will not create a key and will notify you that an account key was not provided.
apiVersion: cert-manager.io/v1
kind: Issuer
metadata:
name: letsencrypt
spec:
acme:
privateKeySecretRef:
name: example-issuer-account-key
disableAccountKeyGeneration: false
Preferred chain
September 29 Let’s Encrypt to its own root certificate authority ISRG Root. Certificates with cross-signatures will be replaced with Identrust. This change does not require modifications in cert-manager settings; all updated or new certificates issued after this date will use the new root CA.
Let’s Encrypt is already signing certificates using this CA and offers them as an 'alternative certificate chain' via ACME. In this version of cert-manager, there is an option to specify access to these chains in the issuer settings. In the parameter preferredChain you can specify the name of the CA that will issue the certificate. If a CA certificate corresponding to the request is available, it will issue you a certificate. Note that this is the preferred option; if nothing is found, a default certificate will be issued. This will ensure that you still renew your certificate after the alternative chain is removed on the ACME issuer side.
You can already obtain certificates signed ISRG Root, like this:
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 chain IdenTrust — set this parameter 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 certificate authority will soon be deprecated; Let’s Encrypt will keep this chain active until September 29, 2021.
Source: habr.com
