Cert-Manager and Ambassador Edge Stack

Note: The Ambassador Edge Stack can issue and manage certificate with the ACME HTTP-01 challenge.

cert-manager is still required for DNS-01 challenges for wildcard domains and when using Ambassador OSS.

Creating and managing certificates in Kubernetes is made simple with Jetstack's cert-manager. Cert-manager will automatically create and renew TLS certificates and store them in Kubernetes secrets for easy use in a cluster. Ambassador will automatically watch for secret changes and reload certificates upon renewal.

Note: Ambassador Edge Stack will automatically create and renew TLS certificates with the HTTP-01 challenge. You should use cert-manager if you need support for the DNS-01 challenge and/or wildcard certificates.

Install Cert-Manager

There are many different ways to install cert-manager. For simplicity, we will use Helm.

1. Install cert-manager

Note: The resource validation webhook is not mandatory, but if implemented, requires additional configuration.

Issuing Certificates

cert-manager issues certificates from a CA such as Let's Encrypt. It does this using the ACME protocol which supports various challenge mechanisms for verifying ownership of the domain.

Issuer

An Issuer or ClusterIssuer identifies which Certificate Authority cert-manager will use to issue a certificate. Issuer is a namespaced resource allowing you to use different CAs in each namespace, a ClusterIssuer is used to issue certificates in any namespace. Configuration depends on which ACME challenge you are using.

Certificate

A Certificate is a namespaced resource that references an Issuer or ClusterIssuer for issuing certificates. Certificates define the DNS name(s) a key and certificate should be issued for, as well as the secret to store those files (e.g. ambassador-certs). Configuration depends on which ACME challenge you are using.

By duplicating issuers, certificates, and secrets one can support multiple domains with SNI.

Challenge

cert-manager supports two kinds of ACME challenges that verify domain ownership in different ways: HTTP-01 and DNS-01.

DNS-01 Challenge

The DNS-01 challenge verifies domain ownership by proving you have control over its DNS records. Issuer configuration will depend on your DNS provider. This example uses AWS Route53.

1. Create the IAM policy specified in the cert-manager AWS Route53 documentation.

2. Note the accessKeyID and create a secret named prod-route53-credentials-secret holding the secret-access-key.

3. Create and apply a ClusterIssuer:

4. Create and apply a certificate:

5. Verify the secret is created

HTTP-01 Challenge

The HTTP-01 challenge verifies ownership of the domain by sending a request for a specific file on that domain. cert-manager accomplishes this by sending a request to a temporary pod with the prefix /.well-known/acme-challenge/. To perform this challenge:

1. Create a ClusterIssuer:

2. Configure a Certificate to use this ClusterIssuer:

3. Apply both the ClusterIssuer and Certificate

   After applying both of these YAML manifests, you will notice that cert-manager has spun up a temporary pod named cm-acme-http-solver-xxxx but no certificate has been issued. Check the cert-manager logs and you will see a log message that looks like this:

4. Create a Mapping for the /.well-known/acme-challenge/ route.

cert-manager uses an Ingress resource to issue the challenge to /.well-known/acme-challenge/ but, since Ambassador is not an Ingress, we will need to create a Mapping so the cert-manager can reach the temporary pod.

Apply the YAML and wait a couple of minutes. cert-manager will retry the challenge and issue the certificate.

5. Verify the secret is created: