Skip to content

adds operator crds helm/kubectl installation guide #435

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
ChrisJBurns merged 2 commits into from
Jan 14, 2026
Merged

adds operator crds helm/kubectl installation guide #435

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
1dd9c73
updates operator crd install docs
ChrisJBurns Jan 14, 2026
8e4a12e
Merge branch 'main' into crds-docs
ChrisJBurns Jan 14, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
128 changes: 112 additions & 16 deletions docs/toolhive/guides-k8s/deploy-operator-helm.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,12 +1,10 @@
---
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.

## Prerequisites

- A Kubernetes cluster (current and two previous minor versions are supported)
Expand All @@ -24,6 +22,17 @@ 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:

- **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.

<Tabs groupId="method" queryString="method">
<TabItem value="helm" label="Helm" default>

```bash
helm upgrade --install toolhive-operator-crds oci://ghcr.io/stacklok/toolhive/toolhive-operator-crds
```
Expand All @@ -36,6 +45,57 @@ command, for example:
helm upgrade --install toolhive-operator-crds oci://ghcr.io/stacklok/toolhive/toolhive-operator-crds --version 0.0.73
```

#### 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-crds oci://ghcr.io/stacklok/toolhive/toolhive-operator-crds \
--set crds.install.virtualMcp=false
```

:::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`.

:::

</TabItem>
<TabItem value="kubectl" label="kubectl">

To install the CRDs using `kubectl`, run the following, ensuring you only apply
the CRDs you need for the features you plan to use:

```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
```

Replace `0.0.73` in the commands above with your target CRD version.

</TabItem>
</Tabs>

## Install the operator

![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=b2e4bc)
Expand Down Expand Up @@ -228,19 +288,31 @@ 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`.
Choose an upgrade method based on your needs:

- **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.

<Tabs groupId="method" queryString="method">
<TabItem value="helm" label="Helm" default>

![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=b2e4bc)

First, upgrade the CRD Helm chart to match your target operator version:
To upgrade the ToolHive operator to a new version, upgrade the CRDs first by
upgrading with the desired CRDs chart:

```bash
helm upgrade -i toolhive-operator-crds oci://ghcr.io/stacklok/toolhive/toolhive-operator-crds --version 0.0.73
```

Then apply the CRDs from the same version tag:
</TabItem>
<TabItem value="kubectl" label="kubectl">

To upgrade the CRDs using `kubectl`, run the following, ensuring you only apply
the CRDs you need for the features you want:

```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
Expand All @@ -253,7 +325,10 @@ kubectl apply -f https://raw.githubusercontent.com/stacklok/toolhive/refs/tags/t
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
```

Replace `0.0.73` in both commands with your target CRD version.
</TabItem>
</Tabs>

Replace `0.0.73` in the commands above with your target CRD version.

### Upgrade the operator Helm release

Expand Down Expand Up @@ -289,14 +364,38 @@ 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.
resources, delete the CRDs.

:::warning

This will delete all MCPServer and related resources in your cluster!

:::

<Tabs groupId="method" queryString="method">
<TabItem value="helm" label="Helm" default>

```bash
helm uninstall toolhive-operator-crds
```

:::note

If you installed the CRDs with Helm and have `crds.keep` still set to `true`,
first upgrade the chart with `--set crds.keep=false` so that when you uninstall
the CRDs chart, it completely removes all CRDs too:

```bash
helm upgrade toolhive-operator-crds oci://ghcr.io/stacklok/toolhive/toolhive-operator-crds --set crds.keep=false
```

:::

</TabItem>
<TabItem value="kubectl" label="kubectl">

To remove the CRDs using `kubectl`, run the following:

```bash
kubectl delete crd mcpexternalauthconfigs.toolhive.stacklok.dev
kubectl delete crd mcptoolconfigs.toolhive.stacklok.dev
Expand All @@ -308,11 +407,8 @@ kubectl delete crd virtualmcpcompositetooldefinitions.toolhive.stacklok.dev
kubectl delete crd virtualmcpservers.toolhive.stacklok.dev
```

Finally, uninstall the CRD Helm chart metadata:

```bash
helm uninstall toolhive-operator-crds
```
</TabItem>
</Tabs>

If you created the `toolhive-system` namespace with Helm's `--create-namespace`
flag, delete it manually:
Expand Down