Operator docs v1.3.1

Version 1.3.0 is totally broken, due to the "support helm install
--skip-crds" change, which is revoked for version 1.3.1.

Also, upon further inspection, there were various parts of the docs
for all existing versions that were just plain wrong.

- The `Three Node Secure Cluster (using LetsEncrypt)` example has never
  worked.  LetsEncrypt won't issue certificates for service names and
  the operator doesn't yet support any other way for nodes to connect to
  each other.  I replaced the broken examples with a note about the
  recommended workaround.  If we can't fix the three node letsencrypt
  problem soon then we should publish an example of the workaround at
  least.

- The helm instructions were silent about the catastrophic data loss
  that could occur if you messed with crds.enabled the wrong way.

- The installation instructions claim that by removing the
  --set=crds.enabled=true flag that CRDs would not be installed, except
  the default value of crds.enabled is also true, so that isn't
  correct.

- The helm upgrade instructions did not include --reuse-values or
  --reset-then-reuse-values, but they did include a --set, which means
  helm would default to --reset-values, which means all values set
  during installation would be discarded.  The instructions falsely
  claimed that values set during installation would be preserved.

Author: rb-kurrent

docs/server/kubernetes-operator/v1.0.0/getting-started/installation.md

@@ -16,8 +16,8 @@ To get the best out of this guide, a basic understanding of [Kubernetes concepts
 :::
 
 * A Kubernetes cluster running `v1.23.1` or later.
-* Permission to create resources, deploy the Operator and install CRDs in the target cluster. 
-* The following CLI tools installed, on your shell’s `$PATH`, with `$KUBECONFIG` pointing to your cluster: 
+* Permission to create resources, deploy the Operator and install CRDs in the target cluster.
+* The following CLI tools installed, on your shell’s `$PATH`, with `$KUBECONFIG` pointing to your cluster:
   * kubectl [install guide](https://kubernetes.io/docs/tasks/tools/install-kubectl)
   * k9s [install guide](https://k9scli.io/topics/install/)
   * Helm 3 CLI [install guide](https://helm.sh/docs/intro/install/)
@@ -53,22 +53,34 @@ If you prefer to install CRDs yourself:
 ```bash
 # Download the kurrentdb-operator Helm chart
 helm pull kurrent-latest/kurrentdb-operator --version 1.0.0 --untar
-# Install the CRDs
-kubectl apply -f kurrentdb-operator/templates/crds
+# Install the CRDs (real license data is not needed at this step)
+helm template -s 'templates/crds/*.yaml' kurrentdb-operator \
+    --set operator.license.file= --set operator.license.key= \
+    | kubectl apply -f -
 ```
 *Expected Output*:
 ```
 customresourcedefinition.apiextensions.k8s.io/kurrentdbbackups.kubernetes.kurrent.io created
 customresourcedefinition.apiextensions.k8s.io/kurrentdbs.kubernetes.kurrent.io created
 ```
 
+After installing CRDs manually, you should include the `--set crds.enabled=false` flag for the `helm
+install` command, and include one of `--set crds.enabled=false`, `--reuse-values`, or
+`--reset-then-reuse-values` for the `helm upgrade` command.
+
+::: caution
+If `crds.enabled` transitions from `true` to `false` during an upgrade or rollback, the CRDs will be
+removed from the cluster, deleting all `KurrentDBs` and `KurrentDBBackups` and their associated
+child resources, including the PVCs and VolumeSnapshots containing your data!
+:::
+
 ## Deployment Modes
 
 The Operator can be scoped to track Kurrent resources across **all** or **specific** namespaces.
 
 ### Cluster-wide
 
-In cluster-wide mode, the Operator tracks Kurrent resources across **all** namespaces and requires `ClusterRole`. Helm creates the ClusteRole automatically.
+In cluster-wide mode, the Operator tracks Kurrent resources across **all** namespaces and requires `ClusterRole`. Helm creates the `ClusterRole` automatically.
 
 To deploy the Operator in this mode, run:
 
@@ -82,11 +94,11 @@ helm install kurrentdb-operator kurrent-latest/kurrentdb-operator \
   --set-file operator.license.file=/path/to/license.lic
 ```
 
-This command: 
-- Deploys the Operator into the `kurrent` namespace (use `--create-namespace` to create it). Feel free to modify this namespace. 
+This command:
+- Deploys the Operator into the `kurrent` namespace (use `--create-namespace` to create it). Feel free to modify this namespace.
 - Creates the namespace (if it already exists, leave out the `--create-namespace` flag)
-- Deploys CRDs (this can be skipped by removing `--set crds.enabled=true`)
-- Applys the Operator license
+- Deploys CRDs (this can be skipped by changing to `--set crds.enabled=false`)
+- Applies the Operator license
 - Deploys a new Helm release called `kurrentdb-operator` in the `kurrent` namespace.
 
 *Expected Output*:
@@ -121,7 +133,7 @@ helm install kurrentdb-operator kurrent-latest/kurrentdb-operator \
 Here's what the command does:
 - Sets the namespace of where the Operator will be deployed i.e. `kurrent` (feel free to change this)
 - Creates the namespace (if it already exists, leave out the `--create-namespace` flag)
-- Deploys CRDs (this can be skipped by removing `--set crds.enabled=true`)
+- Deploys CRDs (this can be skipped by changing to `--set crds.enabled=false`)
 - Configures the Operator license
 - Sets the underlying Operator configuration to target the namespaces: `kurrent` and `foo`
 - Deploys a new Helm release called `kurrentdb-operator` in the `kurrent` namespace
@@ -174,4 +186,4 @@ Pods may also be viewed using the `:pods` command, for example:
 
 Pressing the `Return` key on the selected Operator pod will allow you to drill through the container hosted in the pod, and then finally to the logs:
 
-![Operator Logs](images/install/logs.png)
+![Operator Logs](images/install/logs.png)

docs/server/kubernetes-operator/v1.0.0/operations/database-deployment.md

@@ -379,89 +379,12 @@ kubectl apply -f cluster.yaml
 
 ## Three Node Secure Cluster (using LetsEncrypt)
 
-The following `KurrentDB` resource type defines a three node cluster with the following properties:
-- The database will be deployed in the `kurrent` namespace with the name `kurrentdb-cluster`
-- Security is enabled using certificates from LetsEncrypt
-- KurrentDB version 25.0.0 will be used
-- 1vcpu will be requested as the minimum (upper bound is unlimited) per node
-- 1gb of memory will be used per node
-- 512mb of storage will be allocated for the data disk per node
-- The KurrentDB instance that is provisioned will be exposed as `kurrentdb-{idx}.kurrentdb-cluster.kurrent.test`
-
-```yaml
-apiVersion: cert-manager.io/v1
-kind: Certificate
-metadata:
-  name: kurrentdb-cluster
-  namespace: kurrent
-spec:
-  secretName: kurrentdb-cluster-tls
-  isCA: false
-  usages:
-    - client auth
-    - server auth
-    - digital signature
-    - key encipherment
-  commonName: kurrentdb-node
-  subject:
-    organizations:
-      - Kurrent
-    organizationalUnits:
-      - Cloud
-  dnsNames:
-    - '*.kurrentdb-cluster.kurrent.svc.cluster.local'
-    - '*.kurrentdb-cluster.kurrent.test'
-  privateKey:
-    algorithm: RSA
-    encoding: PKCS1
-    size: 2048
-  issuerRef:
-    name: letsencrypt
-    kind: Issuer
----
-apiVersion: kubernetes.kurrent.io/v1
-kind: KurrentDB
-metadata:
-  name: kurrentdb-cluster
-  namespace: kurrent
-spec:
-  replicas: 3
-  image: docker.kurrent.io/kurrent-latest/kurrentdb:25.0.0
-  resources:
-    requests:
-      cpu: 1000m
-      memory: 1Gi
-  storage:
-    volumeMode: "Filesystem"
-    accessModes:
-      - ReadWriteOnce
-    resources:
-      requests:
-        storage: 512Mi
-  network:
-    domain: kurrentdb-cluster.kurrent.test
-    loadBalancer:
-      enabled: true
-  security:
-    certificateSecret:
-      name: kurrentdb-cluster-tls
-      keyName: tls.crt
-      privateKeyName: tls.key
-```
-
-Before deploying this cluster, ensure that the steps described in section [Using LetsEncrypt certificates](managing-certificates.md#using-trusted-certificates-via-letsencrypt) have been followed.
-
-Follow these steps to deploy the cluster:
-- Copy the YAML snippet above to a file called `cluster.yaml`
-- Ensure that the `kurrent` namespace has been created
-- Run the following command:
-
-```bash
-kubectl apply -f cluster.yaml
-```
-
-Once deployed, navigate to the [Viewing Deployments](#viewing-deployments) section.
+Using LetsEncrypt, or any publicly trusted certificate, in an operator-managed KurrentDB cluster
+is not supported.
 
+The recommended workaround is to combine [self-signed certificates within the cluster](
+#three-node-secure-cluster-using-self-signed-certificates) with an Ingress that does TLS
+termination using the LetsEncrypt certificate.
 
 ## Viewing Deployments
 
@@ -488,7 +411,7 @@ Scrolling further will also show the events related to the deployment, such as:
 
 ### External
 
-The Operator will create services of type `LoadBalancer` to access a KurrentDB cluster (for each node) when the `spec.network.loadBalancer.enabled` flag is set to `true`. 
+The Operator will create services of type `LoadBalancer` to access a KurrentDB cluster (for each node) when the `spec.network.loadBalancer.enabled` flag is set to `true`.
 
 Each service is annotated with `external-dns.alpha.kubernetes.io/hostname: {external cluster endpoint}` to allow the third-party tool [ExternalDNS](https://github.com/kubernetes-sigs/external-dns) to configure external access.
 
@@ -580,4 +503,4 @@ kubectl -n kurrent patch kurrentdb kurrentdb-cluster --type=merge -p '{"spec":{"
 
 ```bash
 kubectl -n kurrent patch kurrentdb kurrentdb-cluster --type=merge -p '{"spec":{"configuration": {"ProjectionsLevel": "all", "StartStandardProjections": "true"}}}'
-```
+```

docs/server/kubernetes-operator/v1.0.0/operations/operator-upgrade.md

@@ -26,12 +26,11 @@ helm repo update
 helm upgrade kurrentdb-operator kurrentdb-operator-repo/kurrentdb-operator \
   --version {version} \
   --namespace kurrent \
-  --set enable.crds=true
+  --reset-then-reuse-values
 ```
 
 Here's what the command does:
 - Refreshes the local Helm repository index
 - Defines where Operator is installed i.e. `kurrent` (feel free to change this)
 - Define the upgrade `{version}` version e.g. 1.1.0
-- Deploys CRDs (this can be skipped by removing `--set crds.enabled=true`)
 - Performs the upgrade (leverages existing release values)

docs/server/kubernetes-operator/v1.1.0/getting-started/installation.md

@@ -16,8 +16,8 @@ To get the best out of this guide, a basic understanding of [Kubernetes concepts
 :::
 
 * A Kubernetes cluster running `v1.23.1` or later.
-* Permission to create resources, deploy the Operator and install CRDs in the target cluster. 
-* The following CLI tools installed, on your shell’s `$PATH`, with `$KUBECONFIG` pointing to your cluster: 
+* Permission to create resources, deploy the Operator and install CRDs in the target cluster.
+* The following CLI tools installed, on your shell’s `$PATH`, with `$KUBECONFIG` pointing to your cluster:
   * kubectl [install guide](https://kubernetes.io/docs/tasks/tools/install-kubectl)
   * k9s [install guide](https://k9scli.io/topics/install/)
   * Helm 3 CLI [install guide](https://helm.sh/docs/intro/install/)
@@ -54,21 +54,31 @@ If you prefer to install CRDs yourself:
 # Download the kurrentdb-operator Helm chart
 helm pull kurrent-latest/kurrentdb-operator --version 1.1.0 --untar
 # Install the CRDs
-kubectl apply -f kurrentdb-operator/templates/crds
+helm template -s 'templates/crds/*.yaml' kurrentdb-operator | kubectl apply -f -
 ```
 *Expected Output*:
 ```
 customresourcedefinition.apiextensions.k8s.io/kurrentdbbackups.kubernetes.kurrent.io created
 customresourcedefinition.apiextensions.k8s.io/kurrentdbs.kubernetes.kurrent.io created
 ```
 
+After installing CRDs manually, you should include the `--set crds.enabled=false` flag for the `helm
+install` command, and include one of `--set crds.enabled=false`, `--reuse-values`, or
+`--reset-then-reuse-values` for the `helm upgrade` command.
+
+::: caution
+If `crds.enabled` transitions from `true` to `false` during an upgrade or rollback, the CRDs will be
+removed from the cluster, deleting all `KurrentDBs` and `KurrentDBBackups` and their associated
+child resources, including the PVCs and VolumeSnapshots containing your data!
+:::
+
 ## Deployment Modes
 
 The Operator can be scoped to track Kurrent resources across **all** or **specific** namespaces.
 
 ### Cluster-wide
 
-In cluster-wide mode, the Operator tracks Kurrent resources across **all** namespaces and requires `ClusterRole`. Helm creates the ClusteRole automatically.
+In cluster-wide mode, the Operator tracks Kurrent resources across **all** namespaces and requires `ClusterRole`. Helm creates the `ClusterRole` automatically.
 
 To deploy the Operator in this mode, run:
 
@@ -82,11 +92,11 @@ helm install kurrentdb-operator kurrent-latest/kurrentdb-operator \
   --set-file operator.license.file=/path/to/license.lic
 ```
 
-This command: 
-- Deploys the Operator into the `kurrent` namespace (use `--create-namespace` to create it). Feel free to modify this namespace. 
+This command:
+- Deploys the Operator into the `kurrent` namespace (use `--create-namespace` to create it). Feel free to modify this namespace.
 - Creates the namespace (if it already exists, leave out the `--create-namespace` flag)
-- Deploys CRDs (this can be skipped by removing `--set crds.enabled=true`)
-- Applys the Operator license
+- Deploys CRDs (this can be skipped by changing to `--set crds.enabled=false`)
+- Applies the Operator license
 - Deploys a new Helm release called `kurrentdb-operator` in the `kurrent` namespace.
 
 *Expected Output*:
@@ -121,7 +131,7 @@ helm install kurrentdb-operator kurrent-latest/kurrentdb-operator \
 Here's what the command does:
 - Sets the namespace of where the Operator will be deployed i.e. `kurrent` (feel free to change this)
 - Creates the namespace (if it already exists, leave out the `--create-namespace` flag)
-- Deploys CRDs (this can be skipped by removing `--set crds.enabled=true`)
+- Deploys CRDs (this can be skipped by changing to `--set crds.enabled=false`)
 - Configures the Operator license
 - Sets the underlying Operator configuration to target the namespaces: `kurrent` and `foo`
 - Deploys a new Helm release called `kurrentdb-operator` in the `kurrent` namespace

docs/server/kubernetes-operator/v1.1.0/operations/database-deployment.md

@@ -444,91 +444,12 @@ kubectl apply -f cluster.yaml
 
 ## Three Node Secure Cluster (using LetsEncrypt)
 
-The following `KurrentDB` resource type defines a three node cluster with the following properties:
-- The database will be deployed in the `kurrent` namespace with the name `kurrentdb-cluster`
-- Security is enabled using certificates from LetsEncrypt
-- KurrentDB version 25.0.0 will be used
-- 1vcpu will be requested as the minimum (upper bound is unlimited) per node
-- 1gb of memory will be used per node
-- 512mb of storage will be allocated for the data disk per node
-- The KurrentDB instance that is provisioned will be exposed as `kurrentdb-{idx}.kurrentdb-cluster.kurrent.test`
-
-```yaml
-apiVersion: cert-manager.io/v1
-kind: Certificate
-metadata:
-  name: kurrentdb-cluster
-  namespace: kurrent
-spec:
-  secretName: kurrentdb-cluster-tls
-  isCA: false
-  usages:
-    - client auth
-    - server auth
-    - digital signature
-    - key encipherment
-  commonName: kurrentdb-node
-  subject:
-    organizations:
-      - Kurrent
-    organizationalUnits:
-      - Cloud
-  dnsNames:
-    - '*.kurrentdb-cluster.kurrent.svc.cluster.local'
-    - '*.kurrentdb-cluster.kurrent.test'
-    - '*.kurrentdb-cluster-replica.kurrent.svc.cluster.local'
-    - '*.kurrentdb-cluster-replica.kurrent.test'
-  privateKey:
-    algorithm: RSA
-    encoding: PKCS1
-    size: 2048
-  issuerRef:
-    name: letsencrypt
-    kind: Issuer
----
-apiVersion: kubernetes.kurrent.io/v1
-kind: KurrentDB
-metadata:
-  name: kurrentdb-cluster
-  namespace: kurrent
-spec:
-  replicas: 3
-  image: docker.kurrent.io/kurrent-latest/kurrentdb:25.0.0
-  resources:
-    requests:
-      cpu: 1000m
-      memory: 1Gi
-  storage:
-    volumeMode: "Filesystem"
-    accessModes:
-      - ReadWriteOnce
-    resources:
-      requests:
-        storage: 512Mi
-  network:
-    domain: kurrentdb-cluster.kurrent.test
-    loadBalancer:
-      enabled: true
-  security:
-    certificateSecret:
-      name: kurrentdb-cluster-tls
-      keyName: tls.crt
-      privateKeyName: tls.key
-```
-
-Before deploying this cluster, ensure that the steps described in section [Using LetsEncrypt certificates](managing-certificates.md#using-trusted-certificates-via-letsencrypt) have been followed.
-
-Follow these steps to deploy the cluster:
-- Copy the YAML snippet above to a file called `cluster.yaml`
-- Ensure that the `kurrent` namespace has been created
-- Run the following command:
-
-```bash
-kubectl apply -f cluster.yaml
-```
-
-Once deployed, navigate to the [Viewing Deployments](#viewing-deployments) section.
+Using LetsEncrypt, or any publicly trusted certificate, in an operator-managed KurrentDB cluster
+is not supported.
 
+The recommended workaround is to combine [self-signed certificates within the cluster](
+#three-node-secure-cluster-using-self-signed-certificates) with an Ingress that does TLS
+termination using the LetsEncrypt certificate.
 
 ## Deploying With Scheduling Constraints
 

docs/server/kubernetes-operator/v1.1.0/operations/operator-upgrade.md

@@ -26,12 +26,11 @@ helm repo update
 helm upgrade kurrentdb-operator kurrentdb-operator-repo/kurrentdb-operator \
   --version {version} \
   --namespace kurrent \
-  --set enable.crds=true
+  --reset-then-reuse-values
 ```
 
 Here's what the command does:
 - Refreshes the local Helm repository index
 - Defines where Operator is installed i.e. `kurrent` (feel free to change this)
 - Define the upgrade `{version}` version e.g. 1.1.0
-- Deploys CRDs (this can be skipped by removing `--set crds.enabled=true`)
 - Performs the upgrade (leverages existing release values)