Kubernetes Cert Manager

Overview

As an alternative to the default Hydrolix ACME Client, Hydrolix supports the k8s cert-manager for automatic certificate acquisition and renewal.

The flexible cert-manager software supports public Certification Authorities (CAs), private CAs, and other security management software, like HashiCorp Vault.

Use this option for automated certificate management if the Hydrolix ACME Client isn't flexible enough for your needs, or see Enable TLS for more TLS options.

This page describes how to install and configure the cert-manager to work with the Hydrolix cluster, and includes example pages for configuring cert-manager to interact with Let's Encrypt using the HTTP challenge or DNS Challenge with common managed DNS providers.

See the k8s cert-manager software for general guidance on configuring that software.

Steps

Install the Custom Resource Definitions (CRDs).
Select how to request certificates.
Configure cert-manager, optionally using a linked guide below.
Check the certificate status.
Confirm reverse proxy loads certificate.

Install Custom Resource Definitions

To begin, install cert-manager using kubectl

kubectl apply -f https://github.com/cert-manager/cert-manager/releases/download/v1.11.0/cert-manager.yaml

Workaround: GKE permission denied

Clusters deployed on GKE (Google Kubernetes Engine) may encounter a 'permission denied' error when creating cert-manager 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:

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

Then, rerun-the command to install the CRDs.

Select how to request certificates

The ACME protocol provides two mechanisms for Certification Authorities (CA) to verify requests for certificates from cert-manager.

Let's Encrypt is a CA. When configuring cert-manager to request a certificate from Let's Encrypt, the request includes a preferred mechanism for validation. This can be either HTTP-01 Challenge or DNS-01 Challenge.

Validate ownership with HTTP

Use an HTTP Challenge, in this example with Let's Encrypt, if your Hydrolix cluster

allows open access to its service IP
doesn't need wildcard certificates

Validate ownership with DNS

Use a DNS challenge configuration if

your Hydrolix cluster doesn't have an open access control list
you prefer to use the DNS
you need additional setup instructions for your managed DNS provider
you need a wildcard certificate

Three example configurations demonstrate cert-manager responding to DNS challenges:

Select from one of the guides that best matches your needs.

Configure `cert-manager`

Make sure that cert-manager is running according to your desired configuration. The guides above may be useful.

Move on to the next step when cert-manager has acquired a certificate and installed it into the traefik-tls secret.

Check the certificate status

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

kubectl describe certificate ${HDX_KUBERNETES_NAMESPACE}

If the CA can validate ownership, you can should see the following:

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

Confirm reverse proxy loads certificate

The traefik reverse proxy detects changes to the traefik-tls secret and reloads, usually within one minute.

To immediately restart, run the following command

kubectl rollout restart deployment traefik

Enable TLS

Once the certificate is deployed, enable TLS for network services by changing the protocol in the hydrolix_url in your Hydrolix spec from http to https:

hydrolix_url: https://${myhost}.hydrolix.live

After changing the protocol, traefik should restart and use the new certificate.