![Native x509 Certificate Management for Kubernetes [cert-manager] - cover graphic](/_next/image/?url=https%3A%2F%2Fcdn.venafi.com%2F994513b8-133f-0003-9fb3-9cbe4b61ffeb%2F4969e89f-e999-46e8-a741-7f98485a9dcd%2Fcertm_hu1231068bf0470217ded6f87d39c76d2e_145241_700x0_resize_q75_box%2520%25281%2529.jpg%3Fw%3D864%26h%3D370%26fm%3Dwebp%26q%3D75%26fit%3Dcrop&w=3840&q=75&dpl=dpl_3EAuLccmwaq4KZ9GcZftJq5NbwLA){kind=small}
Update Please see the releases page on GitHub for the latest release.
Those of you who closely follow our open source projects may have already noticed that our new certificate management tool cert-manager, has been available for some time now.
In fact, we now have over 1,000 stars on GitHub!
Cert-manager is a general purpose x509 certificate management tool for Kubernetes. In today’s modern web, securing application traffic is critical. cert-manager aims to simplify management, issuance and renewal of certificates within your organization.
kube-lego, our original Let’s Encrypt certificate provisioning tool for Kubernetes Ingress resources, has been a great success. It makes securing traffic between your users and your cluster ingress point simple. Over time however, the limitations of building a controller solely around Kubernetes Ingresses became apparent.
By building cert-manager around Kubernetes CustomResourceDefinitions, we have been able to greatly increase the flexibility of configuration, debugging capabilities and also support a wider range of CAs than Let’s Encrypt alone.
This post is a high-level overview of how cert-manager works, and will highlight some of the new features and recent developments in the project.
Issuers and certificates
In the real world of x509 certificates, CAs (Certificate Authorities) are a point of trust, responsible for issuing identities to various clients in the form of signed and trusted x509 certificates.
Let’s Encrypt introduced the ACME protocol, however, not all CAs support this protocol.
In order to support many different types of Certificate Authority, we have introduced the concept of a CA to the Kubernetes API, in the form of ‘Issuers’.
A cert-manager ‘Issuer’ resource represents an entity that is able to sign x509 certificate requests.
Today, we support ACME, CA (i.e. a simple signing keypair stored in a Secret resource) and as of the v0.3.0 release, Hashicorp Vault!
Here’s an example of an issuer resource:
apiVersion: certmanager.k8s.io/v1alpha1
kind: ClusterIssuer
metadata:
name: letsencrypt-staging
spec:
acme:
server: https://acme-staging-v02.api.letsencrypt.org/directory
email: user@example.com
privateKeySecretRef:
name: letsencrypt-private-key
http01: {}In order to request certificates from these Issuers, we also introduce certificate resources. These resources reference a corresponding Issuer resource in order to denote which CA they should be issued by.
Here’s an example of a certificate resource, using the issuer shown previously:
apiVersion: certmanager.k8s.io/v1alpha1
kind: Certificate
metadata:
name: example-com
spec:
secretName: example-com-tls
dnsNames:
- example.com
- www.example.com
issuerRef:
name: letsencrypt-staging
kind: ClusterIssuer
acme:
config:
- http01:
ingressClass: nginx
domains:
- example.com
- www.example.comMore info on Issuers and certificates can be found in our documentation.
What’s new in 0.3
Over the last few weeks, we have been trailing an alpha release candidate of v0.3, our upcoming new release.
This release is packed with new features and bug fixes alike, and this section describes the headline features.
ACMEv2 and wildcard certificates
Let’s Encrypt recently announced v2 of the ACME protocol, which amongst other improvements, now supports wildcard certificates. This has been a long-awaited and requested feature, and one that hasn’t been possible until recently.
In order to allow cert-manager users to request and consume wildcard certificates, we have switched exclusively to use ACMEv2 as part of the v0.3 release.
This allows users to request wildcard certificates just like any other - including full support for doing so via annotated Ingress resources (just like kube-lego!).
This is a great example of how we can add new and more complex features to cert-manager, whilst also continuing to support long-standing, legacy behaviour adopted from kube-lego.
If you’d like to get started and give this a try, check out the latest v0.3 alpha release on our GitHub page. You can request a wildcard certificate just like any other, by specifying *.domain.com as one of your DNS names. See the ACME DNS validation tutorial for more information on how to get started with the DNS-01 challenge.
Vault issuer support
After a lot of hard work, initial support for Hashicorp Vault has been merged into cert-manager!
This is another long requested feature, and a large addition to our set of supported Issuer types.
A special thanks to @vdesjardins, who single handedly and unprompted undertook this work, driving it through the review process to the very end.
This allows end users to create a ‘Vault’ Issuer, which is paired with a single Vault PKI backend role.
Initially we support both token authentication and Vault’s ‘AppRole’ authentication mechanism to securely authorize cert-manager against the Vault server.
The addition of the Vault Issuer bolsters our position as a general purpose certificate manager, and shows the value in providing a single clean abstraction on top of the multitude of different types of CAs out there.
Read more about creating and using the Vault Issuer at the docs.
New documentation site
Within any project, documentation is tough. It needs to provide a clear onboarding experience for brand new users, as well as in-depth details for more advanced users. All the while accounting for the varying skill levels of these users (for example, some may also be brand new to Kubernetes itself!).
We’ve had some brilliant community contributions with user guides and tutorials explaining how to get started with cert-manager.
Up until now, we have used markdown stored in GitHub to host our documentation. This began to cause confusion when we started versioning cert-manager more strictly, and releasing alpha/beta release candidates. In order to handle this, and also to make it easier for users to navigate and discover the various tutorials we do have - we have moved our documentation over to a hosted readthedocs website.
You can check out the new docs on readthedocs - take note that we have a ‘version switcher’ in the bottom left as well, if you are looking for info on the latest 0.3 release.
Each page in the docs also has an “Edit in GitHub” link on the top right, so if you spot a mistake or if you’ve got an idea for a new tutorial please dive in and submit PRs!
What’s next?
cert-manager is still young, with much planned in the future! Here are a couple of highlights from our roadmap:
Defining policy on certificates
Right now, any user that is able to create a certificate resource can request certificates of any sort from any ClusterIssuer, or Issuer within the same namespace.
We intend to provide mechanisms for administrators to define ‘policies’ for who can obtain certificates, and/or how those certificates must be structured. This might include things such as minimum and maximum durations, or a limited set of allowed DNS names.
By defining this policy within Kubernetes itself, we benefit from a common level of policy control between all the different CAs within an organization. This will help your organization audit and manage who can do what.
Advanced resource validation
Kubernetes has recently added support for ValidatingAdmissionWebhooks (as well as their ‘Mutating’ counterparts).
These can be used to provide resource validation (e.g. ensuring that all fields are set to acceptable values), as well as advanced ‘mutation’ of resources (e.g. applying ‘default values’).
One common problem when configuring these webhooks, is that they require x509 certificates in order to be set up and run. This process can be cumbersome, and is exactly the sort of problem cert-manager has been designed to solve!
In future releases of cert-manager, we will introduce our own Validating webhook in order to provide fore-warning to developers of invalid configurations. This will involve a novel ‘bootstrapping’ process in order to allow for ‘self hosted webhooks’ (i.e. webhooks that power cert-manager, hosted by cert-manager).
Along with this, we will be creating tutorials that explain our ‘recommended deployment practice’ for these kinds of webhooks, and how you can utilise cert-manager to handle all aspects of securing them!
Pluggable/out-of-process issuers
Some enterprise users of cert-manager have their own CA process, which is novel and bespoke to their organization.
It is not always feasible to switch a whole organization over to a new protocol in a short period, given so many different business units rely on a x509 certificate platform.
In order to ease the transition period for these companies, we are exploring the addition of a ‘gRPC based Issuer’. This is in a similar vein to CNI (Container Networking Interface) and CRI (Container Runtime Interface). The goal would be to provide a general purpose gRPC interface that anyone can implement in order to sign and renew certificates.
Users that implement this interface will then immediately benefit from the additional policy and renewal features that cert-manager already implements.
Getting involved
cert-manager is growing quickly, and the community around it bolsters every day.
We’d love to see new members join the community, and believe it’s imperative if we want the project to survive.
If you want to get involved, take a look over our Issue board on GitHub, or drop into #cert-manager on the Kubernetes Slack and say hello!