diff --git a/valkey-resources/CHANGELOG.md b/valkey-resources/CHANGELOG.md index 477a4215..4597e02c 100644 --- a/valkey-resources/CHANGELOG.md +++ b/valkey-resources/CHANGELOG.md @@ -1,5 +1,16 @@ # Changelog +## 0.1.3 + +### Added + +- Example values under [`examples/`](examples/): minimal topology, `scheduling.node.spread`, zone topology spread, TLS secret ref, persistence, PodMonitor, and ACL users. +- Index and usage notes in [`examples/README.md`](examples/README.md). + +### Notes + +- Helm unittest smoke renders for the examples directory are deferred to a follow-up. + ## 0.1.2 ### Changed diff --git a/valkey-resources/Chart.yaml b/valkey-resources/Chart.yaml index 50a60412..a0081cf1 100644 --- a/valkey-resources/Chart.yaml +++ b/valkey-resources/Chart.yaml @@ -2,7 +2,7 @@ apiVersion: v2 name: valkey-resources description: Helm chart for operator-managed Valkey resources (ValkeyCluster) type: application -version: 0.1.2 +version: 0.1.3 appVersion: "v0.4.0" kubeVersion: ">=1.20.0-0" home: https://valkey.io/valkey-helm/ diff --git a/valkey-resources/README.md b/valkey-resources/README.md index 436a12a9..5548fde1 100644 --- a/valkey-resources/README.md +++ b/valkey-resources/README.md @@ -1,6 +1,6 @@ # valkey-resources -![Version: 0.1.2](https://img.shields.io/badge/Version-0.1.2-informational?style=flat-square) ![Type: application](https://img.shields.io/badge/Type-application-informational?style=flat-square) ![AppVersion: v0.4.0](https://img.shields.io/badge/AppVersion-v0.4.0-informational?style=flat-square) +![Version: 0.1.3](https://img.shields.io/badge/Version-0.1.3-informational?style=flat-square) ![Type: application](https://img.shields.io/badge/Type-application-informational?style=flat-square) ![AppVersion: v0.4.0](https://img.shields.io/badge/AppVersion-v0.4.0-informational?style=flat-square) Deploys a single operator managed `ValkeyCluster`. Does not install the operator. @@ -21,6 +21,17 @@ helm install valkey-operator valkey/valkey-operator \ helm install my-cluster valkey/valkey-resources -n valkey ``` +### Examples + +Copy-paste values for common shapes live under [`examples/`](examples/) (operator v0.4.0+). Start with `minimal.yaml` and `scheduling-node-spread.yaml` for production node HA via `scheduling.node.spread`. See [`examples/README.md`](examples/README.md). + +```bash +helm install my-cluster ./valkey-resources -n valkey \ + -f valkey-resources/examples/scheduling-node-spread.yaml +``` + +Further examples and helm unittest render smoke for that directory are planned as a follow-up. + ## Configuration `cluster.spec` is a drop-in for `ValkeyCluster.spec` (any CRD field). Nested under `cluster` so future CR kinds can sit beside it without a generic top-level `spec`. diff --git a/valkey-resources/examples/README.md b/valkey-resources/examples/README.md new file mode 100644 index 00000000..38e4559e --- /dev/null +++ b/valkey-resources/examples/README.md @@ -0,0 +1,43 @@ +# valkey-resources examples + +Helm values overlays for common `ValkeyCluster` shapes (operator **v0.4.0+**). + +Each file is meant for `helm install` / `helm upgrade` with `-f`. Merge multiple files when needed. + +From a git checkout: + +```bash +helm install my-cluster ./valkey-resources -n valkey \ + -f valkey-resources/examples/minimal.yaml \ + -f valkey-resources/examples/scheduling-node-spread.yaml +``` + +From the published chart (copy examples from the repo or pin a path): + +```bash +helm install my-cluster valkey/valkey-resources -n valkey \ + -f scheduling-node-spread.yaml +``` + +## Files + +| File | What it shows | +|---|---| +| [minimal.yaml](minimal.yaml) | Explicit shards / replicas only | +| [scheduling-node-spread.yaml](scheduling-node-spread.yaml) | `scheduling.node.spread` (shard-aware node HA) + PDB | +| [scheduling-zone-spread.yaml](scheduling-zone-spread.yaml) | Zone `topologySpreadConstraints` escape hatch | +| [tls.yaml](tls.yaml) | TLS Secret ref via `extraValues` + `tpl` | +| [persistence.yaml](persistence.yaml) | PVC size on StatefulSet | +| [metrics-podmonitor.yaml](metrics-podmonitor.yaml) | PodMonitor for exporter sidecars | +| [users-acl.yaml](users-acl.yaml) | ACL users with password Secret refs | + +## Notes + +- Chart defaults leave `node.spread` off (operator default `Disabled`). Production clusters should set `shard` to at least `Preferred`; see `scheduling-node-spread.yaml`. +- Prefer `node.spread` for hostname / node anti-colocation. Use raw `topologySpreadConstraints` for other keys (for example zones). Do not stack a hostname TSC with `node.spread.primaries` / `pods` at the same strength. +- Secrets are references only; create them out of band. +- CRDs come from the `valkey-operator` chart. Helm does not upgrade CRDs automatically. + +## Follow-up + +More examples and helm unittest render smoke tests for this directory are planned; this set is the first cut. diff --git a/valkey-resources/examples/metrics-podmonitor.yaml b/valkey-resources/examples/metrics-podmonitor.yaml new file mode 100644 index 00000000..a413d791 --- /dev/null +++ b/valkey-resources/examples/metrics-podmonitor.yaml @@ -0,0 +1,14 @@ +# Scrapes ValkeyNode metrics-exporter sidecars (port name metrics, default 9121). +# Needs Prometheus Operator PodMonitor CRDs. Exporter is on by default on the CR +# (cluster.spec.exporter); disable there if you do not want the sidecar. +metrics: + podMonitor: + enabled: true + # Match your Prometheus Operator serviceMonitorSelector / podMonitorSelector + labels: + release: prometheus + +cluster: + spec: + shards: 3 + replicas: 1 diff --git a/valkey-resources/examples/minimal.yaml b/valkey-resources/examples/minimal.yaml new file mode 100644 index 00000000..1f024304 --- /dev/null +++ b/valkey-resources/examples/minimal.yaml @@ -0,0 +1,5 @@ +# Explicit topology size only. Matches chart defaults for shards / replicas. +cluster: + spec: + shards: 3 + replicas: 1 diff --git a/valkey-resources/examples/persistence.yaml b/valkey-resources/examples/persistence.yaml new file mode 100644 index 00000000..c5705b12 --- /dev/null +++ b/valkey-resources/examples/persistence.yaml @@ -0,0 +1,11 @@ +# Durable storage per ValkeyNode. Requires workloadType StatefulSet (default). +# persistence cannot be added or removed after create; size may only grow. +# storageClassName is immutable once set. +cluster: + spec: + shards: 3 + replicas: 1 + workloadType: StatefulSet + persistence: + size: 1Gi + # storageClassName: standard diff --git a/valkey-resources/examples/scheduling-node-spread.yaml b/valkey-resources/examples/scheduling-node-spread.yaml new file mode 100644 index 00000000..8578be60 --- /dev/null +++ b/valkey-resources/examples/scheduling-node-spread.yaml @@ -0,0 +1,25 @@ +# Shard-aware placement on kubernetes.io/hostname via scheduling.node.spread. +# Prefer this over hand-written hostname topologySpreadConstraints. +# +# Modes: Disabled | Preferred | Required +# - shard: same-shard pods (primary + replicas) not co-located (pod anti-affinity) +# - primaries: spreads each shard's node-index-0 pod (creation-time primary), not live role after failover +# - pods: spreads all cluster pods +# +# Do not set primaries and pods to the same non-Disabled mode (admission rejects). +# Production: set shard to at least Preferred so one node loss cannot wipe a whole shard. +cluster: + spec: + shards: 3 + replicas: 1 + podDisruptionBudget: + mode: Cluster + scheduling: + node: + spread: + shard: + mode: Required + primaries: + mode: Preferred + pods: + mode: Disabled diff --git a/valkey-resources/examples/scheduling-zone-spread.yaml b/valkey-resources/examples/scheduling-zone-spread.yaml new file mode 100644 index 00000000..e22d3754 --- /dev/null +++ b/valkey-resources/examples/scheduling-zone-spread.yaml @@ -0,0 +1,19 @@ +# Zone-level topology spread (escape hatch). Operator renders TSC verbatim; +# you must supply labelSelector. Prefer node.spread for hostname / node HA. +# +# fullnameOverride pins ValkeyCluster metadata.name so valkey.io/cluster matches +# the selector. Change both together if you rename the cluster. +fullnameOverride: my-cluster + +cluster: + spec: + shards: 3 + replicas: 1 + scheduling: + topologySpreadConstraints: + - maxSkew: 1 + topologyKey: topology.kubernetes.io/zone + whenUnsatisfiable: ScheduleAnyway + labelSelector: + matchLabels: + valkey.io/cluster: my-cluster diff --git a/valkey-resources/examples/tls.yaml b/valkey-resources/examples/tls.yaml new file mode 100644 index 00000000..f658dfcf --- /dev/null +++ b/valkey-resources/examples/tls.yaml @@ -0,0 +1,12 @@ +# TLS material is a Secret you create. Chart only references the name. +# Secret keys: ca.crt, tls.crt, tls.key +extraValues: + tlsSecret: valkey-tls + +cluster: + spec: + shards: 3 + replicas: 1 + tls: + certificate: + secretName: "{{ .Values.extraValues.tlsSecret }}" diff --git a/valkey-resources/examples/users-acl.yaml b/valkey-resources/examples/users-acl.yaml new file mode 100644 index 00000000..cbe96420 --- /dev/null +++ b/valkey-resources/examples/users-acl.yaml @@ -0,0 +1,24 @@ +# ACL users. Password material lives in a Secret you create; this only references it. +# Usernames must not start with _ (reserved for operator system users). +# +# Example Secret (create before install): +# kubectl create secret generic valkey-users \ +# --from-literal=alicepw='change-me' +extraValues: + usersSecret: valkey-users + +cluster: + spec: + shards: 3 + replicas: 1 + users: + - name: alice + passwordSecret: + name: "{{ .Values.extraValues.usersSecret }}" + keys: [alicepw] + commands: + allow: ["@read", "@write", "@connection"] + deny: ["@admin", "@dangerous"] + keys: + readWrite: ["app:*"] + readOnly: ["shared:*"]