Template docs: credentials from prerequisite secrets (32 pages)

template-catalog/templates/redis-cluster.mdx

@@ -21,14 +21,30 @@ This template deploys into an existing [GVC](/reference/gvc) that you already ha
 | Workload | `RELEASE_NAME-redis-cluster-backup` | Cron job that uploads one RDB snapshot per primary shard to S3 or GCS | `backup.enabled: true` |
 | Secret | `RELEASE_NAME-redis-cluster-config` | `redis.conf` (cluster mode, AOF persistence, port and, when set, the password), file-mounted into each node | — |
 | Secret | `RELEASE_NAME-redis-cluster-startup` | Start script that boots each node and bootstraps the cluster from replica 0 | — |
-| Secret | `RELEASE_NAME-redis-cluster-auth` | Dictionary secret holding `REDIS_PASSWORD` | `redis.password` set |
+| Secret | `RELEASE_NAME-redis-cluster-auth` | Dictionary secret holding `REDIS_PASSWORD` | only with an inline `redis.password`; a password from your own secret is read from that secret instead |
 | Identity | `RELEASE_NAME-redis-cluster-identity` | Workload identity; carries the cloud account binding when backup is enabled | — |
-| Policy | `RELEASE_NAME-redis-cluster-policy` | `reveal` on the config and start-script secrets, and on the auth secret when it exists | — |
+| Policy | `RELEASE_NAME-redis-cluster-policy` | `reveal` on the config and start-script secrets, and on the auth secret or your password secret when authentication is on | — |
 | Volume set | `RELEASE_NAME-redis-cluster-vs` | Per-node data directory (`/data`), `ext4` on `general-purpose-ssd` | — |
 
 ## Prerequisites
 
