Cert-Manager and Ambassador Edge Stack
Note: This document assumes cert-manager v0.15 or greater. This document has been updated to use CRD standards specified in v0.15. Legacy CRD support was removed in cert-manager v0.15, see their upgrading document for more info.
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 v3.
Create the cert-manager CRDs.
kubectl apply -f https://github.com/jetstack/cert-manager/releases/latest/download/cert-manager.crds.yamlAdd the
jetstack
Helm repository.helm repo add jetstack https://charts.jetstack.io && helm repo updateInstall cert-manager.
kubectl create ns cert-managerhelm install cert-manager --namespace cert-manager jetstack/cert-manager
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. Certificate
s 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.
Create the IAM policy specified in the cert-manager AWS Route53 documentation.
Note the
accessKeyID
and create asecret
namedprod-route53-credentials-secret
in the cert-manager namespace that has a key value:secret-access-key
from your AWS IaM credentials.Create and apply a
ClusterIssuer
.---apiVersion: cert-manager.io/v1alpha2kind: ClusterIssuermetadata:name: letsencrypt-prodspec:acme:email: email@example.comserver: https://acme-v02.api.letsencrypt.org/directoryprivateKeySecretRef:name: letsencrypt-prodsolvers:- selector:dnsZones:- "myzone.route53.com"dns01:route53:region: us-east-1accessKeyID: {accessKeyID}hostedZoneID: {Hosted Zone ID} # optional, allows you to reduce the scope of permissions in Amazon IAMsecretAccessKeySecretRef:name: prod-route53-credentials-secretkey: secret-access-keyCreate and apply a
Certificate
.---apiVersion: cert-manager.io/v1alpha2kind: Certificatemetadata:name: myzone.route53.com# cert-manager will put the resulting Secret in the same Kubernetes# namespace as the Certificate. You should create the certificate in# whichever namespace you want to configure a Host.spec:secretName: ambassador-certsissuerRef:name: letsencrypt-prodkind: ClusterIssuercommonName: myzone.route53.comdnsNames:- myzone.route53.comVerify the secret is created.
$ kubectl get secrets -n ambassadorNAME TYPE DATA AGEambassador-certs kubernetes.io/tls 2 1h
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:
Create and apply a
ClusterIssuer
.---apiVersion: cert-manager.io/v1alpha2kind: ClusterIssuermetadata:name: letsencrypt-prodspec:acme:email: email@example.comserver: https://acme-v02.api.letsencrypt.org/directoryprivateKeySecretRef:name: letsencrypt-prodsolvers:- http01:ingress:class: nginxselector: {}Create and apply a
Certificate
.---apiVersion: cert-manager.io/v1alpha2kind: Certificatemetadata:name: ambassador-certs# cert-manager will put the resulting Secret in the same Kubernetes# namespace as the Certificate. You should create the certificate in# whichever namespace you want to configure a Host.namespace: ambassadorspec:secretName: ambassador-certsissuerRef:name: letsencrypt-prodkind: ClusterIssuerdnsNames:- example.comApply both the
ClusterIssuer
andCertificate
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:$ kubectl logs cert-manager-756d6d885d-v7gmg...Preparing certificate default/ambassador-certs with issuerCalling GetOrderCalling GetAuthorizationCalling HTTP01ChallengeResponseCleaning up old/expired challenges for Certificate default/ambassador-certsCalling GetChallengewrong status code '404'Looking up Ingresses for selector certmanager.k8s.io/acme-http-domain=161156668,certmanager.k8s.io/acme-http-token=1100680922Error preparing issuer for certificate default/ambassador-certs: http-01 self check failed for domain "example.comCreate a Mapping for the
/.well-known/acme-challenge/
route.cert-manager uses an
Ingress
to issue the challenge to/.well-known/acme-challenge/
that is incompatible with Ambassador. We will need to create aMapping
so the cert-manager can reach the temporary pod.---apiVersion: getambassador.io/v2kind: Mappingmetadata:name: acme-challenge-mappingspec:prefix: /.well-known/acme-challenge/rewrite: ""service: acme-challenge-service---apiVersion: v1kind: Servicemetadata:name: acme-challenge-servicespec:ports:- port: 80targetPort: 8089selector:acme.cert-manager.io/http01-solver: "true"Apply the YAML and wait a couple of minutes. cert-manager will retry the challenge and issue the certificate.
Verify the secret is created:
$ kubectl get secretsNAME TYPE DATA AGEambassador-certs kubernetes.io/tls 2 1hambassador-token-846d5 kubernetes.io/service-account-token 3 2h
Questions?
We’re here to help. If you have questions, join our Slack or contact us.