diff --git a/content/operate/kubernetes/deployment/helm.md b/content/operate/kubernetes/deployment/helm.md index 5c6665dd7f..3595998800 100644 --- a/content/operate/kubernetes/deployment/helm.md +++ b/content/operate/kubernetes/deployment/helm.md @@ -9,7 +9,6 @@ description: Install Redis Enterprise for Kubernetes version 7.8.6 using Helm ch linkTitle: Helm weight: 11 --- - Helm charts provide a simple way to install the Redis Enterprise for Kubernetes operator in just a few steps. For more information about Helm, go to [https://helm.sh/docs/](https://helm.sh/docs/). {{}} This feature is currently in public preview and is not supported on production workloads. Only new installations of the Redis operator are supported at this time. The steps for [creating the RedisEnterpriseCluster (REC)]({{}}) and other custom resources remain the same.{{}} @@ -21,6 +20,8 @@ Helm charts provide a simple way to install the Redis Enterprise for Kubernetes - [Kubernetes client (kubectl)](https://kubernetes.io/docs/tasks/tools/). - [Helm 3.10 or later](https://helm.sh/docs/intro/install/). +If you suspect your file descriptor limits are below 100,000, you must either manually increase limits or [Allow automatic resource adjustment]({{< relref "/operate/kubernetes/security/allow-resource-adjustment" >}}). Most major cloud providers and standard container runtime configurations set default file descriptor limits well above the minimum required by Redis Enterprise. In these environments, you can safely run without enabling automatic resource adjustment. + ### Example values The steps below use the following placeholders to indicate command line parameters you must provide: diff --git a/content/operate/kubernetes/deployment/openshift/openshift-cli.md b/content/operate/kubernetes/deployment/openshift/openshift-cli.md index 16b8f03859..522909b51b 100644 --- a/content/operate/kubernetes/deployment/openshift/openshift-cli.md +++ b/content/operate/kubernetes/deployment/openshift/openshift-cli.md @@ -10,6 +10,7 @@ description: Redis Enterprise for Kubernetes and cluster can be installed via CL linkTitle: OpenShift CLI weight: 60 --- + Use these steps to set up a Redis Enterprise Software cluster with OpenShift. ## Prerequisites @@ -19,6 +20,10 @@ Use these steps to set up a Redis Enterprise Software cluster with OpenShift. To see which version of Redis Enterprise for Kubernetes supports your OpenShift version, see [Supported Kubernetes distributions]({{< relref "/operate/kubernetes/reference/supported_k8s_distributions" >}}). +{{}} +If you suspect your file descriptor limits are below 100,000, you must either manually increase limits or [Allow automatic resource adjustment]({{< relref "/operate/kubernetes/security/enable-privileged-mode" >}}). Most major cloud providers and standard container runtime configurations set default file descriptor limits well above the minimum required by Redis Enterprise. In these environments, you can safely run without enabling automatic resource adjustment. +{{}} + ## Deploy the operator 1. Create a new project. @@ -70,9 +75,7 @@ DO NOT modify or delete the StatefulSet created during the deployment process. D ## Security context constraints -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 privileged mode, see [Enable privileged mode > OpenShift upgrades]({{}}). +Versions 7.22.0-6 and later run in without permissions to [allow automatic resource adjustment]({{}}). If you use the recommended default security constraints, remove the existing `redis-enterprise-scc-v2` SCC and unbind it from the REC service account after upgrading. ## Create a Redis Enterprise cluster custom resource @@ -80,6 +83,10 @@ To enable privileged mode, see [Enable privileged mode > OpenShift upgrades]({{< You can rename the file to `.yaml`, but it is not required. Examples below use `.yaml`. [Options for Redis Enterprise clusters]({{< relref "/operate/kubernetes/reference/redis_enterprise_cluster_api" >}}) has more info about the Redis Enterprise cluster (REC) custom resource, or see the [Redis Enterprise cluster API]({{}}) for a full list of options. + {{}} +If you suspect your file descriptor limits are below 100,000, you must either manually increase limits or [Allow automatic resource adjustment]({{< relref "/operate/kubernetes/security/enable-privileged-mode" >}}). Most major cloud providers and standard container runtime configurations set default file descriptor limits well above the minimum required by Redis Enterprise. In these environments, you can safely run without enabling automatic resource adjustment. + {{}} + The REC name cannot be changed after cluster creation. {{}} @@ -88,6 +95,10 @@ Each Redis Enterprise cluster requires at least 3 nodes. Single-node RECs are no 2. Apply the custom resource file to create your Redis Enterprise cluster. + {{}} +If you enabled automatic resource adjustment in your configuration, this step will trigger the operator to apply elevated capabilities. Ensure your security context allows it. + {{}} + ```sh oc apply -f .yaml ``` diff --git a/content/operate/kubernetes/deployment/openshift/openshift-operatorhub.md b/content/operate/kubernetes/deployment/openshift/openshift-operatorhub.md index 57763b9f39..37853e856c 100644 --- a/content/operate/kubernetes/deployment/openshift/openshift-operatorhub.md +++ b/content/operate/kubernetes/deployment/openshift/openshift-operatorhub.md @@ -10,9 +10,10 @@ description: OpenShift provides the OperatorHub where you can install the Redis linkTitle: OpenShift OperatorHub weight: 70 --- - You can deploy Redis Enterprise for Kubernetes from the Red Hat OpenShift CLI. You can also use a UI, [OperatorHub](https://docs.openshift.com/container-platform/4.11/operators/index.html) (Red Hat) to install operators and create custom resources. +{{}}If you suspect your file descriptor limits are below 100,000, you must either manually increase limits or [Allow automatic resource adjustment]({{< relref "/operate/kubernetes/security/enable-privileged-mode" >}}). Most major cloud providers and standard container runtime configurations set default file descriptor limits well above the minimum required by Redis Enterprise. In these environments, you can safely run without enabling automatic resource adjustment.{{}} + To see which version of Redis Enterprise for Kubernetes supports your OpenShift version, see [Supported Kubernetes distributions]({{< relref "/operate/kubernetes/reference/supported_k8s_distributions" >}}). ## Install the Redis Enterprise operator @@ -45,19 +46,19 @@ To see which version of Redis Enterprise for Kubernetes supports your OpenShift ## Security context constraints -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 privileged mode, see [Enable privileged mode > OpenShift upgrades]({{}}). +Versions 7.22.0-6 and later run in without permissions to [allow automatic resource adjustment]({{}}). If you use the recommended default security constraints, remove the existing `redis-enterprise-scc-v2` SCC and unbind it from the REC service account after upgrading. ## Create Redis Enterprise custom resources The **Installed Operators**->**Operator details** page shows the provided APIs: **RedisEnterpriseCluster** and **RedisEnterpriseDatabase**. You can select **Create instance** to create custom resources using the OperatorHub interface. -Use the YAML view to create a custom resource file or let OperatorHub generate the YAML file for you by specifying your configuration options in the form view. - The REC name cannot be changed after cluster creation. +Use the YAML view to create a custom resource file or let OperatorHub generate the YAML file for you by specifying your configuration options in the form view. -{{}} In versions 6.4.2-4 and 6.4.2-5, REC creation might fail when using the form view due to an error related to the cluster level LDAP. To avoid this, use the YAML view. +{{}} +If you suspect your file descriptor limits are below 100,000, you must either manually increase limits or [Allow automatic resource adjustment]({{< relref "/operate/kubernetes/security/enable-privileged-mode" >}}). Most major cloud providers and standard container runtime configurations set default file descriptor limits well above the minimum required by Redis Enterprise. In these environments, you can safely run without enabling automatic resource adjustment. {{}} + The REC name cannot be changed after cluster creation. + For more information on creating and maintaining Redis Enterprise custom resources, see [Redis Enterprise clusters (REC)]({{< relref "/operate/kubernetes/re-clusters/" >}}) and [Redis Enterprise databases (REDB)]({{< relref "/operate/kubernetes/re-databases/" >}}). diff --git a/content/operate/kubernetes/deployment/quick-start.md b/content/operate/kubernetes/deployment/quick-start.md index fb37c4b766..23bc34bb50 100644 --- a/content/operate/kubernetes/deployment/quick-start.md +++ b/content/operate/kubernetes/deployment/quick-start.md @@ -9,7 +9,6 @@ description: How to install Redis Enterprise Software for Kubernetes. linkTitle: Kubernetes weight: 10 --- - To deploy Redis Enterprise Software for Kubernetes and start your Redis Enterprise cluster (REC), you need to do the following: - Create a new namespace in your Kubernetes cluster. @@ -27,7 +26,10 @@ To deploy Redis Enterprise for Kubernetes, you'll need: - minimum of three worker nodes - Kubernetes client (kubectl) - access to DockerHub, RedHat Container Catalog, or a private repository that can hold the required images. -NOTE: If you are applying version 7.8.2-6 or above, check if the [OS](https://redis.io/docs/latest/operate/kubernetes/release-notes/7-8-2-releases/7-8-2-6-nov24/#breaking-changes) installed on the node is supported. + +If you suspect your file descriptor limits are below 100,000, you must either manually increase limits or [Allow automatic resource adjustment]({{< relref "/operate/kubernetes/security/allow-resource-adjustment" >}}). Most major cloud providers and standard container runtime configurations set default file descriptor limits well above the minimum required by Redis Enterprise. In these environments, you can safely run without enabling automatic resource adjustment. + +{{}}If you are applying version 7.8.2-6 or above, check if the [OS](https://redis.io/docs/latest/operate/kubernetes/release-notes/7-8-2-releases/7-8-2-6-nov24/#breaking-changes) installed on the node is supported.{{}} ### Create a new namespace @@ -114,6 +116,10 @@ that contains cluster specifications. The following example creates a minimal Redis Enterprise cluster. See the [RedisEnterpriseCluster API reference]({{}}) for more information on the various options available. +{{}} +If you suspect your file descriptor limits are below 100,000, you must either manually increase limits or [Allow automatic resource adjustment]({{< relref "/operate/kubernetes/security/allow-resource-adjustment" >}}). Most major cloud providers and standard container runtime configurations set default file descriptor limits well above the minimum required by Redis Enterprise. In these environments, you can safely run without enabling automatic resource adjustment. +{{}} + 1. Create a file that defines a Redis Enterprise cluster with three nodes. {{}} @@ -151,6 +157,10 @@ Each cluster must have at least 3 nodes. Single-node RECs are not supported. See the [Redis Enterprise hardware requirements]({{< relref "/operate/rs/installing-upgrading/install/plan-deployment/hardware-requirements" >}}) for more information on sizing Redis Enterprise node resource requests. + {{}} +If you enabled automatic resource adjustment in your configuration, this step will trigger the operator to apply elevated capabilities. Ensure your security context allows it. + {{}} + 1. Apply your custom resource file in the same namespace as `my-rec.yaml`. ```sh diff --git a/content/operate/kubernetes/security/allow-resource-adjustment.md b/content/operate/kubernetes/security/allow-resource-adjustment.md new file mode 100644 index 0000000000..b3be0f7800 --- /dev/null +++ b/content/operate/kubernetes/security/allow-resource-adjustment.md @@ -0,0 +1,128 @@ +--- +categories: +- docs +- operate +- kubernetes +description: Enable automatic system resource adjustments for Redis Enterprise to increase file descriptor limits. +linkTitle: Auto resource adjustment +title: Allow automatic resource adjustment +weight: 98 +--- + +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. + +## Default behavior + +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: + +```yaml +securityContext: + allowPrivilegeEscalation: false + capabilities: + drop: + - ALL + privileged: false + readOnlyRootFilesystem: false +``` + +## Enable automatic resource adjustment + +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. + +```yaml +spec: + securityContext: + resourceLimits: + allowAutoAdjustment: true +``` + +Enabling automatic resource adjustment results in the following security context: + +**Note:** Enabling `allowAutoAdjustment` grants the container the `SYS_RESOURCE` capability and permits privilege escalation. + +```yaml +securityContext: + allowPrivilegeEscalation: true + capabilities: + add: + - SYS_RESOURCE + drop: + - ALL + privileged: false + readOnlyRootFilesystem: false +``` + +## OpenShift upgrades + +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. + +```sh +oc delete scc/redis-enterprise-scc-v2 +``` + +```sh +oc adm policy remove-scc-from-user redis-enterprise-scc-v2 -z +``` + +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`]({{< relref "/operate/kubernetes/deployment/openshift/openshift-cli#deploy-the-operator" >}})). + +```sh +oc apply -f openshift/scc.yaml +``` + +```sh +oc adm policy add-scc-to-user redis-enterprise-scc-v2 \ + system:serviceaccount:: +``` + +## New OpenShift installations + +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. + {{}} + + ```sh + oc apply -f openshift/scc.yaml + ``` + + You should see the following output: + + ```sh + securitycontextconstraints.security.openshift.io "redis-enterprise-scc-v2" configured + ``` + +1. Provide the operator permissions for the pods. + + ```sh + oc adm policy add-scc-to-user redis-enterprise-scc-v2 \ + system:serviceaccount:: + ``` + +## SYS_RESOURCE + +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. + +## Choose whether to enable automatic resource adjustment + +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. diff --git a/content/operate/kubernetes/security/enable-privileged-mode.md b/content/operate/kubernetes/security/enable-privileged-mode.md deleted file mode 100644 index 31ecba4f74..0000000000 --- a/content/operate/kubernetes/security/enable-privileged-mode.md +++ /dev/null @@ -1,123 +0,0 @@ ---- -categories: -- docs -- operate -- kubernetes -description: Enable adding additional capabilities to the security context for the Redis Enterprise container by enabling `allowAutoAdjustment`. -linkTitle: Enable privileged mode -title: Enable privileged mode -weight: 98 ---- - -[Security settings for Kubernetes pods](https://kubernetes.io/docs/tasks/configure-pod-container/security-context/) are configured in the [`SecurityContext`](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.32/#securitycontext-v1-core). The `allowPrivilegeEscalation` field controls if a container can gain more privileges than its parent process. - -If `allowPrivilegeEscalation` is set to `true` the container can have additional [Linux capabilities](https://man7.org/linux/man-pages/man7/capabilities.7.html) (such as `SYS_RESOURCE`) and is considered to be running in **privileged mode**. - -Redis Enterprise for Kubernetes 7.22.0-6 introduces the ability to run in **unprivileged mode**, where all capabilities are dropped from the Redis Enterprise container and `allowPrivilegeEscalation` is set to `false`. All other security-related settings remain the same as in privileged mode. Unprivileged mode is the default for installations and upgrades of the Redis Enterprise operator for versions 7.22.0-6 and later. - -## Default behavior - -**Unprivileged mode** is the 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. - -The REC security context will look like this in unprivileged mode: - -```yaml -securityContext: - allowPrivilegeEscalation: false - capabilities: - drop: - - ALL - privileged: false - readOnlyRootFilesystem: false -``` - -## Enable privileged mode - -To allow the Redis Enterprise container additional capabilities, you can enable **privileged mode**. Note that changing the following value on a running cluster will trigger a rolling update. - -To enable **privileged mode**, set `allowAutoAdjustment` to `true`. - -```yaml -spec: - securityContext: - resourceLimits: - allowAutoAdjustment: true -``` - -Allowing automatic resource limit adjustment will result in the security context looking like this: - -```yaml -securityContext: - allowPrivilegeEscalation: true - capabilities: - add: - - SYS_RESOURCE - drop: - - ALL - privileged: false - readOnlyRootFilesystem: false -``` - -OpenShift users upgrading to 7.22.0-6 need to make changes to your existing SCC (security context constraint). - -## OpenShift upgrades - -If running in **unprivileged mode**, remove the custom `redis-enterprise-scc-v2` SCC and unbind it from the REC service account after completing your upgrade. - -```sh -oc delete scc/redis-enterprise-scc-v2 -``` - -```sh -oc adm policy remove-scc-from-user redis-enterprise-scc-v2 -z -``` - -If running in **privileged mode**, manually reapply the [security context constraints (SCC)](https://docs.openshift.com/container-platform/4.8/authentication/managing-security-context-constraints.html) file ([`scc.yaml`]({{< relref "/operate/kubernetes/deployment/openshift/openshift-cli#deploy-the-operator" >}})). - -```sh -oc apply -f openshift/scc.yaml -``` - -```sh -oc adm policy add-scc-to-user redis-enterprise-scc-v2 \ - system:serviceaccount:: -``` - -## New OpenShift installations - -New installations of Redis Enterprise for Kubernetes 7.22.0-6 and later automatically run in **unprivileged mode**, using a built-in `nonroot-v2` which is less permissive and more secure. - -To enable **privileged mode** after installation, apply and grant permissions to the `redis-enterprise-scc-v2` SCC. - -1. Apply the `scc.yaml` file. - - {{}} -Do not edit this file. - {{}} - - ```sh - oc apply -f openshift/scc.yaml - ``` - - You should receive the following response: - - ```sh - securitycontextconstraints.security.openshift.io "redis-enterprise-scc-v2" configured - ``` - -1. Provide the operator permissions for the pods. - - ```sh - oc adm policy add-scc-to-user redis-enterprise-scc-v2 \ - system:serviceaccount:: - ``` - -## SYS_RESOURCE - -The `SYS_RESOURCE` capability may be required if processes in the container need 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 limit is lower and the container lacks the `SYS_RESOURCE` capability, the process may fail repeatedly, rendering the cluster unusable. To use unprivileged mode, configure your Kubernetes worker nodes to ensure a default file descriptor limit of at least 100,000. - -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 unprivileged mode. - -Based on our testing, all major cloud providers configure Kubernetes worker nodes with file descriptor limits well above the required minimum. These setups are compatible with unprivileged mode. The only known exception is clusters created with [Kubespray](hhttps://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 in privileged mode.