Enable TLS

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.
4. Use an External Load Balancer AWS. This solution delegates certificate acquisition and termination responsibility to an AWS Network Load Balancer, which passes through the decrypted connections to the Hydrolix cluster.

Mapping certificates to applications

The Hydrolix reverse proxy software supports a single certificate. This certificate may hold any number of Subject Alternative Names (SANs) and customarily listens on a single IP address, usually managed by an external load balancer which directs traffic to the cluster.

In the common case, the hydrolix_url cluster hostname is the only SAN on the TLS certificate.

Some applications inside the cluster expect or require a distinct hostname to receive traffic.

For these cases, Hydrolix supports the necessary certificate and HTTP routing configuration.

Example describing Superset and wildcard

The Superset pages describe using the Hydrolix ACME Client and credentials to control an AWS Route 53 hosted zone to install and configure the cluster to support this type of configuration.

Using {myhost}.hydrolix.live as an example name, traffic is handled as follows:

• The certificate must contain SANs for both *.{myhost}.hydrolix.live, the wildcard name, and {myhost}.hydrolix.live, the hydrolix_url
• The reverse proxy sends all traffic for the hydrolix_url name, {myhost}.hydrolix.live to the corresponding applications
• All traffic for the name superset.{myhost}.hydrolix.live goes to the Superset pod and application

See also Kibana Automatic Installation which bundles the Quesma application. Administrators can elect to enable public access to Quesma, which also makes use of the same configuration described for Superset.

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.