How-To Guides

This section contains guides for common setups of ClickHouse on private environments.

How-To: Configure Cert Manager to generate the certificates for ClickHouse Server & Keeper

This guide assumes Cert Manager is already installed in the cluster. Additionally, the guide assumes that the ClickHouse Cluster is named default-xx-01.

First we need a certificate authority (CA) to sign the certificates:

apiVersion: cert-manager.io/v1
kind: Issuer
metadata:
  name: selfsigned-issuer
spec:
  selfSigned: {}

For simplicity we use a self-signed Issuer as this will generate a valid CA. This is for testing purposes, for a production grade Issuer we recommend looking at the list of options.

After this we can create a certificate using the Certificate resource:

apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
  name: clickhouse-server-tls
  namespace: ns-default-xx-01
spec:
  secretName: default-xx-01-server-cert-secret
  dnsNames:
    - "*.default-xx-01.ns-default-xx-01.svc.cluster.local"
  issuerRef:
    name: selfsigned-issuer
    kind: Issuer

This will create a secret with the name default-xx-01-server-cert-secret and with the keys ca.crt, tls.crt, and tls.key.

Note that the ca.crt only gets added if it is available from the issuer. E.g. with ACME no ca.crt is added to the secret. In this case the public root should be added to the ca.crt value of the key (e.g. using trust-manager to generate the CA bundle and target the correct secret).

By default the onprem-ClickHouse-cluster Helm chart expects a secret with the name <cluster_name>-server-cert-secret with the keys ca.crt, server.crt & server.key.

The following values can be used to ensure the ClickHouse Cluster loads the certificates from the right keys of the secret:

# Use default secret name (default-xx-01-server-cert-secret) - no need to specify
server:
  openSSL:
    enabled: true
    secret:
      caKey: ca.crt
      certKey: tls.crt
      keyKey: tls.key

The certificates are mounted in the pods at /etc/ClickHouse-server/certs/ for ClickHouse Server or /etc/clickhouse-keeper/certs/ for ClickHouse Keeper. The correct OpenSSL configuration for ClickHouse is generated by the Helm chart.

How-To: Configure remote_servers with secretKeyRef and @from_env

You’ll need at least version 1.1.151 of the onprem-clickHouse-cluster Helm Chart in order to configure ClickHouse Server’s remote_servers setting

This guide shows how to configure remote_servers for use with Distributed tables and the cluster() function. This guide assumes the ClickHouse Cluster is named default-xx-01 and there is a secret named default-xx-01-password in the cluster namespace.

Note: If you integrate with external secret stores, a similar approach can be followed using the Kubernetes Secrets Store CSI Driver to mount and load the secret as an environment variable.

The recommended approach uses Kubernetes secrets with secretKeyRef to inject sensitive data as environment variables, then references those variables in the ClickHouse configuration using @from_env.

Example:

server:
  additionalEnvVars:
    - name: DEFAULT_XX_01_PASSWORD
      valueFrom:
        secretKeyRef:
          name: default-xx-01-password
          key: password
  config:
    remote_servers:
      default-xx-01:
        shard:
          - replica:
              user: default
              password:
                "@from_env": DEFAULT_XX_01_PASSWORD
              host: c-default-xx-01-server-0r280c0-0.c-default-xx-01-server-headless.ns-default-xx-01.svc.cluster.local
              port: 9000
          - replica:
              user: default
              password:
                "@from_env": DEFAULT_XX_01_PASSWORD
              host: c-default-xx-01-server-f9cshqb-0.c-default-xx-01-server-headless.ns-default-xx-01.svc.cluster.local
              port: 9000
          - replica:
              user: default
              password:
                "@from_env": DEFAULT_XX_01_PASSWORD
              host: c-default-xx-01-server-gsip6lp-0.c-default-xx-01-server-headless.ns-default-xx-01.svc.cluster.local
              port: 9000

This pattern ensures sensitive data is not templated directly in manifests. The additionalEnvVars field sets environment variables from Kubernetes secrets using secretKeyRef, and the @from_env directive in the ClickHouse configuration loads those values at runtime.

Note the FQDN format for replica hosts follows the Kubernetes pattern: <pod-name>.<headless-service-name>.<namespace>.svc.cluster.local.