diff --git a/content/operate/kubernetes/deployment/helm.md b/content/operate/kubernetes/deployment/helm.md index fb2247db14..1950057932 100644 --- a/content/operate/kubernetes/deployment/helm.md +++ b/content/operate/kubernetes/deployment/helm.md @@ -31,7 +31,16 @@ The steps below use the following placeholders to indicate command line paramete - `` is the name of the new namespace the Redis operator will run in (example: `ns1`) - `` is the filepath to the Helm chart, if it is stored in a local directory (example: `/home/charts/redis-enterprise-operator`) -## Install +## Install the operator + +Below are several ways to install the operator using Helm. To create the REC in the same step, see [Create the REC at install time](#create-the-rec-at-install-time). + +- [Install from the Redis Helm repository](#install-from-the-redis-helm-repository) +- [Install from local directory](#install-from-local-directory) +- [Specify values during install](#specify-values-during-install) +- [Install with values file](#install-with-values-file) + +### Install from the Redis Helm repository 1. Add the Redis repository. @@ -75,7 +84,7 @@ To monitor the installation add the `--debug` flag. The installation runs severa 2. Install the Helm chart, overriding specific value defaults using `--set`. ```sh -helm install /redis-enterprise-operator \ +helm install /redis-enterprise-operator \ --version \ --namespace \ --create-namespace @@ -92,36 +101,61 @@ helm install /redis-enterprise-operator \ 3. Install the chart with the `--values` option. ```sh -helm install /redis-enterprise-operator \ +helm install /redis-enterprise-operator \ --version \ --namespace \ --create-namespace \ --values ``` -## Migrate from a non-Helm installation +## Create the REC at install time -To migrate an existing non-Helm installation of the Redis Enterprise operator to a Helm-based installation: +The chart can create the `RedisEnterpriseCluster` (REC) custom resource at install time, so a single `helm install` deploys both the operator and the cluster. To enable this, set `cluster.create` to `true` and define the cluster under `cluster.spec` in your values file. The `spec` field accepts any field from the `RedisEnterpriseCluster` CRD. For the full list, see the [RedisEnterpriseCluster API reference]({{}}). -1. [Upgrade]({{}}) your existing Redis Enterprise operator to match the version of the Helm chart you want to install. Use the same non-Helm method you used for the original installation. +{{}} +`cluster.create` defaults to `false`. When `false`, the chart installs only the operator and you create the REC yourself. +{{}} -2. [Install](#install) the Helm chart adding the `--take-ownership` flag: +1. Create a values file with a `cluster` section. For example: - ```sh - helm install /redis-enterprise-operator --take-ownership - ``` + ```yaml + cluster: + create: true + spec: + nodes: 3 + redisEnterpriseImageSpec: + repository: redislabs/redis + redisEnterpriseServicesRiggerImageSpec: + repository: redislabs/k8s-controller + bootstrapperImageSpec: + repository: redislabs/operator + ``` - - The `--take-ownership` flag is available with Helm versions 3.18 or later. - - This flag is only needed for the first installation of the chart. Subsequent upgrades don't require this flag. - - Use the `helm install` command, not `helm upgrade`. +2. Install the chart with the values file. -3. Delete the old `ValidatingWebhookConfiguration` object from the previous non-Helm installation: + ```sh + helm install /redis-enterprise-operator \ + --version \ + --namespace \ + --create-namespace \ + --values + ``` - ```sh - kubectl delete validatingwebhookconfiguration redis-enterprise-admission - ``` + The chart runs a Kubernetes Job to create the REC. The Job deletes itself on success. - This step is only needed when the `admission.limitToNamespace` chart value is set to `true` (the default). In this case, the webhook object installed by the chart is named `redis-enterprise-admission-`, and the original webhook object, named `redis-enterprise-admission`, becomes redundant. If `admission.limitToNamespace` is set to `false`, the webhook installed by the chart is named `redis-enterprise-admission`, and the existing webhook object is reused. +3. Confirm the operator deployment is running. + + ```sh + kubectl get deployment redis-enterprise-operator --namespace + ``` + +4. Wait for the REC to reach the `Running` state. Initialization takes about a minute. + + ```sh + kubectl get rec --namespace + ``` + +To update or uninstall an REC created by the chart, see [Update an REC created by the chart](#update-an-rec-created-by-the-chart) and [Uninstall the REC and operator together](#uninstall-the-rec-and-operator-together). ## Upgrade the chart @@ -155,6 +189,43 @@ If your databases use user-defined modules (custom non-bundled modules), you mus For more information and options when upgrading charts, see [helm upgrade](https://helm.sh/docs/helm/helm_upgrade/). +### Update an REC created by the chart + +If you used `cluster.create: true`, change REC settings by editing `cluster.spec` in your values file and running `helm upgrade`. + +1. Update your values file. For example, to add labels: + + ```yaml + cluster: + create: true + spec: + nodes: 3 + redisEnterpriseImageSpec: + repository: redislabs/redis + redisEnterpriseServicesRiggerImageSpec: + repository: redislabs/k8s-controller + bootstrapperImageSpec: + repository: redislabs/operator + extraLabels: + environment: production + ``` + +2. Apply the changes. + + ```sh + helm upgrade /redis-enterprise-operator \ + --namespace \ + --values + ``` + + Some REC fields trigger a StatefulSet rolling update. Others, such as `extraLabels`, take effect immediately. + +3. Confirm the change. + + ```sh + kubectl get rec --namespace -o yaml + ``` + ## Uninstall 1. Delete any custom resources managed by the operator. See [Delete custom resources]({{}}) for detailed steps. You must delete custom resources in the correct order to avoid errors. @@ -169,8 +240,50 @@ This removes all Kubernetes resources associated with the chart and deletes the {{}}Custom Resource Definitions (CRDs) installed by the chart are not removed during chart uninstallation. To remove them manually after uninstalling the chart, run `kubectl delete crds -l app=redis-enterprise`.{{}} +### Uninstall the REC and operator together + +When `cluster.create` is `true`, `helm uninstall` removes both the REC and the operator. You don't need to delete the REC first. + +```sh +helm uninstall --namespace +``` + +Confirm all resources are gone. + +```sh +kubectl get all --namespace +``` + +{{}} +This applies only to RECs the chart created. If you created the REC outside the chart, follow [Delete custom resources]({{}}) before you run `helm uninstall`. +{{}} + +## Migrate from a non-Helm installation + +To migrate an existing non-Helm installation of the Redis Enterprise operator to a Helm-based installation: + +1. [Upgrade]({{}}) your existing Redis Enterprise operator to match the version of the Helm chart you want to install. Use the same non-Helm method you used for the original installation. + +2. [Install](#install-the-operator) the Helm chart adding the `--take-ownership` flag: + + ```sh + helm install /redis-enterprise-operator --take-ownership + ``` + + - The `--take-ownership` flag is available with Helm versions 3.18 or later. + - This flag is only needed for the first installation of the chart. Subsequent upgrades don't require this flag. + - Use the `helm install` command, not `helm upgrade`. + +3. Delete the old `ValidatingWebhookConfiguration` object from the previous non-Helm installation: + + ```sh + kubectl delete validatingwebhookconfiguration redis-enterprise-admission + ``` + + This step is only needed when the `admission.limitToNamespace` chart value is set to `true` (the default). In this case, the webhook object installed by the chart is named `redis-enterprise-admission-`, and the original webhook object, named `redis-enterprise-admission`, becomes redundant. If `admission.limitToNamespace` is set to `false`, the webhook installed by the chart is named `redis-enterprise-admission`, and the existing webhook object is reused. + ## Known limitations -- The steps for [creating the RedisEnterpriseCluster (REC)]({{}}) and other custom resources remain the same. +- Custom resources other than the REC must still be created using the standard process. The chart doesn't manage them. - The chart doesn't include configuration options for multiple namespaces, rack-awareness, and Vault integration. The steps for configuring these options remain the same. - The chart has had limited testing in advanced setups, including Active-Active configurations, air-gapped deployments, and IPv6/dual-stack environments. \ No newline at end of file