2/May 2018
Those of you who closely follow Jetstack’s 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
organisation.
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.
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.com
More info on Issuers and Certificates can be found in our documentation.
Over the last few weeks, we have been trialling 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!
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 organisation.
This will help your organisation 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 organisation.
It is not always feasible to switch a whole organisation 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.
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!
Want to work on community projects like cert-manager for your day job?
Jetstack are hiring Software Engineers, including remote (EU) roles. Check out our careers page
for more info on the roles and how to apply.