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 CA
server - the ACME server URL of the CA
email - email presented to the ACME API
solvers - 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 and metadata.namespace - the Kubernetes namespace in which the Hydrolix cluster runs
spec.issuerRef.name - the name of the Issuer CRD to use for acquiring this certificate
commonName - the primary name on the certificate
dnsNames - a list of Subject Alternate Names (SANs) to include on the certificate, should always include at least the commonName
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.