From c72cd20416f6fe7b980599ae8c358ba07f2c18c6 Mon Sep 17 00:00:00 2001 From: Dan Barr <6922515+danbarr@users.noreply.github.com> Date: Fri, 7 Nov 2025 20:19:23 -0500 Subject: [PATCH 1/3] Fix the CRD upgrade and uninstall instructions Signed-off-by: Dan Barr <6922515+danbarr@users.noreply.github.com> --- .../guides-k8s/deploy-operator-helm.mdx | 43 ++++++++++++++++--- 1 file changed, 36 insertions(+), 7 deletions(-) diff --git a/docs/toolhive/guides-k8s/deploy-operator-helm.mdx b/docs/toolhive/guides-k8s/deploy-operator-helm.mdx index 88475dbc..1507dfa5 100644 --- a/docs/toolhive/guides-k8s/deploy-operator-helm.mdx +++ b/docs/toolhive/guides-k8s/deploy-operator-helm.mdx @@ -223,11 +223,17 @@ kubectl logs -n toolhive-system ## 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, upgrade the CRDs first. Helm +does not upgrade CRDs automatically, so you need to use `kubectl` or other +tools: ```bash -helm upgrade -i toolhive-operator-crds oci://ghcr.io/stacklok/toolhive/toolhive-operator-crds +kubectl apply -f https://raw.githubusercontent.com/stacklok/toolhive/refs/heads/main/deploy/charts/operator-crds/crds/toolhive.stacklok.dev_mcpexternalauthconfigs.yaml +kubectl apply -f https://raw.githubusercontent.com/stacklok/toolhive/refs/heads/main/deploy/charts/operator-crds/crds/toolhive.stacklok.dev_mcptoolconfigs.yaml +kubectl apply -f https://raw.githubusercontent.com/stacklok/toolhive/refs/heads/main/deploy/charts/operator-crds/crds/toolhive.stacklok.dev_mcpremoteproxies.yaml +kubectl apply -f https://raw.githubusercontent.com/stacklok/toolhive/refs/heads/main/deploy/charts/operator-crds/crds/toolhive.stacklok.dev_mcpservers.yaml +kubectl apply -f https://raw.githubusercontent.com/stacklok/toolhive/refs/heads/main/deploy/charts/operator-crds/crds/toolhive.stacklok.dev_mcpgroups.yaml +kubectl apply -f https://raw.githubusercontent.com/stacklok/toolhive/refs/heads/main/deploy/charts/operator-crds/crds/toolhive.stacklok.dev_mcpregistries.yaml ``` Then upgrade the operator itself: @@ -245,16 +251,39 @@ helm upgrade toolhive-operator oci://ghcr.io/stacklok/toolhive/toolhive-operator ## 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 From 8f347c10c67dea3aa516436679a59e191d1981f7 Mon Sep 17 00:00:00 2001 From: Dan Barr <6922515+danbarr@users.noreply.github.com> Date: Fri, 7 Nov 2025 20:34:44 -0500 Subject: [PATCH 2/3] Update instructions to include specific tags Signed-off-by: Dan Barr <6922515+danbarr@users.noreply.github.com> --- .../guides-k8s/deploy-operator-helm.mdx | 49 ++++++++++++++----- 1 file changed, 38 insertions(+), 11 deletions(-) diff --git a/docs/toolhive/guides-k8s/deploy-operator-helm.mdx b/docs/toolhive/guides-k8s/deploy-operator-helm.mdx index 1507dfa5..af51be21 100644 --- a/docs/toolhive/guides-k8s/deploy-operator-helm.mdx +++ b/docs/toolhive/guides-k8s/deploy-operator-helm.mdx @@ -33,7 +33,7 @@ chart. To install a specific version, append `--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 -i toolhive-operator-crds oci://ghcr.io/stacklok/toolhive/toolhive-operator-crds --version 0.0.52 ``` ## Install the operator @@ -52,7 +52,7 @@ chart. To install a specific version, append `--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 -i toolhive-operator oci://ghcr.io/stacklok/toolhive/toolhive-operator -n toolhive-system --create-namespace --version 0.3.7 ``` Verify the installation: @@ -223,26 +223,53 @@ kubectl logs -n toolhive-system ## Upgrade the operator +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 use `kubectl` or other -tools: +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 -kubectl apply -f https://raw.githubusercontent.com/stacklok/toolhive/refs/heads/main/deploy/charts/operator-crds/crds/toolhive.stacklok.dev_mcpexternalauthconfigs.yaml -kubectl apply -f https://raw.githubusercontent.com/stacklok/toolhive/refs/heads/main/deploy/charts/operator-crds/crds/toolhive.stacklok.dev_mcptoolconfigs.yaml -kubectl apply -f https://raw.githubusercontent.com/stacklok/toolhive/refs/heads/main/deploy/charts/operator-crds/crds/toolhive.stacklok.dev_mcpremoteproxies.yaml -kubectl apply -f https://raw.githubusercontent.com/stacklok/toolhive/refs/heads/main/deploy/charts/operator-crds/crds/toolhive.stacklok.dev_mcpservers.yaml -kubectl apply -f https://raw.githubusercontent.com/stacklok/toolhive/refs/heads/main/deploy/charts/operator-crds/crds/toolhive.stacklok.dev_mcpgroups.yaml -kubectl apply -f https://raw.githubusercontent.com/stacklok/toolhive/refs/heads/main/deploy/charts/operator-crds/crds/toolhive.stacklok.dev_mcpregistries.yaml +helm upgrade 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 +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 + +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 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 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 From 9c2110458573412c5acfc828e357f561f272ea8b Mon Sep 17 00:00:00 2001 From: Dan Barr <6922515+danbarr@users.noreply.github.com> Date: Fri, 7 Nov 2025 20:49:34 -0500 Subject: [PATCH 3/3] Address review Signed-off-by: Dan Barr <6922515+danbarr@users.noreply.github.com> --- .../guides-k8s/deploy-operator-helm.mdx | 33 +++++++++++-------- docs/toolhive/tutorials/quickstart-k8s.mdx | 4 +-- 2 files changed, 21 insertions(+), 16 deletions(-) diff --git a/docs/toolhive/guides-k8s/deploy-operator-helm.mdx b/docs/toolhive/guides-k8s/deploy-operator-helm.mdx index af51be21..53b7154e 100644 --- a/docs/toolhive/guides-k8s/deploy-operator-helm.mdx +++ b/docs/toolhive/guides-k8s/deploy-operator-helm.mdx @@ -25,7 +25,7 @@ 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 @@ -33,7 +33,7 @@ chart. To install a specific version, append `--version ` to the command, for example: ```bash -helm upgrade -i toolhive-operator-crds oci://ghcr.io/stacklok/toolhive/toolhive-operator-crds --version 0.0.52 +helm upgrade --install toolhive-operator-crds oci://ghcr.io/stacklok/toolhive/toolhive-operator-crds --version 0.0.52 ``` ## Install the operator @@ -44,7 +44,7 @@ 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 @@ -52,7 +52,7 @@ chart. To install a specific version, append `--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.3.7 +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 ``` @@ -237,7 +237,7 @@ and then apply the CRDs using `kubectl`. First, upgrade the CRD Helm chart to match your target operator version: ```bash -helm upgrade toolhive-operator-crds oci://ghcr.io/stacklok/toolhive/toolhive-operator-crds --version 0.0.52 +helm upgrade -i toolhive-operator-crds oci://ghcr.io/stacklok/toolhive/toolhive-operator-crds --version 0.0.52 ``` Then apply the CRDs from the same version tag: @@ -253,27 +253,27 @@ kubectl apply -f https://raw.githubusercontent.com/stacklok/toolhive/refs/tags/t Replace `0.0.52` in both commands with your target CRD version. -### Upgrade the operator +### 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 toolhive-operator oci://ghcr.io/stacklok/toolhive/toolhive-operator -n toolhive-system --reuse-values +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 toolhive-operator oci://ghcr.io/stacklok/toolhive/toolhive-operator -n toolhive-system --reuse-values --version 0.3.7 +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 @@ -287,8 +287,13 @@ 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: +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 diff --git a/docs/toolhive/tutorials/quickstart-k8s.mdx b/docs/toolhive/tutorials/quickstart-k8s.mdx index 0decde11..b1ac8298 100644 --- a/docs/toolhive/tutorials/quickstart-k8s.mdx +++ b/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: