Kubernetes Cert Manager
Use cert-manager for certificate lifecycle management
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
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.
See also Enable TLS.
Updated 1 day ago