HTTP Challenge
Use these instructions for a Hydrolix deployment running k8s cert-manager to acquire a certificate from Let's Encrypt using the HTTP challenge.
Prerequisites
Before you can start this guide, you'll need the following:
- A deployed Hydrolix cluster that uses a public load balancer
- A publicly reachable IP, allowing traffic from
0.0.0.0/0
- A publicly visible DNS entry for your Hydrolix cluster hostname, pointed at the public load balancer
The Hydrolix cluster service IP must be publicly reachable for HTTP challenge to succeed. See Configure IP Access to modify the cluster ACL.
Create an Issuer CRD
In TLS ecosystem, an issuer is an entity capable of issuing certificates, more commonly, a Certification Authority (CA). The cert-manager
software uses an Issuer
Custom Resource Definition (CRD)to configure how to interact with any CA.
Create an Issuer
CRD describing the Let's Encrypt production CA with the following required elements:
name
- display name of the issuer or CAserver
- the ACME server URL of the CAemail
- email presented to the ACME APIsolvers
- preferred configuration for responding to the ACME challeng
Each solver has slightly different configuration. See configuration examples.
For further detail, see Issuer Configuration.
The following example generates a certificate using Let's Encrypt. It validates the domain control using HTTP and ingress traefik
:
apiVersion: cert-manager.io/v1
kind: Issuer
metadata:
name: letsencrypt-production-http
namespace: ${HDX_KUBERNETES_NAMESPACE}
spec:
acme:
server: https://acme-v02.api.letsencrypt.org/directory
email: ${HDX_ADMIN_EMAIL}
privateKeySecretRef:
name: letsencrypt-production-http
solvers:
- selector: {}
http01:
ingress:
class: traefik
After creating this Issuer
CRD in yaml file issuer-prod-lets-enc.yaml
, deploy to your cluster:
kubectl apply -f issuer-prod-lets-enc.yaml
Create a Certificate CRD
After deploying your certificate Issuer
, create a new Certificate
which manages the lifetime of certificate contents, secrets, and related status information when interacting with the CA.
The Certificate
CRD contains the information required to generate and send a Certificate Signing Request (CSR), and will also store a successfully acquired TLS certificate and its private key in the configured secret.
metadata.name
andmetadata.namespace
- the Kubernetes namespace in which the Hydrolix cluster runsspec.issuerRef.name
- the name of theIssuer
CRD to use for acquiring this certificatecommonName
- the primary name on the certificatednsNames
- a list of Subject Alternate Names (SANs) to include on the certificate, should always include at least thecommonName
spec.secretName
- where to store the certificate and corresponding TLS private key
Hydrolix requires the certificate to be stored into the secretName: traefik-tls
. This is the default location used by the reverse proxy when loading a certificate.
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: ${HDX_KUBERNETES_NAMESPACE}
namespace: ${HDX_KUBERNETES_NAMESPACE}
spec:
secretName: traefik-tls
issuerRef:
name: letsencrypt-production-http
commonName: ${myhost}.hydrolix.live
dnsNames:
- ${myhost}.hydrolix.live
After creating this Certificate
CRD in yaml file cert-req.yaml
, deploy to your cluster
kubectl apply -f cert-req.yaml
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
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 9 days ago