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.

Prerequisites

• 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.

Create or replace a certificate

1. Concatenate your server certificate, all intermediate certificates, and the root certificate into a single file chain.pem. Keep the key file separate.

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

   Shell

   kubectl create secret tls traefik-tls --key=certificates.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.

3. Verify presence of TLS data in cluster.

   Shell

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

   example

   $ 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
   

4. Wait for, or cause 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
   

5. 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://{myhost}.hydrolix.live
   

   See also Enable TLS.

6. 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://{myhost}.hydrolix.live
   

Kubernetes certificate chain order

Kubernetes requires full chain certificates. The certificate chain should begin with your certificate, continue with intermediate certificates down the chain, and end with the root certificate:

-----BEGIN CERTIFICATE-----  
{ Your issued Certificate }  
-----END CERTIFICATE-----  
----BEGIN CERTIFICATE-----  
{ Intermediate Certificate }  
-----END CERTIFICATE-----  
-----BEGIN CERTIFICATE-----  
{ Root Certificate }  
-----END CERTIFICATE-----

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