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/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..09160180fb --- /dev/null +++ b/website/docs/getting-started/setup/installation-guides/kubernetes/enable-redis-auth.md @@ -0,0 +1,185 @@ +--- +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 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). + +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 + +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: + + ```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 + ``` + +3. Verify that the Secret exists: + + ```bash + kubectl get secret appsmith-redis-secret -n appsmith-ee + ``` + +4. 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: + +```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 +``` + +### 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. + +:::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`: + +```yaml +redis: + auth: + enabled: false +``` + +This restores the behavior of earlier chart versions: a passwordless Redis. + +### 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" +``` + +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 + +Chart versions older than 3.8.2 require manual configuration to enable Redis authentication: + +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: + + ```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 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: + + ```bash + helm upgrade -i appsmith-ee appsmith-ee/appsmith -n appsmith-ee -f values.yaml + ``` + +## 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: + +```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). + +## 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/external-redis.mdx b/website/docs/getting-started/setup/instance-configuration/external-redis.mdx index b87dd62a7f..a8c1e68d6d 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: 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 ec116fb32a..f7d0c5b615 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', + }, ], }, {