Let's Encrypt Certificates

Prerequisites

Before you can start this guide, you'll need the following:

• A deployed Hydrolix cluster that uses a public load balancer.
• A DNS entry that points to the public load balancer.
• Public IP Access, to allow Let's Encrypt verification.

Install Custom Resource Definitions for cert-manager

Run one of the following commands, depending on your Kubernetes version, to install the Custom Resource Definitions (CRDs) that you need to run cert-manager:

# Kubernetes v1.16 and above
kubectl apply --namespace=$HDX_KUBERNETES_NAMESPACE -f https://github.com/cert-manager/cert-manager/releases/download/v1.1.1/cert-manager.yaml

# Kubernetes pre-v1.16
kubectl apply --validate=false --namespace=$HDX_KUBERNETES_NAMESPACE -f https://github.com/cert-manager/cert-manager/releases/download/v1.1.1/cert-manager-legacy.yaml

📘

Workaround for Permission Denied Error on GKE

Clusters deployed on GKE (Google Kubernetes Engine) may encounter a 'permission denied' error when creating these resources. This happens because of how GKE handles RBAC and IAM permissions. To work around this issue, run the above command from an account with 'cluster-admin' privileges. You can elevate your account to cluster-admin privileges with the following command:

Shell

kubectl create clusterrolebinding cluster-admin-binding  
    --clusterrole=cluster-admin  
    --user=$(gcloud config get-value core/account)

Then, rerun-the command to install the CRDs.

Create a Certificate Issuer Configuration

In this step, we'll create an Issuer leveraging Let's Encrypt production certificate authority. The Issuer contains the following information:

• name - name of the issuer used to generate new certificate requests
• ACME server - server used to generate the ACME challenge
• email - email used for the certificate information
• solvers - used to validate ownership of the domain

The following example generates a certificate using Let's Encrypt. It validates the domain ownership using HTTP and ingress traefik:

apiVersion: cert-manager.io/v1
kind: Issuer
metadata:
  name: letsencrypt-production-http
  namespace: $YOURNAMESPACE - TO BE REPLACE
spec:
  acme:
    server: https://acme-v02.api.letsencrypt.org/directory
    email: $YOUREMAILMANAGINGCERTIFICATE - TO BE REPLACE
    privateKeySecretRef:
      name: letsencrypt-production-http
    solvers:
    - selector: {}
      http01:
        ingress:
          class: traefik

Once you generate the issuer configuration, store it in issuer-prod-lets-enc.yaml. Deploy it in your cluster with the following command:

kubectl apply -f issuer-prod-lets-enc.yaml

Create a Certificate Request Configuration

Once you've deployed your certificate Issuer, you can create a new certificate request with your domain.
By default, Hydrolix loads the certificate from a secret named traefik-tls.
The following example shows the full syntax to define this secret in a file called cert-req.yaml:

apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
  name: $YOURNAMESPACE - TODO REPLACE ME!
  namespace: $YOURNAMESPACE - TODO REPLACE ME!
spec:
  secretName: traefik-tls
  issuerRef:
    name: letsencrypt-production-http
  commonName: $YOURDOMAIN - TODO REPLACE ME!
  dnsNames:
  - $YOURDOMAIN - TODO REPLACE ME!

Use the following command to deploy the request in your cluster:

kubectl apply -f cert-req.yaml

Check the Certificate Request Status

Once applied, you can check the certificate status with the following command:

kubectl describe certificate $YOURNAMESPACE

If the certificate successfully validates, you can should see the following:

Normal  Issuing    12s   cert-manager-certificates-issuing          The certificate has been successfully issued

Enable TLS on traefik

Once the certificate is deployed, enable HTTPS by changing the hydrolix_url field in your cluster configuration from "http" to "https":

hydrolix_url: <https://$YOURHOSTNAME>

After changing the protocol, traefik should restart and use the newly deployed Let's Encrypt certificate.

Return to the Add a Custom Certificate guide to validate your results.