Provision Certificate Manually

Overview

Hydrolix allows manual configuration of a certificate for use in securing the network services on a cluster.

This page describes how to install a web server TLS certificate and its key for securing communication. The Hydrolix system accepts valid, standard x509 TLS certificates from any Certification Authority (CA).

See Enable TLS for more TLS options.

Before you begin

• A deployed Hydrolix cluster
• A valid TLS certificate and corresponding private key

Install into the traefik-tls secret, wait a moment or restart the traefik reverse proxy, and enable TLS in the Hydrolix cluster spec.

Brief description

TLS certificates contain public information. TLS private keys contain sensitive, identifying information and should be kept secret. Keep the TLS key and certificates in separate files.

You will load them as a matched pair into a single Kubernetes Secret resource.

All browsers, operating systems, and TLS clients have a root certificate trust store.

Every server using TLS certificates must supply its own certificate, usually called a server or leaf certificate and any intermediate certificates that a CA has used to generate the leaf certificate.

For TLS clients to be able to connect successfully, you must create one file containing the leaf certificate and all intermediate certificates. This is a certificate chain.

Certificate chain order

Include the leaf certificate and all intermediates except the root.

See also Check certificate chain order

Create or replace a certificate

1. Concatenate your server certificate and all intermediate certificates furnished by your preferred CA into a single file, chain.pem.

2. Keep the key file separate, tls.key.

3. Install the pair into the traefik-tls Kubernetes secret to add a new certificate or overwrite and replace an existing one.

   Shell

   kubectl create secret tls traefik-tls --key=tls.key --cert=chain.pem
   

   This creates a secret in Kubernetes called traefik-tls and stores your certificate and private key in that secret. Traefik automatically checks for the traefik-tls secret, and uses it if valid.

4. Verify the presence of TLS data in the cluster.

   Command to List the traefik-tls Secret

   kubectl -n <namespace> get secret traefik-tls -o yaml
   

   Example Listing of traefik-tls Secret

   $ kubectl -n hydrolix get secret traefik-tls -o yaml  
   apiVersion: v1  
   data:  
     tls.crt: ${BASE64_ENCODED_CERTIFICATE_CHAIN}
     tls.key: ${BASE64_ENCODED_PRIVATE_KEY}
   kind: Secret  
   metadata:  
     creationTimestamp: "2023-06-27T15:27:12Z"  
     name: traefik-tls  
     namespace: hydrolix  
     resourceVersion: "32029846"  
     uid: 33c06aa2-b81f-44a9-9123-c24e1af94bb5  
   type: kubernetes.io/tls
   

   Alternately, use k9s: Type :secrets, select traefik-tls and type x to view the decoded contents.

5. Wait for, or cause the reverse proxy to reload.

   Wait a minute or so. Optionally, immediately apply the changes by restarting the traefik service:

   Normally, the traefik reverse proxy will detect the certificate change and reload the new certificate.

   Optionally, you can immediately restart the traefik service

   Shell

   kubectl rollout restart deployment traefik
   

6. Ensure that TLS is enabled for the cluster.

   Enable HTTPS by changing the hydrolix_url field in your cluster configuration from "http" to "https":

   hydrolixcluster.yaml

   hydrolix_url: https://${HDX_HOSTNAME}
   

   See also Enable TLS.

7. Verify TLS connection is working

   Use a browser or network command to connect to the cluster hostname and look at the certificate returned.

   Shell

   curl https://${HDX_HOSTNAME}
   

Delete a certificate

Remove a certificate by deleting the traefik-tls secret.

⚠️

Removing a certificate will interrupt connections to your cluster

The traefik-tls secret contains the TLS private key and corresponding certificate used for securing communication with the cluster. Services that depend on reachability over TLS won't work until a replacement certificate has been provisioned and installed.

Example command

kubectl -n $HDX_NAMESPACE delete secret traefik-tls