Skip to content

draft: adds base for operator install docs #395

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

Open
ChrisJBurns wants to merge 1 commit into
base: main
Choose a base branch
from
+184 −91
Open

draft: adds base for operator install docs #395

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
258 changes: 178 additions & 80 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,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

Expand All @@ -14,59 +19,94 @@ 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 <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
```
<Tabs>
<TabItem value="helm" label="Helm" default>

## 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:

```bash
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:
This command installs the latest version of the ToolHive operator Helm chart. To
install a specific version, append `--version <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
```

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 <TOOLHIVE_OPERATOR_POD_NAME>
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
Expand Down Expand Up @@ -223,73 +263,51 @@ kubectl logs -n toolhive-system <TOOLHIVE_OPERATOR_POD_NAME>

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

Expand All @@ -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:
</TabItem>
<TabItem value="kubectl" label="kubectl">

## 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
Comment on lines +393 to +394
Copy link

Copilot AI Dec 12, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Inconsistent placeholder formatting. The placeholder VERSION should use angle brackets to match the convention used elsewhere in the document (line 53 uses <VERSION>). Change VERSION to <VERSION> in both URLs for consistency.

Suggested change
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
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

Copilot uses AI. Check for mistakes.
```

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

</TabItem>
</Tabs>

## Next steps

See [Run MCP servers in Kubernetes](./run-mcp-k8s.mdx) to learn how to create
Expand Down Expand Up @@ -395,11 +493,11 @@ kubectl get crd | grep toolhive
kubectl delete crd <CRD_NAME>
```

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

</details>
Expand Down
8 changes: 5 additions & 3 deletions docs/toolhive/guides-k8s/intro.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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).
1 change: 0 additions & 1 deletion docs/toolhive/tutorials/opentelemetry.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
```

Expand Down
Loading