From ecb5f83a4885544a3a1ee2e9656daf5058c235d8 Mon Sep 17 00:00:00 2001 From: Luis Ibarra Date: Fri, 12 Jun 2026 11:58:38 -0500 Subject: [PATCH 01/10] docs: add Redis authentication guide and sidebar entry --- .../kubernetes/enable-redis-auth.md | 198 ++++++++++++++++++ .../instance-configuration/helm-chart.md | 2 + website/sidebars.js | 5 + 3 files changed, 205 insertions(+) create mode 100644 website/docs/getting-started/setup/installation-guides/kubernetes/enable-redis-auth.md diff --git a/website/docs/getting-started/setup/installation-guides/kubernetes/enable-redis-auth.md b/website/docs/getting-started/setup/installation-guides/kubernetes/enable-redis-auth.md new file mode 100644 index 0000000000..8875477e53 --- /dev/null +++ b/website/docs/getting-started/setup/installation-guides/kubernetes/enable-redis-auth.md @@ -0,0 +1,198 @@ +--- +description: Enable Redis authentication for the bundled Redis on existing Appsmith Helm chart deployments. +toc_max_heading_level: 2 +--- + +# Enable Redis Authentication + +Starting with Helm chart version **3.8.2**, the bundled Redis instance is password-protected by default. The chart generates the password automatically, stores it in a Kubernetes Secret, and wires it into both Redis and Appsmith. + +This page explains how Redis authentication works in the chart and how to enable it on existing deployments, including deployments running chart versions older than 3.8.2. + +This page applies only to the **bundled Redis** subchart (`redis.enabled: true`). If you use an external Redis instance, see [External Redis](/getting-started/setup/instance-configuration/external-redis). + +## How it works + +When `redis.auth.enabled` is `true`, the chart manages the Redis password end to end: + +- A **pre-install/pre-upgrade hook Job** checks whether the Secret named by `redis.auth.existingSecret` exists. If it doesn't, the Job generates a random password and creates the Secret with it. If the Secret already exists (created by a previous upgrade or by you), the Job leaves it untouched, so the password stays stable across upgrades. +- The Appsmith pods receive the password **by Secret reference** and assemble the authenticated `APPSMITH_REDIS_URL` from it at runtime. The password never lands in the chart's ConfigMap. +- The Redis readiness init container authenticates its `ping` checks using the same Secret. + +The relevant chart values: + +| Key | Default | Description | +|---|---|---| +| `redis.auth.enabled` | `true` | Enable authentication for the bundled Redis. | +| `redis.auth.existingSecret` | `appsmith-redis-secret` | Name of the Secret holding the Redis password. Created by the bootstrap Job when absent. | +| `redis.auth.existingSecretPasswordKey` | `redis-password` | Key within the Secret that holds the password. | +| `redisAuth.passwordInit.image.*` | `docker.io/alpine/kubectl:latest` | Image used by the bootstrap Job. Override it in air-gapped environments or to pin a specific tag. | + +For the full list of values, see the [chart README](https://github.com/appsmithorg/appsmith/tree/release/deploy/helm#appsmith). + +## Upgrade an existing deployment to chart 3.8.2 or later + +For most deployments, enabling Redis authentication is a standard chart upgrade. The bootstrap Job handles the password automatically. + +1. Update your local chart repository and upgrade: + + ```bash + helm repo update + helm upgrade -i appsmith-ee appsmith-ee/appsmith -n appsmith-ee -f values.yaml + ``` + + During the upgrade, the hook Job creates the `appsmith-redis-secret` Secret, Redis restarts with the password enabled, and the Appsmith pods restart with the authenticated connection URL. + +2. Verify that the Secret exists: + + ```bash + kubectl get secret appsmith-redis-secret -n appsmith-ee + ``` + +3. Verify that all pods are running and that Appsmith can reach Redis: + + ```bash + kubectl get pods -n appsmith-ee + ``` + + Optionally, test the authenticated connection directly: + + ```bash + kubectl exec -it appsmith-ee-redis-master-0 -n appsmith-ee -- \ + sh -c 'REDISCLI_AUTH="" redis-cli ping' + ``` + + Replace `` with the value from the `appsmith-redis-secret` Secret. The command should return `PONG`. + +### Bring your own password + +To control the password yourself, create the Secret **before** installing or upgrading. The bootstrap Job detects it and leaves it untouched: + +```bash +kubectl create secret generic appsmith-redis-secret \ + --from-literal=redis-password='' \ + -n appsmith-ee +``` + +To use a different Secret name or key, point the chart at it in `values.yaml`: + +```yaml +redis: + auth: + existingSecret: my-redis-secret + existingSecretPasswordKey: my-password-key +``` + +### Opt out + +To keep the bundled Redis unauthenticated (for example, in an isolated development cluster), disable auth in `values.yaml`: + +```yaml +redis: + auth: + enabled: false +``` + +This restores the behavior of earlier chart versions: a passwordless Redis with a plain `APPSMITH_REDIS_URL` in the ConfigMap. + +### ArgoCD deployments + +No special handling is required on chart 3.8.2 or later. ArgoCD runs the chart's pre-install/pre-upgrade hooks as PreSync hooks, and the bootstrap Job is idempotent, so the password is generated once and reused on every subsequent sync. The Secret is created without Helm release labels or owner references, so ArgoCD does not track or diff it. You don't need an `ignoreDifferences` rule. + +### Air-gapped and restricted networks + +The bootstrap Job pulls `docker.io/alpine/kubectl:latest` by default. If your cluster cannot reach Docker Hub, mirror the image to your private registry and override it in `values.yaml`: + +```yaml +redisAuth: + passwordInit: + image: + registry: registry.example.com + repository: mirrored/alpine-kubectl + tag: "1.33.1" +``` + +Pinning a specific tag is also recommended if you need reproducible deployments. + +## Enable auth on chart versions before 3.8.2 + +Chart versions older than 3.8.2 don't include the password bootstrap Job and can't assemble the authenticated Redis URL from a Secret. To enable Redis authentication without upgrading the chart, wire it manually: + +1. Create the password Secret: + + ```bash + kubectl create secret generic appsmith-redis-secret \ + --from-literal=redis-password='' \ + -n appsmith-ee + ``` + +2. Point the bundled Redis subchart at the Secret in `values.yaml`: + + ```yaml + redis: + auth: + enabled: true + existingSecret: appsmith-redis-secret + existingSecretPasswordKey: redis-password + ``` + +3. Set the authenticated Redis URL explicitly, since older charts only render the passwordless URL: + + ```yaml + applicationConfig: + APPSMITH_REDIS_URL: "redis://:@-redis-master..svc.cluster.local:6379" + ``` + + Replace `` and `` with your Helm release name and namespace. + + :::caution + On charts older than 3.8.2, the password set in `applicationConfig` is stored in cleartext in the rendered ConfigMap and in your `values.yaml`. Upgrading to chart 3.8.2 or later avoids this: the password is injected by Secret reference instead. Remove the manual `APPSMITH_REDIS_URL` override after upgrading so the chart can manage the URL. + ::: + +4. Apply the changes: + + ```bash + helm upgrade -i appsmith-ee appsmith-ee/appsmith -n appsmith-ee -f values.yaml + ``` + +### ArgoCD on older charts + +On older charts, always use the pre-created Secret approach above. If you enable `redis.auth.enabled` without `existingSecret`, the Bitnami Redis subchart generates a new random password on every render, and each ArgoCD sync rotates it, breaking existing connections until the pods restart. + +If you can't use a pre-created Secret, the alternative is to ignore drift on the generated Secret in your Application spec: + +```yaml +spec: + ignoreDifferences: + - kind: Secret + name: -redis + jsonPointers: + - /data +``` + +This is a workaround, not a recommendation. The pre-created Secret keeps the password deterministic and visible to you, and upgrading to chart 3.8.2 or later removes the problem entirely. + +## Troubleshooting + +**Appsmith logs show `NOAUTH Authentication required` or `WRONGPASS`** + +The password in the Secret doesn't match what Redis was started with, typically after editing the Secret manually. After changing the password, restart both Redis and Appsmith so they pick up the new value: + +```bash +kubectl rollout restart statefulset appsmith-ee-redis-master -n appsmith-ee +kubectl rollout restart statefulset appsmith-ee -n appsmith-ee +``` + +**The bootstrap Job pod shows `ImagePullBackOff`** + +Your cluster can't pull `docker.io/alpine/kubectl`. Mirror the image and override `redisAuth.passwordInit.image` as described in [Air-gapped and restricted networks](#air-gapped-and-restricted-networks). + +**Appsmith can't resolve the Redis host** + +The chart derives the Redis hostname from the release name and assumes the release name does not contain the word `redis`. If yours does, the Bitnami subchart shortens its resource names and the derived hostname no longer matches. Set `applicationConfig.APPSMITH_REDIS_URL` explicitly with the actual Redis service hostname, or reinstall under a release name without `redis` in it. + +## See also + +- [Helm Chart](/getting-started/setup/instance-configuration/helm-chart#redis): Architecture and configuration reference for the Appsmith Helm chart. +- [External Redis](/getting-started/setup/instance-configuration/external-redis): Connect Appsmith to a Redis instance outside the cluster. +- [Chart parameters reference](https://github.com/appsmithorg/appsmith/tree/release/deploy/helm#parameters): Full list of configurable Helm values. diff --git a/website/docs/getting-started/setup/instance-configuration/helm-chart.md b/website/docs/getting-started/setup/instance-configuration/helm-chart.md index 2f48c966e6..73e47c9523 100644 --- a/website/docs/getting-started/setup/instance-configuration/helm-chart.md +++ b/website/docs/getting-started/setup/instance-configuration/helm-chart.md @@ -56,6 +56,8 @@ For a complete walkthrough of the MongoDB Operator, see the [MongoDB Kubernetes Redis is used for session storage and caching. The chart bundles Redis by default (`redis.enabled: true`) and runs it in the cluster alongside Appsmith. You can also bring your own Redis—for example, a cloud-managed service like AWS ElastiCache—by disabling the bundled instance and setting `APPSMITH_REDIS_URL` in `applicationConfig`. +Since chart 3.8.2, the bundled Redis is password-protected by default. The chart generates the password and stores it in a Kubernetes Secret automatically. See [Enable Redis Authentication](/getting-started/setup/installation-guides/kubernetes/enable-redis-auth) for how it works and how to enable it on existing deployments. + Redis data is ephemeral, so switching between bundled and external doesn't require a data migration. See [External Redis](/getting-started/setup/instance-configuration/external-redis) for configuration details. ### PostgreSQL diff --git a/website/sidebars.js b/website/sidebars.js index f46b04ddb1..4fb0aad9e5 100644 --- a/website/sidebars.js +++ b/website/sidebars.js @@ -134,6 +134,11 @@ const sidebars = { id: 'getting-started/setup/installation-guides/kubernetes/publish-appsmith-online', label: 'Ingress and TLS', }, + { + type: 'doc', + id: 'getting-started/setup/installation-guides/kubernetes/enable-redis-auth', + label: 'Redis Authentication', + }, ], }, { From bc904d78beafcead35a64a72f04c66a63fbcaca8 Mon Sep 17 00:00:00 2001 From: Luis Ibarra Date: Mon, 15 Jun 2026 10:53:46 -0500 Subject: [PATCH 02/10] docs: trim Redis auth guide to be action-oriented Remove the "How it works" section, the standalone ArgoCD note, and internal-behavior narration throughout so the guide focuses on the steps users need to act on. Co-Authored-By: Claude Opus 4.8 --- .../kubernetes/enable-redis-auth.md | 43 ++++--------------- 1 file changed, 8 insertions(+), 35 deletions(-) diff --git a/website/docs/getting-started/setup/installation-guides/kubernetes/enable-redis-auth.md b/website/docs/getting-started/setup/installation-guides/kubernetes/enable-redis-auth.md index 8875477e53..e3f3978ded 100644 --- a/website/docs/getting-started/setup/installation-guides/kubernetes/enable-redis-auth.md +++ b/website/docs/getting-started/setup/installation-guides/kubernetes/enable-redis-auth.md @@ -7,32 +7,13 @@ toc_max_heading_level: 2 Starting with Helm chart version **3.8.2**, the bundled Redis instance is password-protected by default. The chart generates the password automatically, stores it in a Kubernetes Secret, and wires it into both Redis and Appsmith. -This page explains how Redis authentication works in the chart and how to enable it on existing deployments, including deployments running chart versions older than 3.8.2. +This page explains how to enable Redis authentication on existing deployments, including deployments running chart versions older than 3.8.2. This page applies only to the **bundled Redis** subchart (`redis.enabled: true`). If you use an external Redis instance, see [External Redis](/getting-started/setup/instance-configuration/external-redis). -## How it works - -When `redis.auth.enabled` is `true`, the chart manages the Redis password end to end: - -- A **pre-install/pre-upgrade hook Job** checks whether the Secret named by `redis.auth.existingSecret` exists. If it doesn't, the Job generates a random password and creates the Secret with it. If the Secret already exists (created by a previous upgrade or by you), the Job leaves it untouched, so the password stays stable across upgrades. -- The Appsmith pods receive the password **by Secret reference** and assemble the authenticated `APPSMITH_REDIS_URL` from it at runtime. The password never lands in the chart's ConfigMap. -- The Redis readiness init container authenticates its `ping` checks using the same Secret. - -The relevant chart values: - -| Key | Default | Description | -|---|---|---| -| `redis.auth.enabled` | `true` | Enable authentication for the bundled Redis. | -| `redis.auth.existingSecret` | `appsmith-redis-secret` | Name of the Secret holding the Redis password. Created by the bootstrap Job when absent. | -| `redis.auth.existingSecretPasswordKey` | `redis-password` | Key within the Secret that holds the password. | -| `redisAuth.passwordInit.image.*` | `docker.io/alpine/kubectl:latest` | Image used by the bootstrap Job. Override it in air-gapped environments or to pin a specific tag. | - -For the full list of values, see the [chart README](https://github.com/appsmithorg/appsmith/tree/release/deploy/helm#appsmith). - ## Upgrade an existing deployment to chart 3.8.2 or later -For most deployments, enabling Redis authentication is a standard chart upgrade. The bootstrap Job handles the password automatically. +For most deployments, enabling Redis authentication is a standard chart upgrade. 1. Update your local chart repository and upgrade: @@ -41,8 +22,6 @@ For most deployments, enabling Redis authentication is a standard chart upgrade. helm upgrade -i appsmith-ee appsmith-ee/appsmith -n appsmith-ee -f values.yaml ``` - During the upgrade, the hook Job creates the `appsmith-redis-secret` Secret, Redis restarts with the password enabled, and the Appsmith pods restart with the authenticated connection URL. - 2. Verify that the Secret exists: ```bash @@ -66,7 +45,7 @@ For most deployments, enabling Redis authentication is a standard chart upgrade. ### Bring your own password -To control the password yourself, create the Secret **before** installing or upgrading. The bootstrap Job detects it and leaves it untouched: +To control the password yourself, create the Secret **before** installing or upgrading: ```bash kubectl create secret generic appsmith-redis-secret \ @@ -93,11 +72,7 @@ redis: enabled: false ``` -This restores the behavior of earlier chart versions: a passwordless Redis with a plain `APPSMITH_REDIS_URL` in the ConfigMap. - -### ArgoCD deployments - -No special handling is required on chart 3.8.2 or later. ArgoCD runs the chart's pre-install/pre-upgrade hooks as PreSync hooks, and the bootstrap Job is idempotent, so the password is generated once and reused on every subsequent sync. The Secret is created without Helm release labels or owner references, so ArgoCD does not track or diff it. You don't need an `ignoreDifferences` rule. +This restores the behavior of earlier chart versions: a passwordless Redis. ### Air-gapped and restricted networks @@ -116,7 +91,7 @@ Pinning a specific tag is also recommended if you need reproducible deployments. ## Enable auth on chart versions before 3.8.2 -Chart versions older than 3.8.2 don't include the password bootstrap Job and can't assemble the authenticated Redis URL from a Secret. To enable Redis authentication without upgrading the chart, wire it manually: +Chart versions older than 3.8.2 require manual configuration to enable Redis authentication: 1. Create the password Secret: @@ -136,7 +111,7 @@ Chart versions older than 3.8.2 don't include the password bootstrap Job and can existingSecretPasswordKey: redis-password ``` -3. Set the authenticated Redis URL explicitly, since older charts only render the passwordless URL: +3. Set the authenticated Redis URL explicitly: ```yaml applicationConfig: @@ -157,9 +132,7 @@ Chart versions older than 3.8.2 don't include the password bootstrap Job and can ### ArgoCD on older charts -On older charts, always use the pre-created Secret approach above. If you enable `redis.auth.enabled` without `existingSecret`, the Bitnami Redis subchart generates a new random password on every render, and each ArgoCD sync rotates it, breaking existing connections until the pods restart. - -If you can't use a pre-created Secret, the alternative is to ignore drift on the generated Secret in your Application spec: +If you can't use a pre-created Secret, ignore drift on the generated Secret in your Application spec: ```yaml spec: @@ -189,7 +162,7 @@ Your cluster can't pull `docker.io/alpine/kubectl`. Mirror the image and overrid **Appsmith can't resolve the Redis host** -The chart derives the Redis hostname from the release name and assumes the release name does not contain the word `redis`. If yours does, the Bitnami subchart shortens its resource names and the derived hostname no longer matches. Set `applicationConfig.APPSMITH_REDIS_URL` explicitly with the actual Redis service hostname, or reinstall under a release name without `redis` in it. +This can happen when your Helm release name contains the word `redis`, which prevents the chart from deriving the correct Redis hostname. Set `applicationConfig.APPSMITH_REDIS_URL` explicitly with the actual Redis service hostname, or reinstall under a release name without `redis` in it. ## See also From 31b34de64219c8d5c24944cb64526148f5a3a5da Mon Sep 17 00:00:00 2001 From: Luis Ibarra Date: Mon, 15 Jun 2026 11:33:34 -0500 Subject: [PATCH 03/10] docs: note removing explicit redis.auth.enabled=false before upgrade An explicit redis.auth.enabled: false in an existing values.yaml overrides the new chart default, leaving Redis auth disabled after the upgrade. Add a step to check for and remove it. Co-Authored-By: Claude Opus 4.8 --- .../kubernetes/enable-redis-auth.md | 14 +++++++++++--- 1 file changed, 11 insertions(+), 3 deletions(-) diff --git a/website/docs/getting-started/setup/installation-guides/kubernetes/enable-redis-auth.md b/website/docs/getting-started/setup/installation-guides/kubernetes/enable-redis-auth.md index e3f3978ded..26d5bdbcd8 100644 --- a/website/docs/getting-started/setup/installation-guides/kubernetes/enable-redis-auth.md +++ b/website/docs/getting-started/setup/installation-guides/kubernetes/enable-redis-auth.md @@ -15,20 +15,28 @@ This page applies only to the **bundled Redis** subchart (`redis.enabled: true`) For most deployments, enabling Redis authentication is a standard chart upgrade. -1. Update your local chart repository and upgrade: +1. Check your `values.yaml` for an explicit `redis.auth.enabled: false`. Older deployments often carry this from a previous install, and an explicit value overrides the new default, leaving authentication disabled after the upgrade. Remove the override or set it to `true`: + + ```yaml + redis: + auth: + enabled: true + ``` + +2. Update your local chart repository and upgrade: ```bash helm repo update helm upgrade -i appsmith-ee appsmith-ee/appsmith -n appsmith-ee -f values.yaml ``` -2. Verify that the Secret exists: +3. Verify that the Secret exists: ```bash kubectl get secret appsmith-redis-secret -n appsmith-ee ``` -3. Verify that all pods are running and that Appsmith can reach Redis: +4. Verify that all pods are running and that Appsmith can reach Redis: ```bash kubectl get pods -n appsmith-ee From 4e20851adcd7ca3886d4ce0a8018e4424b491df1 Mon Sep 17 00:00:00 2001 From: Luis Ibarra Date: Mon, 15 Jun 2026 11:35:31 -0500 Subject: [PATCH 04/10] docs: make the values.yaml check step action-first Lead with the action rather than the explanation. Co-Authored-By: Claude Opus 4.8 --- .../setup/installation-guides/kubernetes/enable-redis-auth.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/docs/getting-started/setup/installation-guides/kubernetes/enable-redis-auth.md b/website/docs/getting-started/setup/installation-guides/kubernetes/enable-redis-auth.md index 26d5bdbcd8..c0cb76666c 100644 --- a/website/docs/getting-started/setup/installation-guides/kubernetes/enable-redis-auth.md +++ b/website/docs/getting-started/setup/installation-guides/kubernetes/enable-redis-auth.md @@ -15,7 +15,7 @@ This page applies only to the **bundled Redis** subchart (`redis.enabled: true`) For most deployments, enabling Redis authentication is a standard chart upgrade. -1. Check your `values.yaml` for an explicit `redis.auth.enabled: false`. Older deployments often carry this from a previous install, and an explicit value overrides the new default, leaving authentication disabled after the upgrade. Remove the override or set it to `true`: +1. Remove any explicit `redis.auth.enabled: false` from your `values.yaml`, or set it to `true`. An explicit `false` overrides the new default and leaves authentication disabled after the upgrade: ```yaml redis: From 57810502b3b0516ad3be2a245505cb03af06d20f Mon Sep 17 00:00:00 2001 From: Luis Ibarra Date: Wed, 24 Jun 2026 20:22:06 -0500 Subject: [PATCH 05/10] docs: drop ArgoCD-on-older-charts workaround section Per review: removes a confusing workaround section in favor of the pre-created Secret path already documented. Co-Authored-By: Claude Opus 4.8 --- .../kubernetes/enable-redis-auth.md | 15 --------------- 1 file changed, 15 deletions(-) diff --git a/website/docs/getting-started/setup/installation-guides/kubernetes/enable-redis-auth.md b/website/docs/getting-started/setup/installation-guides/kubernetes/enable-redis-auth.md index c0cb76666c..0622394465 100644 --- a/website/docs/getting-started/setup/installation-guides/kubernetes/enable-redis-auth.md +++ b/website/docs/getting-started/setup/installation-guides/kubernetes/enable-redis-auth.md @@ -138,21 +138,6 @@ Chart versions older than 3.8.2 require manual configuration to enable Redis aut helm upgrade -i appsmith-ee appsmith-ee/appsmith -n appsmith-ee -f values.yaml ``` -### ArgoCD on older charts - -If you can't use a pre-created Secret, ignore drift on the generated Secret in your Application spec: - -```yaml -spec: - ignoreDifferences: - - kind: Secret - name: -redis - jsonPointers: - - /data -``` - -This is a workaround, not a recommendation. The pre-created Secret keeps the password deterministic and visible to you, and upgrading to chart 3.8.2 or later removes the problem entirely. - ## Troubleshooting **Appsmith logs show `NOAUTH Authentication required` or `WRONGPASS`** From 543912d26bf345c71f2d50bb7875056233b9fd4b Mon Sep 17 00:00:00 2001 From: Luis Ibarra Date: Thu, 25 Jun 2026 23:09:31 -0500 Subject: [PATCH 06/10] docs: document the self-managed redis.auth.password path Add a "Self-manage the Redis password" subsection covering the redis.auth.password + empty existingSecret + matching APPSMITH_REDIS_URL combination, and a troubleshooting entry for the chart's fail-fast guard. Drop the now-stale "Appsmith can't resolve the Redis host" entry: the chart's redisMasterHost helper now derives the host from the subchart's common.names.fullname, which handles release names containing "redis". Co-Authored-By: Claude Opus 4.8 --- .../kubernetes/enable-redis-auth.md | 23 +++++++++++++++---- 1 file changed, 19 insertions(+), 4 deletions(-) diff --git a/website/docs/getting-started/setup/installation-guides/kubernetes/enable-redis-auth.md b/website/docs/getting-started/setup/installation-guides/kubernetes/enable-redis-auth.md index 0622394465..7889640c8b 100644 --- a/website/docs/getting-started/setup/installation-guides/kubernetes/enable-redis-auth.md +++ b/website/docs/getting-started/setup/installation-guides/kubernetes/enable-redis-auth.md @@ -70,6 +70,21 @@ redis: existingSecretPasswordKey: my-password-key ``` +### Self-manage the Redis password + +To set the Redis password directly instead of letting the chart manage a Secret — for example, when migrating a deployment that already sets `redis.auth.password` — set all three values in `values.yaml`: + +```yaml +redis: + auth: + password: "" + existingSecret: "" +applicationConfig: + APPSMITH_REDIS_URL: "redis://:@-redis-master..svc.cluster.local:6379" +``` + +`existingSecret` must be empty so the chart skips its bootstrap Secret, and `APPSMITH_REDIS_URL` must carry the same password. The chart rejects the install with an error if `redis.auth.password` is set without both. + ### Opt out To keep the bundled Redis unauthenticated (for example, in an isolated development cluster), disable auth in `values.yaml`: @@ -140,6 +155,10 @@ Chart versions older than 3.8.2 require manual configuration to enable Redis aut ## Troubleshooting +**Install fails with `redis.auth.password is set, which is only supported on the self-managed path`** + +Either unset `redis.auth.password` and use a Secret instead (see [Bring your own password](#bring-your-own-password)), or set the full self-managed configuration (see [Self-manage the Redis password](#self-manage-the-redis-password)). + **Appsmith logs show `NOAUTH Authentication required` or `WRONGPASS`** The password in the Secret doesn't match what Redis was started with, typically after editing the Secret manually. After changing the password, restart both Redis and Appsmith so they pick up the new value: @@ -153,10 +172,6 @@ kubectl rollout restart statefulset appsmith-ee -n appsmith-ee Your cluster can't pull `docker.io/alpine/kubectl`. Mirror the image and override `redisAuth.passwordInit.image` as described in [Air-gapped and restricted networks](#air-gapped-and-restricted-networks). -**Appsmith can't resolve the Redis host** - -This can happen when your Helm release name contains the word `redis`, which prevents the chart from deriving the correct Redis hostname. Set `applicationConfig.APPSMITH_REDIS_URL` explicitly with the actual Redis service hostname, or reinstall under a release name without `redis` in it. - ## See also - [Helm Chart](/getting-started/setup/instance-configuration/helm-chart#redis): Architecture and configuration reference for the Appsmith Helm chart. From 757b0a15440a511f9e0722610df41a974ff02e19 Mon Sep 17 00:00:00 2001 From: Luis Ibarra Date: Thu, 25 Jun 2026 23:10:27 -0500 Subject: [PATCH 07/10] docs: drop em dash in self-managed password subsection Co-Authored-By: Claude Opus 4.8 --- .../setup/installation-guides/kubernetes/enable-redis-auth.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/docs/getting-started/setup/installation-guides/kubernetes/enable-redis-auth.md b/website/docs/getting-started/setup/installation-guides/kubernetes/enable-redis-auth.md index 7889640c8b..48a0785eed 100644 --- a/website/docs/getting-started/setup/installation-guides/kubernetes/enable-redis-auth.md +++ b/website/docs/getting-started/setup/installation-guides/kubernetes/enable-redis-auth.md @@ -72,7 +72,7 @@ redis: ### Self-manage the Redis password -To set the Redis password directly instead of letting the chart manage a Secret — for example, when migrating a deployment that already sets `redis.auth.password` — set all three values in `values.yaml`: +To set the Redis password directly instead of letting the chart manage a Secret (for example, when migrating a deployment that already sets `redis.auth.password`), set all three values in `values.yaml`: ```yaml redis: From 7dac43c1fd1d58c9fb58fdca72acf14a99c28f16 Mon Sep 17 00:00:00 2001 From: Luis Ibarra Date: Wed, 1 Jul 2026 10:20:39 -0500 Subject: [PATCH 08/10] docs: enforce authentication for external and cloud-managed Redis Cloud-managed Redis (ElastiCache, Azure Cache, Memorystore, Redis Cloud) must run with authentication enabled. Update the external Redis examples to credentialed connection strings, add an "Enable authentication" section with provider-specific formats, and update the AWS ECS and GCP Cloud Run HA guides to enable auth and connect with credentials. Also fix a copy-paste reference to ElastiCache in the GCP guide. Co-Authored-By: Claude Opus 4.8 --- .../setup/environment-variables.md | 2 +- .../aws-ecs/set-up-high-availability.mdx | 8 +++-- .../google-cloud-run/manage-traffic.mdx | 7 ++-- .../instance-configuration/external-redis.mdx | 36 ++++++++++++++++--- 4 files changed, 41 insertions(+), 12 deletions(-) diff --git a/website/docs/getting-started/setup/environment-variables.md b/website/docs/getting-started/setup/environment-variables.md index 07b2601cc2..e2e2b44382 100644 --- a/website/docs/getting-started/setup/environment-variables.md +++ b/website/docs/getting-started/setup/environment-variables.md @@ -310,7 +310,7 @@ Defines the database driver that Keycloak will use to interact with the external ##### `APPSMITH_REDIS_URL`
- Appsmith uses this variable to establish a link to an external Redis server, which Appsmith uses for session handling and caching operations. This connection string typically includes the Redis host, port number, and optionally, authentication credentials. + Appsmith uses this variable to establish a link to an external Redis server, which Appsmith uses for session handling and caching operations. The connection string includes the Redis host, port number, and authentication credentials, for example `redis://:@:`. Always include credentials for external or cloud-managed Redis, and use the `rediss://` scheme when encryption in transit is enabled. See [Enable authentication](/getting-started/setup/instance-configuration/external-redis#enable-authentication).
### Custom domain diff --git a/website/docs/getting-started/setup/installation-guides/aws-ecs/set-up-high-availability.mdx b/website/docs/getting-started/setup/installation-guides/aws-ecs/set-up-high-availability.mdx index 869a9cc098..a054e67b3d 100644 --- a/website/docs/getting-started/setup/installation-guides/aws-ecs/set-up-high-availability.mdx +++ b/website/docs/getting-started/setup/installation-guides/aws-ecs/set-up-high-availability.mdx @@ -81,9 +81,11 @@ Appsmith relies on Redis for caching and session storage. To configure Redis for - **Dev/Test**: `cache.r7g.large` (13.07 GiB memory, up to 12.5 Gigabit network performance). - **Demo**: `cache.t4g.micro` (0.5 GiB memory, up to 5 Gigabit network performance). -8. Review the settings, and once satisfied, click **Create** to launch the Redis instance. +8. Enable **Encryption in transit** and set a **Redis AUTH token** (or create an RBAC user) so the cache requires authentication. Store the AUTH token securely. Never run ElastiCache without authentication. -9. Once the Redis cluster is created, copy and securely store the endpoint and connection details. You'll need these when configuring high availability in the next steps. +9. Review the settings, and once satisfied, click **Create** to launch the Redis instance. + +10. Once the Redis cluster is created, copy and securely store the endpoint, port, and AUTH token. You'll need these when configuring high availability in the next steps. ### Configure PostgreSQL (optional) @@ -116,7 +118,7 @@ To ensure Appsmith is highly available, configure it to use multiple instances, 3. Add the following environment variables under **Container-1**. Use the values obtained during the [Set up external databases](#set-up-external-databases) section. - `APPSMITH_DB_URL=`: Use the connection string for your MongoDB database, configured during its setup. - - `APPSMITH_REDIS_URL=`: Use the Redis connection string or endpoint provided after setting up your Redis instance on AWS ElastiCache. + - `APPSMITH_REDIS_URL=rediss://:@:6379`: Use the ElastiCache endpoint with the AUTH token so Appsmith connects with authentication. Use the `rediss://` scheme because encryption in transit is enabled. See [Enable authentication](/getting-started/setup/instance-configuration/external-redis#enable-authentication). - `APPSMITH_KEYCLOAK_DB_URL=`: This should be the endpoint of the PostgreSQL database you set up for Keycloak. - `APPSMITH_KEYCLOAK_DB_DRIVER=postgresql`: Set the driver to `postgresql` as Keycloak uses PostgreSQL for its database. - `APPSMITH_KEYCLOAK_DB_USERNAME=`: Enter the username you configured during the PostgreSQL setup. diff --git a/website/docs/getting-started/setup/installation-guides/google-cloud-run/manage-traffic.mdx b/website/docs/getting-started/setup/installation-guides/google-cloud-run/manage-traffic.mdx index 368c254e59..bf819742cd 100644 --- a/website/docs/getting-started/setup/installation-guides/google-cloud-run/manage-traffic.mdx +++ b/website/docs/getting-started/setup/installation-guides/google-cloud-run/manage-traffic.mdx @@ -73,8 +73,9 @@ Appsmith relies on Redis for caching and session storage. Set up a Redis instanc - **Configure read replicas**: Select `2 Read Replicas` if using the Standard tier to ensure high availability. 4. Under **Set up connection**, choose the default option for **Network**. 5. Expand the **Configuration** section and select **6.x** (recommended) for the Redis version. -6. Click the **Create** button to deploy the Redis instance. -7. Once the instance is ready, note down the **Primary Endpoint**, as this will be used later in your Appsmith configuration. +6. Enable **AUTH** and **in-transit encryption** so the instance requires authentication. Store the AUTH string securely. Never run Memorystore without authentication. +7. Click the **Create** button to deploy the Redis instance. +8. Once the instance is ready, note down the **Primary Endpoint** and the **AUTH string**, as these will be used later in your Appsmith configuration. @@ -146,7 +147,7 @@ After setting up external databases, configure Appsmith on Google Cloud Run for 3. Add the following environment variables: - `APPSMITH_DB_URL=`: Use the connection string for your MongoDB database, configured during its setup. - - `APPSMITH_REDIS_URL=`: Use the Redis connection string or endpoint provided after setting up your Redis instance on AWS ElastiCache. + - `APPSMITH_REDIS_URL=rediss://:@:6379`: Use the Memorystore primary endpoint with the AUTH string so Appsmith connects with authentication. Use the `rediss://` scheme because in-transit encryption is enabled. See [Enable authentication](/getting-started/setup/instance-configuration/external-redis#enable-authentication). - `APPSMITH_KEYCLOAK_DB_URL=`: This should be the endpoint of the PostgreSQL database you set up for Keycloak. - `APPSMITH_KEYCLOAK_DB_DRIVER=postgresql`: Set the driver to `postgresql` as Keycloak uses PostgreSQL for its database. - `APPSMITH_KEYCLOAK_DB_USERNAME=`: Enter the username you configured during the PostgreSQL setup. diff --git a/website/docs/getting-started/setup/instance-configuration/external-redis.mdx b/website/docs/getting-started/setup/instance-configuration/external-redis.mdx index b87dd62a7f..f8696ac416 100644 --- a/website/docs/getting-started/setup/instance-configuration/external-redis.mdx +++ b/website/docs/getting-started/setup/instance-configuration/external-redis.mdx @@ -21,9 +21,9 @@ Follow these steps to set up an external Redis instance for Appsmith. If you alr 1. Create a Redis instance: - **Self-hosted Redis**: Install and configure Redis on your server using the [Redis installation guide](https://redis.io/docs/latest/get-started/). - - **Cloud-hosted Redis**: Set up a managed Redis instance using a cloud provider such as AWS ElastiCache, Redis Cloud, or Azure Cache for Redis. + - **Cloud-hosted Redis**: Set up a managed Redis instance using a cloud provider such as AWS ElastiCache, Redis Cloud, or Azure Cache for Redis. Enable authentication on the instance (see [Enable authentication](#enable-authentication)). Cloud-managed Redis must never be exposed without a password. -2. Retrieve the connection details of your Redis instance, including the hostname and port. Store these details securely. You need them to configure the Redis instance on Appsmith. +2. Retrieve the connection details of your Redis instance, including the hostname, port, and the authentication password or AUTH token. Store these details securely. You need them to configure the Redis instance on Appsmith. ## Connect Appsmith to external Redis @@ -31,25 +31,29 @@ Follow these steps to connect your Appsmith instance to the external Redis insta 1. Go to the directory containing the Appsmith configuration file, such as `docker.env` for Docker or `values.yaml` for Kubernetes. -2. Add or update the following environment variable with your Redis connection details: +2. Add or update the following environment variable with your Redis connection details. Include the password so Appsmith connects with authentication: * **Docker**: ```yaml - APPSMITH_REDIS_URL=redis://{redis.instance.hostname}:{port} + APPSMITH_REDIS_URL=redis://:{password}@{redis.instance.hostname}:{port} ``` Replace: + - `{password}` with the Redis password or AUTH token. - `{redis.instance.hostname}` with the Redis instance hostname or IP address. - `{port}` with the Redis port (default: 6379). * **Kubernetes**: ```yaml - APPSMITH_REDIS_URL:redis://{redis.instance.hostname}:{port} + APPSMITH_REDIS_URL:redis://:{password}@{redis.instance.hostname}:{port} ``` Replace: + - `{password}` with the Redis password or AUTH token. - `{redis.instance.hostname}` with the Redis instance hostname or IP address. - `{port}` with the Redis port (default: 6379). + If your instance has encryption in transit enabled, use the `rediss://` scheme instead of `redis://`. For provider-specific formats, see [Enable authentication](#enable-authentication). + 3. Update the Appsmith server configuration to establish a connection with the external Redis instance. - **Docker**: ```bash @@ -63,6 +67,28 @@ Follow these steps to connect your Appsmith instance to the external Redis insta 4. Log in to your Appsmith application and verify that the instance is functioning as expected. 5. Confirm that data caching and sessions management is happening by the external Redis instance. +## Enable authentication + +:::caution +Cloud-managed Redis (AWS ElastiCache, Azure Cache for Redis, GCP Memorystore, Redis Cloud) must run with authentication enabled, and Appsmith must connect with credentials. Never expose an external Redis instance without a password. +::: + +Provide the credentials in `APPSMITH_REDIS_URL`. Two forms are supported: + +- `redis://:@:` when the instance uses a single password or AUTH token. +- `redis://:@:` when the instance uses an ACL / RBAC user. + +Use the `rediss://` scheme instead of `redis://` when encryption in transit is enabled. Appsmith also supports the `redis-cluster://` scheme for clustered instances. + +Enable authentication on the managed instance and build the connection string as follows: + +| Provider | Enable on the instance | Connection string | +|---|---|---| +| **AWS ElastiCache** | Turn on **Encryption in transit** and set a **Redis AUTH token** (or create an RBAC user). | `rediss://:@:6379` | +| **Azure Cache for Redis** | TLS is required. Use the **access key** as the password on the TLS port `6380`. | `rediss://:@.redis.cache.windows.net:6380` | +| **GCP Memorystore** | Enable **AUTH** and **in-transit encryption**. | `rediss://:@:6379` | +| **Redis Cloud** | Set a database password. | `redis://:@:` (use `rediss://` with TLS) | + ## Troubleshooting If you face connection issues: From 07cebfef66cec440867bba818f237102cd508b7f Mon Sep 17 00:00:00 2001 From: Luis Ibarra Date: Wed, 1 Jul 2026 10:30:38 -0500 Subject: [PATCH 09/10] docs: address council review findings on Redis auth docs - Add a plaintext-storage caution and rotation pointer to the self-manage password path (security). - State rollout expectation (ephemeral Redis, brief logout, no data loss) on the upgrade path (product). - Note that examples assume release name appsmith-ee and that the Redis Secret name is a fixed default; add a Docker pointer (architecture). - Discourage the :latest bootstrap image in favor of a pinned tag. - Align terminology: cleartext -> plaintext. - Fix invalid YAML (missing space) in the external Redis k8s example. Co-Authored-By: Claude Opus 4.8 --- .../kubernetes/enable-redis-auth.md | 14 ++++++++++---- .../instance-configuration/external-redis.mdx | 2 +- 2 files changed, 11 insertions(+), 5 deletions(-) diff --git a/website/docs/getting-started/setup/installation-guides/kubernetes/enable-redis-auth.md b/website/docs/getting-started/setup/installation-guides/kubernetes/enable-redis-auth.md index 48a0785eed..c308a917a1 100644 --- a/website/docs/getting-started/setup/installation-guides/kubernetes/enable-redis-auth.md +++ b/website/docs/getting-started/setup/installation-guides/kubernetes/enable-redis-auth.md @@ -9,11 +9,13 @@ Starting with Helm chart version **3.8.2**, the bundled Redis instance is passwo This page explains how to enable Redis authentication on existing deployments, including deployments running chart versions older than 3.8.2. -This page applies only to the **bundled Redis** subchart (`redis.enabled: true`). If you use an external Redis instance, see [External Redis](/getting-started/setup/instance-configuration/external-redis). +This page applies only to the **bundled Redis** subchart (`redis.enabled: true`). If you use an external Redis instance, see [External Redis](/getting-started/setup/instance-configuration/external-redis). For a Docker single-container deployment, use External Redis to run an authenticated instance. + +The examples use the release name `appsmith-ee`. Substitute your own release name and namespace. The Secret name `appsmith-redis-secret` is a fixed default (set by `redis.auth.existingSecret`) and is not release-prefixed. ## Upgrade an existing deployment to chart 3.8.2 or later -For most deployments, enabling Redis authentication is a standard chart upgrade. +For most deployments, enabling Redis authentication is a standard chart upgrade. Redis stores only sessions and cache, so enabling authentication briefly logs users out and repopulates the cache with no data loss while the pods roll. 1. Remove any explicit `redis.auth.enabled: false` from your `values.yaml`, or set it to `true`. An explicit `false` overrides the new default and leaves authentication disabled after the upgrade: @@ -85,6 +87,10 @@ applicationConfig: `existingSecret` must be empty so the chart skips its bootstrap Secret, and `APPSMITH_REDIS_URL` must carry the same password. The chart rejects the install with an error if `redis.auth.password` is set without both. +:::caution +This path stores the password in plaintext in two places: `redis.auth.password` and the `APPSMITH_REDIS_URL` in your `values.yaml` and the rendered ConfigMap. Prefer the chart-managed Secret (the default) or [Bring your own password](#bring-your-own-password), and manage rotation through your secret manager (for example, Sealed Secrets or Vault). +::: + ### Opt out To keep the bundled Redis unauthenticated (for example, in an isolated development cluster), disable auth in `values.yaml`: @@ -110,7 +116,7 @@ redisAuth: tag: "1.33.1" ``` -Pinning a specific tag is also recommended if you need reproducible deployments. +The default tag is `latest`. Pin a specific tag or digest for reproducible, supply-chain-safe deployments. ## Enable auth on chart versions before 3.8.2 @@ -144,7 +150,7 @@ Chart versions older than 3.8.2 require manual configuration to enable Redis aut Replace `` and `` with your Helm release name and namespace. :::caution - On charts older than 3.8.2, the password set in `applicationConfig` is stored in cleartext in the rendered ConfigMap and in your `values.yaml`. Upgrading to chart 3.8.2 or later avoids this: the password is injected by Secret reference instead. Remove the manual `APPSMITH_REDIS_URL` override after upgrading so the chart can manage the URL. + On charts older than 3.8.2, the password set in `applicationConfig` is stored in plaintext in the rendered ConfigMap and in your `values.yaml`. Upgrading to chart 3.8.2 or later avoids this: the password is injected by Secret reference instead. Remove the manual `APPSMITH_REDIS_URL` override after upgrading so the chart can manage the URL. ::: 4. Apply the changes: diff --git a/website/docs/getting-started/setup/instance-configuration/external-redis.mdx b/website/docs/getting-started/setup/instance-configuration/external-redis.mdx index f8696ac416..a8c1e68d6d 100644 --- a/website/docs/getting-started/setup/instance-configuration/external-redis.mdx +++ b/website/docs/getting-started/setup/instance-configuration/external-redis.mdx @@ -45,7 +45,7 @@ Follow these steps to connect your Appsmith instance to the external Redis insta * **Kubernetes**: ```yaml - APPSMITH_REDIS_URL:redis://:{password}@{redis.instance.hostname}:{port} + APPSMITH_REDIS_URL: redis://:{password}@{redis.instance.hostname}:{port} ``` Replace: - `{password}` with the Redis password or AUTH token. From b344dafc5d7da24dd3e29d6ffee9a1aa17802038 Mon Sep 17 00:00:00 2001 From: Luis Ibarra Date: Wed, 1 Jul 2026 10:37:07 -0500 Subject: [PATCH 10/10] docs: trim redundant scope notes from Redis auth page Co-Authored-By: Claude Opus 4.8 --- .../setup/installation-guides/kubernetes/enable-redis-auth.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/website/docs/getting-started/setup/installation-guides/kubernetes/enable-redis-auth.md b/website/docs/getting-started/setup/installation-guides/kubernetes/enable-redis-auth.md index c308a917a1..09160180fb 100644 --- a/website/docs/getting-started/setup/installation-guides/kubernetes/enable-redis-auth.md +++ b/website/docs/getting-started/setup/installation-guides/kubernetes/enable-redis-auth.md @@ -9,9 +9,9 @@ Starting with Helm chart version **3.8.2**, the bundled Redis instance is passwo This page explains how to enable Redis authentication on existing deployments, including deployments running chart versions older than 3.8.2. -This page applies only to the **bundled Redis** subchart (`redis.enabled: true`). If you use an external Redis instance, see [External Redis](/getting-started/setup/instance-configuration/external-redis). For a Docker single-container deployment, use External Redis to run an authenticated instance. +This page applies only to the **bundled Redis** subchart (`redis.enabled: true`). If you use an external Redis instance, see [External Redis](/getting-started/setup/instance-configuration/external-redis). -The examples use the release name `appsmith-ee`. Substitute your own release name and namespace. The Secret name `appsmith-redis-secret` is a fixed default (set by `redis.auth.existingSecret`) and is not release-prefixed. +The examples use the release name `appsmith-ee`. Substitute your own release name and namespace. ## Upgrade an existing deployment to chart 3.8.2 or later