Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
26 changes: 19 additions & 7 deletions agent/ARCHITECTURE_FACTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,9 +11,11 @@ Evidence below refers to `valkey-operator` commit
`20b3b6758fe6f5431e0e183e841d606b935c0853` (`origin/master`, 2026-08-11) plus
the code-free product-naming commits up to
`0135484d90d7bff19bd56fe5d08ed4657fc26df7`.
Both are ancestors of the shipped tag `v2.0.0`.
The server-image facts refer to the `valkey` container-source commit
`7cb5874adf2c867dc2fc423435e33edc82226caa`, which is the commit suffix used by
that Operator baseline's 7.2, 8.1, and 9.1 image tags.
`7cb5874adf2c867dc2fc423435e33edc82226caa`. The `v2.0.0` 7.2, 8.1, and 9.1 image
tags carry the suffix `cf797832`, which is that commit plus one Alpine
base-image bump and no server change; it still builds 7.2.14, 8.1.9, and 9.1.1.

## Product contract

Expand All @@ -27,7 +29,11 @@ that Operator baseline's 7.2, 8.1, and 9.1 image tags.
writes `Valkey®` at the first usage of the mark in every listing field. The
current wording is in `TERMINOLOGY.md`. The `valkey-operator` `master` branch
still carries the superseded notice until that change is cherry-picked.
- The next major product release is `2.0.0`: `version:1`.
- The current product release is `2.0.0`: `version:1`, shipped as
`valkey-operator` tag `v2.0.0`. It was released on 2026-09-08 and runs on
Alauda Container Platform v4.2, v4.3, and v4.4. Release date, lifecycle dates,
and platform versions are product-owner requirements with no source-code
evidence; see `SOURCE_POLICY.md`.
- The Operator image map selects Valkey server lines `7.2`, `8.1`, and `9.1`:
`values.yaml:17-34`. These are the only supported versions in product docs.
The pinned container source builds patch versions 7.2.14, 8.1.9, and 9.1.1.
Expand Down Expand Up @@ -82,10 +88,16 @@ that Operator baseline's 7.2, 8.1, and 9.1 image tags.
passage that tells a reader to inspect the replication credential must name the
directive per line: `CONFIG GET primaryauth` returns an empty result on 7.2,
which reads as "not set" while the credential is in fact held by `masterauth`.
- The Helm Chart CRD copy under `charts/valkey-operator/crds` is stale: it omits
9.0 and 9.1, while the API type and canonical generated CRD include them. A
2.0.0 release package must install the canonical schema so supported line 9.1
passes admission.
- The Helm Chart CRD copy under `charts/valkey-operator/crds` is stale at tag
`v2.0.0`: it omits 9.0 and 9.1, while the API type and canonical generated CRD
include them. That copy is not the delivered artifact. The chart is an upstream
directory untouched since commit `d430d34`, referenced by neither the
`Makefile` nor `.build/build.yaml`; `.artifact/metadata.yaml` declares
`packageType: OperatorBundle`, and `make bundle` generates the bundle from
`config/manifests`, which pulls `config/crd/bases`. Product docs therefore
require installed-schema verification during release acceptance without
attributing the risk to the in-repo chart copy. The stale copy should still be
regenerated or removed in `valkey-operator`.
- `replicasOfShard` is described in API comments as replica count, but builders use
it as a StatefulSet Pod count. Documentation uses the implemented member-count
behavior and preserves the literal field name in YAML.
Expand Down
20 changes: 14 additions & 6 deletions agent/CONTENT_AUDIT.md
Original file line number Diff line number Diff line change
Expand Up @@ -15,8 +15,12 @@ official command source as the surrounding section.
## Baselines and claim classes

- **P — product requirement:** the product name Alauda Cache Service E2,
CLI-only operation, 2.0.0 as the next major release, supported server lines
7.2/8.1/9.1, and no disaster recovery.
CLI-only operation, supported server lines 7.2/8.1/9.1, and no disaster
recovery. For the 2.0.0 release: release date 2026-09-08, a two-year lifecycle
ending full support on 2027-09-30 and maintenance on 2028-09-30, and support on
Alauda Container Platform v4.2, v4.3, and v4.4, and no predecessor product
version — the 2.x line only. These release facts are supplied by the product
owner and have no source-code evidence; `SOURCE_POLICY.md` records them.
- **O — Operator implementation:** `valkey-operator` `origin/master` commit
`20b3b6758fe6f5431e0e183e841d606b935c0853`, plus the code-free
product-naming commits up to `0135484d90d7bff19bd56fe5d08ed4657fc26df7`.
Expand All @@ -36,8 +40,8 @@ protocol semantics come from the official Valkey documentation.

| Conflict | Evidence | Documentation resolution |
| --- | --- | --- |
| Supported 9.1 versus stale packaged custom resource definition (CRD) | O: `api/rds/v1alpha1/valkey_types.go`, `config/crd/bases/rds.valkey.buf.red_valkeys.yaml`, and `charts/valkey-operator/crds/rds.valkey.buf.red_valkeys.yaml` | Declare the P support range, require installed-schema verification, and call a missing 9.1 enum a packaging defect. |
| Broader 8.0/9.0 source surface | O: high-level enum and image map; I: the pinned baseline builds only 7.2/8.1/9.1 and removed the 8.0/9.0 directories | The image map and P contract are narrower: only 7.2/8.1/9.1 are supported. |
| Supported 9.1 versus stale in-repo Helm Chart custom resource definition (CRD) copy | O: at tag `v2.0.0`, `api/rds/v1alpha1/valkey_types.go` and `config/crd/bases/rds.valkey.buf.red_valkeys.yaml` enumerate `7.2`/`8.0`/`8.1`/`9.0`/`9.1`, while `charts/valkey-operator/crds/rds.valkey.buf.red_valkeys.yaml` still enumerates `7.2`/`8.0`/`8.1`. The chart is an upstream artifact untouched since `d430d34`, is referenced by neither the `Makefile` nor `.build/build.yaml`, and is not the delivered package: `.artifact/metadata.yaml` declares `packageType: OperatorBundle`, and `make bundle` generates the bundle from `config/manifests`, which pulls `config/crd/bases`. | Declare the P support range and require installed-schema verification during release acceptance. Do not attribute the risk to the in-repo chart copy, which customers never install. |
| Broader 8.0/9.0 source surface | O: high-level enum and version map at tag `v2.0.0`, whose API comment records that no image is shipped for `8.0`/`9.0` and that without a `VALKEY_VERSION_MAP` entry they resolve to a bare `:8.0`/`:9.0` tag; I: the pinned baseline builds only 7.2/8.1/9.1 and removed the 8.0/9.0 directories | The version map and P contract are narrower: only 7.2/8.1/9.1 are supported; `8.0`/`9.0` are admissible but unshipped, untested, and usable only with a self-supplied image. |
| Affinity schema versus builders | O: `api/core/types.go`; `internal/builder/clusterbuilder/statefulset.go`; `internal/builder/failoverbuilder/statefulset.go`; the Cluster ensure-resource actor preserving old StatefulSet affinity on update | Document exact builder behavior, mark Cluster custom affinity unreliable, and document that Cluster affinity changes reach only StatefulSets created afterward. |
| Ignored `spec.storage.accessMode` | O: `api/core/types.go` default plus hard-coded `ReadWriteOnce` in the Cluster and Failover StatefulSet builders | Document the fixed `ReadWriteOnce` access mode and remove the access-mode choice from examples. |
| Dead `retainAfterDeleted` and PVC ownership | O: value-copy owner-reference loop in both StatefulSet builders; no production PVC-deletion path | Document that PVCs always remain after deletion and require explicit cleanup. |
Expand All @@ -56,17 +60,21 @@ protocol semantics come from the official Valkey documentation.
| Page and section | Claim basis |
| --- | --- |
| `index.mdx` — navigation | Site tree only; this landing page contains no product capability claims. |
| `intro.mdx` — release and server versions | P: release date and supported Alauda Container Platform versions; O: high-level enum and version map. |
| `intro.mdx` — reconciliation and capabilities | O: high-level controllers, topology actors, service/config/exporter/certificate builders, the credential-protection paths, and APIs; I: `CONFIG GET` redaction. |
| `intro.mdx` — architectures and member counts | O: webhook/defaulting logic and StatefulSet replica assignments; U: [Cluster specification](https://valkey.io/topics/cluster-spec/), [replication](https://valkey.io/topics/replication/), and [Sentinel](https://valkey.io/topics/sentinel/). |
| `intro.mdx` — responsibility boundary | P for unsupported backup, restore, disaster recovery, and Web Console; D from asynchronous replication and absence of protection controllers. |
| `architecture.mdx` — resource translation | O: `internal/controller/rds/valkey/cluster.go`, `failover.go`, and owner references in builders. |
| `architecture.mdx` — Cluster | O: Cluster engine/builders; U: [Cluster specification](https://valkey.io/topics/cluster-spec/). |
| `architecture.mdx` — Failover and Replica | O: high-level Failover generation, monitor selection, role-Service selectors; U: [replication](https://valkey.io/topics/replication/) and [Sentinel](https://valkey.io/topics/sentinel/). |
| `architecture.mdx` — storage and status | O: storage API/builders and phase constants/controller assignments; D for failure-domain and data-protection cautions. |
| `installation.mdx` — prerequisites and defaults | O: Helm values/templates, CRDs, role-based access control, webhook, cert-manager, labels, and metrics Service. Distribution-specific commands remain explicitly unknown. |
| `installation.mdx` — prerequisites and defaults | P: supported Alauda Container Platform versions. O: Helm values/templates, CRDs, role-based access control, webhook, cert-manager, labels, and metrics Service. Registry, namespace, channel, and approval strategy remain distribution-specific and explicitly unknown. |
| `upgrade.mdx` — scope and platform compatibility | P: no predecessor product version, supported Alauda Container Platform versions, and the v4.1 exclusion. The product source-to-target upgrade path for later 2.0.x releases remains delegated to release metadata. |
| `upgrade.mdx` — product upgrade | O: chart resources and API ownership; D from compatibility risk. Package commands and rollback contract are explicitly delegated to release metadata. |
| `lifecycle_policy.mdx` — version dimensions | P, O `version`/`values.yaml`, O status assignment, and I exact Dockerfile versions. Unpublished dates/matrix are marked unknown. |
| `lifecycle_policy.mdx` — timeline, compatibility, and support phases | P: release date 2026-09-08, end of full support 2027-09-30, end of maintenance 2028-09-30, and Alauda Container Platform v4.2/v4.3/v4.4. The phase, release, and maintenance wording follows the Alauda Cache Service E1 policy adapted to Valkey. |
| `lifecycle_policy.mdx` — version dimensions | P, O `version`/`values.yaml`, O status assignment, and I exact Dockerfile versions. |
| `limitations.mdx` — unsupported and conflicting features | P plus repository-absence checks and each conflict in the release-level table above. |
| `release_notes.mdx` — compatibility and support matrix | P: release date and supported Alauda Container Platform versions; O: supported server lines. |
| `release_notes.mdx` — 2.0.0 scope | P, O implemented feature paths including the credential-protection hardening, I exact patch baseline and `CONFIG GET` redaction, and the recorded source conflicts. |

## Feature guides
Expand Down
27 changes: 25 additions & 2 deletions agent/SOURCE_POLICY.md
Original file line number Diff line number Diff line change
Expand Up @@ -26,8 +26,31 @@ For the initial 2.0.0 documentation, the inspected operator baseline is
`origin/master` commit `20b3b6758fe6f5431e0e183e841d606b935c0853` from
2026-08-11, together with the product-naming commits up to
`0135484d90d7bff19bd56fe5d08ed4657fc26df7`, which rename the display title to
Alauda Cache Service E2 and change no code. The server-image baseline pinned by
the Operator image tags is `7cb5874adf2c867dc2fc423435e33edc82226caa`.
Alauda Cache Service E2 and change no code. Both are ancestors of the shipped
`valkey-operator` tag `v2.0.0`. The server-image baseline pinned by the `v2.0.0`
Operator image tags is `cf797832`, which is `7cb5874adf2c867dc2fc423435e33edc82226caa`
plus one Alpine base-image bump and no server change; it builds Valkey 7.2.14,
8.1.9, and 9.1.1. The release candidate pinned in the `artifacts` registry,
`33812cb4`, is an ancestor of `v2.0.0` and differs from it only in the
`redis-exporter` image tag, so the version, schema, and server-image claims in
these documents hold for either commit.

The following 2.0.0 release facts are product-owner requirements (evidence class
1). They have no source-code evidence and must not be inferred from the
repositories:

- release date 2026-09-08;
- a two-year lifecycle: end of full support 2027-09-30, end of maintenance
2028-09-30. Lifecycle dates are the release date plus one and two years,
rounded to the end of that month, following the Alauda Cache Service E1
convention;
- supported platform versions Alauda Container Platform v4.2, v4.3, and v4.4;
- 2.0.0 has no predecessor product version. The documentation covers the 2.x
line only: `valkey-operator` `release-1.0`, `release-1.1`, `v1.0.0`, and
`v1.1.0` are out of scope, no 1.x row belongs in the lifecycle timeline, and no
1.x-to-2.0.x upgrade path is documented. Because there is no predecessor,
2.0.0 carries no fixed-issue, known-issue, or security-fix release-note
sections.

Trademark wording does not come from the upstream project. `TERMINOLOGY.md`
carries the notice and the symbol rule that the ACP component compliance rules
Expand Down
5 changes: 5 additions & 0 deletions agent/TERMINOLOGY.md
Original file line number Diff line number Diff line change
Expand Up @@ -29,6 +29,11 @@ i18n:
| operator-owned resource | — | Child resource generated and reconciled from `Valkey`; users inspect it but change the owning high-level resource. |
| large key | `valkey-cli --bigkeys` | Key whose size or collection cardinality creates workload-specific operational risk. Do not imply one universal size threshold. |
| Web Console | — | Unsupported for this product; do not provide UI instructions. |
| Alauda Container Platform | — | The platform the product is installed on. Always write the full name; do not abbreviate it to ACP in published pages. |
| Full Support | — | First lifecycle phase of a minor version, from its release date to its end of full support. All bug fixes and security patches are delivered on that minor line. |
| Maintenance | — | Second lifecycle phase, from end of full support to end of maintenance. Only critical bug fixes and security patches are delivered; non-critical fixes are not backported. |
| end of full support | — | The date on which a minor version leaves Full Support. Lowercase in prose; title case only as a table column heading. |
| end of maintenance | — | The date after which a minor version is no longer supported. Lowercase in prose; title case only as a table column heading. |

## Trademark notice and symbol

Expand Down
17 changes: 8 additions & 9 deletions docs/en/installation.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -16,6 +16,8 @@ are not defined by the Valkey Operator repository.

## Prerequisites

- Alauda Container Platform v4.2, v4.3, or v4.4. Alauda Cache Service E2 version
2.0.0 is not supported on v4.1 or earlier;
- a supported Kubernetes cluster and a `kubectl` context allowed to install the
chart's cluster-scoped custom resource definitions (CRDs), admission webhooks,
and role-based access control resources;
Expand All @@ -25,10 +27,10 @@ are not defined by the Valkey Operator repository.
`Issuer` or `ClusterIssuer` is also required when instance TLS is enabled;
- a Prometheus-compatible scraper if exporter-sidecar metrics will be collected.

Obtain the release-specific platform compatibility matrix before production
installation. The documentation baseline does not define the supported Alauda
Container Platform versions, registry address, package namespace, channel, or
upgrade approval strategy.
The supported platform versions are listed in the
[compatibility and support matrix](./release_notes.mdx#compatibility-and-support-matrix).
The registry address, package namespace, channel, and upgrade approval strategy
are distribution-specific and come from the delivered release package.

## Preflight checks

Expand Down Expand Up @@ -81,11 +83,8 @@ kubectl get crd \
users.valkey.buf.red
```

The inspected 2.0.0 source contains two generated CRD copies that disagree on
the version enum: the API source and `config/crd/bases` include `9.1`, while the
Helm Chart CRD copy is stale. A release package that supports 9.1 must install a
CRD whose enum includes `7.2`, `8.1`, and `9.1`. Verify the installed schema
before creating an instance:
A 2.0.0 package must install a `Valkey` CRD whose version enum includes `7.2`,
`8.1`, and `9.1`. Verify the installed schema before creating an instance:

```bash
kubectl explain valkey.spec.version
Expand Down
14 changes: 10 additions & 4 deletions docs/en/intro.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -27,7 +27,9 @@ Console. Use `kubectl`, `valkey-cli`, and Kubernetes-native automation.

## Release and server versions

The next major product release is `2.0.0`. It supports these Valkey server lines:
The current product release is `2.0.0`, released on 2026-09-08. It runs on
Alauda Container Platform v4.2, v4.3, and v4.4, and supports these Valkey server
lines:

| Supported line | Use in `spec.version` |
| --- | --- |
Expand All @@ -36,9 +38,13 @@ The next major product release is `2.0.0`. It supports these Valkey server lines
| Valkey 9.1 | `"9.1"` |

Do not use `8.0` or `9.0`, even if a compatibility enum in an installed custom
resource definition (CRD) accepts those values. The 2.0.0 Operator image map
selects only the 7.2, 8.1, and 9.1 server lines. A schema enum value for
another line does not establish product support.
resource definition (CRD) accepts those values. The 2.0.0 Operator version map
selects only the 7.2, 8.1, and 9.1 server lines, and no image is shipped for the
other two. A schema enum value for another line does not establish product
support.

For support phases and end-of-support dates, see
[Lifecycle Policy](./lifecycle_policy.mdx).

## Architectures

Expand Down
Loading