feat: support externally managed secret (#168)

Author: GrigoryPervakov

api/v1alpha1/clickhousecluster_types.go

@@ -80,6 +80,11 @@ type ClickHouseClusterSpec struct {
 	// VersionProbeTemplate overrides for the version detection Job.
 	// +optional
 	VersionProbeTemplate *VersionProbeTemplate `json:"versionProbeTemplate,omitempty"`
+
+	// ExternalSecret is an optional reference to an externally-managed Secret containing cluster secrets.
+	// The secret must reside in the same namespace as the cluster.
+	// +optional
+	ExternalSecret *ExternalSecret `json:"externalSecret,omitempty"`
 }
 
 // WithDefaults sets default values for ClickHouseClusterSpec fields.
@@ -344,8 +349,13 @@ func (v *ClickHouseCluster) PodDisruptionBudgetNameByShard(shard int32) string {
 	return fmt.Sprintf("%s-%d", v.SpecificName(), shard)
 }
 
-// SecretName returns name of the Secret with operator generated values.
+// SecretName returns name of the Secret with cluster secret values.
+// When ExternalSecret is configured, returns the external secret name instead of the operator-generated one.
 func (v *ClickHouseCluster) SecretName() string {
+	if v.Spec.ExternalSecret != nil {
+		return v.Spec.ExternalSecret.Name
+	}
+
 	return v.SpecificName()
 }
 

api/v1alpha1/common.go

@@ -351,6 +351,34 @@ func (s *ClusterTLSSpec) Validate() error {
 	return nil
 }
 
+// ExternalSecretPolicy controls how the operator treats the external secret's content.
+// +kubebuilder:validation:Enum=Observe;Manage
+type ExternalSecretPolicy string
+
+const (
+	// ExternalSecretPolicyObserve is the default policy: the operator reads and validates the secret;
+	// reconciliation is blocked if any required key is absent.
+	// Missing required keys and their expected formats are reported via the ExternalSecretValid status condition at runtime.
+	ExternalSecretPolicyObserve ExternalSecretPolicy = "Observe"
+	// ExternalSecretPolicyManage is the policy where the operator fills in any missing required keys by generating
+	// values for them. The secret is updated but never owned or deleted by the operator.
+	ExternalSecretPolicyManage ExternalSecretPolicy = "Manage"
+)
+
+// ExternalSecret is a reference to a Secret in the same namespace.
+type ExternalSecret struct {
+	// Name of the Secret.
+	// +kubebuilder:validation:Required
+	Name string `json:"name"`
+
+	// Policy controls how the operator treats the secret's content.
+	// Observe (default): blocks reconciliation if any required key is missing.
+	// Manage: generates missing required keys into the existing secret.
+	// +optional
+	// +kubebuilder:default:=Observe
+	Policy ExternalSecretPolicy `json:"policy,omitempty"`
+}
+
 // SecretKeySelector selects a key of a Secret.
 type SecretKeySelector struct {
 	// The name of the secret in the cluster's namespace to select from.

api/v1alpha1/conditions.go

@@ -75,6 +75,13 @@ const (
 	ClickHouseConditionReplicasInSync       ConditionReason = "ReplicasInSync"
 	ClickHouseConditionDatabasesNotCreated  ConditionReason = "DatabasesNotCreated"
 	ClickHouseConditionReplicasNotCleanedUp ConditionReason = "ReplicasNotCleanedUp"
+
+	// ClickHouseConditionTypeExternalSecretValid indicates whether the externally managed Secret contains all required keys.
+	// This condition is present only when spec.externalSecret is configured; it is removed when externalSecret is unset.
+	ClickHouseConditionTypeExternalSecretValid      ConditionType   = "ExternalSecretValid"
+	ClickHouseConditionReasonExternalSecretValid    ConditionReason = "ExternalSecretValid"
+	ClickHouseConditionReasonExternalSecretNotFound ConditionReason = "ExternalSecretNotFound"
+	ClickHouseConditionReasonExternalSecretInvalid  ConditionReason = "ExternalSecretInvalid"
 )
 
 // KeeperCluster specific condition types and reasons.
@@ -88,33 +95,3 @@ const (
 	KeeperConditionReasonWaitingFollowers         ConditionReason = "WaitingFollowers"
 	KeeperConditionReasonReadyToScale             ConditionReason = "ReadyToScale"
 )
-
-var (
-	// AllClickHouseConditionTypes lists all ClickHouseCluster condition types.
-	AllClickHouseConditionTypes = []ConditionType{
-		ConditionTypeSpecValid,
-		ConditionTypeReconcileSucceeded,
-		ConditionTypeReplicaStartupSucceeded,
-		ConditionTypeHealthy,
-		ConditionTypeClusterSizeAligned,
-		ConditionTypeConfigurationInSync,
-		ConditionTypeVersionInSync,
-		ConditionTypeVersionUpgraded,
-		ConditionTypeReady,
-		ClickHouseConditionTypeSchemaInSync,
-	}
-
-	// AllKeeperConditionTypes lists all KeeperCluster condition types.
-	AllKeeperConditionTypes = []ConditionType{
-		ConditionTypeSpecValid,
-		ConditionTypeReconcileSucceeded,
-		ConditionTypeReplicaStartupSucceeded,
-		ConditionTypeHealthy,
-		ConditionTypeClusterSizeAligned,
-		ConditionTypeConfigurationInSync,
-		ConditionTypeVersionInSync,
-		ConditionTypeVersionUpgraded,
-		ConditionTypeReady,
-		KeeperConditionTypeScaleAllowed,
-	}
-)

api/v1alpha1/events.go

@@ -25,6 +25,12 @@ const (
 	EventReasonClusterNotReady EventReason = "ClusterNotReady"
 )
 
+// Event reasons for external secret issues.
+const (
+	EventReasonExternalSecretInvalid  EventReason = "ExternalSecretInvalid"
+	EventReasonExternalSecretNotFound EventReason = "ExternalSecretNotFound"
+)
+
 // Event reasons for version checks.
 const (
 	EventReasonVersionDiverge     EventReason = "VersionDiverge"

api/v1alpha1/zz_generated.deepcopy.go

@@ -1091,6 +1091,27 @@ spec:
                       backing this claim.
                     type: string
                 type: object
+              externalSecret:
+                description: |-
+                  ExternalSecret is an optional reference to an externally-managed Secret containing cluster secrets.
+                  The secret must reside in the same namespace as the cluster.
+                properties:
+                  name:
+                    description: Name of the Secret.
+                    type: string
+                  policy:
+                    default: Observe
+                    description: |-
+                      Policy controls how the operator treats the secret's content.
+                      Observe (default): blocks reconciliation if any required key is missing.
+                      Manage: generates missing required keys into the existing secret.
+                    enum:
+                    - Observe
+                    - Manage
+                    type: string
+                required:
+                - name
+                type: object
               keeperClusterRef:
                 description: Reference to the KeeperCluster that is used for ClickHouse
                   coordination.

config/crd/bases/clickhouse.com_clickhouseclusters.yaml

@@ -1094,6 +1094,27 @@ spec:
                       backing this claim.
                     type: string
                 type: object
+              externalSecret:
+                description: |-
+                  ExternalSecret is an optional reference to an externally-managed Secret containing cluster secrets.
+                  The secret must reside in the same namespace as the cluster.
+                properties:
+                  name:
+                    description: Name of the Secret.
+                    type: string
+                  policy:
+                    default: Observe
+                    description: |-
+                      Policy controls how the operator treats the secret's content.
+                      Observe (default): blocks reconciliation if any required key is missing.
+                      Manage: generates missing required keys into the existing secret.
+                    enum:
+                    - Observe
+                    - Manage
+                    type: string
+                required:
+                - name
+                type: object
               keeperClusterRef:
                 description: Reference to the KeeperCluster that is used for ClickHouse
                   coordination.

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

@@ -58,6 +58,7 @@ ClickHouseClusterSpec defines the desired state of ClickHouseCluster.
 | `clusterDomain` | string | ClusterDomain is the Kubernetes cluster domain suffix used for DNS resolution. | false | cluster.local |
 | `upgradeChannel` | string | UpgradeChannel specifies the release channel for major version upgrade checks.<br />When empty, only minor updates will be proposed. Allowed values are: stable, lts or specific major.minor version (e.g. 25.8). | false |  |
 | `versionProbeTemplate` | [VersionProbeTemplate](#versionprobetemplate) | VersionProbeTemplate overrides for the version detection Job. | false |  |
+| `externalSecret` | [ExternalSecret](#externalsecret) | ExternalSecret is an optional reference to an externally-managed Secret containing cluster secrets.<br />The secret must reside in the same namespace as the cluster. | false |  |
 
 Appears in:
 - [ClickHouseCluster](#clickhousecluster)
@@ -181,6 +182,32 @@ Appears in:
 
 
 
+## ExternalSecret
+
+ExternalSecret is a reference to a Secret in the same namespace.
+
+| Field | Type | Description | Required | Default |
+|-------|------|-------------|----------|---------|
+| `name` | string | Name of the Secret. | true |  |
+| `policy` | [ExternalSecretPolicy](#externalsecretpolicy) | Policy controls how the operator treats the secret's content.<br />Observe (default): blocks reconciliation if any required key is missing.<br />Manage: generates missing required keys into the existing secret. | false | Observe |
+
+Appears in:
+- [ClickHouseClusterSpec](#clickhouseclusterspec)
+
+
+## ExternalSecretPolicy
+
+ExternalSecretPolicy controls how the operator treats the external secret's content.
+
+| Field | Description |
+|-------|-------------|
+| `Observe` | ExternalSecretPolicyObserve is the default policy: the operator reads and validates the secret;<br />reconciliation is blocked if any required key is absent.<br />Missing required keys and their expected formats are reported via the ExternalSecretValid status condition at runtime.<br /> |
+| `Manage` | ExternalSecretPolicyManage is the policy where the operator fills in any missing required keys by generating<br />values for them. The secret is updated but never owned or deleted by the operator.<br /> |
+
+Appears in:
+- [ExternalSecret](#externalsecret)
+
+
 ## KeeperCluster
 
 KeeperCluster is the Schema for the `keeperclusters` API.

docs/api_reference.md

@@ -69,9 +69,11 @@ const (
 )
 
 type secretSpec struct {
-	Key      string
-	Env      string
-	Format   string
+	Key    string
+	Env    string
+	Format string
+	// Hint is a human-readable description of the expected value.
+	Hint     string
 	Generate func() any
 	Enabled  func(cluster *v1.ClickHouseCluster) bool
 }
@@ -96,11 +98,12 @@ var (
 	minVersionNamedCollections    = upgrade.ClickHouseVersion{Major: 25, Minor: 12} //nolint:mnd
 	breakingStatefulSetVersion, _ = semver.Parse("0.0.1")
 	clusterSecrets                = []secretSpec{
-		{Key: SecretKeyInterserverPassword, Env: EnvInterserverPassword, Format: "%s"},
-		{Key: SecretKeyManagementPassword, Format: "%s"},
-		{Key: SecretKeyKeeperIdentity, Env: EnvKeeperIdentity, Format: "clickhouse:%s"},
-		{Key: SecretKeyClusterSecret, Env: EnvClusterSecret, Format: "%s"},
+		{Key: SecretKeyInterserverPassword, Env: EnvInterserverPassword, Format: "%s", Hint: "plaintext password"},
+		{Key: SecretKeyManagementPassword, Format: "%s", Hint: "plaintext password"},
+		{Key: SecretKeyKeeperIdentity, Env: EnvKeeperIdentity, Format: "clickhouse:%s", Hint: `"clickhouse:<password>"`},
+		{Key: SecretKeyClusterSecret, Env: EnvClusterSecret, Format: "%s", Hint: "plaintext password"},
 		{Key: SecretKeyNamedCollectionsKey, Env: EnvNamedCollectionsKey, Format: "%x",
+			Hint:     fmt.Sprintf("hex-encoded %d-byte AES key", NamedCollectionsKeyByteLen),
 			Generate: func() any { return controllerutil.GenerateRandomBytes(NamedCollectionsKeyByteLen) },
 			Enabled: func(cluster *v1.ClickHouseCluster) bool {
 				return upgrade.VersionAtLeast(cluster.Status.Version, minVersionNamedCollections)

internal/controller/clickhouse/constants.go

@@ -515,4 +515,83 @@ var _ = When("reconciling ClickHouseCluster", Ordered, func() {
 		}, &sts)).To(Succeed())
 		Expect(sts.Annotations[controllerutil.AnnotationSpecHash]).ToNot(Equal(pvcCR.Status.StatefulSetRevision))
 	})
+
+	It("should correctly work with ExternalSecret", func(ctx context.Context) {
+		By("creating a new cluster with ExternalSecret")
+
+		secret := corev1.Secret{
+			ObjectMeta: metav1.ObjectMeta{
+				Namespace: "default",
+				Name:      "eso-managed-secret",
+			},
+			Data: map[string][]byte{
+				SecretKeyInterserverPassword: []byte("interserver-pass"),
+			},
+		}
+
+		esoCR := &v1.ClickHouseCluster{
+			ObjectMeta: metav1.ObjectMeta{
+				Name:      "ext-secret",
+				Namespace: "default",
+			},
+			Spec: v1.ClickHouseClusterSpec{
+				KeeperClusterRef: &corev1.LocalObjectReference{Name: keeperName},
+				ExternalSecret: &v1.ExternalSecret{
+					Name: secret.Name,
+				},
+			},
+		}
+		Expect(suite.Client.Create(ctx, esoCR)).To(Succeed())
+
+		By("reconciling without secret")
+
+		_, err := controller.Reconcile(ctx, ctrl.Request{NamespacedName: esoCR.NamespacedName()})
+		Expect(err).NotTo(HaveOccurred())
+		Expect(suite.Client.Get(ctx, esoCR.NamespacedName(), esoCR)).To(Succeed())
+
+		cond := meta.FindStatusCondition(esoCR.Status.Conditions, v1.ClickHouseConditionTypeExternalSecretValid)
+		Expect(cond).ToNot(BeNil())
+		Expect(cond.Status).To(Equal(metav1.ConditionFalse))
+		Expect(cond.Reason).To(BeEquivalentTo(v1.ClickHouseConditionReasonExternalSecretNotFound))
+
+		testutil.AssertEvents(recorder.Events, map[string]int{
+			"ExternalSecretNotFound": 1,
+			"ClusterNotReady":        1,
+		})
+
+		testutil.CompleteVersionProbeJob(ctx, suite, esoCR.Namespace, esoCR.SpecificName(), "26.1.1.1")
+
+		By("creating partial secret and reconciling")
+		Expect(suite.Client.Create(ctx, &secret)).To(Succeed())
+		_, err = controller.Reconcile(ctx, ctrl.Request{NamespacedName: esoCR.NamespacedName()})
+		Expect(err).NotTo(HaveOccurred())
+		Expect(suite.Client.Get(ctx, esoCR.NamespacedName(), esoCR)).To(Succeed())
+
+		cond = meta.FindStatusCondition(esoCR.Status.Conditions, v1.ClickHouseConditionTypeExternalSecretValid)
+		Expect(cond).ToNot(BeNil())
+		Expect(cond.Status).To(Equal(metav1.ConditionFalse))
+		Expect(cond.Reason).To(BeEquivalentTo(v1.ClickHouseConditionReasonExternalSecretInvalid))
+		Expect(cond.Message).To(ContainSubstring("cluster-secret"))
+		Expect(cond.Message).To(ContainSubstring("keeper-identity"))
+		Expect(cond.Message).To(ContainSubstring("management-password"))
+		Expect(cond.Message).To(ContainSubstring("plaintext password"))
+		Expect(cond.Message).NotTo(ContainSubstring("interserver-password"))
+
+		By("reconciling with external secret manage policy")
+
+		esoCR.Spec.ExternalSecret.Policy = v1.ExternalSecretPolicyManage
+		Expect(suite.Client.Update(ctx, esoCR)).To(Succeed())
+		_, err = controller.Reconcile(ctx, ctrl.Request{NamespacedName: esoCR.NamespacedName()})
+		Expect(err).NotTo(HaveOccurred())
+
+		Expect(suite.Client.Get(ctx, esoCR.NamespacedName(), esoCR)).To(Succeed())
+		cond = meta.FindStatusCondition(esoCR.Status.Conditions, v1.ClickHouseConditionTypeExternalSecretValid)
+		Expect(cond).ToNot(BeNil())
+		Expect(cond.Status).To(Equal(metav1.ConditionTrue))
+		Expect(cond.Reason).To(BeEquivalentTo(v1.ClickHouseConditionReasonExternalSecretValid))
+
+		Expect(suite.Client.Get(ctx, client.ObjectKeyFromObject(&secret), &secret)).To(Succeed())
+		Expect(secret.Data).To(HaveKey(SecretKeyManagementPassword))
+		Expect(secret.Data).To(HaveKey(SecretKeyClusterSecret))
+	})
 })