diff --git a/docs/toolhive/guides-k8s/deploy-operator-helm.mdx b/docs/toolhive/guides-k8s/deploy-operator-helm.mdx index 768e8b28..6fb0d74c 100644 --- a/docs/toolhive/guides-k8s/deploy-operator-helm.mdx +++ b/docs/toolhive/guides-k8s/deploy-operator-helm.mdx @@ -1,11 +1,16 @@ --- title: Deploy the operator description: - How to deploy the ToolHive operator in a Kubernetes cluster using Helm + How to deploy the ToolHive operator in a Kubernetes cluster using Helm or + kubectl --- -Helm is the officially supported method to install the ToolHive operator in a -Kubernetes cluster. +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +This guide covers how to install the ToolHive operator in a Kubernetes cluster. +You can install using either Helm (recommended) or kubectl with static +manifests. ## Prerequisites @@ -14,32 +19,29 @@ Kubernetes cluster. - [`kubectl`](https://kubernetes.io/docs/tasks/tools/) configured to communicate with your cluster - [Helm](https://helm.sh/docs/intro/install/) (v3.10 minimum, v3.14+ - recommended) - -## Install the CRDs + recommended) - only required for Helm installation method -![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) +## Installation methods -The ToolHive operator requires Custom Resource Definitions (CRDs) to manage -MCPServer resources. The CRDs define the structure and behavior of MCPServers in -your cluster. +Choose an installation method based on your needs: -```bash -helm upgrade --install toolhive-operator-crds oci://ghcr.io/stacklok/toolhive/toolhive-operator-crds -``` +- **Helm** (recommended): Provides customization options and manages the full + lifecycle of the operator. CRDs are installed and upgraded automatically as + part of the Helm chart. +- **kubectl**: Uses static manifests for a simple installation. Useful for + environments where Helm isn't available or for GitOps workflows. -This command installs the latest version of the ToolHive operator CRDs Helm -chart. To install a specific version, append `--version ` to the -command, for example: - -```bash -helm upgrade --install toolhive-operator-crds oci://ghcr.io/stacklok/toolhive/toolhive-operator-crds --version 0.0.73 -``` + + -## Install the operator +## Install with 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) +The ToolHive operator Helm chart includes the Custom Resource Definitions (CRDs) +required to manage MCP server resources. CRDs are installed automatically when +you install the chart and upgraded automatically when you upgrade the chart. + To install the ToolHive operator using default settings, run the following command: @@ -47,15 +49,47 @@ command: 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 ` to the -command, for example: +This command installs the latest version of the ToolHive operator Helm chart. To +install a specific version, append `--version ` to the command, for +example: + +```bash +helm upgrade --install toolhive-operator oci://ghcr.io/stacklok/toolhive/toolhive-operator -n toolhive-system --create-namespace --version 0.6.0 +``` + +### CRD configuration options + +The Helm chart provides fine-grained control over which CRDs are installed. By +default, all CRDs are installed. You can selectively enable or disable CRD +groups using these values: + +| Value | Description | Default | +| ------------------------- | ----------------------------------------------------- | ------- | +| `crds.install.server` | Install server CRDs (MCPServer, MCPRemoteProxy, etc.) | `true` | +| `crds.install.registry` | Install registry CRDs (MCPRegistry) | `true` | +| `crds.install.virtualMcp` | Install vMCP CRDs (VirtualMCPServer, etc.) | `true` | +| `crds.keep` | Preserve CRDs when uninstalling the chart | `true` | + +For example, to install only server-related CRDs without vMCP support: ```bash -helm upgrade --install toolhive-operator oci://ghcr.io/stacklok/toolhive/toolhive-operator -n toolhive-system --create-namespace --version 0.5.6 +helm upgrade --install toolhive-operator oci://ghcr.io/stacklok/toolhive/toolhive-operator \ + -n toolhive-system --create-namespace \ + --set crds.install.virtualMcp=false ``` -Verify the installation: +:::note + +The `crds.keep` option adds the `helm.sh/resource-policy: keep` annotation to +CRDs, which prevents Helm from deleting them during `helm uninstall`. This +protects your custom resources from accidental deletion. If you want to remove +CRDs during uninstall, set `crds.keep=false`. + +::: + +### Verify the installation + +Check that the operator pod is running: ```bash kubectl get pods -n toolhive-system @@ -63,10 +97,16 @@ kubectl get pods -n toolhive-system After about 30 seconds, you should see the `toolhive-operator` pod running. +Verify that the CRDs are installed: + +```bash +kubectl get crd | grep toolhive +``` + Check the logs of the operator pod: ```bash -kubectl logs -f -n toolhive-system +kubectl logs -f -n toolhive-system -l app.kubernetes.io/name=toolhive-operator ``` This shows you the logs of the operator pod, which can help you debug any @@ -223,73 +263,51 @@ 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 upgrade the CRD Helm chart -and then apply the CRDs using `kubectl`. +The ToolHive operator Helm chart manages CRDs as part of the chart templates. +This means both the operator and CRDs are upgraded together when you run +`helm upgrade`. -![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 --version 0.0.73 -``` +![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) -Then apply the CRDs from the same version tag: +To upgrade to the latest version: ```bash -kubectl apply -f https://raw.githubusercontent.com/stacklok/toolhive/refs/tags/toolhive-operator-crds-0.0.73/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.73/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.73/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.73/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.73/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.73/deploy/charts/operator-crds/crds/toolhive.stacklok.dev_mcpregistries.yaml -kubectl apply -f https://raw.githubusercontent.com/stacklok/toolhive/refs/tags/toolhive-operator-crds-0.0.73/deploy/charts/operator-crds/crds/toolhive.stacklok.dev_virtualmcpcompositetooldefinitions.yaml -kubectl apply -f https://raw.githubusercontent.com/stacklok/toolhive/refs/tags/toolhive-operator-crds-0.0.73/deploy/charts/operator-crds/crds/toolhive.stacklok.dev_virtualmcpservers.yaml +helm upgrade toolhive-operator oci://ghcr.io/stacklok/toolhive/toolhive-operator -n toolhive-system --reuse-values ``` -Replace `0.0.73` 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) +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 +helm upgrade toolhive-operator oci://ghcr.io/stacklok/toolhive/toolhive-operator -n toolhive-system --reuse-values --version 0.6.0 ``` -This upgrades the operator to the latest version available in the OCI registry. -To upgrade to a specific version, add the `--version` flag: +If you have a custom `values.yaml` file, include it with the `-f` flag: ```bash -helm upgrade -i toolhive-operator oci://ghcr.io/stacklok/toolhive/toolhive-operator -n toolhive-system --reuse-values --version 0.5.6 +helm upgrade toolhive-operator oci://ghcr.io/stacklok/toolhive/toolhive-operator -n toolhive-system --reuse-values -f values.yaml ``` -If you have a custom `values.yaml` file, include it with the `-f` flag: +After upgrading, verify the new version is running: ```bash -helm upgrade -i toolhive-operator oci://ghcr.io/stacklok/toolhive/toolhive-operator -n toolhive-system --reuse-values -f values.yaml +kubectl get pods -n toolhive-system +kubectl get crd | grep toolhive ``` ## Uninstall the operator -To uninstall the operator and CRDs: - -First, uninstall the operator: +To uninstall the ToolHive 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. +By default, CRDs are preserved when you uninstall the chart (due to the +`crds.keep=true` setting). This prevents accidental deletion of your MCPServer +resources. + +If you want to completely remove ToolHive including all CRDs and related +resources, delete the CRDs manually: :::warning @@ -299,28 +317,108 @@ 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 +kubectl delete crd mcpremoteproxies.toolhive.stacklok.dev +kubectl delete crd mcpservers.toolhive.stacklok.dev +kubectl delete crd mcptoolconfigs.toolhive.stacklok.dev kubectl delete crd virtualmcpcompositetooldefinitions.toolhive.stacklok.dev kubectl delete crd virtualmcpservers.toolhive.stacklok.dev ``` -Finally, uninstall the CRD Helm chart metadata: +If you created the `toolhive-system` namespace with Helm's `--create-namespace` +flag, delete it manually: ```bash -helm uninstall toolhive-operator-crds +kubectl delete namespace toolhive-system ``` -If you created the `toolhive-system` namespace with Helm's `--create-namespace` -flag, delete it manually: + + + +## Install with kubectl + +You can install the ToolHive operator using static manifests with kubectl. This +method is useful for environments where Helm isn't available or for GitOps +workflows that prefer plain Kubernetes manifests. + +### Install the CRDs + +First, install the Custom Resource Definitions (CRDs): ```bash -kubectl delete namespace toolhive-system +kubectl apply -f https://github.com/stacklok/toolhive/releases/latest/download/toolhive-operator-crds.yaml +``` + +To install a specific version, replace `latest` with the version tag: + +```bash +kubectl apply -f https://github.com/stacklok/toolhive/releases/download/v0.6.12/toolhive-operator-crds.yaml +``` + +### Install the operator + +Install the operator deployment and associated resources: + +```bash +kubectl apply -f https://github.com/stacklok/toolhive/releases/latest/download/toolhive-operator.yaml +``` + +To install a specific version: + +```bash +kubectl apply -f https://github.com/stacklok/toolhive/releases/download/v0.6.12/toolhive-operator.yaml +``` + +### Verify the installation + +Check that the operator pod is running: + +```bash +kubectl get pods -n toolhive-system +``` + +Verify that the CRDs are installed: + +```bash +kubectl get crd | grep toolhive +``` + +## Upgrade with kubectl + +To upgrade the operator, apply the new version of the manifests. Upgrade the +CRDs first, then the operator: + +```bash +kubectl apply -f https://github.com/stacklok/toolhive/releases/download/VERSION/toolhive-operator-crds.yaml +kubectl apply -f https://github.com/stacklok/toolhive/releases/download/VERSION/toolhive-operator.yaml +``` + +Replace `VERSION` with your target version (for example, `v0.6.12`). + +## Uninstall with kubectl + +To uninstall the operator: + +```bash +kubectl delete -f https://github.com/stacklok/toolhive/releases/latest/download/toolhive-operator.yaml ``` +To also remove the CRDs (this deletes all MCPServer resources): + +:::warning + +This will delete all MCPServer and related resources in your cluster! + +::: + +```bash +kubectl delete -f https://github.com/stacklok/toolhive/releases/latest/download/toolhive-operator-crds.yaml +``` + + + + ## Next steps See [Run MCP servers in Kubernetes](./run-mcp-k8s.mdx) to learn how to create @@ -395,11 +493,11 @@ kubectl get crd | grep toolhive kubectl delete crd ``` -To reinstall the CRDs: +To reinstall the CRDs with Helm, uninstall the operator and reinstall it: ```bash -helm uninstall toolhive-operator-crds -helm upgrade -i toolhive-operator-crds oci://ghcr.io/stacklok/toolhive/toolhive-operator-crds +helm uninstall toolhive-operator -n toolhive-system +helm upgrade --install toolhive-operator oci://ghcr.io/stacklok/toolhive/toolhive-operator -n toolhive-system --create-namespace ``` diff --git a/docs/toolhive/guides-k8s/intro.mdx b/docs/toolhive/guides-k8s/intro.mdx index b6b78f97..2081ccf0 100644 --- a/docs/toolhive/guides-k8s/intro.mdx +++ b/docs/toolhive/guides-k8s/intro.mdx @@ -55,9 +55,11 @@ learn how to expose your MCP servers and connect clients, see ## Installation -[Use Helm to install the ToolHive operator](./deploy-operator-helm.mdx) in your -Kubernetes cluster. Helm simplifies the installation process and lets you manage -the operator using Helm charts. +Install the ToolHive operator in your Kubernetes cluster using either +[Helm or kubectl](./deploy-operator-helm.mdx). Helm is recommended for most +users as it provides customization options and manages the full lifecycle of the +operator. kubectl installation is available for environments where Helm isn't +available or for GitOps workflows. Once the operator is installed, you can create and manage MCP servers using the [`MCPServer` custom resource](./run-mcp-k8s.mdx). diff --git a/docs/toolhive/tutorials/opentelemetry.mdx b/docs/toolhive/tutorials/opentelemetry.mdx index d7999bd5..bc7ad1e9 100644 --- a/docs/toolhive/tutorials/opentelemetry.mdx +++ b/docs/toolhive/tutorials/opentelemetry.mdx @@ -367,7 +367,6 @@ Otherwise, set up a local kind cluster and install the ToolHive operator: ```bash kind create cluster --name toolhive -helm upgrade -i toolhive-operator-crds oci://ghcr.io/stacklok/toolhive/toolhive-operator-crds helm upgrade -i toolhive-operator oci://ghcr.io/stacklok/toolhive/toolhive-operator -n toolhive-system --create-namespace ``` diff --git a/docs/toolhive/tutorials/quickstart-k8s.mdx b/docs/toolhive/tutorials/quickstart-k8s.mdx index bc18d3ec..b9816aec 100644 --- a/docs/toolhive/tutorials/quickstart-k8s.mdx +++ b/docs/toolhive/tutorials/quickstart-k8s.mdx @@ -102,13 +102,7 @@ from your main system and can be easily deleted when you're done. Now deploy the ToolHive operator to your cluster using Helm. The operator will watch for MCP server resources and manage their lifecycle automatically. -First, install the operator CRDs: - -```bash -helm upgrade --install toolhive-operator-crds oci://ghcr.io/stacklok/toolhive/toolhive-operator-crds -``` - -Then install the operator: +Install the operator (this also installs the required CRDs): ```bash helm upgrade --install toolhive-operator oci://ghcr.io/stacklok/toolhive/toolhive-operator -n toolhive-system --create-namespace