-None for a default install.
+None for a default install, which runs without a password.
+
+To protect the cluster with a password (recommended), create a [dictionary secret](/guides/create-secret/dictionary) holding it **before** you install, then point `redis.auth.fromSecret` at it (see [Authentication](#authentication)):
+
+```bash
+cpln secret create-dictionary --name my-redis-cluster-auth --entry password="$(openssl rand -hex 24)"
+```
+
+The key defaults to `password` (`redis.auth.fromSecret.passwordKey`). Use a password without spaces or quotes.
+
+<Warning>
+If the secret is missing, the nodes never start and `cpln logs` shows nothing. The reason is in `status.versions[].message`:
+
+```bash
+cpln workload get-deployments RELEASE_NAME-redis-cluster --gvc GVC_NAME -o yaml
+```
+</Warning>
 
 Scheduled backups need an S3 or GCS bucket, a Control Plane [cloud account](/guides/create-cloud-account) and, on AWS, a bucket-scoped IAM policy before they can be enabled — see [Backing Up](#backing-up).
 
@@ -38,9 +54,11 @@ A default install needs no values:
 
 ```bash
 cpln helm install RELEASE_NAME oci://ghcr.io/controlplane-com/templates/redis-cluster \
-  --version 1.6.0 --gvc GVC_NAME
+  --version 1.7.0 --gvc GVC_NAME
 ```
 
+To turn on authentication from the secret in [Prerequisites](#prerequisites), add `--set redis.auth.fromSecret.enabled=true --set redis.auth.fromSecret.name=my-redis-cluster-auth`.
+
 <CardGroup cols={2}>
     <Card title="UI" href="/template-catalog/install-manage/ui" icon="laptop">
     Browse, install, and manage templates visually
@@ -147,13 +165,22 @@ Each node keeps its data directory (`/data`) on its own volume in the [volume se
 
 ### Authentication
 
+Off by default. Turn it on with ONE of the two options; the secret is the recommended one:
+
 ```yaml
-# Configure Redis authentication by uncommenting and setting the password field
-redis: {}
-  # password: "your-secure-password-here"
+redis:
+  auth:
+    fromSecret:
+      enabled: false
+      name: ""                    # e.g. my-redis-cluster-auth; create it before install (see Prerequisites)
+      passwordKey: password       # the secret key that holds the password
+  # Less secure: an inline password, stored in plain text in the Helm release.
+  # password: "change-me-redis-cluster-password"
 ```
 
-Authentication is off by default. Setting `redis.password` creates the `RELEASE_NAME-redis-cluster-auth` secret and injects the value into both `requirepass` and `masterauth` in `redis.conf`, so clients and the nodes themselves authenticate with it. The password is a Helm value and is stored in the release. Add `--no-auth-warning -a PASSWORD` to every `redis-cli` call on this page when it is set.
+Both options set `requirepass` and `masterauth`, so clients and the nodes themselves authenticate with the password. With the secret, the password reaches the nodes only through an environment variable resolved at start; it is never written into a rendered file or the release. An inline `redis.password` creates the `RELEASE_NAME-redis-cluster-auth` secret and is stored in the release. Setting both options at once is refused at install. Add `--no-auth-warning -a PASSWORD` to every `redis-cli` call on this page when authentication is on.
+
+**Changing the password:** update the secret, then run `cpln workload force-redeployment RELEASE_NAME-redis-cluster --gvc GVC_NAME`. Nodes restart one at a time, and a node on the new password cannot replicate from a node still on the old one until the rollout completes, so plan a maintenance window. The backup job reads the secret on its next run.
 
 ### Backup
 
@@ -192,7 +219,7 @@ The template exposes no public endpoint. Reach the cluster from workloads in the
 |---|---|---|
 | Cluster seed address, inside the GVC | `RELEASE_NAME-redis-cluster.GVC_NAME.cpln.local:6379` | Resolves to any node; a cluster-aware client discovers the rest from it |
 | Redirect hostnames | `RELEASE_NAME-redis-cluster-N.RELEASE_NAME-redis-cluster:6379` | What `MOVED` and `ASK` redirects name node *N* as; resolvable only from inside the GVC, which is why clients must run there |
-| Password | `cpln secret reveal RELEASE_NAME-redis-cluster-auth -o yaml` | Only when `redis.password` is set |
+| Password | `cpln secret reveal my-redis-cluster-auth -o yaml` (your secret), or `cpln secret reveal RELEASE_NAME-redis-cluster-auth -o yaml` with an inline `redis.password` | Only when authentication is on |
 
 Use a cluster-aware client (or `redis-cli -c`): a plain client pointed at one node receives `MOVED` redirects it does not follow, which is the most common cause of "it does not work" with this template.
 
@@ -292,6 +319,7 @@ What the backup is: three standard, gzipped RDB files, one per shard, and RDB fi
 - **From 1.5.0 or earlier — the readiness probe requires a real `PONG`.** Earlier versions ran a bare `redis-cli ping`, which exits 0 even when the server answers `NOAUTH Authentication required`, so a password-protected cluster could report ready without being usable. From 1.6.0 a node that cannot authenticate is not ready, and because the nodes roll in order, a bad credential stalls the rollout at the first replica instead of rolling all six into a broken state.
 - **From 1.5.0 or earlier — cluster creation retries transient DNS failures.** During first boot the cluster create step re-resolves every peer hostname, and a name that briefly stops resolving used to restart the container. From 1.6.0 creation retries in place and still fails loudly (`FATAL: cluster create did not succeed after 12 attempts`) if it genuinely cannot succeed.
 - **1.6.0 adds `engine`.** The default `redis` deploys exactly as before; see [Engine](#engine) before setting `valkey`.
+- **1.7.0 adds `redis.auth.fromSecret`**, which reads the password from your own secret. An inline `redis.password` keeps working unchanged; see [Authentication](#authentication).
 
 Upgrades roll the nodes in order; each node's data and cluster state are on its volume, so the cluster re-forms from `nodes.conf` as the nodes come back.
 
@@ -335,9 +363,9 @@ Upgrades roll the nodes in order; each node's data and cluster state are on its
   <Accordion title="NOAUTH Authentication required">
     **Symptom:** a client or `redis-cli` call answers `(error) NOAUTH Authentication required.`
 
-    **Cause:** `redis.password` is set and the client did not authenticate.
+    **Cause:** authentication is on (`redis.auth.fromSecret` or `redis.password`) and the client did not authenticate.
 
-    **Fix:** pass the password — `redis-cli --no-auth-warning -a PASSWORD`, or your client library's password option. Read it back with `cpln secret reveal RELEASE_NAME-redis-cluster-auth -o yaml`.
+    **Fix:** pass the password — `redis-cli --no-auth-warning -a PASSWORD`, or your client library's password option. Read it back from your secret with `cpln secret reveal my-redis-cluster-auth -o yaml`, or with `cpln secret reveal RELEASE_NAME-redis-cluster-auth -o yaml` for an inline password.
   </Accordion>
   <Accordion title="A node never becomes ready after changing engine, and cpln logs shows nothing">
     **Symptom:** after a `cpln helm upgrade` that changed `engine`, the first replaced node never reports ready, `cpln logs` returns no lines for it and the deployment message is empty.
@@ -365,7 +393,8 @@ Upgrades roll the nodes in order; each node's data and cluster state are on its
 ## Important Notes
 
 - **Your client must speak the Redis Cluster protocol and run inside the same GVC.** A plain client gets `MOVED` redirects it will not follow, and the redirect hostnames resolve only inside the GVC.
-- **Authentication is off by default.** Anything `internalAccess` admits has full access until you set `redis.password`.
+- **Authentication is off by default.** Anything `internalAccess` admits has full access until you turn it on with `redis.auth.fromSecret` (recommended) or an inline `redis.password`.
+- **A changed password secret takes effect only after a forced redeployment** of `RELEASE_NAME-redis-cluster`; nodes on the new and the old password cannot replicate until the rollout completes.
 - **Keep `replicas` at 6.** Fewer cannot form a cluster; more is rejected by a platform quota.
 - **Never set `internalAccess.type: none`.** The nodes stop reaching each other and the cluster breaks.
 - **Choose `engine` at install time.** Switching it on a release that holds data is unsupported, and the failure leaves no log output.

template-catalog/templates/redis.mdx

@@ -22,8 +22,8 @@ This template deploys into an existing [GVC](/reference/gvc) that you already ha
 | Workload | `RELEASE_NAME-redis-backup` | Cron job that uploads an RDB snapshot to S3 or GCS; runs as the Redis identity | `backup.enabled: true` |
 | Secret | `RELEASE_NAME-redis-config` | `redis.conf`, file-mounted into each Redis container | — |
 | Secret | `RELEASE_NAME-sentinel-config` | `sentinel.conf`, file-mounted into each Sentinel container | `mode: production` (default) |
-| Secret | `RELEASE_NAME-redis-auth-password` | Redis password | `redis.auth.password.enabled: true` |
-| Secret | `RELEASE_NAME-sentinel-auth-password` | Sentinel password | `sentinel.auth.password.enabled: true` (production mode) |
+| Secret | `RELEASE_NAME-redis-auth-password` | Redis password, created only for a password set in values | `redis.auth.password.enabled: true` |
+| Secret | `RELEASE_NAME-sentinel-auth-password` | Sentinel password, created only for a password set in values | `sentinel.auth.password.enabled: true` (production mode) |
 | Secret | `RELEASE_NAME-redis-backup-config` | Bucket and region for the backup job | `backup.enabled: true` |
 | Identity | `RELEASE_NAME-redis-identity` | Identity of the Redis workload and the backup job; carries the cloud account binding when backup is enabled | — |
 | Identity | `RELEASE_NAME-sentinel-identity` | Sentinel workload identity | `mode: production` (default) |
@@ -40,15 +40,14 @@ This template deploys into an existing [GVC](/reference/gvc) that you already ha
 None for a default install. Three optional features need something to exist first:
 
 <Steps>
-  <Step title="Optional: bring your own password secret">
-    By default authentication is off, and `redis.auth.password` creates the password secret for you. To supply the password from a secret you manage instead, create a dictionary secret whose key matches `passwordKey` (default `password`) before installing. Use a separate secret for the Sentinel tier if you enable `sentinel.auth.fromSecret`.
+  <Step title="Optional: a password secret for authentication (recommended)">
+    Authentication is off by default. To turn it on, the recommended way is a password secret you create **before** install, so the password never enters the release values. Create a [dictionary secret](/guides/create-secret/dictionary) with the password under the key `password` (the default `passwordKey`); one secret can serve both Redis and Sentinel:
 
     ```bash
-    cpln secret create-dictionary --name SECRET_NAME \
-      --entry password='YOUR-STRONG-PASSWORD'
+    cpln secret create-dictionary --name my-redis-password --entry password="$(openssl rand -hex 32)"
     ```
 
-    Set `redis.auth.fromSecret.name` (and `sentinel.auth.fromSecret.name`) to this name and `fromSecret.enabled` to `true`. See [Authentication](#authentication).
+    Set `redis.auth.fromSecret.name` (and, in production mode, `sentinel.auth.fromSecret.name`) to this name and `fromSecret.enabled` to `true`. See [Authentication](#authentication).
 
     <Warning>
     If the secret does not exist when the workload starts, the deployment wedges silently: `cpln logs` returns nothing and the workload never becomes ready. The missing secret is named only in `status.versions[].message`:
@@ -77,6 +76,8 @@ cpln helm install RELEASE_NAME oci://ghcr.io/controlplane-com/templates/redis \
   --version 3.9.0 --gvc GVC_NAME
 ```
 
+To turn on authentication from the password secret in [Prerequisites](#prerequisites), set `redis.auth.fromSecret.enabled=true` and `redis.auth.fromSecret.name=my-redis-password`, and the same two keys under `sentinel.auth` in production mode.
+
 <CardGroup cols={2}>
     <Card title="UI" href="/template-catalog/install-manage/ui" icon="laptop">
     Browse, install, and manage templates visually
@@ -189,22 +190,40 @@ redis:
 
 #### Authentication
 
-Authentication is off by default. Enable exactly one method per tier; the chart refuses to render with both enabled. In production mode the Sentinel tier takes the same two options under `sentinel.auth`; dev mode uses `redis.auth` only and refuses `sentinel.auth`.
+Authentication is off by default. Enable exactly one method per tier; the chart refuses to render with both enabled. In production mode apply the same config under both `redis.auth` and `sentinel.auth`; dev mode uses `redis.auth` only and refuses `sentinel.auth`.
+
+Recommended: read the password from the secret created in [Prerequisites](#prerequisites):
 
 ```yaml
 redis:
   auth:
     fromSecret:
-      enabled: false              # set true to read the password from a secret you created (see Prerequisites)
-      name: example-redis-auth-password
+      enabled: true
+      name: my-redis-password   # dictionary secret; must exist before install
+      passwordKey: password     # key holding the password
+
+sentinel:
+  auth:
+    fromSecret:
+      enabled: true
+      name: my-redis-password   # the same secret can serve both tiers
       passwordKey: password
+```
+
+Still supported, but less secure: a password in values is stored in the Helm release, and the chart creates the password secret from it:
+
+```yaml
+redis:
+  auth:
     password:
-      enabled: false              # set true to have the chart create the password secret from `value`
+      enabled: true
       value: change-me-redis-password
 ```
 
+Set the password at install. Nodes read the secret only when they start, so a new value reaches them only after `cpln workload force-redeployment`, and that is a password change on a running release (see the warning below). With Sentinel persistence on, Sentinel also keeps the password it wrote at its first start.
+
 <Warning>
-**Do not change the password on a running release.** Changing `redis.auth.password.value` (or the contents of the referenced secret) stops the rolling update: a restarted replica can no longer authenticate to the master, so it never becomes ready and the rollout stops advancing. Setting the previous password back recovers it. To change the password, uninstall and reinstall.
+**Do not change the password on a running release,** in values or in the password secret. Changing `redis.auth.password.value` (or the contents of the referenced secret) stops the rolling update: a restarted replica can no longer authenticate to the master, so it never becomes ready and the rollout stops advancing. Setting the previous password back recovers it. To change the password, uninstall and reinstall.
 </Warning>
 
 A password may contain spaces, quotes, backslashes and any other printable character. Line breaks, tabs and other control characters are not supported, because each password is written on a single configuration line.
@@ -675,7 +694,8 @@ Afterwards, point your clients at Sentinel (`RELEASE_NAME-sentinel.GVC_NAME.cpln
 - **Choose `engine` at install time.** Switching it on a running release does not migrate anything; Valkey cannot read data written by Redis 8.
 - **Choose persistence at install time when you can.** To add it to a running release, set `suspend: true` in the same upgrade, then `suspend: false`; data held only in memory is lost.
 - **`suspend: true` stops every node.** Without persistence, the data in memory is lost.
-- **Never change the password in place.** The rolling update stops advancing; set the previous password back to recover, and reinstall to change it.
+- **Prefer `auth.fromSecret` over a password in values**, which is stored in the Helm release. Create the secret before install; a missing one is named only in `status.versions[].message` from `cpln workload get-deployments`.
+- **Never change the password in place,** in values or in the password secret. The rolling update stops advancing; set the previous password back to recover, and reinstall to change it.
 - **In production mode, always discover the master through Sentinel** (`mymaster` at `RELEASE_NAME-sentinel.GVC_NAME.cpln.local:26379`). A client pinned to replica 0 gets `READONLY` errors after any failover or upgrade. In dev mode, connect to `RELEASE_NAME-redis.GVC_NAME.cpln.local:6379` directly.
 - **Enable `sentinel.persistence` in production** so the elected master survives Sentinel restarts.
 - **The Redis 7.4 to 8 upgrade is one-way.** Snapshot the volume set before upgrading if you need a rollback path.