Create versioned Zensical docs site and slim repo docs

[immanuel-peter]

Create a versioned Zensical docs site and slim repo docs

Summary

Create a dedicated Zensical documentation site for the Redis operator so user-facing documentation lives in one navigable, version-aware manual instead of being spread across the README, repo runbooks, internal package READMEs, and issue history.

The model should be closer to the CloudNativePG docs site: a complete operator manual with concepts, guides, operations, troubleshooting, API reference, release notes, and versioned docs for users pinned to older operator releases.

Why This Matters

The operator has grown beyond a README-and-runbooks documentation model. Recent closed issues added or clarified production-facing behavior across storage, backup, TLS, connection secrets, scheduled backups, memory configuration, cluster mode, Sentinel mode, monitoring, failover, and upgrades.

Users need docs organized by task and operator behavior, not by where the implementation happened in the repository. Maintainers also need the repo docs to be slimmer so the source tree is not carrying a second full documentation site.

Recommended Docs IA

Introduction

• Overview
• Use cases
• Architecture
• CloudNativePG-inspired design
• Supported modes and capability matrix

Getting Started

• Before you start
• Installation with Helm
• Installation with Kustomize
• Quickstart
• Connecting to Redis

Core Concepts

• RedisCluster lifecycle
• Instance manager
• Services and labels
• Status, conditions, and events
• Admission defaults and validation
• Security model

Deployment Modes

• Standalone mode
• Sentinel mode
• Redis Cluster mode
• Standalone to Sentinel migration
• Replica mode / cross-cluster disaster recovery

Configuration

• Storage: PVC and emptyDir
• Memory and eviction
• Auth, ACLs, and generated secrets
• TLS
• Connection Secret
• Scheduling and placement
• Hibernation and maintenance windows

Backup And Recovery

• Backup concepts
• On-demand backups
• Scheduled backups
• S3-compatible destinations
• Azure Blob destinations
• Restore/bootstrap from backup
• Retention semantics
• Cluster-mode shard artifacts

Operations

• Rolling updates
• Operator upgrades
• Failover and fencing
• Split-brain prevention
• Node maintenance
• PVC resize
• Monitoring and alerting
• Performance and sizing
• Troubleshooting
• Runbooks migrated into task-oriented operations pages

Reference

• RedisCluster API
• RedisBackup API
• RedisScheduledBackup API
• Helm values
• Metrics
• Labels and annotations
• Release notes

Issue History Mapping

Use closed issues and the deleted local .issues tracker as the source map for what the docs must cover.

Closed GitHub issues that map directly to user-facing docs

• Support ephemeral RedisCluster storage #8: Ephemeral RedisCluster storage -> storage guide, emptyDir data-loss semantics, backup/restore limitations.
• Support Azure Blob Storage backup destinations #9: Azure Blob Storage backup destinations -> backup destination guide and credential matrix.
• Document stable service names and pod label contracts #10: Stable service names and pod label contracts -> services and labels reference.
• Define a standalone-to-sentinel migration path #11: Standalone-to-Sentinel migration path -> mode migration guide and operations page.
• Optionally publish Redis connection details in a Secret #12: Optional Redis connection details Secret -> connection secret guide.
• Honor RedisScheduledBackup cron schedules #13: RedisScheduledBackup cron schedules -> scheduled backup guide, cron/timezone validation.
• Clarify and implement backup artifact retention cleanup #14: Backup artifact retention cleanup -> retention semantics; history limits prune Kubernetes RedisBackup objects only, not remote artifacts.
• Add first-class maxmemory and eviction policy configuration #15: First-class maxmemory and eviction policy -> memory guide.
• Support TLS for sentinel mode #16: TLS for Sentinel mode -> TLS guide and mode-specific caveats.

Deleted local .issues tracker items that should inform the docs

The old .issues tracker was removed in commit 6951a75, but its contents are useful as a production-readiness outline. Important docs seeds include:

• Local feat(issue-1): add Dockerfile, CI pipeline, and fix all lint issues #1-Auto-generated auth secret is not persisted in desired state, allowing Redis to run without auth #4: Dockerfile, CI, smoke tests, integration tests, chaos testing -> contributor/testing page.
• Local fix(auth): persist generated auth secret and enforce fallback projection #5: Sentinel and cluster mode support -> deployment modes section.
• Local Support Redis Cluster mode (hash-slot sharding) #6: Security audit and RBAC tightening -> security model and RBAC reference.
• Local feat(cluster): implement Redis cluster mode orchestration #7: Operator upgrade story and CRD versioning -> upgrade guide and versioning policy.
• Local Support ephemeral RedisCluster storage #8: Operational runbooks -> migrate into the Operations section.
• Local Support Azure Blob Storage backup destinations #9: Reconciler performance benchmarks -> performance and sizing page.
• Local Document stable service names and pod label contracts #10: PKI rotation E2E test -> webhook PKI / admission docs.
• Local Define a standalone-to-sentinel migration path #11-Optionally publish Redis connection details in a Secret #12: go.sum verification and dependency automation -> contributor/maintenance notes.
• Local Honor RedisScheduledBackup cron schedules #13: OLM bundle for OperatorHub -> future distribution docs.
• Local Clarify and implement backup artifact retention cleanup #14: Automated restore from backup on bootstrap -> restore/bootstrap guide.
• Local Add first-class maxmemory and eviction policy configuration #15: Client and replication TLS support -> TLS guide.
• Local Support TLS for sentinel mode #16: Runtime primary isolation detection -> split-brain prevention and failover docs.
• Local Make monitoring chart rendering explicit and consistent #17 and Document stable Redis service contract #25: Prometheus metrics, Grafana dashboard, alerting rules -> monitoring docs.
• Local Expose operational actions through a typed API #18: Supervised primary update strategy -> rolling updates and upgrade docs.
• Local Add ephemeral storage support for Redis clusters #19: Structured chaos testing framework -> reliability/testing docs.
• Local Add Azure Blob backup and restore support #20: Node maintenance window support -> maintenance operations guide.
• Local Validate RedisScheduledBackup cron schedules #21: Online PVC resize support -> storage operations guide.
• Local docs(backup): clarify scheduled-backup history limits prune K8s resources, not remote artifacts #22: Backup/restore E2E test suite -> backup validation and examples.
• Local Add first-class Redis memory configuration #23: Operator upgrade E2E test -> upgrade validation flow.
• Local Support standalone to sentinel migration #24: Cross-cluster replication for DR -> replica mode / DR guide.

