🥇Cert-manager 1.0 is out

If you ask an experienced, wise engineer what he thinks about cert-manager and why everyone uses it, then the specialist will sigh, hug him in confidence and say wearily: “Everyone uses it, because there are no sane alternatives. Our mice cry, prick, but continue to live with this cactus. Why do we love? Because it works. Why don't we love? Because new versions are constantly coming out that use new features. And you have to update the cluster over and over again. And the old versions stop working, because there is a conspiracy and a great mysterious shamanism.

But the developers claim that cert-manager 1.0 everything will change.

Believe it?

Cert-manager is the native Kubernetes certificate management controller. It can be used to issue certificates from various sources: Let's Encrypt, HashiCorp Vault, Venafi, signing and self-signed key pairs. It also allows you to keep keys up-to-date by expiration date, and also tries to automatically renew certificates at a specified time before they expire. Cert-manager is based on kube-lego and has also used some tricks from other similar projects such as kube-cert-manager.

Release Notes

With version 1.0, we put a mark of trust for three years of development of the cert-manager project. During this time, it has evolved significantly in functionality and stability, but most of all in the community. Today, we see many people using it to secure their Kubernetes clusters as well as deploying it to various parts of the ecosystem. A lot of bugs have been fixed in the last 16 releases. And what needed to be broken is broken. Several visits to work with the API have improved its interaction with users. We've resolved 1500 issues on GitHub with more pull requests from 253 community members.

With the release of 1.0, we officially declare that cert-manager is a mature project. We also promise to keep our API compatible v1.

Many thanks to everyone who helped us make cert-manager all these three years! Let version 1.0 be the first of many big things to come.

Release 1.0 is a stable release with several priority areas:

v1 API;
Team kubectl cert-manager status, to help with problem analysis;
Using the latest stable Kubernetes APIs;
Improved logging;
ACME improvements.

Be sure to read the upgrade notes before upgrading.

API v1

Version v0.16 worked with the API v1beta1. This added some structural changes and also improved the API field documentation. Version 1.0 builds on this with an API v1. This API is our first stable one, at the same time we have already given compatibility guarantees, but with the API v1 we promise to maintain compatibility for years to come.

Changes made (note: our conversion tools take care of everything for you):

Certificate:

emailSANs now called emailAddresses
uriSANs — uris

These changes add compatibility with other SANs (subject alt names, approx. translator), as well as with the Go API. We are removing this term from our API.

Update

If you are using Kubernetes 1.16+, converting webhooks will allow you to simultaneously and seamlessly work with API versions v1alpha2, v1alpha3, v1beta1 и v1. With these, you will be able to use the new version of the API without changing or redeploying your old resources. We highly recommend upgrading your manifests to the API v1, as previous versions will be deprecated soon. Users legacy versions of cert-manager will still only have access to v1, upgrade steps can be found here.

kubectl cert-manager status command

With new improvements in our extension to kubectl it became easier to investigate the problems associated with the non-issuance of certificates. kubectl cert-manager status now gives a lot more information about what's going on with the certificates and also shows the certificate issuance stage.

After installing the extension, you can run kubectl cert-manager status certificate <имя-сертификата>, which will look up the certificate with the given name and any related resources such as CertificateRequest, Secret, Issuer, and Order and Challenges if using certificates from ACME.

An 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: <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 can also help you learn more about the contents of the certificate. Detailed example 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:  <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 the latest stable Kubernetes APIs

Cert-manager was one of the first to implement Kubernetes CRDs. This, and our support for Kubernetes versions up to 1.11, meant we needed to support the legacy apiextensions.k8s.io/v1beta1 for our CRDs as well 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 offer full support apiextensions.k8s.io/v1 и admissionregistration.k8s.io/v1 for Kubernetes 1.16 (where they were added) and newer. For users of previous versions, we continue to offer support v1beta1 in our legacy version.

Improved logging

In this release, we have updated the logging library to klog/v2, used in Kubernetes 1.19. We also review each journal we write to make sure it is assigned the appropriate level. We were guided by this guidance from Kubernetes. There are five (actually six, approx. translator) logging levels starting from Error (level 0), which prints only important errors, and ends with Trace (level 5) which will help you know exactly what is going on. With this change, we have reduced the number of logs if you do not need debug information when running cert-manager.

Tip: cert-manager runs at level 2 by default (Info), you can override this using global.logLevel in Helmchart.

Note: Viewing the logs is the last resort when troubleshooting. For more information check out our leadership.

Editor's n.b.: To learn more about how it all works under the hood of Kubernetes, get valuable advice from practicing teachers, as well as quality technical support help, you can take part in online intensives Kubernetes Base, which will be held September 28-30, and Kubernetes Megawhich will be held October 14-16.

ACME Improvements

The most common use of cert-manager is probably related to issuing certificates from Let's Encrypt using ACME. Version 1.0 is notable for using community feedback to add two small but important improvements to our ACME issuer.

Disable account key generation

If you use ACME certificates in large volumes, you are likely to use the same account on multiple clusters, so your certificate issuance restrictions will apply to all of them. This was already possible in cert-manager when copying the secret specified in privateKeySecretRef. This use case was quite buggy, as cert-manager tried to be helpful and happily created a new account key if it didn't find one. That's why we added disableAccountKeyGenerationto protect you from this behavior if you set this option to true - cert-manager will not generate a key and will warn you that it has not been provided with an account key.

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 will go over to your own root CA ISRG Root. Cross-signed certificates will be replaced by Identrust. This change does not require changes to the cert-manager settings, all updated or new certificates issued after this date will use the new root CA.

Let's Encrypt already signs certificates with this CA and offers them as an "alternate certificate chain" via ACME. In this version of cert-manager, it is possible to set access to these chains in the issuer settings. In parameter preferredChain you can specify the name of the CA in use, with which the certificate will be issued. If a CA certificate matching the request is available, it will issue you a certificate. Please note that this is the preferred option, if nothing is found, a default certificate will be issued. This will ensure that you will still renew your certificate after deleting the alternate chain on the ACME issuer side.

Already today you can receive certificates signed by ISRG Root, So:

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 leave the chain IdenTrust - set this 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"

Please note that this root CA will be deprecated soon, Let's Encrypt will keep this chain active until September 29, 2021.

Source: habr.com

cert-manager 1.0 released