title: Redis Enterprise for Kubernetes Release Notes 6.0.6-6 (June 2020)

title: Overview

text: Redis Enterprise for Kubernetes 6.0.6-6 is now available. This release includes Redis Enterprise (RS) version [6.0]() and introduces new features, improvements, and bug fixes.

title: Overview

text:
This release of the operator provides:

- Support for the Redis Enterprise Software release 6.0.6
- Includes the new database and admission controllers
- Various improvements and bug fixes

To upgrade your deployment to this latest release, see ["Upgrade a Redis Enterprise cluster (REC) on Kubernetes"]().

If you are running Active-Active (CRBD) databases on a previous release, do not upgrade to 6.0.6-6 at this time. There is an issue with the upgrade process that is currently being investigated (RED43635). For more information and support please [contact Redis support](https://redislabs.com/company/support/).

title: Images

text:
- **Redis Enterprise** - redislabs/redis:6.0.6-6 or redislabs/redis:6.0.6-6.rhel7-openshift
- **Operator** - redislabs/operator:6.0.6-6 or redislabs/operator:6.0.6-6.rhel7
- **Services Rigger** - redislabs/k8s-controller:6.0.6-6 or redislabs/k8s-controller:6.0.6-6.rhel7

title: New features and improvements

text:
- Database controller - A new database controller in the operator provides the ability to create
and manage databases on a Redis Enterprise cluster via a custom resource (RED36516).

- Admission controller - A new admission controller in the operator provides validation of
database custom resources (RED36458).

- Pod tolerations - Support for specifying Redis Enterprise cluster node pod tolerations of node taints
has been added to the cluster CR (see podTolerations) (RED33069).

- Pod annotations - Support for specifying Redis Enterprise cluster node pod annotations has been
added to the cluster CR (see podAnnotations) (RED35613).

- Kubernetes versions - Support for Kubernetes 1.17 was added and versions 1.9 and 1.10 (previously deprecated) are no longer supported (RED41049).

- Improved OLM Experience - The overall user experience and documentation in the OLM (OperatorHub) has been improved (RED37008).

- Resource limits - Resource limits have been added to the recommended operator configuration (RED39572).

- LoadBalancer service type added - The `LoadBalancer` value has been added to the `databaseServiceType` option in `servicesRiggerSpec` (RED43215):

    [code example]

title: Important fixes

text:
- Service creation failure causes cluster setup failure (RED37197)
- UI service update failure (RED37198)
- Error shown in OLM deployment: "The field status.state is invalid" (RED40278)
- OLM: StatefulSet not listed as an object owned by the Redis Enterprise Cluster (RED39296)
- Setting extraLabels in the cluster CR did not label pods on OpenShift (RED39763)
- log_collector failed to get the pods logs when a namespace wasn't given (RED39292)
- Role and RoleBinding created or updated using an existing ServiceAccount in REC spec (RED42912)

title: Known limitations

text:
- CrashLoopBackOff pod status and cluster recovery - When a pod status is CrashLoopBackOff and we run the cluster recovery, the process
will not complete. The solution is to delete the crashing pods manually and
recovery process will continue (RED33713).

- Active-Active (CRDB) - limitation on cluster name length - A cluster name longer than 20 characters will result in a rejected route
configuration as the host part of the domain name exceeds 63 characters. Cluster
names must be limited to 20 characters or less (RED25871).

- Active-Active (CRDB) service broker cleanup - The service broker doesn't clean up database service bindings in case of failures.
These bindings must be removed manually (RED25825).

- Service broker deployment error - The service broker deployment results in an error when two types of service naming
schemes are set. Choosing one of the methods will resolve this error (`redis-port`
is the recommended default) (RED25547).

- Cluster spec invalid errors not reported - A cluster CR specification error is not reported if two or more invalid CR resources are
updated in sequence (RED25542).

- Unreachable cluster does not produce an error - When a cluster is in an unreachable state the state is still `running` instead of
being reported as an error (RED32805).

- Readiness probe ignores rladmin failure - STS Readiness probe doesn't mark a node as not ready when rladmin status nodes fails (RED39300).

- Missing permission for role - The redis-enterprise-operator role is missing permission on replicasets (RED39002).

- Openshift 3.11 doesn't support DockerHub private registry - Openshift 3.11 doesn't support DockerHub private registry. This is a known OpenShift
issue and not addressable by Redis Enterprise for Kubernetes (RED38579).

- Possible DNS conflicts within cluster nodes - DNS conflicts are possible between the cluster mdns_server and the K8s DNS.
This only impacts DNS resolution from within cluster node and while using the full fqdn *.cluster.local (RED37462).

- Coexistence of 5.4.10 and 5.4.6 clusters - K8s clusters with Redis Enterprise 5.4.6 clusters are negatively affected by installing a Redis Enterprise 5.4.10 cluster due to changes in CRD (CustomeResourceDefinition) (RED37233).

- Redis Enterprise CPU utilization metric reports at K8s node level rather than at pod level - In Kubernetes, the node CPU usage we report on is the usage of the K8S worker node hosting the REC pod (RED-36884). Pod resource utilization should be measured by K8s-native means rather than through the application.

- Cluster name is limited on OpenShift via OLM - In OLM-deployed operators, the deployment of the cluster will fail if the name
is not "rec". When the operator is deployed via the OLM, the security context constraints (scc)
is bound to a specific service account name (i.e., "rec"). Naming the cluster
"rec" resolves the issue (RED39825).

title: Coming Soon

text:
The following lists features, fixes and changes the Redis team is currently investing in:

- Redis Enterprise and Kubernetes Container Artifacts - tarting from the next release of Redis Enterprise for K8s, new container artifacts will be published using different base images:

    - **Redis Enterprise** - A UBI (RHEL 7) base image will replace the Ubuntu and the RHEL7 base images
    - **Operator** - An Image built from scratch containing the Golang executable will replace the Ubuntu and the RHEL7 base images
    - **Services Rigger** - A UBI (RHEL 7) base image will replace the Ubuntu and the RHEL7 base images

- Deprecation notice - he service broker solution is deprecated and will not be supported starting from the next release of the Redis Enterprise Operator for Kubernetes.

- Additional Redis Enterprise Database configuration options in the Database Controller - We're currently investing in the following additional capabilities of the Database Controller:
    - Support for loading database modules
    - Support for setting up Alerts, expressed as K8s events
    - Support for configuring database backup options
    - Support for Kubernetes 1.18
    - Support for Rancher K8s distribution

code:
servicesRiggerSpec:
       databaseServiceType: LoadBalancer

section_id: new-features-and-improvements


title: Redis Enterprise for Kubernetes Release Notes 6.0.8-1 (October 2020)

summary: Support for RS 6.0.8-28, OpenShift 4.5, K8s 1.18, and Gesher admission controller proxy.

page_type: content

title: Overview

role: overview

text: The Redis Enterprise K8s 6.0.8-1 release is a *major release* on top of [6.0.6-24](https://github.com/RedisLabs/redis-enterprise-k8s-docs/releases/tag/v6.0.6-24) providing support for the latest [Redis Enterprise Software release 6.0.8-28](https://docs.redislabs.com/latest/rs/release-notes/rs-6-0-8-september-2020/) and includes several enhancements (including OpenShift 4.5 and Kubernetes 1.18 support) and bug fixes.

title: Overview

text:
This release of the operator provides:

 * New features
 * New support K8s distributions and platforms
 * Various bug fixes

To upgrade your deployment to this latest release, see ["Upgrade a Redis Enterprise cluster (REC) on Kubernetes"]().

title: Images

role: content

text:
* **Redis Enterprise** - redislabs/redis:6.0.8-28 or redislabs/redis:6.0.8-28.rhel7-openshift
 * **Operator** - redislabs/operator:6.0.8-1
 * **Services Rigger** - redislabs/k8s-controller:6.0.8-1 or redislabs/services-manager:6.0.8-1 (Red Hat registry)

title: New features

text:
* Redis [Modules](https://redislabs.com/redis-enterprise/modules/) can now be [configured](https://github.com/RedisLabs/redis-enterprise-k8s-docs/blob/master/redis_enterprise_database_api.md#dbmodule) in the database custom resource.
 * Support was added for **[OpenShift 4.5](https://docs.openshift.com/container-platform/4.5/release_notes/ocp-4-5-release-notes.html)**
 * Support was added for **Kubernetes 1.18**
 * Added support for the Gesher admission control proxy to provide an administrator the ability to setup delegation to avoid the need for administrator intervention on every namespaced deployed operator.

title: Important fixes

text:
* Added the missing Services Rigger health check (RED47062)
 * Fixed failures when updating the ui service type (RED45771)

title: Known limitations

title: CrashLoopBackOff causes cluster recovery to be incomplete  (RED33713)

text: When a pod status is CrashLoopBackOff and we run the cluster recovery, the process will not complete. The workaround is to delete the crashing pods manually and recovery process will continue.

title: Long cluster names cause routes to be rejected  (RED25871)

text: A cluster name longer than 20 characters will result in a rejected route configuration as the host part of the domain name exceeds 63 characters. The workaround is to limit cluster name to 20 characters or less.

title: Cluster CR (REC) errors are not reported after invalid updates (RED25542)

text: A cluster CR specification error is not reported if two or more invalid CR resources are updated in sequence.

title: An unreachable cluster has status running (RED32805)

text: When a cluster is in an unreachable state the state is still running instead of being reported as an error.

title: Readiness probe incorrect on failures (RED39300)

text: STS Readiness probe doesn't mark a node as not ready when rladmin status on the node fails.

title: Role missing on replica sets (RED39002)

text: The redis-enterprise-operator role is missing permission on replica sets.

title: Private registries are not supported on OpenShift 3.11 (RED38579)

text: Openshift 3.11 doesn't support dockerhub private registry. This is a known OpenShift issue.

title: Internal DNS and Kubernetes DNS may have conflicts (RED37462)

text: DNS conflicts are possible between the cluster mdns_server and the K8s DNS. This only impacts DNS resolution from within cluster nodes for Kubernetes DNS names.

title: 5.4.10 negatively impacts 5.4.6 (RED37233)

text: Kubernetes-based 5.4.10 deployments seem to negatively impact existing 5.4.6 deployments that share a Kubernetes cluster.

title: Node CPU usage is reported instead of pod CPU usage (RED36884)

text: In Kubernetes, the node CPU usage we report on is the usage of the Kubernetes worker node hosting the REC pod.

title: Master pod label in Rancher (RED42896)

text: Master pod is not always labeled in Rancher.

title: Cluster fail to start for clusters with unsynchronized clocks (RED47254)

text: When REC clusters are deployed on clusters with unsynchronized clocks, the cluster does not start correctly. The fix is to use NTP to synchronize the underlying K8s nodes.

title: Errors in operator log for REDB status (RED44919)

role: errors

text: Benign errors are reported in the operator log when using database controller (REDB) (e.g., "failed to update database status". These errors can be ignored.

title: Compatibility Notes

role: compatibility

text:
* Support for **OpenShift 4.5** was **added**,
* Support for **Kubernetes 1.18** was **added**,
* Support for the previous deprecated **Kubernetes 1.11 and 1.12** has been **removed**.


title: Redis Enterprise for Kubernetes Release Notes 6.0.8-20 (December 2020)

summary: Support for RS 6.0.8, consumer namespaces, Gesher admission controller proxy, and custom resource validation via schema.

title: Overview

text: The Redis Enterprise K8s 6.0.8-20 release is a *major release* on top of [6.0.8-1](https://github.com/RedisLabs/redis-enterprise-k8s-docs/releases/tag/v6.0.8-1) providing support for the [Redis Enterprise Software release 6.0.8-30](https://docs.redislabs.com/latest/rs/release-notes/rs-6-0-8-september-2020/) and includes several enhancements and bug fixes.

title: Overview

text:
This release of the operator provides:

 * New features
 * Various bug fixes

To upgrade your deployment to this latest release, see ["Upgrade a Redis Enterprise cluster (REC) on Kubernetes"]().

title: Images

text:
This release includes the following container images:
 * **Redis Enterprise**: redislabs/redis:6.0.8-30 or redislabs/redis:6.0.8-30.rhel7-openshift
 * **Operator and Bootstrapper**: redislabs/operator:6.0.8-20
 * **Services Rigger**: redislabs/k8s-controller:6.0.8-20 or redislabs/services-manager:6.0.8-20 (Red Hat registry)

title: New features

text:
* You can now create database custom resources (REDB CRs) in consumer namespaces that are separate from the operator and cluster namespace. You configured the operator deployment to watch specific namespaces for these REDB CRs.
 * The Gesher admission control proxy is now certified by Red Hat.
 * REDB CRs no longer require a Redis Enterprise cluster name. The name will default to the cluster in the context of the operator.
 * REC and REDB CRs are now validated via a schema.

title: Important fixes

text:
* The database controller (REDB) no longer generates the following error message:  "failed to update database status"
 * Issues with configuring replica-of through the database controller (REDB) and TLS have been fixed. (RED48285)
 * A timeout issue with `rlutil upgrade` was fixed. (RED48700)

title: Known limitations

text: When a pod's status is `CrashLoopBackOff` and we run the cluster recovery, the process will not complete. The workaround is to delete the crashing pods manually. The recovery process will then continue.

text: A cluster name longer than 20 characters will result in a rejected route configuration because the host part of the domain name will exceed 63 characters. The workaround is to limit cluster name to 20 characters or fewer.

text: When a cluster is in an unreachable state, the state is still `running` instead of being reported as an error.

text: STS Readiness probe does not mark a node as "not ready" when running `rladmin status` on the node fails.

title: Role missing on replica sets (RED39002)

text: The `redis-enterprise-operator` role is missing permission on replica sets.

text: Openshift 3.11 does not support DockerHub private registries. This is a known OpenShift issue.

title: Clusters must be named "rec" in OLM-based deployments (RED39825)

text: In OLM-deployed operators, the deployment of the cluster will fail if the name is not "rec". When the operator is deployed via the OLM, the security context constraints (scc) is bound to a specific service account name (i.e., "rec"). The workaround is to name the cluster "rec".

title: Master pod label in Rancher (RED42896)

text: The master pod is not always labeled in Rancher.

title: REC clusters fail to start on Kubernetes clusters with unsynchronized clocks (RED47254)

text: When REC clusters are deployed on Kubernetes clusters with unsynchronized clocks, the REC cluster does not start correctly. The fix is to use NTP to synchronize the underlying K8s nodes.


title: Add client certificates

summary: Add client certificates to your REDB custom resource.

title: Overview

text: For each client certificate you want to use with your database, you need to create a Kubernetes secret to hold it. You can then reference that secret in your Redis Enterprise database (REDB) custom resource spec.

title: Create a secret to hold the new certificate

text:
1. [Create the secret config file](https://kubernetes.io/docs/tasks/configmap-secret/managing-secret-using-config-file/) with the required fields shown below.

    [code example]

1. Apply the file to create the secret resource.

    [code example]

title: Edit the REDB resource

text:
1. Add the secret name to the REDB custom resource (`redb.yaml`) with the `clientAuthenticationCertificates` property in the `spec` section.

  [code example]

code:
apiVersion: v1
    kind: Secret
    type: Opaque
    metadata:
      name: <client-cert-secret>
      namespace: <your-rec-namespace>
    data:
      cert: <client-certificate>

code: kubectl apply -f <client-cert-secret>.yaml

code:
spec:
      clientAuthenticationCertificates:
      - <client-cert-secret>

section_id: edit-the-redb-resource


title: Allow automatic resource adjustment

summary: Enable automatic system resource adjustments for Redis Enterprise to increase file descriptor limits.

title: Overview

text: Redis Enterprise for Kubernetes 7.22.0-6 introduces the ability to run with automatic resource adjustment disabled, which drops all capabilities from the Redis Enterprise container and sets `allowPrivilegeEscalation` to `false`. All other security-related settings remain the same as in automatic resource adjustment enabled. Automatic resource adjustment disabled is the default for installations and upgrades of the Redis Enterprise operator for versions 7.22.0-6 and later.

title: Default behavior

text:
Automatic resource adjustment is disabled by default for installations and upgrades of the Redis Enterprise operator for versions 7.22.0-6 and later. This default behavior is in effect if REC spec has `allowAutoAdjustment` set to `false` or removed.

If automatic resource adjustment is disabled, the REC security context looks like this:

[code example]

title: Enable automatic resource adjustment

text:
To allow the Redis Enterprise container to adjust system resource limits automatically, set `allowAutoAdjustment` to `true`. This will grant the container elevated capabilities such as `SYS_RESOURCE`. Note that changing this value on a running cluster will trigger a rolling update.

[code example]

Enabling automatic resource adjustment results in the following security context:

**Note:** Enabling `allowAutoAdjustment` grants the container the `SYS_RESOURCE` capability and permits privilege escalation.

[code example]

title: OpenShift upgrades

text:
If you're upgrading OpenShift to 7.22.0-6, update your existing SCC (security context constraint).

If running with automatic resource adjustment disabled, remove the custom `redis-enterprise-scc-v2` SCC and unbind it from the REC service account after you complete the upgrade.

[code example]

[code example]

If running with automatic resource adjustment enabled, manually reapply the [security context constraints (SCC)](https://docs.openshift.com/container-platform/4.8/authentication/managing-security-context-constraints.html) file ([`scc.yaml`]()).

[code example]

[code example]

title: New OpenShift installations

text:
New installations of Redis Enterprise for Kubernetes 7.22.0-6 and later automatically run with automatic resource adjustment disabled, using a built-in `nonroot-v2` which is more secure and less permissive.

To enable automatic resource adjustment after installation, apply and grant permissions to the `redis-enterprise-scc-v2` SCC.

1. Apply the `scc.yaml` file.

Do not edit this file.

    [code example]

    You should see the following output:

    [code example]

1. Provide the operator permissions for the pods.

    [code example]

title: SYS_RESOURCE

text:
Some Redis Enterprise processes may require the `SYS_RESOURCE` capability to raise resource limits, such as the maximum number of open file descriptors.

Some Redis Enterprise processes require the ability to open at least 100,000 file descriptors. If the default is lower and `SYS_RESOURCE` is not enabled, these processes may fail.

title: Choose whether to enable automatic resource adjustment

text:
Use the following guidance to decide whether to enable automatic resource adjustment:

- If you're running on a major cloud provider such as AWS, GKE, or AKS, automatic resource adjustment disabled is likely sufficient.
- If you're running on-prem or using Kubespray, verify your file descriptor limits. You can:
  - Configure limits manually and use automatic resource adjustment disabled.
  - Enable automatic resource adjustment to allow Redis Enterprise to increase limits, which requires privilege escalation.

If you are already running a Redis Enterprise cluster on Kubernetes, your worker nodes are likely configured correctly. In this case, it is safe to upgrade the operator and use automatic resource adjustment disabled.

Based on our testing, all major cloud providers configure Kubernetes worker nodes with file descriptor limits well above the required minimum. These environments typically work without enabling automatic resource adjustment. The only known exception is clusters created with [Kubespray](https://kubespray.io/#/), which sets default file descriptor limits below the required 100,000. If you use Kubespray with default settings, you must run the operator with automatic resource adjustment enabled.

code:
securityContext:
  allowPrivilegeEscalation: false
  capabilities:
    drop:
    - ALL
  privileged: false
  readOnlyRootFilesystem: false

section_id: default-behavior

code:
spec:
  securityContext:
    resourceLimits:
      allowAutoAdjustment: true

section_id: enable-automatic-resource-adjustment

code:
securityContext:
  allowPrivilegeEscalation: true
  capabilities:
    add:
    - SYS_RESOURCE
    drop:
    - ALL
  privileged: false
  readOnlyRootFilesystem: false

code: oc delete scc/redis-enterprise-scc-v2

section_id: openshift-upgrades

code: oc adm policy remove-scc-from-user redis-enterprise-scc-v2 -z <service-account-name>

code: oc apply -f openshift/scc.yaml

code:
oc adm policy add-scc-to-user redis-enterprise-scc-v2 \
  system:serviceaccount:<my-project>:<rec-name>

section_id: new-openshift-installations

code:
oc adm policy add-scc-to-user redis-enterprise-scc-v2 \
      system:serviceaccount:<my-project>:<rec>


title: Store configuration in Kubernetes Secrets

summary: Store Redis Enterprise configuration items in Kubernetes Secrets for automatic updates and secure management.

title: Overview

text: You can store Redis Enterprise configuration items in Kubernetes Secrets for automatic updates and secure management. When you update these Secrets, the operator immediately reads the changes and propagates them to the Redis Enterprise Cluster (REC).

title: License configuration

text: Redis Enterprise clusters require a valid license. You can apply licenses using Kubernetes Secrets (recommended) or embed them directly in the cluster specification.

title: Determine your cluster FQDN

text:
To configure licensing, you need your Redis Enterprise cluster's fully qualified domain name (FQDN). Use this format: `<REC-name>.<namespace>.svc.cluster.local`

For example: `my-rec.my-ns.svc.cluster.local`

title: Use a Kubernetes Secret (recommended)

text:
1. Create a secret from your license file:

    [code example]

2. Add the secret reference to your REC specification:

    [code example]

title: Embed license directly in REC specification

text:
Alternatively, you can embed the license directly in the REC YAML:

[code example]

You must include the pipe symbol (`|`) after `license:` and maintain proper indentation.

title: Cluster credential configuration

text: Redis Enterprise clusters require admin credentials for the operator to manage the cluster. You can configure these credentials using Kubernetes Secrets.

title: Default behavior

text: By default, the operator automatically creates a secret with a random username and auto-generated password during cluster creation. The secret name defaults to the cluster name.

title: Customize the credential secret

text:
You can customize the credential secret name during cluster creation using the `clusterCredentialSecretName` field in your REC specification. The secret must contain `username` and `password` fields.

The `clusterCredentialSecretName` field cannot be changed after cluster creation.

For detailed instructions, see [Customize the credential secret name]().

title: TLS certificate configuration

text: You can store TLS certificates in Kubernetes Secrets to secure communication between clients and Redis Enterprise databases.

title: Client certificates for mTLS

text:
1. Create a secret with your client certificate:

    [code example]

2. Add the secret to your REDB using the `clientAuthenticationCertificates` property. See [Add client certificates]() for details.

title: Service certificates

text:
To configure certificates for proxy, API, or other services, create secrets with certificate and key files:

[code example]

title: Internode encryption certificates

text:
You can provide custom certificates for control plane and data plane internode encryption. Create separate secrets for each encryption type:

[code example]

[code example]

Reference these secrets in your REC specification under `spec.certificates`. See [Internode encryption]() for complete configuration details.

title: Best practices

text:
- Store sensitive configuration in Secrets rather than directly in YAML files.
- Use `--from-file` to avoid manual base64 encoding.
- Create secrets in the same namespace as your REC or REDB resources.
- Use descriptive secret names for easy identification.
- Regularly rotate certificates and update secrets.

title: See also

role: related

text:
- [Manage REC credentials]()
- [Manage REC certificates]()
- [Add client certificates]()
- [Redis Enterprise Cluster API reference]()

code: kubectl -n <namespace> create secret generic rec-license --from-file=license=./license.txt

section_id: use-a-kubernetes-secret-recommended

code:
spec:
      licenseSecretName: rec-license

code:
spec:
  nodes: 3
  license: |
    ----- LICENSE START -----
    eai14c/y6XNVykffDQSPUsHKcmpgOFUlmyTBDUEZEz+GLbXAgQFOmxcdbR9J
    ...remaining license key content...
    ----- LICENSE END -----

code: kubectl -n <namespace> create secret generic client-cert-secret --from-file=cert=<path-to-cert>

section_id: client-certificates-for-mtls

code:
kubectl create secret generic <secret-name> \
  --from-file=certificate=</PATH/TO/certificate.pem> \
  --from-file=key=</PATH/TO/key.pem> \
  --from-literal=name=<proxy | api | cm | syncer | metrics_exporter>

section_id: service-certificates

code:
kubectl create secret generic cp-internode-cert \
  --from-file=certificate=</path/to/cp-certificate.pem> \
  --from-file=key=</path/to/cp-key.pem> \
  --from-literal=name=cp_internode_encryption

section_id: internode-encryption-certificates

code:
kubectl create secret generic dp-internode-cert \
  --from-file=certificate=</path/to/dp-certificate.pem> \
  --from-file=key=</path/to/dp-key.pem> \
  --from-literal=name=dp_internode_encryption


title: Security

summary: Configure security settings for Redis Enterprise clusters and databases on Kubernetes.

title: Manage Redis Enterprise cluster (REC) credentials

summary: Enable SAML-based SSO authentication for Redis Enterprise for Kubernetes.

title: Enable SSO authentication

summary: Install your own certificates to be used by the Redis Enterprise cluster's operator.

title: Manage Redis Enterprise cluster (REC) certificates

title: Add client certificates

summary: Enable LDAP authentication for Redis Enterprise for Kubernetes.

title: Enable LDAP authentication

summary: Configure HashiCorp Vault as the centralized secret management system for Redis Enterprise for Kubernetes.

title: Integrate HashiCorp Vault with Redis Enterprise for Kubernetes

title: Allow automatic resource adjustment

summary: Enable encryption for communication between REC nodes and configure custom certificates.

title: Enable internode encryption

title: Overview

text: Configure security settings for your Redis Enterprise deployment on Kubernetes. Redis Enterprise for Kubernetes provides comprehensive security features including TLS encryption, authentication, access control, and certificate management.

title: Credentials and authentication

text:
Manage cluster credentials and authentication settings:

- [Manage REC credentials]() - Configure and manage Redis Enterprise cluster credentials
- [Configuration secrets]() - Store Redis Enterprise configuration items in Kubernetes Secrets for automatic updates and secure management
- [LDAP authentication]() - Integrate with LDAP for centralized authentication
- [SSO authentication]() - Enable SAML-based single sign-on for Cluster Manager UI access

title: Certificates and encryption

text:
Configure TLS certificates and encryption for secure communications:

- [Manage REC certificates]() - Configure cluster certificates for TLS encryption
- [Add client certificates]() - Set up client certificate authentication for databases
- [Internode encryption]() - Enable encryption between cluster nodes and configure custom certificates

title: Secret management

text:
Configure external secret management systems:

- [HashiCorp Vault integration]() - Configure HashiCorp Vault as the centralized secret management system for Redis Enterprise for Kubernetes

title: Resource management

text:
Configure security-related resource settings:

- [Allow resource adjustment]() - Enable automatic adjustment of system resources for security compliance


title: Enable internode encryption

title: Overview

text: Internode encryption provides added security by encrypting communication between nodes in your Redis Enterprise cluster (REC).

title: Enable internode encryption

text:
Enable internode encryption in the `spec` section of your REC custom resource file.

[code example]

This change will apply to all databases created in the REC. You can override the cluster-wide setting for individual databases.

Edit your Redis Enterprise database (REDB) custom resource file to disable internode encryption for only that database.

[code example]

To learn more about internode encryption, see [Internode encryption for Redis Enterprise Software]().

title: Use custom certificates for internode encryption

text: By default, Redis Enterprise uses self-signed certificates for internode encryption. You can provide your own certificates for both control plane and data plane internode encryption by storing them in Kubernetes secrets and referencing them in your REC specification.

title: Prerequisites

text:
- Certificates must be in PEM format
- You must create the Kubernetes secrets before referencing them in the REC spec
- Certificates should include the full certificate chain if using a certificate authority

title: Create secrets for internode encryption certificates

text:
Create Kubernetes secrets to store your internode encryption certificates. You need separate secrets for control plane and data plane encryption.

1. Create a secret for control plane internode encryption:

    [code example]

2. Create a secret for data plane internode encryption:

    [code example]

title: Configure certificates in REC spec

role: configuration

text:
Add the certificate secret names to the `certificates` section of your REC specification:

[code example]

You can configure one or both certificate types. If you don't specify a certificate secret name, the cluster uses a self-signed certificate for that encryption type.

Apply the updated REC specification:

[code example]

title: Certificate rotation

text:
You can rotate internode encryption certificates using either of these methods:

#### Method 1: Update the existing secret

Edit the certificate data in the existing Kubernetes secret. The operator automatically detects the change and applies the new certificate.

[code example]

#### Method 2: Create a new secret and update the REC spec

1. Create a new secret with the updated certificate:

    [code example]

2. Update the REC specification to reference the new secret:

    [code example]

3. Apply the updated REC specification:

    [code example]

title: Certificate lifecycle

text: When you remove a certificate secret reference from the REC specification, the operator does not delete the certificate from the Redis Enterprise cluster. The cluster continues to use the previously configured certificate until you explicitly replace it or the cluster reverts to using a self-signed certificate.

title: More info

text:
- [Manage REC certificates]() - General certificate management for Redis Enterprise clusters
- [Configuration secrets]() - Best practices for storing configuration in Kubernetes secrets
- [Internode encryption for Redis Enterprise Software]() - Detailed information about how internode encryption works

code:
spec:
    dataInternodeEncryption: true

section_id: enable-internode-encryption

code:
spec:
    dataInternodeEncryption: false

code:
kubectl create secret generic cp-internode-cert \
      --from-file=certificate=</path/to/cp-certificate.pem> \
      --from-file=key=</path/to/cp-key.pem> \
      --from-literal=name=cp_internode_encryption

code:
kubectl create secret generic dp-internode-cert \
      --from-file=certificate=</path/to/dp-certificate.pem> \
      --from-file=key=</path/to/dp-key.pem> \
      --from-literal=name=dp_internode_encryption

code:
spec:
  dataInternodeEncryption: true
  certificates:
    cpInternodeEncryptionCertificateSecretName: cp-internode-cert
    dpInternodeEncryptionCertificateSecretName: dp-internode-cert

section_id: configure-certificates-in-rec-spec

code: kubectl apply -f <rec-file>.yaml

code:
kubectl create secret generic cp-internode-cert \
  --from-file=certificate=</path/to/new-cp-certificate.pem> \
  --from-file=key=</path/to/new-cp-key.pem> \
  --from-literal=name=cp_internode_encryption \
  --dry-run=client -o yaml | kubectl apply -f -

section_id: certificate-rotation

code:
kubectl create secret generic cp-internode-cert-new \
      --from-file=certificate=</path/to/new-cp-certificate.pem> \
      --from-file=key=</path/to/new-cp-key.pem> \
      --from-literal=name=cp_internode_encryption

code:
spec:
      certificates:
        cpInternodeEncryptionCertificateSecretName: cp-internode-cert-new


title: Enable LDAP authentication

title: LDAP support for Redis Enterprise Software

text:
Redis Enterprise Software supports LDAP authentication and authorization through [role-based access controls]() (RBAC). You can map LDAP groups to [Redis Enterprise roles]() to control access to your database and the Cluster Manager UI. For more details on how LDAP works with Redis Enterprise, see [LDAP authentication]().

Redis Enterprise for Kubernetes supports enabling and configuring LDAP authentication using the `RedisEnterpriseCluster` (REC) custom resource. Currently, the Redis Enterprise cluster (REC) only supports configuration related to the LDAP server, such as server addresses, connection details, credentials, and query configuration.

To [map LDAP groups to Redis Enterprise access control roles](), you'll need to use the Redis Enterprise [API]() or [admin console]().

title: Enable LDAP

text:
To enable LDAP for your REC, use the `.spec.ldap` field in the `RedisEnterpriseCluster` custom resource.

The following `RedisEnterpriseCluster` example resource enables a basic LDAP configuration:

[code example]

Refer to the `RedisEnterpriseCluster` [API reference](https://github.com/RedisLabs/redis-enterprise-k8s-docs/blob/master/redis_enterprise_cluster_api.md#ldapspec) for full details on the available fields.

title: Bind credentials

text:
For LDAP servers that require authentication for client queries, store the bind credentials in a secret and reference them in the `RedisEnterpriseCluster` custom resource.

1. Create a secret to store the bind credentials.

    [code example]
    The secret must:
    - Reside within the same namespace as the `RedisEnterpriseCluster` custom resource.
    - Include a `dn` key with the distinguished name for the user performing the query (such as `cn=admin,dc=example,dc=org`).
    - Include a `password` key with the bind password.

    Replace the `<placeholders>` in the command above with your own values.

1. Reference the secret name in the `.spec.ldap.bindCredentialsSecretName` field of the `RedisEnterpriseCluster` custom resource.

    [code example]

title: LDAPS or STARTTLS protocols

text:
In addition to plain LDAP protocol, Redis Enterprise Software also supports LDAPS and STARTTLS protocols for secure communication with the LDAP server.

To enable one of these protocols, edit the `spec.ldap.protocol` field in the `RedisEnterpriseCluster` custom resource:

#### Enable `LDAPS`

  [code example]

  Default port: 636

#### Enable `STARTTLS`

  [code example]

  Default port: 389

title: CA certificate

text:
To use a custom CA certificate for validating the LDAP server certificate, store the CA certificate in a secret and reference the secret in the `RedisEnterpriseCluster` custom resource.

1. Create a secret to hold the CA certificate.

    [code example]

    The secret must:
    - Reside within the same namespace as the `RedisEnterpriseCluster` custom resource.
    - Include a `cert` key with a PEM-encoded CA certificate (such as `cacert.pem`).

    Replace the `<placeholders>` in the command above with your own values.

1. Reference the secret name in the `spec.ldap.caCertificateSecretName` field of the `RedisEnterpriseCluster` custom resource.

    [code example]

title: Client certificates

text:
To use an LDAP client certificate, store the certificate in a secret and reference the secret in the `RedisEnterpriseCluster` custom resource.

1. Create a secret to hold the client certificate.

    [code example]

    The secret must:
    - Reside within the same namespace as the `RedisEnterpriseCluster` custom resource.
    - Include a `name` key explicitly set to `ldap_client`.
    - Include a `certificate` key for the public key (such as `cert.pem`).
    - Include a `key` key for the private key (such as `key.pem`).

    Replace the `<placeholders>` in the command above with your own values.

1. Reference the secret name in the `.spec.certificates.ldapClientCertificateSecretName` field of the `RedisEnterpriseCluster` custom resource, substituting your own values for `<placeholders>`.

    [code example]

title: Known limitations

text:
Redis Enterprise Software can't resolve DNS names with a `.local` suffix.
  If your LDAP server is in the same Kubernetes cluster and exposed via a Service object, *avoid* addresses such as `openldap.openldap.svc.cluster.local`. Instead, *use short-form addresses* such as `openldap.openldap.svc`.

title: Next steps

text:
To [map LDAP groups to Redis Enterprise access control roles](), you'll need to use the Redis Enterprise [API]() or [admin console]().

For more details on how LDAP works with Redis Enterprise, see [LDAP authentication]().

code:
apiVersion: app.redislabs.com/v1
kind: RedisEnterpriseCluster
metadata:
  name: rec
spec:
  nodes: 3
  ldap:
    protocol: LDAP
    servers:
    - host: openldap.openldap.svc
      port: 389
    bindCredentialsSecretName: ldap-bind-credentials
    cacheTTLSeconds: 600
    enabledForControlPlane: true
    enabledForDataPlane: true
    authenticationQuery:
      template: cn=%u,ou=default,dc=example,dc=org
    authorizationQuery:
      attribute: memberOf

section_id: enable-ldap

code:
kubectl -n <rec-namespace> create secret generic <bind-secret-name> \
        --from-literal=dn='<disinguished-name>' \
        --from-literal=password=<password>

section_id: bind-credentials

code:
spec:
      ldap:
        bindCredentialsSecretName: <bind-secret-name>

code:
spec:
        ldap:
          protocol: LDAPS

section_id: ldaps-or-starttls-protocols

code:
spec:
        ldap:
          protocol: STARTTLS

code:
kubectl -n <rec-namespace> create secret generic <ca-secret-name> \
        --from-file=cert=<ca-cert>.pem

section_id: ca-certificate

code:
spec:
      ldap:
        caCertificateSecretName: <ca-secret-name>

code:
kubectl -n <rec-namespace> create secret generic <client-secret-name> \
      --from-literal=name=ldap_client \
      --from-file=certificate=<client-cert-file> \
      --from-file=key=<private-key-file>

section_id: client-certificates

code:
spec:
      certificates:
        ldapClientCertificateSecretName: <client-secret-name>


title: Overview

text:
By default, Redis Enterprise Software for Kubernetes generates TLS certificates for the cluster during creation. These self-signed certificates are generated on the first node of each Redis Enterprise cluster (REC) and are copied to all other nodes added to the cluster. For the list of of certificates used by Redis Enterprise Software and the traffic they encrypt, see the [certificates table]().

To install and use your own certificates with Kubernetes on your Redis Enterprise cluster, they need to be stored in [secrets](https://kubernetes.io/docs/concepts/configuration/secret/). The REC custom resource also needs to be configured with those secret names to read and use the certificates.

text:
Create the [secret](https://kubernetes.io/docs/tasks/configmap-secret/managing-secret-using-kubectl/) with the required fields shown below.

  [code example]

For internode encryption certificates, see [Internode encryption]() for detailed configuration instructions.

title: Update certificates in the REC custom resource

text:
Edit the Redis Enterprise cluster (REC) custom resource to add a `certificates` subsection under the `spec` section. You are only required to add the fields for the certificates you are installing.

[code example]

title: Update certificates through the API

text:
Alternatively, you can also update the REC certificates via the API:

[code example]

title: Verify the certificate was updated

text:
Check the operator logs and use the API to verify the certificate has been updated.

  [code example]

title: More info

text:
- [Update certificates]()
- [Install your own certificates]()
- [Glossary/Transport Layer Security (TLS)]()

code:
kubectl create secret generic <secret-name> \
    --from-file=certificate=</PATH/TO/certificate.pem> \
    --from-file=key=</PATH/TO/key.pem> \
    --from-literal=name=<proxy | api | cm | syncer | metrics_exporter | cp_internode_encryption | dp_internode_encryption>

code:
spec:
  certificates:
    apiCertificateSecretName: <apicert-secret-name>
    cmCertificateSecretName: <cmcert-secret-name>
    syncerCertificateSecretName: <syncercert-secret-name>
    metricsExporterCertificateSecretName: <metricscert-secret-name>
    proxyCertificateSecretName: <proxycert-secret-name>
    cpInternodeEncryptionCertificateSecretName: <cpine-secret-name>
    dpInternodeEncryptionCertificateSecretName: <dpine-secret-name>

code:
PUT /v1/cluster/update_cert
{
   "certificate": <certificate>,
   "key": <cert-key>,
   "name": <cert-name>
}

section_id: update-certificates-through-the-api

code: GET /v1/cluster/certificates

section_id: verify-the-certificate-was-updated


title: Overview

text:
Redis Enterprise for Kubernetes uses a custom resource called [`RedisEnterpriseCluster`]() to create a Redis Enterprise cluster (REC). During creation, it generates random credentials for the operator to use. The credentials are saved in a Kubernetes (K8s) [secret](https://kubernetes.io/docs/concepts/configuration/secret/). The secret name defaults to the cluster name and is specified by the `clusterCredentialSecretName` field in the REC specification.

This procedure is only supported for operator versions 6.0.20-12 and above.

title: Retrieve the current username and password

text:
The credentials can be used to access the Redis Enterprise admin console or the API. Connectivity must be configured to the REC [pods](https://kubernetes.io/docs/concepts/workloads/pods/) using an appropriate service (or port forwarding).

1. Inspect the random username and password created by the operator during creation with the `kubectl get secret` command.

    [code example]

    The command outputs the encoded password and username, similar to the example below.

      [code example]

1. Decode the password and username with the `echo` command and the password from the previous step.

    [code example]

    This outputs the password and username in plain text. In this example, the plain text password is `12345678` and the username is `demo@example.com`.

title: Change the Redis Enterprise cluster (REC) credentials

title: Change the REC password for the current username

text:
1. Access a [pod](https://kubernetes.io/docs/concepts/workloads/pods/) running a Redis Enterprise cluster.

[code example]

2. Add a new password for the existing user.

[code example]

3. From outside the pod, update the REC credential secret.

[code example]

4. Wait five minutes for all the components to read the new password from the updated secret. If you proceed to the next step too soon, the account could get locked.

5. Access a pod running a Redis Enterprise cluster again.

[code example]

6. Remove the previous password to ensure only the new one applies.

[code example]

 The username for the K8s secret is the email displayed on the Redis Enterprise admin console.

title: Change both the REC username and password

text:
1. [Connect to the admin console]()

2. [Add another admin user]() and choose a new password.

3. Specify the new username in the `username` field of your REC custom resource spec.

4. Update the REC credential secret:

[code example]

5. Wait five minutes for all the components to read the new password from the updated secret. If you proceed to the next step too soon, the account could get locked.

6. Delete the previous admin user from the cluster.

The operator may log errors in the time between updating the username in the REC spec and the secret update.

title: Update the credentials secret in Vault

text:
If you store your secrets with Hashicorp Vault, update the secret for the REC credentials with the following key-value pairs:

[code example]

For more information about Vault integration with the Redis Enterprise Cluster see [Integrating Redis Enterprise for Kubernetes with Hashicorp Vault](https://github.com/RedisLabs/redis-enterprise-k8s-docs/blob/master/vault/README.md).

code: kubectl get secret rec -o jsonpath='{.data}'

code: echo MTIzNDU2NzgK | base64 --decode

code: kubectl exec -it <rec-resource-name>-0 -c redis-enterprise-node -- /bin/bash

code:
REC_USER="`cat /opt/redislabs/credentials/username`" \
REC_PASSWORD="`cat /opt/redislabs/credentials/password`" \
curl -k --request POST \
  --url https://localhost:9443/v1/users/password \
  -u "$REC_USER:$REC_PASSWORD" \
  --header 'Content-Type: application/json' \
  --data "{\"username\":\"$REC_USER\", \
  \"old_password\":\"$REC_PASSWORD\", \
  \"new_password\":\"<NEW PASSWORD>\"}"

code:
kubectl create secret generic <cluster_secret_name> \
  --save-config \
  --dry-run=client \
  --from-literal=username=<current-username> \
  --from-literal=password=<new-password> \
  -o yaml | \
kubectl apply -f -

code:
REC_USER="`cat /opt/redislabs/credentials/username`"; \
REC_PASSWORD="`cat /opt/redislabs/credentials/password`"; \
curl -k --request DELETE \
  --url https://localhost:9443/v1/users/password \
  -u "$REC_USER:$REC_PASSWORD" \
  --header 'Content-Type: application/json' \
  --data "{\"username\":\"$REC_USER\", \
  \"old_password\":\"<OLD PASSWORD\"}"

code:
kubectl create secret generic <cluster_secret_name> \
  --save-config \
  --dry-run=client \
  --from-literal=username=<new-username> \
  --from-literal=password=<new-password> \
  -o yaml | \
kubectl apply -f -

section_id: update-the-credentials-secret-in-vault


title: Enable SSO authentication

title: Overview

text: Redis Enterprise Software supports SAML 2.0 single sign-on (SSO) for the Cluster Manager UI with both IdP-initiated and SP-initiated authentication. User accounts are automatically created on first sign-in using just-in-time (JIT) provisioning.

title: IdP requirements

text:
Your identity provider must support:

- SAML 2.0 protocol
- Signed SAML responses
- HTTP-Redirect binding for SP-initiated SSO
- HTTP-POST binding for SAML assertions

title: Enable SSO

text: To enable SSO for your Redis Enterprise cluster (REC), follow these steps to configure SAML authentication.

title: Prerequisites

text:
Before enabling SSO, ensure you have:

1. An existing Redis Enterprise cluster (REC) deployed in Kubernetes

2. **External access to the Cluster Manager UI** - The Cluster Manager UI must be accessible externally via a LoadBalancer service or Ingress so users can access it from their browser and the identity provider can redirect back after authentication. See [Connect to the admin console]() for configuration options.

3. A SAML 2.0-compatible identity provider (such as Okta, Azure AD, or similar)

4. Admin access to your identity provider

5. A TLS certificate and private key for the service provider (SP)

SSO requires external access to the Cluster Manager UI. Port forwarding is not sufficient for SSO authentication because the identity provider needs to redirect users back to the UI after authentication. You must configure either a LoadBalancer service (via `spec.uiServiceType: LoadBalancer`) or an Ingress controller.

title: Step 1: Upload Service Provider certificate and private key

text:
The Service Provider certificate is used by the cluster to sign SAML requests and encrypt SAML responses.

1. Create a secret with your service provider certificate and private key:

    [code example]

    The secret must:
    - Reside within the same namespace as the `RedisEnterpriseCluster` custom resource.
    - Include a `name` key explicitly set to `sso_service`.
    - Include a `certificate` key with the public certificate in PEM format.
    - Include a `key` key with the private key in PEM format.

    Replace the `<placeholders>` in the command above with your own values.

2. Configure the service provider certificate in the `RedisEnterpriseCluster` custom resource:

    [code example]

3. Apply the configuration:

    [code example]

#### Configure Service Provider base address (optional)

The base address is used to construct service provider URLs, such as the Assertion Consumer Service (ACS) URL and Single Logout (SLO) URL.

If not specified, the base address is automatically determined from the REC Cluster Manager UI service:
- If the UI service type is `LoadBalancer` (configured via `spec.uiServiceType`), the load balancer address is used.
- Otherwise, the cluster-internal DNS name is used (for example, `rec-ui.svc.cluster.local`).
- The port defaults to 8443 if not specified.

To explicitly set the base address, add it to the `serviceProvider` section:

[code example]

Format: `[<scheme>://]<hostname>[:<port>]`

Examples:
- `"https://redis-ui.example.com:443"` (recommended - explicit scheme)
- `"redis-ui.example.com:443"` (defaults to https://)
- `"http://redis-ui.example.com:9443"` (NOT recommended for production)

Using `http://` is NOT recommended for production environments as it transmits sensitive SAML assertions in plaintext. Only use `http://` for testing or development purposes.

**Usage guidelines:**
- **For LoadBalancer services:** Leave this field blank to use the default REC UI service, or set it explicitly to the LoadBalancer address for custom services.
- **For Ingress:** Set this to the ingress hostname and port (typically 443), for example, `"https://redis-ui.example.com:443"`.

title: Step 2: Download Service Provider metadata

text:
After applying the configuration, retrieve the service provider metadata to use when configuring your identity provider.

#### Option A: Retrieve from Kubernetes secret

If you configured `spMetadataSecretName` in Step 1, the operator creates a secret with the SP metadata:

[code example]

This secret is only created when the cluster is configured to use Kubernetes secrets (`spec.clusterCredentialSecretType` is unset or set to `"kubernetes"`). When using Vault secrets, use Option B instead.

#### Option B: Retrieve from the API

You can obtain the SP metadata directly from the Redis Enterprise Server API:

[code example]

Replace `<rec-pod-name>`, `<username>`, and `<password>` with your cluster details.

title: Step 3: Set up SAML app in your identity provider

text:
Use the Service Provider metadata from Step 2 to configure a SAML application in your identity provider.

1. Sign in to your identity provider's admin console (for example, Okta, Azure AD, Google Workspace).

2. Create a new SAML 2.0 application or integration.

3. Upload the `sp-metadata.xml` file or manually configure the SAML settings using values from the metadata:
   - **Entity ID (SP)**: Found in the `entityID` attribute of the metadata
   - **Assertion Consumer Service (ACS) URL**: Found in the `AssertionConsumerService` element's `Location` attribute
   - **Single Logout (SLO) URL**: Found in the `SingleLogoutService` element's `Location` attribute (if present)

4. Configure the SAML assertion to include the following attributes:
   - `email` - User's email address (required)
   - `firstName` - User's first name (optional)
   - `lastName` - User's last name (optional)
   - `redisRoleMapping` - Role mapping for JIT user provisioning (required for new users)

Refer to your identity provider's documentation for specific configuration steps.

title: Step 4: Download identity provider metadata

text:
After configuring the SAML app in your identity provider, download the identity provider metadata and certificate.

1. In your identity provider's admin console, locate the SAML app you created in Step 3.

2. Download the following:
   - **IdP metadata XML**: Contains the IdP configuration (entity ID, SSO URL, SLO URL)
   - **IdP certificate**: Public certificate used to verify SAML assertions

Save these files for use in Step 5.

title: Step 5: Configure SAML identity provider in Redis Enterprise

text:
Now configure the identity provider details in your Redis Enterprise cluster.

1. Create a secret with the Identity Provider certificate:

    [code example]

    The secret must:
    - Reside within the same namespace as the `RedisEnterpriseCluster` custom resource.
    - Include a `name` key explicitly set to `sso_issuer`.
    - Include a `certificate` key with the IdP public certificate in PEM format.
    - **Not** include a `key` field (only the public certificate is needed).

    Replace `<idp-cert-file>` with the path to your IdP certificate file.

While IdP metadata XML may contain the certificate, Redis Enterprise Server does not use it from there, so the certificate must be provided separately via this secret.

2. Configure the IdP using one of the following options:

#### Option A: Use IdP metadata XML (recommended)

Using IdP metadata XML is the recommended approach as it's less error-prone.

1. Create a secret with the IdP metadata:

    [code example]

    The secret must:
    - Reside within the same namespace as the `RedisEnterpriseCluster` custom resource.
    - Include an `idp_metadata` key with the IdP metadata XML content.
    - The XML can be plain text or base64-encoded; the operator handles encoding as needed.

    Replace `<idp-metadata-file>` with the path to your IdP metadata XML file.

2. Update the `RedisEnterpriseCluster` custom resource to add the IdP configuration:

    [code example]

3. Apply the updated configuration:

    [code example]

#### Option B: Manual issuer configuration

If IdP metadata XML is unavailable, you can manually configure the issuer settings.

1. Update the `RedisEnterpriseCluster` custom resource with the IdP details:

    [code example]

    Replace the values with your identity provider's configuration:

    - `entityID`: Identity Provider entity ID (issuer identifier)
    - `loginURL`: Identity Provider SSO login URL where SAML authentication requests are sent
    - `logoutURL`: Identity Provider single logout URL (optional)

2. Apply the updated configuration:

    [code example]

If both `idpMetadataSecretName` and `issuer` are provided, `idpMetadataSecretName` takes precedence and `issuer` is ignored.

title: Step 6: Assign SAML app to users

text:
In your identity provider's admin console, assign users to the SAML application you created in Step 3.

1. Navigate to the SAML app in your identity provider.

2. Assign existing users or groups to the application.

3. For new users who will use just-in-time (JIT) provisioning, ensure the `redisRoleMapping` attribute is configured with appropriate Redis Enterprise roles.

Refer to your identity provider's documentation for specific steps on assigning users to applications.

title: Step 7: Activate SSO

text:
Finally, activate SSO by enabling it in the `RedisEnterpriseCluster` custom resource.

1. Update the `RedisEnterpriseCluster` custom resource to enable SSO:

    [code example]

2. Apply the configuration:

    [code example]

3. Test SSO by accessing the Cluster Manager UI and clicking **Sign in with SSO**.

title: Complete example

text:
Here's a complete example of a `RedisEnterpriseCluster` resource with SSO enabled:

[code example]

Refer to the `RedisEnterpriseCluster` [API reference](https://github.com/RedisLabs/redis-enterprise-k8s-docs/blob/master/redis_enterprise_cluster_api.md#ssospec) for full details on the available fields.

title: Next steps

text:
After enabling SSO:

1. Configure users in your identity provider with matching email addresses
2. Set up the `redisRoleMapping` attribute in your identity provider to assign appropriate roles for new users
3. Test both IdP-initiated and SP-initiated SSO flows

For more information about Redis Enterprise Software security, see [Access control]().

code:
kubectl -n <rec-namespace> create secret generic sso-service-cert \
      --from-literal=name=sso_service \
      --from-file=certificate=<sp-cert-file> \
      --from-file=key=<sp-key-file>

code:
apiVersion: app.redislabs.com/v1
    kind: RedisEnterpriseCluster
    metadata:
      name: rec
    spec:
      nodes: 3
      certificates:
        ssoServiceCertificateSecretName: sso-service-cert
      sso:
        enabled: false  # SSO not yet active - set to true in Step 7 after completing configuration
        enforceSSO: false  # Optional: set to true to disable local authentication for non-admin users
        saml:
          spMetadataSecretName: sp-metadata  # Optional: store SP metadata in a secret
          serviceProvider:
            baseAddress: "https://redis-ui.example.com:443"  # Optional: customize base address

code: kubectl apply -f <rec-config-file>.yaml

code:
spec:
  sso:
    saml:
      serviceProvider:
        baseAddress: "https://redis-ui.example.com:443"

code: kubectl -n <rec-namespace> get secret sp-metadata -o jsonpath='{.data.sp_metadata}' | base64 -d > sp-metadata.xml

code:
kubectl -n <rec-namespace> exec -it <rec-pod-name> -c redis-enterprise-node -- \
  curl -k -u "<username>:<password>" \
  https://localhost:9443/v1/cluster/sso/saml/metadata/sp > sp-metadata.xml

code:
kubectl -n <rec-namespace> create secret generic sso-issuer-cert \
      --from-literal=name=sso_issuer \
      --from-file=certificate=<idp-cert-file>

code:
kubectl -n <rec-namespace> create secret generic idp-metadata \
      --from-file=idp_metadata=<idp-metadata-file>.xml

code:
spec:
      certificates:
        ssoServiceCertificateSecretName: sso-service-cert
        ssoIssuerCertificateSecretName: sso-issuer-cert
      sso:
        enabled: false  # SSO not yet active - set to true in Step 7 after completing configuration
        enforceSSO: false  # Optional: set to true to disable local authentication for non-admin users
        saml:
          idpMetadataSecretName: idp-metadata
          spMetadataSecretName: sp-metadata
          serviceProvider:
            baseAddress: "https://redis-ui.example.com:443"

code:
spec:
      certificates:
        ssoServiceCertificateSecretName: sso-service-cert
        ssoIssuerCertificateSecretName: sso-issuer-cert
      sso:
        enabled: false  # SSO not yet active - set to true in Step 7 after completing configuration
        enforceSSO: false  # Optional: set to true to disable local authentication for non-admin users
        saml:
          issuer:
            entityID: "urn:sso:example:idp"
            loginURL: "https://idp.example.com/sso/saml"
            logoutURL: "https://idp.example.com/slo/saml"  # optional
          spMetadataSecretName: sp-metadata
          serviceProvider:
            baseAddress: "https://redis-ui.example.com:443"

code:
spec:
      certificates:
        ssoServiceCertificateSecretName: sso-service-cert
        ssoIssuerCertificateSecretName: sso-issuer-cert
      sso:
        enabled: true
        enforceSSO: false  # Set to true to disable local authentication for non-admin users
        saml:
          idpMetadataSecretName: idp-metadata
          spMetadataSecretName: sp-metadata
          serviceProvider:
            baseAddress: "https://redis-ui.example.com:443"

code:
apiVersion: app.redislabs.com/v1
kind: RedisEnterpriseCluster
metadata:
  name: rec
spec:
  nodes: 3
  certificates:
    ssoServiceCertificateSecretName: sso-service-cert
    ssoIssuerCertificateSecretName: sso-issuer-cert
  sso:
    enabled: true
    enforceSSO: false
    saml:
      idpMetadataSecretName: idp-metadata
      spMetadataSecretName: sp-metadata
      serviceProvider:
        baseAddress: "https://redis-ui.example.com:443"

section_id: complete-example


title: Overview

text: You can configure HashiCorp Vault as the centralized secret management system for the Redis Enterprise Kubernetes operator, replacing the default Kubernetes secrets. This integration provides enhanced security, centralized secret management, and advanced features like secret rotation and audit logging.

title: What secrets are managed by Vault?

text:
When Vault integration is enabled, all secrets referenced in Redis Enterprise custom resources are retrieved from Vault instead of Kubernetes secrets, including:

| **Category** | **Secret Type** | **API Field** | **Description** |
|---|---|---|---|
| **Cluster secrets** |  |  |  |
|  | [Cluster credentials]() | [`clusterCredentialSecretName`]() | Authentication credentials for cluster access |
|  | [License]() | [`licenseSecretName`]() | Redis Enterprise license key |
|  | [API certificate]() | [`apiCertificateSecretName`]() | TLS certificate for API server |
|  | [Cluster manager certificate]() | [`cmCertificateSecretName`]() | TLS certificate for cluster manager |
|  | [Metrics exporter certificate]() | [`metricsExporterCertificateSecretName`]() | TLS certificate for metrics exporter |
|  | [Proxy certificate]() | [`proxyCertificateSecretName`]() | TLS certificate for proxy |
|  | [Syncer certificate]() | [`syncerCertificateSecretName`]() | TLS certificate for Active-Active syncer |
|  | [LDAP client certificate]() | [`ldapClientCertificateSecretName`]() | TLS certificate for LDAP client authentication |
|  | [User-defined module credentials]() | [`credentialsSecret`]() | Credentials for downloading user-defined modules from authenticated repositories |
| **Database secrets** |  |  |  |
|  | [Database passwords]() | Various | Passwords for Redis databases |
|  | [Replica source client TLS key]() | [`clientKeySecret`]() | Client TLS key for cross-cluster replication |
|  | [Replica source server certificate]() | [`serverCertSecret`]() | Server certificate for cross-cluster replication |
|  | [S3 backup credentials]() | [`awsSecretName`]() | AWS S3 storage credentials for database backups |
|  | [SFTP backup credentials]() | [`sftpSecretName`]() | SFTP storage credentials for database backups |
|  | [Swift backup credentials]() | [`swiftSecretName`]() | Swift storage credentials for database backups |
|  | [Azure Blob backup credentials]() | [`absSecretName`]() | Azure Blob storage credentials for database backups |
|  | [Google Cloud backup credentials]() | [`gcsSecretName`]() | Google Cloud storage credentials for database backups |
|  | [Client authentication certificates]() | Various | TLS client certificates for authentication |
| **Other secrets** |  |  |  |
|  | [Remote cluster secrets]() | [`secretName`]() | Credentials for Redis Enterprise Remote Cluster (RERC) configurations |
|  | [Active-Active database secrets]() | [`globalConfigurations`]() | All secret names specified in REAADB global configurations |

For complete details on supported secrets, see the [`RedisEnterpriseCluster` API reference]() and [`RedisEnterpriseDatabase` API reference]().

title: Secret path structure

text:
Vault secrets follow a hierarchical path structure:
[code example]

Default example:
[code example]

When using OpenShift, replace `kubectl` commands with `oc` throughout this guide.

title: Prerequisites

text:
Before integrating Redis Enterprise operator with HashiCorp Vault, ensure you have the following components properly configured:

HashiCorp Vault Requirements:

- Vault instance: HashiCorp Vault v1.15.2+ with TLS and network connectivity to your Kubernetes cluster
- Authentication method: Configure Kubernetes authentication method in Vault (see [HashiCorp's Kubernetes Auth documentation](https://developer.hashicorp.com/vault/docs/auth/kubernetes))
- Secret engine: Enable and configure KV version 2 secret engine
  - Default mount path: `secret/` (configurable)
  - Used to store all Redis Enterprise secrets
  - Supports versioning and metadata

Kubernetes Requirements:

- Vault Agent Injector: Deploy the HashiCorp Vault Agent Injector
  - Enables automatic secret injection into pods
  - See [Vault Agent Injector tutorial](https://developer.hashicorp.com/vault/tutorials/kubernetes/kubernetes-sidecar)
- Network access: Ensure Kubernetes cluster can reach Vault
  - Configure appropriate network policies and firewall rules
  - Vault typically runs on port 8200 (HTTPS)
- Service accounts: Proper RBAC configuration for operator service accounts

Vault editions:

This guide supports both Vault Community and Enterprise editions:

- Vault Community: Use all commands without `-namespace` flags or `VAULT_NAMESPACE` parameters
- Vault Enterprise: Supports namespaces for logical isolation and multi-tenancy (separate from Kubernetes namespaces)

Minimum token TTL:

Configure Vault token policies with minimum TTL of 1 hour:
- Prevents frequent token renewal overhead
- Ensures stable operation during maintenance windows
- See [Vault token management](https://developer.hashicorp.com/vault/tutorials/tokens/token-management)

title: Deployment scenarios

text:
This guide covers the most common deployment scenario with the following assumptions:

- Vault Enterprise with namespace support (adapt for Community Edition by removing namespace parameters)
- Multiple Redis Enterprise clusters in the same Kubernetes cluster
- Namespace isolation using Kubernetes namespace suffixes for Vault configurations
- Production security with proper RBAC and network policies

Multi-cluster considerations: When deploying across multiple Kubernetes clusters with identical namespace names, additional prefixing may be required to avoid Vault path conflicts.

title: Configure the operator

text:
1. Configure Vault policies and roles

   Create a policy that grants the Redis Enterprise operator read access to secrets:

   [code example]

   Parameter explanation:
   - `<VAULT_NAMESPACE>`: Your Vault Enterprise namespace (omit for Community Edition)
   - `<K8S_NAMESPACE>`: Kubernetes namespace where Redis Enterprise operator is deployed

   Configure a Vault role that binds the operator's service account to the policy:

   [code example]

   Parameter explanation:
   - `<AUTH_PATH>`: Kubernetes auth method path in Vault (default: `kubernetes`)
   - Role name includes namespace for multi-tenant isolation

2. Configure operator environment

   Create a ConfigMap with Vault configuration for the Redis Enterprise operator:

   [code example]

   Apply the configuration:

   [code example]

   Configuration parameters:

   | Parameter | Description | Default | Required |
   |-----------|-------------|---------|----------|
   | `CREDENTIAL_TYPE` | Must be set to `"vault"` to enable Vault integration | - | Yes |
   | `VAULT_SERVER_FQDN` | Vault server hostname (e.g., `vault.vault-ns.svc.cluster.local`) | - | Yes |
   | `VAULT_SERVICE_PORT_HTTPS` | Vault HTTPS port | `8200` | Yes |
   | `VAULT_SECRET_ROOT` | KV-v2 secret engine mount path | `secret` | Yes |
   | `VAULT_SECRET_PREFIX` | Prefix for all Redis Enterprise secrets | `redisenterprise` | Yes |
   | `VAULT_ROLE` | Vault role for operator authentication | `redis-enterprise-operator` | Yes |
   | `VAULT_AUTH_PATH` | Kubernetes auth method path | `kubernetes` | Yes |
   | `VAULT_NAMESPACE` | Vault Enterprise namespace | - | Enterprise only |
   | `VAULT_CACHE_SECRET_EXPIRATION_SECONDS` | Secret cache duration | `120` | No |

   Secret path construction: Secrets are stored at `<VAULT_SECRET_ROOT>/data/<VAULT_SECRET_PREFIX>/<secret-name>`

3. Deploy the operator

   Deploy the Redis Enterprise operator following the [standard installation guide]().

   The operator pod will not be ready until the admission controller secret is stored in Vault (covered in the next step).

4. Configure admission controller secret

   Generate and store the admission controller TLS certificate in Vault:

   [code example]

   Copy the certificate file to Vault (if Vault is running in Kubernetes):

   [code example]

   Store the certificate in Vault:

   [code example]

   Once the operator is running with Vault integration, proceed to create Redis Enterprise clusters. Do not create clusters before completing this setup.

5. Create Vault CA certificate secret

   Create a Kubernetes secret containing the Certificate Authority certificate used by your Vault instance:

   [code example]

   The Vault server certificate must be signed by the Certificate Authority provided in this secret.

title: Create Redis Enterprise clusters

text:
1. Generate cluster credentials

   Unlike standard deployments, Vault integration requires manually creating cluster credentials:

   [code example]

   Store credentials in Vault:

   [code example]

   - The username field in the REC spec is ignored when using Vault
   - The username from the Vault secret takes precedence
   - Use strong, unique passwords for each cluster

2. Create cluster service account role

   Configure a Vault role for the Redis Enterprise cluster's service account:

   [code example]

3. Deploy Redis Enterprise cluster

   Create the `RedisEnterpriseCluster` resource with Vault configuration:

   [code example]

   Apply the configuration:

   [code example]

   Key configuration fields:

   | Field | Description | Example |
   |-------|-------------|---------|
   | `clusterCredentialSecretName` | Path of the secret in Vault containing cluster credentials. Can be customized during cluster creation but cannot be changed afterward. The secret must be pre-created in Vault. | `rec` |
   | `clusterCredentialSecretType` | Must be set to `vault` | `vault` |
   | `clusterCredentialSecretRole` | Vault role for cluster authentication | `redis-enterprise-rec-<K8S_NAMESPACE>` |
   | `vaultCASecret` | Kubernetes secret containing Vault's CA certificate | `vault-ca-cert` |
   | `podAnnotations` | Vault agent annotations for pod-level configuration | See example above |

title: Create Redis Enterprise databases

text:
To create a Redis Enterprise database (REDB) with Vault integration:

1. Create database password in Vault:
   [code example]

2. Create the REDB custom resource:
   Follow the standard [database creation process](). The REC configuration automatically enables Vault integration for all databases.

3. Configure additional secrets (optional):
   Store additional REDB secrets in the path `redisenterprise-<K8S_NAMESPACE>/`. Secrets must comply with the [REDB secrets schema]().

When using the Redis Enterprise Vault plugin, set `defaultUser: false` and associate users through ACL bindings to the REDB.

For complete field documentation, see the [Redis Enterprise database API reference]().

title: Redis Enterprise Remote Cluster secrets

text: The `secretName` field is supported and should be stored in HashiCorp Vault when the Redis Enterprise cluster uses Vault as a secret source.

title: Redis Enterprise Active-Active database secrets

text: REAADB resources include REDB specifications in the `globalConfigurations` field. All secret names specified in these configurations are supported and should be stored in HashiCorp Vault when the Redis Enterprise cluster uses Vault as a secret source.

title: Manage secrets

text: Complete field documentation is available in the [`RedisEnterpriseCluster` API reference]() and [`RedisEnterpriseDatabase` API reference]().

title: Redis Enterprise cluster secrets

text:
#### Example REC configuration with all certificates

[code example]

You can also update certificates using `kubectl patch`:

[code example]

title: Database secrets

text:
#### Database passwords
Store database passwords in Vault using the database name as the secret key:

[code example]

#### Backup storage credentials
Store backup storage credentials for Redis Enterprise databases:

[code example]

#### TLS certificates
Store TLS certificates for database connections:

[code example]

title: User-defined module credentials

text:
Store credentials for downloading user-defined modules from authenticated repositories:

[code example]

Reference this secret in your REC specification's `userDefinedModules` section. See [Configure modules]() for details.

title: Troubleshooting

title: Common Issues and Solutions

text:
#### Operator pod not ready

Symptoms: Operator pod remains in `Pending` or `CrashLoopBackOff` state

Causes and solutions:

1. Missing admission controller secret:
   [code example]

2. Vault CA certificate issues:
   [code example]

3. Network connectivity:
   [code example]

#### Authentication failures

Symptoms: `Failed to authenticate with Vault` errors in operator logs

Solutions:

1. Verify Vault role configuration:
   [code example]

2. Check service account token:
   [code example]

#### Secret retrieval failures

Symptoms: `Failed to read Vault secret` errors

Solutions:

1. Verify secret exists:
   [code example]

2. Check policy permissions:
   [code example]

3. Validate secret format:
   [code example]

title: Debugging commands

text:
Check operator logs:
[code example]

Verify Vault configuration:
[code example]

Test Vault authentication:
[code example]

section_id: secret-path-structure

code:
vault policy write -namespace=<VAULT_NAMESPACE> redisenterprise-<K8S_NAMESPACE> - <<EOF
   path "secret/data/redisenterprise-<K8S_NAMESPACE>/*" {
     capabilities = ["create", "read", "update", "delete", "list"]
   }
   path "secret/metadata/redisenterprise-<K8S_NAMESPACE>/*" {
     capabilities = ["list"]
   }
   EOF

section_id: configure-the-operator

code:
vault write -namespace=<VAULT_NAMESPACE> auth/<AUTH_PATH>/role/redis-enterprise-operator-<K8S_NAMESPACE> \
           bound_service_account_names="redis-enterprise-operator" \
           bound_service_account_namespaces=<K8S_NAMESPACE> \
           policies=redisenterprise-<K8S_NAMESPACE>

code:
# operator-environment-config.yaml
   apiVersion: v1
   kind: ConfigMap
   metadata:
     name: operator-environment-config
     namespace: <K8S_NAMESPACE>
   data:
     CREDENTIAL_TYPE: "vault"
     VAULT_SERVER_FQDN: "<VAULT_FQDN>"
     VAULT_SERVICE_PORT_HTTPS: "8200"
     VAULT_SECRET_ROOT: "secret"
     VAULT_SECRET_PREFIX: "redisenterprise-<K8S_NAMESPACE>"
     VAULT_ROLE: "redis-enterprise-operator-<K8S_NAMESPACE>"
     VAULT_AUTH_PATH: "<AUTH_PATH>"
     VAULT_NAMESPACE: "<VAULT_NAMESPACE>"
     VAULT_CACHE_SECRET_EXPIRATION_SECONDS: "120"

code: kubectl apply -f operator-environment-config.yaml

code:
kubectl exec -it $(kubectl get pod -l name=redis-enterprise-operator -o jsonpath='{.items[0].metadata.name}') \
     -c redis-enterprise-operator -- /usr/local/bin/generate-tls -infer | tail -4 > output.json

code: kubectl cp output.json vault-0:/tmp -n vault

code: vault kv put -namespace=<VAULT_NAMESPACE> <VAULT_SECRET_ROOT>/redisenterprise-<K8S_NAMESPACE>/admission-tls @output.json

code:
kubectl create secret generic vault-ca-cert \
           --namespace <K8S_NAMESPACE> \
           --from-file=vault.ca=<vault-ca-cert-file-path>

code:
# Generate a secure random password
   openssl rand -base64 32

section_id: create-redis-enterprise-clusters

code:
vault kv put -namespace=<VAULT_NAMESPACE> \
     <VAULT_SECRET_ROOT>/redisenterprise-<K8S_NAMESPACE>/<REC_NAME> \
     username=<YOUR_USERNAME> \
     password=<YOUR_PASSWORD>

code:
vault write -namespace=<VAULT_NAMESPACE> \
     auth/<AUTH_PATH>/role/redis-enterprise-rec-<K8S_NAMESPACE> \
     bound_service_account_names=<REC_NAME> \
     bound_service_account_namespaces=<K8S_NAMESPACE> \
     policies=redisenterprise-<K8S_NAMESPACE>

code:
apiVersion: app.redislabs.com/v1
   kind: RedisEnterpriseCluster
   metadata:
     name: rec
     namespace: <K8S_NAMESPACE>
     labels:
       app: redis-enterprise
   spec:
     nodes: 3
     clusterCredentialSecretName: rec
     clusterCredentialSecretType: vault
     clusterCredentialSecretRole: redis-enterprise-rec-<K8S_NAMESPACE>
     vaultCASecret: vault-ca-cert
     podAnnotations:
       vault.hashicorp.com/auth-path: auth/<AUTH_PATH>
       vault.hashicorp.com/namespace: <VAULT_NAMESPACE>

code: kubectl apply -f redis-enterprise-cluster.yaml

code:
vault kv put -namespace=<VAULT_NAMESPACE> \
     <VAULT_SECRET_ROOT>/redisenterprise-<K8S_NAMESPACE>/redb-<DATABASE_NAME> \
     password=<DATABASE_PASSWORD>

section_id: create-redis-enterprise-databases

code:
apiVersion: app.redislabs.com/v1
kind: RedisEnterpriseCluster
metadata:
  name: rec
  labels:
    app: redis-enterprise
spec:
  nodes: 3
  licenseSecretName: <VAULT_SECRET_NAME>
  clusterCredentialSecretName: <VAULT_SECRET_NAME>
  certificates:
    apiCertificateSecretName: <VAULT_SECRET_NAME>
    cmCertificateSecretName: <VAULT_SECRET_NAME>
    metricsExporterCertificateSecretName: <VAULT_SECRET_NAME>
    proxyCertificateSecretName: <VAULT_SECRET_NAME>
    syncerCertificateSecretName: <VAULT_SECRET_NAME>
    ldapClientCertificateSecretName: <VAULT_SECRET_NAME>
  # Vault configuration
  clusterCredentialSecretType: vault
  clusterCredentialSecretRole: redis-enterprise-rec-<K8S_NAMESPACE>
  vaultCASecret: vault-ca-cert
  podAnnotations:
    vault.hashicorp.com/auth-path: auth/<AUTH_PATH>
    vault.hashicorp.com/namespace: <VAULT_NAMESPACE>

section_id: redis-enterprise-cluster-secrets

code: kubectl patch rec rec --type merge --patch '{"spec": {"certificates": {"apiCertificateSecretName": "<VAULT_SECRET_NAME>"}}}'

code:
vault kv put -namespace=<VAULT_NAMESPACE> \
  <VAULT_SECRET_ROOT>/redisenterprise-<K8S_NAMESPACE>/<DATABASE_NAME> \
  password=<DATABASE_PASSWORD>

section_id: database-secrets

code:
vault kv put -namespace=<VAULT_NAMESPACE> \
  <VAULT_SECRET_ROOT>/redisenterprise-<K8S_NAMESPACE>/<BACKUP_SECRET_NAME> \
  AWS_ACCESS_KEY_ID=<access_key> \
  AWS_SECRET_ACCESS_KEY=<secret_key>

code:
vault kv put -namespace=<VAULT_NAMESPACE> \
  <VAULT_SECRET_ROOT>/redisenterprise-<K8S_NAMESPACE>/<CERT_SECRET_NAME> \
  tls.crt=<certificate_content> \
  tls.key=<private_key_content>

code:
vault kv put -namespace=<VAULT_NAMESPACE> \
  <VAULT_SECRET_ROOT>/redisenterprise-<K8S_NAMESPACE>/<MODULE_CREDENTIALS_SECRET_NAME> \
  username=<repository_username> \
  password=<repository_password>

section_id: user-defined-module-credentials

code:
# Check if admission-tls secret exists in Vault
   vault kv get -namespace=<VAULT_NAMESPACE> <VAULT_SECRET_ROOT>/redisenterprise-<K8S_NAMESPACE>/admission-tls

section_id: common-issues-and-solutions

code:
# Verify vault-ca-cert secret exists
   kubectl get secret vault-ca-cert -n <K8S_NAMESPACE>

   # Check certificate content
   kubectl get secret vault-ca-cert -n <K8S_NAMESPACE> -o jsonpath='{.data.vault\.ca}' | base64 -d

code:
# Test Vault connectivity from operator pod
   kubectl exec -it <operator-pod> -c redis-enterprise-operator -- \
     curl -k https://<VAULT_FQDN>:8200/v1/sys/health

code: vault read -namespace=<VAULT_NAMESPACE> auth/<AUTH_PATH>/role/redis-enterprise-operator-<K8S_NAMESPACE>

code:
# Verify service account exists
   kubectl get serviceaccount redis-enterprise-operator -n <K8S_NAMESPACE>

   # Check token mount
   kubectl describe pod <operator-pod> -n <K8S_NAMESPACE> | grep -A5 "Mounts:"

code: vault kv get -namespace=<VAULT_NAMESPACE> <VAULT_SECRET_ROOT>/redisenterprise-<K8S_NAMESPACE>/<secret-name>

code: vault policy read -namespace=<VAULT_NAMESPACE> redisenterprise-<K8S_NAMESPACE>

code:
# Cluster credentials must have 'username' and 'password' keys
   vault kv get -format=json -namespace=<VAULT_NAMESPACE> <VAULT_SECRET_ROOT>/redisenterprise-<K8S_NAMESPACE>/<cluster-name>

code: kubectl logs -f deployment/redis-enterprise-operator -n <K8S_NAMESPACE> -c redis-enterprise-operator

section_id: debugging-commands

code: kubectl get configmap operator-environment-config -n <K8S_NAMESPACE> -o yaml

code:
# From within operator pod
kubectl exec -it <operator-pod> -n <K8S_NAMESPACE> -c redis-enterprise-operator -- \
  cat /var/run/secrets/kubernetes.io/serviceaccount/token


title: Upgrade Redis Enterprise for Kubernetes

summary: Upgrade Redis Enterprise operator, clusters, and databases on Kubernetes.

summary: This task describes how to upgrade a Redis Enterprise cluster via the operator.

title: Upgrade Redis Enterprise for Kubernetes

summary: This task describes how to upgrade a Redis Enterprise cluster via OpenShift CLI.

title: Upgrade Redis Enterprise with OpenShift CLI

summary: This task describes how to upgrade a Redis Enterprise cluster via OpenShift OperatorHub.

title: Upgrade Redis Enterprise with OpenShift OperatorHub

title: Overview

text: Keep your Redis Enterprise deployment up to date with the latest features, security patches, and bug fixes. The upgrade process involves updating three main components in sequence: the Redis Enterprise operator, Redis Enterprise clusters (REC), and Redis Enterprise databases (REDB).

title: Upgrade methods

text:
Choose the appropriate upgrade method for your deployment:

- [Upgrade Redis Enterprise for Kubernetes]() - Standard upgrade process for most Kubernetes distributions
- [Upgrade with OpenShift CLI]() - OpenShift-specific upgrade using CLI tools
- [Upgrade with OpenShift OperatorHub]() - Upgrade using OpenShift OperatorHub and OLM
- [Upgrade with Helm]() - Helm-specific upgrade instructions for chart-based deployments

title: Upgrade process

text:
The upgrade process includes updating three components in order:

1. **Upgrade the Redis Enterprise operator** - Update the operator to the latest version
2. **Upgrade the Redis Enterprise cluster (REC)** - Update cluster nodes and infrastructure
3. **Upgrade Redis Enterprise databases (REDB)** - Update database versions and configurations

title: Upgrade compatibility

text:
When upgrading, both your Kubernetes version and Redis operator version need to be supported at all times.

If your current Kubernetes distribution is not [supported](), upgrade to a supported distribution before upgrading.

title: RHEL9-based image

text:
As of version 7.8.2-6, Redis Enterprise images are based on Red Hat Enterprise Linux 9 (RHEL9). This means upgrades require:

- [Cluster version of 7.4.2-2 or later](https://redis.io/docs/latest/operate/kubernetes/7.4.6/upgrade/).
- Database version 7.2 or later.
- RHEL9 compatible binaries for any modules you need.

For detailed steps, see the relevant upgrade page:

- [OpenShift CLI]()
- [OpenShift OperatorHub]()
- [Kubernetes]()


title: Overview

text:
Redis implements rolling updates for software upgrades in Kubernetes deployments. The upgrade process includes updating three components:

  1. [Upgrade the Redis Enterprise operator](#upgrade-the-operator)
  1. [Upgrade the Redis Enterprise cluster (REC)](#upgrade-the-redis-enterprise-cluster)
  1. [Upgrade Redis Enterprise databases (REDB)](#upgrade-databases)

title: Prerequisites

text:
The following steps ensure you have the minimum versions of all components necessary to upgrade to 7.8.2-6 or later. **Without these minimum versions, the upgrade will freeze and require manual recovery.**

See the [troubleshooting](#troubleshooting) section for details on recovering a failed upgrade.

#### Kubernetes version

Check [Supported Kubernetes distributions]() to make sure your Kubernetes distribution is supported. If not, upgrade your Kubernetes distribution before upgrading the Redis operator.

#### Redis operator version

Your Redis Enterprise clusters must be running version 7.4.2-2 or later before upgrading to 7.8.2-6 or later. See the [7.4 upgrade](https://redis.io/docs/latest/operate/kubernetes/7.4.6/upgrade/openshift-cli/) for detailed steps.

#### Redis database version

Your Redis databases must be running version 7.2 or later before upgrading your cluster version. See [upgrade databases](#upgrade-databases) for detailed steps. You can find your database version in the [REDB `spec.redisVersion` field]().

#### User-defined modules

If your databases use user-defined modules (custom non-bundled modules):

- Set `autoUpgradeRedisEnterprise: false` in the REC custom resource before upgrading the operator.
- Define the user-defined modules in the REC custom resource before upgrading the database.
- See [Edit `redisEnterpriseImageSpec`](#edit-redisenterpriseimagespec) for more details.

For more information about user-defined modules, see [User-defined modules]().

#### RHEL9-compatible modules

Upgrading to Redis operator versions 7.8.2-6 and later  involves migrating your Redis Enterprise nodes to RHEL9 from either Ubuntu 18 or RHEL8. If your databases use modules, you need to manually install modules compatible with RHEL9.

To see which modules you have installed, run:

[code example]

To see which modules are currently in use, run:

[code example]

See [Upgrade modules]() for details on how to upgrade modules with the `rladmin` tool.

#### Valid license

Use `kubectl get rec` and verify the `LICENSE STATE` is valid on your REC before you start the upgrade process.

title: Upgrade with Helm charts

text:
If you installed the Redis Enterprise operator using Helm charts on OpenShift, you can upgrade using Helm commands. This method automatically handles the operator upgrade and Custom Resource Definition (CRD) updates.

To upgrade using Helm on OpenShift:

[code example]

For example:

[code example]

After the Helm upgrade completes, continue with [upgrading the Redis Enterprise cluster](#upgrade-the-redis-enterprise-cluster) and [upgrading databases](#upgrade-databases).

For detailed Helm upgrade instructions, see [Upgrade the chart]().

title: Upgrade the operator

text: If your databases use user-defined modules, set `autoUpgradeRedisEnterprise: false` in the REC custom resource before upgrading the operator.

title: Download the bundle

text:
Make sure you pull the correct version of the bundle. You can find the version tags
by checking the [operator releases on GitHub](https://github.com/RedisLabs/redis-enterprise-k8s-docs/releases)
or by [using the GitHub API](https://docs.github.com/en/rest/reference/repos#releases).

For OpenShift environments, the name of the bundle is `openshift.bundle.yaml`, and so the `curl` command to run is:

[code example]

If you need a different release, replace `VERSION` in the above with a specific release tag.

title: Apply the bundle

text:
Apply the bundle to deploy the new operator binary. This will also apply any changes in the new release to custom resource definitions, roles, role binding, or operator service accounts.

If you are not pulling images from Docker Hub, update the operator image spec to point to your private repository.
If you have made changes to the role, role binding, RBAC, or custom resource definition (CRD) in the previous version, merge them with the updated declarations in the new version files.

If you are using OpenShift, run this instead:

[code example]

After running this command, you should see a result similar to this:

[code example]

title: Reapply the admission controller webhook {#reapply-webhook}

text: If you have the admission controller enabled, you need to manually reapply the `ValidatingWebhookConfiguration`.

title: Verify the operator is running

text:
You can check your deployment to verify the operator is running in your namespace.

[code example]

You should see a result similar to this:

[code example]

 We recommend upgrading the REC as soon as possible after updating the operator. After the operator upgrade completes, the operator suspends the management of the REC and its associated REDBs, until the REC upgrade completes.

title: Security context constraints

role: security

text:
Upgrades to versions 7.22.0-6 and later run in **unprivileged mode** without any additional permissions or capabilities. If you don't specifally require additional capabilities, we recommend you maintain the default unprivileged mode, as its more secure. After upgrading, remove the existing `redis-enterprise-scc-v2` SCC and unbind it from the REC service account.

To enable automatic resource adjustment, see [Allow automatic resource adjustment > OpenShift upgrades]().

title: Upgrade the Redis Enterprise cluster

text:
Verify your license is valid before upgrading. Invalid licenses will cause the upgrade to fail.

Use `oc get rec` and verify the `LICENSE STATE` is valid on your REC before you start the upgrade process.

The Redis Enterprise cluster (REC) can be updated automatically or manually. To trigger automatic upgrade of the REC after the operator upgrade completes, specify `autoUpgradeRedisEnterprise: true` in your REC spec. If you don't have automatic upgrade enabled, follow the below steps for the manual upgrade.

Before beginning the upgrade of the Redis Enterprise cluster, check the K8s operator [release notes]() to find the Redis Enterprise image tag.

After the operator upgrade is complete, you can upgrade Redis Enterprise cluster (REC).

title: Edit `redisEnterpriseImageSpec`

text:
1. Edit the REC custom resource YAML file.

    [code example]

1. Replace the `versionTag:` declaration under `redisEnterpriseImageSpec` with the new version tag.

    [code example]

1. Define any user-defined modules used by databases in the cluster.

    [code example]

  The `name` field must match the `display_name` or `module_name` that appears in the module manifest (for example, "redisgears"). This enables the operator to run validation on the user-defined module. If these names don't match, the operator can't run validation on the user-defined module and preventable errors may occur.

Adding or modifying the `userDefinedModules` list triggers a rolling restart of the Redis Enterprise cluster pods in addition to the rolling upgrade for the version change.

1. Save the changes to apply.

title: Reapply roles and role bindings

text: If your operator is monitoring multiple namespaces, you'll need to [reapply your role and role bindings]() for each managed namespace. See [Manage databases in multiple namespaces]() for more details.

title: Monitor the upgrade

text:
You can view the state of the REC with `oc get rec`.

  During the upgrade, the state should be `Upgrade`.
  When the upgrade is complete and the cluster is ready to use, the state will change to `Running`.
  If the state is `InvalidUpgrade`, there is an error (usually relating to configuration) in the upgrade.

[code example]

To see the status of the current rolling upgrade, run:

[code example]

title: Upgrade databases

text:
After the cluster is upgraded, you can upgrade your databases.

To upgrade your REDB, specify your new database version in the `spec.redisVersion` field in the REDB or REAADB custom resources. Supported database versions for operator versions include "7.2", "7.4", "8.0", and "8.2" (note this value is a string).

For Active-Active databases, the `redis.Version` change only needs to be applied on one participating cluster and will automatically propagate to all other participating clusters. All participating clusters must be running operator version 8.0.2-2 or later.

If your REAADB uses supported modules, keep the existing `moduleList` version numbers unchanged when upgrading `redisVersion`. The database will automatically use the module versions that are bundled with the new Redis version, regardless of what versions are specified in `moduleList`. After the upgrade is complete, you can optionally change the old version numbers from `moduleList`, but this change has no functional impact.

#### Upgrade with user-defined modules

If a user-defined module is used by any database in the cluster, the module must be defined in the REC custom resource before upgrading the database. See [Add user-defined modules to the REC]() for detailed instructions.

#### General upgrade notes

Note that if your cluster [`redisUpgradePolicy`]() or your database [`redisVersion`]() are set to `major`, you won't be able to upgrade those databases to minor versions. See [Redis upgrade policy]() for more details.

title: Troubleshooting

text: If you start an upgrade without meeting the [prerequisites](#prerequisites), the operator will freeze the upgrade. Check the operator logs for the source of the error. The REDB reconsilliation doesn't work during an upgrade, so you need to apply a manual fix with the Redis Software API (examples below). The updates will also need to be added to the REDB custom resource.

title: Invalid module version

text:
If the operator logs show an event related to an unsupported module, download the updated module locally, and install it using the `v2/modules` API endpoint.

[code example]

After updating the modules with the Redis Software API, update the REDB custom resource to reflect the change.

title: Invalid database version

text:
If the operator logs show an event related to an incompatible database version, upgrade the database using the Redis Software API.

[code example]

After updating the database with the Redis Software API, update the REDB custom resource to reflect the change.

code: curl -k -u <rec_username>:<rec_password> -X GET https://localhost:9443/v1/modules | jq -r 'map([.module_name, .semantic_version, (.platforms | keys)]) | .[] | .[0] as $name | .[1] as $version | .[2][] | $name + "-" + $version + "-" + .' | sort

section_id: prerequisites

code: curl -k -u <rec_username>:<rec_password> -X GET https://localhost:9443/v1/bdbs | jq -r '.[].module_list | map(.module_name + "-" + .semantic_version) | .[]'

code:
helm upgrade <release-name> <repo-name>/redis-enterprise-operator --version <chart-version> \
    --set openshift.mode=true

section_id: upgrade-with-helm-charts

code:
helm upgrade my-redis-enterprise <repo-name>/redis-enterprise-operator --version 7.8.2-2 \
    --set openshift.mode=true

code: curl --silent -O https://raw.githubusercontent.com/RedisLabs/redis-enterprise-k8s-docs/$VERSION/openshift.bundle.yaml

section_id: download-the-bundle

code: oc apply -f openshift.bundle.yaml

section_id: apply-the-bundle

section_id: verify-the-operator-is-running

code:
NAME                        READY   UP-TO-DATE   AVAILABLE   AGE
redis-enterprise-operator   1/1     1            1           0m36s

code: oc edit rec <your-rec.yaml>

section_id: edit-redisenterpriseimagespec

code:
spec:
      redisEnterpriseImageSpec:
        imagePullPolicy:  IfNotPresent
        repository:       redislabs/redis
        versionTag:       <new-version-tag>

code:
spec:
      userDefinedModules:
        - name: "custom-module"
          source:
            https:
              url: "https://modules.company.com/search-v2.1.zip"
              credentialsSecret: "module-repo-creds"

code:
$ oc get rec
NAME   NODES   VERSION      STATE     SPEC STATUS   LICENSE STATE   SHARDS LIMIT   LICENSE EXPIRATION DATE   AGE
rec    3       6.2.10-107   Upgrade   Valid         Valid           4              2022-07-16T13:59:00Z      92m

section_id: monitor-the-upgrade

code: oc rollout status sts <REC_name>

code: curl -sfk -u <rec_username>:<rec_password> -X POST -F 'module=@<full path to your module>' https://localhost:9443/v2/modules

section_id: invalid-module-version

code: curl -sfk -u <rec_username>:<rec_password> -X POST -H "Content-Type: application/json" -d '{"redis_version": <target redis version>}' https://localhost:9443/v1/bdbs/<BDB UID>/upgrade

section_id: invalid-database-version