Slim READMEs, Remove Runbook Sprawl, Update AGENTS.md

README direction

Keep README.md as a minimal repo landing page:

• What the operator is.
• Current latest version.
• Quick install links.
• Link to hosted docs.
• Local development and contribution links.
• Support/status badges.

Move detailed feature documentation out of the README and into the docs site.

Runbook direction

The repo probably does not need a full docs/runbooks/ tree once the Zensical site exists.

Migrate runbook content into the docs site's Operations section:

• Manual failover
• Split-brain recovery
• PVC corruption / replica rebuild
• Secret rotation
• Operator upgrade
• Total cluster loss
• Stuck reconciler
• Standalone to Sentinel migration

After migration, either delete the repo runbooks or replace docs/runbooks/index.md with a short pointer to the hosted docs.

Internal READMEs

Keep maintainer-facing READMEs where they explain code structure, contracts, or package-specific internals. They should not duplicate public docs.

Likely to keep, but slim if needed:

• internal/controller/cluster/README.md
• internal/instance-manager/README.md
• internal/controller/backup/README.md after extracting public backup content
• cmd/manager/README.md
• config/rbac/README.md
• config/crd/README.md
• webhooks/README.md
• CONTRIBUTING.md

AGENTS.md cleanup

Update AGENTS.md before or during this work.

Current guidance says spec.mode: cluster is reserved and intentionally not implemented. That is stale: live code and README currently indicate Redis Cluster mode is implemented and supported.

The docs site should not inherit stale contributor guidance. Update the AGENTS mode section to match the current code and document any real cluster-mode limitations in the public docs.

Zensical And Versioned Docs

Use Zensical for the new docs site.

Important finding: Zensical's actual site is https://zensical.org, and the repository is zensical/zensical.

Zensical appears to be MkDocs-compatible and is aiming to support versioned docs. Its public roadmap lists versioning work under "Next up", including:

• Git tag based versioning
• Branch-based workflows
• Folder-based version trees
• Differential rebuilds

Its plugin support page also lists mike as a Tier 1 MkDocs plugin target, which is relevant because mike is the common MkDocs versioning plugin.

Do not assume native Zensical versioning is fully production-ready without verifying at implementation time. Design the docs source and release workflow to be version-ready either way.

Recommended URL model:

• /docs/latest/
• /docs/v0.2.1/
• /docs/v0.2.2/

Recommended implementation options:

1. Use native Zensical versioning if it is available and stable.
2. Use mike or a MkDocs-compatible versioning flow if Zensical supports it well enough.
3. Publish separate static docs builds per git tag if native versioning is not ready.

Version docs at least per minor release. Preserve patch-version URLs when a patch changes CRDs, Helm values, validation behavior, backup/restore behavior, or operational procedures.

Implementation Scope

• Scaffold a Zensical docs site in this repository or a dedicated docs repository, depending on the chosen hosting workflow.
• Define the IA above in navigation.
• Migrate current public docs into the new IA.
• Convert runbooks into Operations pages.
• Slim README and repo docs after migration.
• Add generated or semi-generated API reference from CRDs.
• Add generated or semi-generated Helm values reference.
• Add a release/versioning workflow for docs.
• Update AGENTS.md to remove stale cluster-mode guidance.
• Add links from README and chart notes to the hosted docs.

Acceptance Criteria

• A Zensical docs site can be built locally.
• The docs site has a stable navigation structure matching the IA above.
• README is reduced to a concise repo landing page and links to the docs site.
• Existing runbook content is represented in the Operations section or intentionally dropped with rationale.
• User-facing backup, storage, memory, TLS, connection secret, monitoring, mode, upgrade, and service-contract docs are migrated into the site.
• Docs include an explicit versioning plan and route structure.
• API reference covers RedisCluster, RedisBackup, and RedisScheduledBackup.
• Helm values reference exists or has a documented generation path.
• AGENTS.md no longer says cluster mode is unimplemented unless the implementation is actually removed.

Notes

CloudNativePG is the right reference point for depth and organization, not necessarily exact page names. The Redis operator docs should explain Redis-specific behavior directly while keeping the operator-manual structure: concepts, guides, operations, troubleshooting, API reference, and release notes.