create REC with helm (#3288)

Author: kaitlynmichael

content/operate/kubernetes/deployment/helm.md

@@ -31,7 +31,16 @@ The steps below use the following placeholders to indicate command line paramete
 - `<namespace-name>` is the name of the new namespace the Redis operator will run in (example: `ns1`)
 - `<path-to-chart>` 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 <operator-name> <repo-name>/redis-enterprise-operator \
+helm install <release-name> <repo-name>/redis-enterprise-operator \
     --version <chart-version> \
     --namespace <namespace-name> \
     --create-namespace
@@ -92,36 +101,61 @@ helm install <operator-name> <repo-name>/redis-enterprise-operator \
 3. Install the chart with the `--values` option.
 
 ```sh
-helm install <operator-name> <repo-name>/redis-enterprise-operator \
+helm install <release-name> <repo-name>/redis-enterprise-operator \
     --version <chart-version> \
     --namespace <namespace-name> \
     --create-namespace \
     --values <path-to-values-file>
 ```
 
-## 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]({{<relref "/operate/kubernetes/reference/api/redis_enterprise_cluster_api">}}).
 
-1. [Upgrade]({{<relref "operate/kubernetes/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.
+{{<note>}}
+`cluster.create` defaults to `false`. When `false`, the chart installs only the operator and you create the REC yourself.
+{{</note>}}
 
-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 <release-name> <repo-name>/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 <release-name> <repo-name>/redis-enterprise-operator \
+        --version <chart-version> \
+        --namespace <namespace-name> \
+        --create-namespace \
+        --values <path-to-values-file>
+    ```
 
-   ```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-<namespace>`, 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 <namespace-name>
+    ```
+
+4. Wait for the REC to reach the `Running` state. Initialization takes about a minute.
+
+    ```sh
+    kubectl get rec --namespace <namespace-name>
+    ```
+
+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 <release-name> <repo-name>/redis-enterprise-operator \
+        --namespace <namespace-name> \
+        --values <path-to-values-file>
+    ```
+
+    Some REC fields trigger a StatefulSet rolling update. Others, such as `extraLabels`, take effect immediately.
+
+3. Confirm the change.
+
+    ```sh
+    kubectl get rec <rec-name> --namespace <namespace-name> -o yaml
+    ```
+
 ## Uninstall
 
 1. Delete any custom resources managed by the operator. See [Delete custom resources]({{<relref "operate/kubernetes/re-clusters/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
 
 {{<note>}}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`.{{</note>}}
 
+### 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 <release-name> --namespace <namespace-name>
+```
+
+Confirm all resources are gone.
+
+```sh
+kubectl get all --namespace <namespace-name>
+```
+
+{{<note>}}
+This applies only to RECs the chart created. If you created the REC outside the chart, follow [Delete custom resources]({{<relref "operate/kubernetes/re-clusters/delete-custom-resources">}}) before you run `helm uninstall`.
+{{</note>}}
+
+## 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]({{<relref "operate/kubernetes/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 <release-name> <repo-name>/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-<namespace>`, 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)]({{<relref "operate/kubernetes/deployment/quick-start#create-a-redis-enterprise-cluster-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.