This section configures your AKS to leverage LetsEncrypt.org and automatically obtain a TLS/SSL certificate for your domain. The certificate will be installed on Application Gateway, which will perform SSL/TLS termination for your AKS cluster. The setup described here uses the cert-manager Kubernetes add-on, which automates the creation and management of certificates.
Follow the steps below to install cert-manager on your existing AKS cluster.
-
Helm Chart
Run the following script to install the
cert-manager
helm chart. This will:- create a new
cert-manager
namespace on your AKS - create the following CRDs: Certificate, Challenge, ClusterIssuer, Issuer, Order
- install cert-manager chart (from docs.cert-manager.io)
# Install the CustomResourceDefinition resources separately # Note: --validate=false is required per https://github.com/jetstack/cert-manager/issues/2208#issuecomment-541311021 kubectl apply -f https://raw.githubusercontent.com/jetstack/cert-manager/release-0.13/deploy/manifests/00-crds.yaml --validate=false # Create the namespace for cert-manager kubectl create namespace cert-manager # Label the cert-manager namespace to disable resource validation kubectl label namespace cert-manager cert-manager.io/disable-validation=true # Add the Jetstack Helm repository helm repo add jetstack https://charts.jetstack.io # Update your local Helm chart repository cache helm repo update # Install v0.11 of cert-manager Helm chart helm install cert-manager \ --namespace cert-manager \ --version v0.13.0 \ jetstack/cert-manager
- create a new
-
ClusterIssuer Resource
Create a
ClusterIssuer
resource. It is required bycert-manager
to represent theLets Encrypt
certificate authority where the signed certificates will be obtained.By using the non-namespaced
ClusterIssuer
resource, cert-manager will issue certificates that can be consumed from multiple namespaces.Let’s Encrypt
uses the ACME protocol to verify that you control a given domain name and to issue you a certificate. More details on configuringClusterIssuer
properties here.ClusterIssuer
will instructcert-manager
to issue certificates using theLets Encrypt
staging environment used for testing (the root certificate not present in browser/client trust stores).The default challenge type in the YAML below is
http01
. Other challenges are documented on letsencrypt.org - Challenge TypesIMPORTANT: Update
<YOUR.EMAIL@ADDRESS>
in the YAML belowkubectl apply -f - <<EOF apiVersion: cert-manager.io/v1alpha2 kind: ClusterIssuer metadata: name: letsencrypt-staging spec: acme: # You must replace this email address with your own. # Let's Encrypt will use this to contact you about expiring # certificates, and issues related to your account. email: <YOUR.EMAIL@ADDRESS> # ACME server URL for Let’s Encrypt’s staging environment. # The staging environment will not issue trusted certificates but is # used to ensure that the verification process is working properly # before moving to production server: https://acme-staging-v02.api.letsencrypt.org/directory privateKeySecretRef: # Secret resource used to store the account's private key. name: letsencrypt-secret # Enable the HTTP-01 challenge provider # you prove ownership of a domain by ensuring that a particular # file is present at the domain solvers: - http01: ingress: class: azure/application-gateway EOF
-
Deploy App
Create an Ingress resource to Expose the
guestbook
application using the Application Gateway with the Lets Encrypt Certificate.Ensure you Application Gateway has a public Frontend IP configuration with a DNS name (either using the default
azure.com
domain, or provision aAzure DNS Zone
service, and assign your own custom domain). Note the annotationcert-manager.io/cluster-issuer: letsencrypt-staging
, which tells cert-manager to process the tagged Ingress resource.IMPORTANT: Update
<PLACEHOLDERS.COM>
in the YAML below with your own domain (or the Application Gateway one, for example 'kh-aks-ingress.westeurope.cloudapp.azure.com')kubectl apply -f - <<EOF apiVersion: networking.k8s.io/v1 kind: Ingress metadata: name: guestbook-letsencrypt-staging annotations: kubernetes.io/ingress.class: azure/application-gateway cert-manager.io/cluster-issuer: letsencrypt-staging cert-manager.io/acme-challenge-type: http01 spec: tls: - hosts: - <PLACEHOLDERS.COM> secretName: guestbook-secret-name rules: - host: <PLACEHOLDERS.COM> http: paths: - backend: service: name: frontend port: number: 80 EOF
Use
kubectl describe clusterissuer letsencrypt-staging
to view the state of status of the ACME account registration. Usekubectl get secret guestbook-secret-name -o yaml
to view the certificate issued.After a few seconds, you can access the
guestbook
service through the Application Gateway HTTPS url using the automatically issued stagingLets Encrypt
certificate. Your browser may warn you of an invalid cert authority. The staging certificate is issued byCN=Fake LE Intermediate X1
. This is an indication that the system worked as expected and you are ready for your production certificate. -
Production Certificate Once your staging certificate is setup successfully you can switch to a production ACME server:
- Replace the staging annotation on your Ingress resource with:
cert-manager.io/cluster-issuer: letsencrypt-prod
- Delete the existing staging
ClusterIssuer
you created in the previous step and create a new one by replacing the ACME server from the ClusterIssuer YAML above withhttps://acme-v02.api.letsencrypt.org/directory
- Replace the staging annotation on your Ingress resource with:
-
Certificate Expiration and Renewal Before the
Lets Encrypt
certificate expires,cert-manager
will automatically update the certificate in the Kubernetes secret store. At that point, Application Gateway Ingress Controller will apply the updated secret referenced in the ingress resources it is using to configure the Application Gateway.