feat: do not set caBundle from certificate by default, only with explicit setting

Author: GrigoryPervakov

api/v1alpha1/clickhousecluster_types.go

@@ -158,10 +158,6 @@ func (s *ClickHouseClusterSpec) WithDefaults() {
 		}
 	}
 
-	if s.Settings.TLS.CABundle != nil && s.Settings.TLS.CABundle.Key == "" {
-		s.Settings.TLS.CABundle.Key = "ca.crt"
-	}
-
 	if s.DataVolumeClaimSpec != nil && len(s.DataVolumeClaimSpec.AccessModes) == 0 {
 		s.DataVolumeClaimSpec.AccessModes = []corev1.PersistentVolumeAccessMode{DefaultAccessMode}
 	}

api/v1alpha1/common.go

@@ -324,17 +324,27 @@ type ClusterTLSSpec struct {
 	// +kubebuilder:default:=false
 	// +optional
 	Required bool `json:"required,omitempty"`
-	// ServerCertSecretRef is a reference to a TLS Secret containing the server certificate.
+	// ServerCertSecret is a reference to a TLS Secret containing the server certificate.
 	// It is expected that the Secret has the same structure as certificates generated by cert-manager,
 	// with the certificate and private key stored under "tls.crt" and "tls.key" keys respectively.
 	// +optional
 	ServerCertSecret *corev1.LocalObjectReference `json:"serverCertSecret,omitempty"`
-	// CABundle is a reference to a TLS Secret containing the CA bundle.
-	// If empty and ServerCertSecret is specified, the CA bundle from certificate will be used.
-	// Otherwise, system trusted CA bundle will be used.
+	// CABundle is a reference to a Secret key holding a CA bundle used to verify peer certificates.
+	// If empty, the system trusted CA bundle is used.
 	// Key is defaulted to "ca.crt" if not specified.
 	// +optional
-	CABundle *SecretKeySelector `json:"caBundle,omitempty"`
+	CABundle *CABundleSelector `json:"caBundle,omitempty"`
+}
+
+// CABundleSelector selects a key holding a CA bundle from a Secret in the cluster's namespace.
+type CABundleSelector struct {
+	// The name of the secret in the cluster's namespace to select from.
+	// +kubebuilder:validation:Required
+	Name string `json:"name,omitempty"`
+	// The key of the secret to select from.  Must be a valid secret key.
+	// +kubebuilder:default:="ca.crt"
+	// +optional
+	Key string `json:"key,omitempty"`
 }
 
 // Validate validates the ClusterTLSSpec configuration.

api/v1alpha1/zz_generated.deepcopy.go

@@ -5,7 +5,7 @@ LABEL operators.operatorframework.io.bundle.mediatype.v1=registry+v1
 LABEL operators.operatorframework.io.bundle.manifests.v1=manifests/
 LABEL operators.operatorframework.io.bundle.metadata.v1=metadata/
 LABEL operators.operatorframework.io.bundle.package.v1=clickhouse-operator
-LABEL operators.operatorframework.io.bundle.channels.v1=stable
+LABEL operators.operatorframework.io.bundle.channels.v1=stable,fast
 LABEL operators.operatorframework.io.bundle.channel.default.v1=stable
 LABEL operators.operatorframework.io.metrics.builder=operator-sdk-v1.42.2
 LABEL operators.operatorframework.io.metrics.mediatype.v1=metrics+v1

bundle.Dockerfile

@@ -6460,12 +6460,12 @@ spec:
                     properties:
                       caBundle:
                         description: |-
-                          CABundle is a reference to a TLS Secret containing the CA bundle.
-                          If empty and ServerCertSecret is specified, the CA bundle from certificate will be used.
-                          Otherwise, system trusted CA bundle will be used.
+                          CABundle is a reference to a Secret key holding a CA bundle used to verify peer certificates.
+                          If empty, the system trusted CA bundle is used.
                           Key is defaulted to "ca.crt" if not specified.
                         properties:
                           key:
+                            default: ca.crt
                             description: The key of the secret to select from.  Must
                               be a valid secret key.
                             type: string
@@ -6474,7 +6474,6 @@ spec:
                               to select from.
                             type: string
                         required:
-                        - key
                         - name
                         type: object
                       enabled:
@@ -6489,7 +6488,7 @@ spec:
                         type: boolean
                       serverCertSecret:
                         description: |-
-                          ServerCertSecretRef is a reference to a TLS Secret containing the server certificate.
+                          ServerCertSecret is a reference to a TLS Secret containing the server certificate.
                           It is expected that the Secret has the same structure as certificates generated by cert-manager,
                           with the certificate and private key stored under "tls.crt" and "tls.key" keys respectively.
                         properties:

config/crd/bases/clickhouse.com_clickhouseclusters.yaml

@@ -6110,12 +6110,12 @@ spec:
                     properties:
                       caBundle:
                         description: |-
