Fix the CRD upgrade and uninstall instructions (#283)

Signed-off-by: Dan Barr <[email protected]>
Co-authored-by: Dan Barr <[email protected]>

Author: danbarr

docs/toolhive/guides-k8s/deploy-operator-helm.mdx

@@ -25,15 +25,15 @@ MCPServer resources. The CRDs define the structure and behavior of MCPServers in
 your cluster.
 
 ```bash
-helm upgrade -i toolhive-operator-crds oci://ghcr.io/stacklok/toolhive/toolhive-operator-crds
+helm upgrade --install toolhive-operator-crds oci://ghcr.io/stacklok/toolhive/toolhive-operator-crds
 ```
 
 This command installs the latest version of the ToolHive operator CRDs Helm
 chart. To install a specific version, append `--version <VERSION>` to the
 command, for example:
 
 ```bash
-helm upgrade -i toolhive-operator-crds oci://ghcr.io/stacklok/toolhive/toolhive-operator-crds --version 0.0.21
+helm upgrade --install toolhive-operator-crds oci://ghcr.io/stacklok/toolhive/toolhive-operator-crds --version 0.0.52
 ```
 
 ## Install the operator
@@ -44,15 +44,15 @@ To install the ToolHive operator using default settings, run the following
 command:
 
 ```bash
-helm upgrade -i toolhive-operator oci://ghcr.io/stacklok/toolhive/toolhive-operator -n toolhive-system --create-namespace
+helm upgrade --install toolhive-operator oci://ghcr.io/stacklok/toolhive/toolhive-operator -n toolhive-system --create-namespace
 ```
 
 This command installs the latest version of the ToolHive operator CRDs Helm
 chart. To install a specific version, append `--version <VERSION>` to the
 command, for example:
 
 ```bash
-helm upgrade -i toolhive-operator oci://ghcr.io/stacklok/toolhive/toolhive-operator -n toolhive-system --create-namespace --version 0.2.10
+helm upgrade --install toolhive-operator oci://ghcr.io/stacklok/toolhive/toolhive-operator -n toolhive-system --create-namespace --version 0.3.7
 ```
 
 Verify the installation:
@@ -88,7 +88,7 @@ operator:
 Install the operator with your custom values:
 
 ```bash {3}
-helm upgrade -i toolhive-operator oci://ghcr.io/stacklok/toolhive/toolhive-operator\
+helm upgrade --install toolhive-operator oci://ghcr.io/stacklok/toolhive/toolhive-operator\
   -n toolhive-system --create-namespace\
   -f values.yaml
 ```
@@ -129,7 +129,7 @@ operator:
 Reference the `values.yaml` file when you install the operator using Helm:
 
 ```bash {3}
-helm upgrade -i toolhive-operator oci://ghcr.io/stacklok/toolhive/toolhive-operator \
+helm upgrade --install toolhive-operator oci://ghcr.io/stacklok/toolhive/toolhive-operator \
   -n toolhive-system --create-namespace
   -f values.yaml
 ```
@@ -170,7 +170,7 @@ environment.
 Reference the `values.yaml` file when you install the operator using Helm:
 
 ```bash {3}
-helm upgrade -i toolhive-operator oci://ghcr.io/stacklok/toolhive/toolhive-operator \
+helm upgrade --install toolhive-operator oci://ghcr.io/stacklok/toolhive/toolhive-operator \
   -n toolhive-system --create-namespace
   -f values.yaml
 ```
@@ -223,38 +223,99 @@ kubectl logs -n toolhive-system <TOOLHIVE_OPERATOR_POD_NAME>
 
 ## Upgrade the operator
 
-To upgrade the ToolHive operator to a new version, use the same commands you
-used to install it. First, upgrade the CRDs if a new version is available:
+To upgrade the ToolHive operator to a new version, you need to upgrade both the
+CRDs and the operator installation.
+
+### Upgrade the CRDs
+
+To upgrade the ToolHive operator to a new version, upgrade the CRDs first. Helm
+does not upgrade CRDs automatically, so you need to upgrade the CRD Helm chart
+and then apply the CRDs using `kubectl`.
+
+![Latest CRD Helm chart release](https://img.shields.io/github/v/release/stacklok/toolhive?filter=toolhive-operator-crds-*&style=for-the-badge&logo=helm&label=Latest%20CRD%20chart&color=097aff)
+
+First, upgrade the CRD Helm chart to match your target operator version:
 
 ```bash
-helm upgrade -i toolhive-operator-crds oci://ghcr.io/stacklok/toolhive/toolhive-operator-crds
+helm upgrade -i toolhive-operator-crds oci://ghcr.io/stacklok/toolhive/toolhive-operator-crds --version 0.0.52
 ```
 
-Then upgrade the operator itself:
+Then apply the CRDs from the same version tag:
 
 ```bash
-helm upgrade toolhive-operator oci://ghcr.io/stacklok/toolhive/toolhive-operator -n toolhive-system --reuse-values
+kubectl apply -f https://raw.githubusercontent.com/stacklok/toolhive/refs/tags/toolhive-operator-crds-0.0.52/deploy/charts/operator-crds/crds/toolhive.stacklok.dev_mcpexternalauthconfigs.yaml
+kubectl apply -f https://raw.githubusercontent.com/stacklok/toolhive/refs/tags/toolhive-operator-crds-0.0.52/deploy/charts/operator-crds/crds/toolhive.stacklok.dev_mcptoolconfigs.yaml
+kubectl apply -f https://raw.githubusercontent.com/stacklok/toolhive/refs/tags/toolhive-operator-crds-0.0.52/deploy/charts/operator-crds/crds/toolhive.stacklok.dev_mcpremoteproxies.yaml
+kubectl apply -f https://raw.githubusercontent.com/stacklok/toolhive/refs/tags/toolhive-operator-crds-0.0.52/deploy/charts/operator-crds/crds/toolhive.stacklok.dev_mcpservers.yaml
+kubectl apply -f https://raw.githubusercontent.com/stacklok/toolhive/refs/tags/toolhive-operator-crds-0.0.52/deploy/charts/operator-crds/crds/toolhive.stacklok.dev_mcpgroups.yaml
+kubectl apply -f https://raw.githubusercontent.com/stacklok/toolhive/refs/tags/toolhive-operator-crds-0.0.52/deploy/charts/operator-crds/crds/toolhive.stacklok.dev_mcpregistries.yaml
+```
+
+Replace `0.0.52` in both commands with your target CRD version.
+
+### Upgrade the operator Helm release
+
+Then, upgrade the operator installation using Helm.
+
+![Latest Operator Helm chart release](https://img.shields.io/github/v/release/stacklok/toolhive?filter=toolhive-operator-0*&style=for-the-badge&logo=helm&label=Latest%20Operator%20chart&color=097aff)
+
+```bash
+helm upgrade -i toolhive-operator oci://ghcr.io/stacklok/toolhive/toolhive-operator -n toolhive-system --reuse-values
 ```
 
 This upgrades the operator to the latest version available in the OCI registry.
+To upgrade to a specific version, add the `--version` flag:
+
+```bash
+helm upgrade -i toolhive-operator oci://ghcr.io/stacklok/toolhive/toolhive-operator -n toolhive-system --reuse-values --version 0.3.7
+```
+
 If you have a custom `values.yaml` file, include it with the `-f` flag:
 
 ```bash
-helm upgrade toolhive-operator oci://ghcr.io/stacklok/toolhive/toolhive-operator -n toolhive-system --reuse-values -f values.yaml
+helm upgrade -i toolhive-operator oci://ghcr.io/stacklok/toolhive/toolhive-operator -n toolhive-system --reuse-values -f values.yaml
 ```
 
 ## Uninstall the operator
 
-To uninstall the operator and CRDs, run the following commands:
+To uninstall the operator and CRDs:
+
+First, uninstall the operator:
 
 ```bash
 helm uninstall toolhive-operator -n toolhive-system
+```
+
+Then, if you want to completely remove ToolHive including all CRDs and related
+resources, delete the CRDs manually.
+
+:::warning
+
+This will delete all MCPServer and related resources in your cluster!
+
+:::
+
+```bash
+kubectl delete crd mcpexternalauthconfigs.toolhive.stacklok.dev
+kubectl delete crd mcptoolconfigs.toolhive.stacklok.dev
+kubectl delete crd mcpremoteproxies.toolhive.stacklok.dev
+kubectl delete crd mcpservers.toolhive.stacklok.dev
+kubectl delete crd mcpgroups.toolhive.stacklok.dev
+kubectl delete crd mcpregistries.toolhive.stacklok.dev
+```
+
+Finally, uninstall the CRD Helm chart metadata:
+
+```bash
 helm uninstall toolhive-operator-crds
 ```
 
-This removes all the Kubernetes components associated with the chart and deletes
-the release. You'll need to delete the namespace manually if you used Helm to
-create it.
+If you created the `toolhive-system` namespace with Helm's `--create-namespace`
+flag, delete it manually:
+
+```bash
+kubectl delete namespace toolhive-system
+```
 
 ## Next steps
 

docs/toolhive/tutorials/quickstart-k8s.mdx

@@ -105,13 +105,13 @@ watch for MCP server resources and manage their lifecycle automatically.
 First, install the operator CRDs:
 
 ```bash
-helm upgrade -i toolhive-operator-crds oci://ghcr.io/stacklok/toolhive/toolhive-operator-crds
+helm upgrade --install toolhive-operator-crds oci://ghcr.io/stacklok/toolhive/toolhive-operator-crds
 ```
 
 Then install the operator:
 
 ```bash
-helm upgrade -i toolhive-operator oci://ghcr.io/stacklok/toolhive/toolhive-operator -n toolhive-system --create-namespace
+helm upgrade --install toolhive-operator oci://ghcr.io/stacklok/toolhive/toolhive-operator -n toolhive-system --create-namespace
 ```
 
 Verify that the operator deployed successfully: