Skip to content

docs(redis): correct the cross-datacenter replication API surface (cherry-pick of #59) #60

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
chideat merged 1 commit into from
Sep 9, 2026
Merged

docs(redis): correct the cross-datacenter replication API surface (cherry-pick of #59) #60

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
32 changes: 32 additions & 0 deletions TERMINOLOGY_CANDIDATES.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -97,6 +97,38 @@ and in `doc/backup-restore-rwo.md` are deliberately kept out of customer docs.
| **bundle version** (API `spec.upgradeOption.crVersion`) | `redis-operator` `api/middleware/v1/redis_types.go:32-36` (`CRVersion`, `AutoUpgrade`) and `:339` (`printcolumn` name `Bundle Version`); annotation `middleware.instance/crVersion` in `internal/config/keys.go:44`; tier selection in `pkg/actor/manager.go:107-140` (`Search` takes the highest actor whose `Version()` is not greater than the annotation, defaulting to the operator's own version) | Not new — `docs/en/functions/10-create-instance.mdx:261` already documents the `BUNDLE VERSION` column as "the version number of the operator managing the instance". This is the first place the docs pair that display name with the `crVersion` / `autoUpgrade` API fields, and the first place a docs statement depends on a specific value. `crVersion` is the operator's own version (`internal/vc/generator.go:60,163`, from `REDIS_OPERATOR_VERSION`), so the column is product-version-shaped. **The published threshold `5.1.0` is deliberately conservative**: the code boundary is `4.1.2`, because the frozen `v5.0` tier (`Version()` `4.1.2`, serving `[4.1.2, 5.1.0)`, introduced by `7a7ebc3c` as a verbatim copy of a canonical builder that already carried the network-delivered restore) also skips the mount-based path — so instances pinned at `4.1.2`–`5.0.x` do not in fact need `ReadWriteMany`. Wording chosen by the maintainer 2026-09-07; revisit if the frozen tier changes. |
| **transient in-cluster source** | `internal/ops/restoresource/source.go`; `internal/builder/restorebuilder/source.go`; wired by the base and `v5.0` ensure-resource actors (`internal/ops/{cluster,failover}/actor[/v5.0]/actor_ensure_resource.go`) | **Coined for these docs.** The implementation is a versitygw S3 gateway; the docs deliberately name neither the project nor S3, to avoid confusing it with the **S3 Backup** method on the same page. Confirm the phrase. |

## Cross-datacenter replication API correction (added 2026-09-07)

Terms and phrasings introduced while validating
`docs/en/functions/95-disaster-recovery/` against a live business cluster
(operator `v5.1.0-rc.43.g2e4ef16f`, an ancestor of `release-5.1` whose only
intervening commits are e2e tests) and against `release-5.1` source. Repository
paths are relative to the sibling checkout `redis-group/redis-operator`.

| Term as used in docs | Provenance | Note for the reviewer |
|:---|:---|:---|
| **module peer port** (`7379`) | `internal/config/keys.go:54-57` — `ActiveRedisPeerPort = 7379`, "the module-owned peer listener port"; the Service port is appended only for mesh in `internal/builder/activeredis/service.go:66-80` | Replaces the docs' former "dedicated peer port", which implied a separate transport that Disaster Recovery links use. They do not: the port is a Service-level **alias onto the same proxy listener**, added only in Active-Active mode. Confirm the phrase, and confirm that "alias" is the right word for customer docs. |
| **default-account `RedisUser`** | `internal/builder/activeredis/peerauth.go:26-48` (`DefaultAccountRedisUserRef`); names generated by `internal/builder/clusterbuilder/acl.go:74-76` (`drc-acl-<name>-default`) and `internal/builder/failoverbuilder/acl.go:74-76` (`rfr-acl-<name>-default`) | **Coined for these docs.** Names the `RedisUser` object holding an instance's `default` account. As of `207d1c3c` (*accept the default account as a peer-auth credential*) this is the binding both setup guides now document for Redis `7.2`, and the one the operator writes for Redis `6.0`. The code has no customer-facing name for it. Confirm the phrase, and confirm that spelling the generated resource names out in the docs is wanted. |
| **peer-auth binding** | `api/middleware/redis/v1alpha1/activeredis_types.go:63-84` (`RedisUserRef`); `internal/controller/middleware/redis_peerauth_provision.go` | The docs already used *peer-auth credential* for the value. *Binding* is now used for the `spec.activeRedis.redisUserRef` reference itself, so that "the credential" and "the field naming it" stop being the same word. Confirm both are wanted. |
| **one endpoint carries both transports** | `internal/builder/activeredis/service.go:49-56` — "ONE proxy endpoint carries both transports. The proxy has a single listener and picks the backend port per session" | **Coined for these docs.** Describes why a Disaster Recovery link needs only the proxy RESP address. Confirm the phrasing; the alternative is to describe the per-session routing explicitly, which is more accurate but longer. |

Resolved by this change, and recorded here because the wrong names were
published: `spec.activeRedis.redisUserName` does not exist (the field is
`redisUserRef`, `api/middleware/redis/v1alpha1/activeredis_types.go:84`), and
`ActiveRedisConnection.spec.secretName` has been removed
(`internal/controller/middleware/activeredisconnection_controller.go:205-217`).
Both were verified against the live API by server-side dry-run. `aapeerrepl` is
gone from the product as well — `77851bdc` removed the mint along with
`secretName`, its only password source — so the docs no longer name it; it
survives only as a test constant in `tests/framework/activeredis/deployer.go:53`.

Checked and left unchanged: `status.upstreamPeer.service_metadata` is real —
`internal/controller/middleware/redis/activeredis_args.go:47-50` injects
`instance=<namespace>/<name>` on both generations, plus `version=` on the new
module. The live connection shows it empty only because
`activeredisconnection_controller.go:433-439` records `upstreamPeer` once, from
the first shard to report peer info, and that shard reported none.

## Known inconsistencies to resolve

1. **"Source side" / "Target side" (Web Console) vs. "upstream" / "downstream"
Expand Down
16 changes: 10 additions & 6 deletions docs/en/functions/95-disaster-recovery/10-intro.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -72,8 +72,8 @@ The replication module ships in two generations. Which one an instance loads is
| Active-Active (`mesh`) | Not supported | Supported |
| Replicated command set | Smaller — commands introduced after Redis 6.0 are not replicated | Full; see [Command Support](./60-commands.mdx) |
| Command guards | None — `MOVE`, `SWAPDB`, `RESTORE`, `FLUSHALL`, and `FLUSHDB` are replicated rather than refused | `MOVE`, `SWAPDB`, and `RESTORE` are always refused; `FLUSHALL` and `FLUSHDB` are refused while peers are attached |
| Peer authentication | None at the module level; the link credential comes from the `ActiveRedisConnection` `spec.secretName` | Mandatory. The instance binds a `RedisUser` through `spec.activeRedis.redisUserName`; `spec.secretName` is ignored |
| Peer transport | Proxy Redis Serialization Protocol (RESP) port (`6379`) | Dedicated peer port (`7379`) fronted by the proxy |
| Peer authentication | None at the module level. The link authenticates as the instance's default account, which the operator binds for you through `spec.activeRedis.redisUserRef` | Mandatory. The instance binds a `RedisUser` through `spec.activeRedis.redisUserRef` — normally its own default account, which must then carry the same password in every datacenter |
| Peer transport | Proxy Redis Serialization Protocol (RESP) port (`6379`) | The same proxy RESP port (`6379`) — one endpoint carries both transports. Active-Active additionally exposes the module peer port (`7379`) |
| Persistence | RDB recommended | RDB only — `appendonly=yes` is rejected by admission |
| Database count | Standard | `databases` must be `<= 16` |

Expand All @@ -97,11 +97,15 @@ A proxy is deployed for both module generations. Enabling cross-datacenter repli

| Port | Name | Purpose | Applies to |
|:-----|:-----|:--------|:-----------|
| `6379` | `proxy` | RESP endpoint. Pre-flight inspection, and — on Redis `6.0` — the replication transport. Also the address used in mesh seed entries. | All versions |
| `7379` | `peer` | The peer port. On the new module this is the **only** peer transport: it carries both Disaster Recovery replication and Active-Active gossip. | Redis `7.2` |
| `6379` | `proxy` | RESP endpoint, and the replication transport for both module generations. The proxy tells a peer session apart from a client session and routes it accordingly, so one endpoint carries both. This is the address recorded in mesh seed entries and in an `ActiveRedisConnection`'s `spec.addresses`. | All versions |
| `7379` | `peer` | The module peer port, aliased onto the same proxy listener. It is added to the proxy Service **only in Active-Active mode**, because a mesh member gossips its own local peer port and something must answer on it. | Redis `7.2`, Active-Active only |

<Directive type="warning" title="Expose the peer port unchanged">
When an external load balancer or firewall fronts the proxy of a Redis `7.2` instance, it must expose port `7379` as `7379`. The module always advertises its own local peer port for the data plane, so remapping it breaks replication. Only the RESP port may be remapped, through `announcePort` in Active-Active mode or `spec.peerPort` on an `ActiveRedisConnection`.
<Directive type="info" title="A Disaster Recovery link uses one endpoint">
The proxy Service of a `peerof` instance carries no `7379` port, and none needs to be opened between datacenters. A Disaster Recovery link addresses the proxy RESP endpoint alone — the address recorded in the downstream's `ActiveRedisConnection`.
</Directive>

<Directive type="warning" title="In Active-Active, expose the peer port unchanged">
When an external load balancer or firewall fronts the proxy of an Active-Active member, it must expose port `7379` as `7379`. The module always advertises its own local peer port for that traffic, so remapping it breaks the mesh. Only the RESP port may be remapped, through `announcePort`.
</Directive>

### Instance ID: Service ID
Expand Down
Loading