-                          CABundle is a reference to a TLS Secret containing the CA bundle.
-                          If empty and ServerCertSecret is specified, the CA bundle from certificate will be used.
-                          Otherwise, system trusted CA bundle will be used.
+                          CABundle is a reference to a Secret key holding a CA bundle used to verify peer certificates.
+                          If empty, the system trusted CA bundle is used.
                           Key is defaulted to "ca.crt" if not specified.
                         properties:
                           key:
+                            default: ca.crt
                             description: The key of the secret to select from.  Must
                               be a valid secret key.
                             type: string
@@ -6124,7 +6124,6 @@ spec:
                               to select from.
                             type: string
                         required:
-                        - key
                         - name
                         type: object
                       enabled:
@@ -6139,7 +6138,7 @@ spec:
                         type: boolean
                       serverCertSecret:
                         description: |-
-                          ServerCertSecretRef is a reference to a TLS Secret containing the server certificate.
+                          ServerCertSecret is a reference to a TLS Secret containing the server certificate.
                           It is expected that the Secret has the same structure as certificates generated by cert-manager,
                           with the certificate and private key stored under "tls.crt" and "tls.key" keys respectively.
                         properties:

config/crd/bases/clickhouse.com_keeperclusters.yaml

@@ -137,7 +137,7 @@ spec:
           every replica.
         displayName: Stateful Set Revision
         path: statefulSetRevision
-      - description: CurrentRevision indicates latest requested KeeperCluster spec
+      - description: UpdateRevision indicates latest requested KeeperCluster spec
           revision.
         displayName: Update Revision
         path: updateRevision
@@ -146,6 +146,7 @@ spec:
         path: version
       - description: |-
           VersionProbeRevision is the image hash of the last successful version probe.
+
           Deprecated: Keeper version probe Jobs are not used; this field is retained for backward compatibility.
         displayName: Version Probe Revision
         path: versionProbeRevision

config/manifests/bases/clickhouse-operator.clusterserviceversion.yaml

@@ -6463,12 +6463,12 @@ spec:
                     properties:
                       caBundle:
                         description: |-
-                          CABundle is a reference to a TLS Secret containing the CA bundle.
-                          If empty and ServerCertSecret is specified, the CA bundle from certificate will be used.
-                          Otherwise, system trusted CA bundle will be used.
+                          CABundle is a reference to a Secret key holding a CA bundle used to verify peer certificates.
+                          If empty, the system trusted CA bundle is used.
                           Key is defaulted to "ca.crt" if not specified.
                         properties:
                           key:
+                            default: ca.crt
                             description: The key of the secret to select from.  Must
                               be a valid secret key.
                             type: string
@@ -6477,7 +6477,6 @@ spec:
                               to select from.
                             type: string
                         required:
-                        - key
                         - name
                         type: object
                       enabled:
@@ -6492,7 +6491,7 @@ spec:
                         type: boolean
                       serverCertSecret:
                         description: |-
-                          ServerCertSecretRef is a reference to a TLS Secret containing the server certificate.
+                          ServerCertSecret is a reference to a TLS Secret containing the server certificate.
                           It is expected that the Secret has the same structure as certificates generated by cert-manager,
                           with the certificate and private key stored under "tls.crt" and "tls.key" keys respectively.
                         properties:

dist/chart/templates/crd/clickhouseclusters.clickhouse.com.yaml

@@ -6113,12 +6113,12 @@ spec:
                     properties:
                       caBundle:
                         description: |-
-                          CABundle is a reference to a TLS Secret containing the CA bundle.
-                          If empty and ServerCertSecret is specified, the CA bundle from certificate will be used.
-                          Otherwise, system trusted CA bundle will be used.
+                          CABundle is a reference to a Secret key holding a CA bundle used to verify peer certificates.
+                          If empty, the system trusted CA bundle is used.
                           Key is defaulted to "ca.crt" if not specified.
                         properties:
                           key:
+                            default: ca.crt
                             description: The key of the secret to select from.  Must
                               be a valid secret key.
                             type: string
@@ -6127,7 +6127,6 @@ spec:
                               to select from.
                             type: string
                         required:
-                        - key
                         - name
                         type: object
                       enabled:
@@ -6142,7 +6141,7 @@ spec:
                         type: boolean
                       serverCertSecret:
                         description: |-
-                          ServerCertSecretRef is a reference to a TLS Secret containing the server certificate.
+                          ServerCertSecret is a reference to a TLS Secret containing the server certificate.
                           It is expected that the Secret has the same structure as certificates generated by cert-manager,
                           with the certificate and private key stored under "tls.crt" and "tls.key" keys respectively.
                         properties:

dist/chart/templates/crd/keeperclusters.clickhouse.com.yaml

@@ -29,17 +29,16 @@ rotate that Secret, but any tool that writes a Secret in the expected format wor
 ## How the operator expects certificates {#secret-format}
 
 TLS is enabled by pointing `spec.settings.tls.serverCertSecret` at a Secret that
-contains three keys:
+contains the server keypair:
 
