SAP · nejec · Jul 13, 2026
diff --git a/README.md b/README.md
@@ -9,7 +9,7 @@ which can be used to deploy valkey caches for cluster-internal usage. For exampl
 
 ```yaml
 apiVersion: cache.cs.sap.com/v1alpha1
-kind: Valkey 
+kind: Valkey
 metadata:
   name: test
 spec:
@@ -30,6 +30,75 @@ to install valkey in the cluster. As a consequence of this fact, the following t
 
 Sharding (valkey-cluster) scenarios are not supported.
 
+### Image and version
+
+By default the operator deploys the `bitnamilegacy/valkey` image from Docker Hub, at the tag the underlying
+chart pins. The image can be customized through the following attributes:
+
+- `spec.version` sets the image tag (shorthand for `spec.image.tag`).
+- `spec.image.registry`, `spec.image.repository` and `spec.image.tag` address the Valkey server image.
+  `spec.image.tag` takes precedence over `spec.version`.
+- `spec.image.pullPolicy` sets the pull policy of the server, sentinel and exporter images.
+- `spec.image.pullSecrets` references secrets used to pull from a private registry; they are set on the
+  pod, so they cover its sidecar images too.
+- `spec.sentinel.image` and `spec.metrics.image` address the sentinel and metrics exporter images, each
+  taking its own `registry`, `repository` and `tag`. `spec.sentinel.image` covers the sidecar only; the
+  Valkey server container in a sentinel pod takes `spec.image`.
+
+Both sidecars inherit `registry` from `spec.image`; the sentinel inherits `tag` too, while the exporter
+carries its own version rather than Valkey's. `repository` never inherits: each image keeps its own
+default, so mirroring into a flat path means setting `repository` on each image.
+
+The tag is used verbatim, so it is a literal image tag rather than a bare Valkey version. The bundled
+Bitnami-based images carry an OS/revision suffix, e.g. `8.1.2-debian-12-r0`, and a bare `8.1.2` only works
+if your registry publishes it.
+
+For example, to pull all images from a private mirror of the bundled repositories:
+
+```yaml
+spec:
+  image:
+    registry: registry.example.com
+    tag: 8.1.2-debian-12-r0
+    pullSecrets:
+    - my-registry-secret
+```
+
+`spec.image.registry` replaces the registry segment only, so the images resolve to:
+
+- `registry.example.com/bitnamilegacy/valkey:8.1.2-debian-12-r0`
+- `registry.example.com/bitnamilegacy/valkey-sentinel:8.1.2-debian-12-r0` (sentinel mode)
+- `registry.example.com/bitnamilegacy/redis-exporter:<tag bundled with the chart>` (if metrics are enabled)
+
+If your mirror uses a different layout, spell each image out in full. A `registry` may include a path prefix:
+
+```yaml
+spec:
+  image:
+    registry: harbor.example.com/dockerhub
+    repository: mycorp/valkey
+    tag: 8.1.2-debian-12-r0
+  sentinel:
+    enabled: true
+    image:
+      repository: mycorp/valkey-sentinel
+  metrics:
+    enabled: true
+    image:
+      registry: quay.example.com
+      repository: mycorp/redis-exporter
+      tag: 1.67.0-debian-12-r0
+```
+
+The pull secrets have to exist in the namespace of the `Valkey` object; the operator does not create them.
+
+Without `spec.metrics.image.tag` the exporter uses whatever `metrics.image.tag` is pinned to in
+[the bundled chart](pkg/operator/data/charts/valkey/values.yaml). That pin moves when the operator bumps the
+chart, so set the tag explicitly if you mirror the exporter.
+
+Server, sentinel and exporter are the only images the operator renders itself. It passes images from
+`spec.sidecars` through unchanged.
+
 ### Sentinel mode
 
 If `spec.sentinel.enabled` is false, one valkey primary node will be deployed, and `spec.replicas - 1` read replicas.

diff --git a/api/v1alpha1/types.go b/api/v1alpha1/types.go
@@ -24,6 +24,7 @@ type ValkeySpec struct {
 	Replicas                                int `json:"replicas,omitempty"`
 	component.KubernetesPodProperties       `json:",inline"`
 	component.KubernetesContainerProperties `json:",inline"`
+	Image                                   *ImageProperties       `json:"image,omitempty"`
 	Sidecars                                []corev1.Container     `json:"sidecars,omitempty"`
 	Sentinel                                *SentinelProperties    `json:"sentinel,omitempty"`
 	Metrics                                 *MetricsProperties     `json:"metrics,omitempty"`
@@ -34,15 +35,41 @@ type ValkeySpec struct {
 	ExtraFlags                              []string               `json:"extraFlags,omitempty"`
 }
 
+// ImageProperties addresses the Valkey server image. Pull policy applies to the server, sentinel
+// and exporter images. Pull secrets are set on the pod, so they cover its sidecar images too.
+// The sentinel also inherits registry and tag; the exporter inherits only registry.
+type ImageProperties struct {
+	Registry   string `json:"registry,omitempty"`
+	Repository string `json:"repository,omitempty"`
+	Tag        string `json:"tag,omitempty"`
+	// +kubebuilder:validation:Enum=Always;Never;IfNotPresent
+	PullPolicy  corev1.PullPolicy `json:"pullPolicy,omitempty"`
+	PullSecrets []string          `json:"pullSecrets,omitempty"`
+}
+
+// ImageOverride addresses one image on its own. Registry falls back to spec.image, and so does the
+// sentinel's tag. Repository never falls back: each image keeps its own default. Pull policy and
+// pull secrets always come from spec.image.
+type ImageOverride struct {
+	Registry   string `json:"registry,omitempty"`
+	Repository string `json:"repository,omitempty"`
+	Tag        string `json:"tag,omitempty"`
+}
+
 // SentinelProperties models attributes of the sentinel sidecar
 type SentinelProperties struct {
-	Enabled                                 bool `json:"enabled,omitempty"`
+	Enabled bool `json:"enabled,omitempty"`
+	// Image of the sentinel sidecar. The valkey server container in the same pod takes its image
+	// from spec.image.
+	Image                                   *ImageOverride `json:"image,omitempty"`
 	component.KubernetesContainerProperties `json:",inline"`
 }
 
 // MetricsProperties models attributes of the metrics exporter sidecar
 type MetricsProperties struct {
-	Enabled                                 bool `json:"enabled,omitempty"`
+	Enabled bool `json:"enabled,omitempty"`
+	// Image of the metrics exporter. Its tag defaults to the version bundled with the chart.
+	Image                                   *ImageOverride `json:"image,omitempty"`
 	component.KubernetesContainerProperties `json:",inline"`
 	ServiceMonitor                          *MetricsServiceMonitorProperties `json:"monitor,omitempty"`
 	PrometheusRule                          *MetricsPrometheusRuleProperties `json:"prometheusRule,omitempty"`

diff --git a/api/v1alpha1/zz_generated.deepcopy.go b/api/v1alpha1/zz_generated.deepcopy.go
diff --git a/crds/cache.cs.sap.com_valkeys.yaml b/crds/cache.cs.sap.com_valkeys.yaml
@@ -1127,12 +1127,48 @@ spec:
                 items:
                   type: string
                 type: array
+              image:
+                description: |-
+                  ImageProperties addresses the Valkey server image. Pull policy applies to the server, sentinel
+                  and exporter images. Pull secrets are set on the pod, so they cover its sidecar images too.
+                  The sentinel also inherits registry and tag; the exporter inherits only registry.
+                properties:
+                  pullPolicy:
+                    description: PullPolicy describes a policy for if/when to pull
+                      a container image
+                    enum:
+                    - Always
+                    - Never
+                    - IfNotPresent
+                    type: string
+                  pullSecrets:
+                    items:
+                      type: string
+                    type: array
+                  registry:
+                    type: string
+                  repository:
+                    type: string
+                  tag:
+                    type: string
+                type: object
               metrics:
                 description: MetricsProperties models attributes of the metrics exporter
                   sidecar
                 properties:
                   enabled:
                     type: boolean
+                  image:
+                    description: Image of the metrics exporter. Its tag defaults to
+                      the version bundled with the chart.
+                    properties:
+                      registry:
+                        type: string
+                      repository:
+                        type: string
+                      tag:
+                        type: string
+                    type: object
                   monitor:
                     properties:
                       additionalLabels:
@@ -4081,6 +4117,18 @@ spec:
                 properties:
                   enabled:
                     type: boolean
+                  image:
+                    description: |-
+                      Image of the sentinel sidecar. The valkey server container in the same pod takes its image
+                      from spec.image.
+                    properties:
+                      registry:
+                        type: string
+                      repository:
+                        type: string
+                      tag:
+                        type: string
+                    type: object
                   resources:
                     description: ResourceRequirements describes the compute resource
                       requirements.

diff --git a/pkg/operator/data/binding.yaml b/pkg/operator/data/binding.yaml
@@ -11,7 +11,7 @@ primaryPort: {{ .primaryPort }}
 replicaHost: {{ .replicaHost }}
 replicaPort: {{ .replicaPort }}
 {{- end }}
-password: {{ .password }}
+password: {{ .password | quote }}
 {{- if .tlsEnabled }}
 tlsEnabled: true
 caData: |