> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-sync-clickhouse-operator-docs-7e82242.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](https://cert-manager.io/) 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:

```yaml theme={null}
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](https://cert-manager.io/docs/configuration/issuers/).

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

```yaml theme={null}
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](https://cert-manager.io/docs/trust/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:

```yaml theme={null}
# 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`](/core/reference/settings/server-settings/settings#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](https://kubernetes.io/docs/concepts/configuration/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](https://github.com/kubernetes-sigs/secrets-store-csi-driver) to mount and [load the secret as an environment variable](https://secrets-store-csi-driver.sigs.k8s.io/topics/set-as-env-var).

The recommended approach uses [Kubernetes secrets with `secretKeyRef`](https://kubernetes.io/docs/tasks/inject-data-application/distribute-credentials-secure/#define-container-environment-variables-using-secret-data) to inject sensitive data as environment variables, then references those variables in the ClickHouse configuration using [`@from_env`](/core/concepts/features/configuration/server-config/configuration-files#from_env_zk).

Example:

```yaml theme={null}
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`.