-| Secret key | Contents                         |
-|------------|----------------------------------|
-| `tls.crt`  | PEM-encoded server certificate   |
-| `tls.key`  | PEM-encoded private key          |
-| `ca.crt`   | PEM-encoded CA certificate chain |
+| Secret key | Contents                       | Required |
+|------------|--------------------------------|----------|
+| `tls.crt`  | PEM-encoded server certificate | Yes      |
+| `tls.key`  | PEM-encoded private key        | Yes      |
 
 This is exactly the layout cert-manager writes for a `Certificate` resource, so no
-conversion is needed. The operator mounts these into each pod at
-`/etc/clickhouse-server/tls/` and wires them into ClickHouse's `openSSL` configuration.
+conversion is needed. The operator mounts the keypair into each pod at
+`/etc/clickhouse-server/tls/` and wires it into ClickHouse's `openSSL` configuration.
 
 <Note>
 `serverCertSecret` is **mandatory** when `tls.enabled: true`. The validating
@@ -232,13 +231,15 @@ spec:
 
 Keeper exposes its secure client port on `2281`. Once Keeper has TLS enabled, **the
 ClickHouse cluster connects to it over TLS automatically** — no extra setting on the
-ClickHouseCluster side. ClickHouse verifies the Keeper certificate using its own
-`ca.crt` bundle when it has TLS enabled, otherwise the system default CA bundle.
+ClickHouseCluster side. ClickHouse verifies the Keeper certificate against the system
+trust store, plus any [`caBundle`](#custom-ca) you configure.
 
 ## Custom CA bundle {#custom-ca}
 
-If ClickHouse must trust a CA different from the one in its server certificate (for
-example, Keeper signed by a separate CA), supply a `caBundle`:
+By default ClickHouse verifies the peers it connects to (other replicas, Keeper, HTTPS
+dictionary sources, S3, …) against the **system trust store**. To **additionally** trust
+a private CA — a self-signed or internal CA whose root is not in the system store —
+supply a `caBundle`:
 
 ```yaml
 spec:
@@ -252,8 +253,11 @@ spec:
         key: ca.crt
 ```
 
-The operator mounts this bundle and points the client-side `openSSL` verification at
-it instead of the certificate's own `ca.crt`.
+The operator mounts this bundle and adds it to the `openSSL` client trust store
+(`caConfig`). The system trust store stays in effect — your private CA is trusted **in
+addition to** the public roots, so connections to public endpoints keep working. For a
+self-signed setup, point `caBundle` at the `ca.crt` key of the same Secret cert-manager
+wrote (as in the `cluster_with_ssl` example).
 
 ## Customizing the TLS settings {#custom-tls-settings}
 
@@ -296,15 +300,15 @@ kubectl -n <namespace> get svc <cluster-name>-clickhouse-headless \
 
 ```bash
 kubectl -n <namespace> exec <pod> -- ls /etc/clickhouse-server/tls/
-# ca-bundle.crt  clickhouse-server.crt  clickhouse-server.key
+# clickhouse-server.crt  clickhouse-server.key   (plus custom-ca.crt when caBundle is set)
 ```
 
-| Symptom | Likely cause |
-|---|---|
-| Pods fail to start / volume mount error after enabling TLS | The referenced Secret is missing or lacks `tls.crt`/`tls.key`/`ca.crt`. The operator does not validate the Secret's contents — missing keys surface as a pod volume-mount failure, not a dedicated status condition. Inspect the pod with `kubectl describe pod`. |
-| Webhook rejects the cluster | `required: true` set without `enabled: true`, or `enabled: true` without `serverCertSecret`. |
-| Client `certificate verify failed` | Client is not trusting the CA. Pass the `ca.crt` from the Secret, or check the `dnsNames` on the certificate cover the host you connect to. |
-| A plaintext client suddenly can't connect | `required: true` removed ports `9000`/`8123`. Switch the client to `9440`/`8443`, or set `required: false` to keep insecure ports open during migration. |
+| Symptom                                                    | Likely cause                                                                                                                                                                                                                                                                                                        |
+|------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| Pods fail to start / volume mount error after enabling TLS | The referenced Secret is missing or lacks `tls.crt`/`tls.key` (or, when `caBundle` is set, the Secret/key it references). The operator does not validate the Secret's contents — missing keys surface as a pod volume-mount failure, not a dedicated status condition. Inspect the pod with `kubectl describe pod`. |
+| Webhook rejects the cluster                                | `required: true` set without `enabled: true`, or `enabled: true` without `serverCertSecret`.                                                                                                                                                                                                                        |
+| Client `certificate verify failed`                         | Client is not trusting the CA. Pass the `ca.crt` from the Secret, or check the `dnsNames` on the certificate cover the host you connect to.                                                                                                                                                                         |
+| A plaintext client suddenly can't connect                  | `required: true` removed ports `9000`/`8123`. Switch the client to `9440`/`8443`, or set `required: false` to keep insecure ports open during migration.                                                                                                                                                            |
 
 ## See also {#see-also}