Enable TLS

Use TLS to communicate securely with your Hydrolix cluster services and endpoints

Overview

Hydrolix provides multiple ways to manage and use certificates on your cluster.

TLS options

  1. Use the provided Hydrolix ACME Client. It interacts with Let's Encrypt or Buypass for automated certificate provisioning and renewal for all Hydrolix TLS requirements.
  2. Run the Kubernetes Certificate Manager in your cluster. Store the certificate data in a Kubernetes Secret accessible to the Hydrolix operator software, which installs it into the reverse proxy and other required Hydrolix servers. The cert-manager software interacts with many certification authorities (CAs) and provides domain and hostname ownership challenge solvers for working with many managed DNS providers.
  3. Bring your own certificate and Provision Certificate Manually into the cluster configuration. This technique allows external acquisition of certificates when choice of a certification authority (CA) is important or automation isn't desired.

Enable TLS

To enable TLS termination, change the protocol in the hydrolix_url to https.

In your hydrolixcluster.yaml configuration file, select one of the below lines with your cluster hostname.

spec:
  hydrolix_url: https://{myhost}.hydrolix.live     # -- Configures Hydrolix cluster to use TLS
  hydrolix_url: http://{myhost}.hydrolix.live      # -- Configures Hydrolix cluster to use plaintext HTTP

Network listeners

When the hydrolix_url protocol is http:

  • all incoming traffic to HTTP on tcp/80 is routed to the Hydrolix applications
  • the ClickHouse native service is available on tcp/9000

When the hydrolix_url protocol is https:

  • all incoming connections to HTTPS on tcp/443 are TLS-terminated on the traefik reverse proxy and then routed to Hydrolix applications
  • only requests for ACME /.well-known/acme-challenge/ are served over plaintext HTTP on tcp/80
  • all other incoming connections to HTTP on tcp/80 are application-redirected to HTTPS on port tcp/443
  • the ClickHouse native service is available over TLS on tcp/9440

Ports mentioned above are all default. They're individually configurable using Hydrolix tunables.

  • use http_port for plaintext HTTP
  • use https_port for HTTPS
  • use native_port for ClickHouse native protocol
  • use native_tls_port for TLS-wrapped ClickHouse native protocol

See Hydrolix Tunables List and Hydrolix Tunables for usage information.

⚠️

Consult detail pages for external TLS solutions

When the TLS termination occurs outside of the cluster, consult the external TLS documentation pages here for instructions.

When https is configured in the cluster, the traefik reverse proxy terminates incoming TLS connection requests.

If there is no configured certificate in the traefik-tls cluster secret, Hydrolix uses a self-signed certificate until a certificate is automatically acquired or manually configured.

Disable TLS

Use http in hydrolix_url

In your hydrolixcluster.yaml configuration file, choose http as the protocol.

spec:
  hydrolix_url: http://{myhost}.hydrolix.live

See Network listeners for the changes to the network services and ports.

Turn off HTTPS listener

Prevent the cluster from listening for HTTPS (TLS) connections with the tunable disable_traefik_https_port.

spec:
  disable_traefik_https_port: true

Under this configuration, incoming connections to tcp/443 will be ignored.

Turn off HTTP listener

Prevent the cluster from listening for plaintext HTTP connections using the tunable disable_traefik_http_port.

Under this configuration, incoming connections to tcp/80 will be ignored.

spec:
  disable_traefik_http_port: true

⚠️

TLS HTTP Challenges Can Require HTTP

CAs use plaintext HTTP on tcp/80 to complete the HTTP Challenge. If your certificate uses this method for proof of control of hostname, don't disable plaintext HTTP.

See Hydrolix Tunables List and Hydrolix Tunables for usage information.