diff --git a/docs/toolhive/guides-cli/advanced-cicd.mdx b/docs/toolhive/guides-cli/advanced-cicd.mdx index 8113bd5e..36d619f7 100644 --- a/docs/toolhive/guides-cli/advanced-cicd.mdx +++ b/docs/toolhive/guides-cli/advanced-cicd.mdx @@ -313,6 +313,6 @@ When implementing advanced CI/CD patterns: ## Related information - [Build MCP server containers](./build-containers.mdx) -- [Run MCP servers in Kubernetes](../guides-k8s/run-mcp-k8s.md) +- [Run MCP servers in Kubernetes](../guides-k8s/run-mcp-k8s.mdx) - [`thv build` command reference](../reference/cli/thv_build.md) - [Secrets management](./secrets-management.mdx) diff --git a/docs/toolhive/guides-cli/build-containers.mdx b/docs/toolhive/guides-cli/build-containers.mdx index 89e06eb8..a94ba231 100644 --- a/docs/toolhive/guides-cli/build-containers.mdx +++ b/docs/toolhive/guides-cli/build-containers.mdx @@ -316,7 +316,7 @@ thv build --tag my-server:dev go:///path/to/my-project - Use built containers with [`thv run`](./run-mcp-servers.mdx) for local development -- Deploy pre-built containers to [Kubernetes](../guides-k8s/run-mcp-k8s.md) +- Deploy pre-built containers to [Kubernetes](../guides-k8s/run-mcp-k8s.mdx) - Set up [CI/CD pipelines](#cicd-integration) for automated building - Learn about [container registry workflows](#custom-image-tagging) @@ -324,7 +324,7 @@ thv build --tag my-server:dev go:///path/to/my-project - [`thv build` command reference](../reference/cli/thv_build.md) - [Run MCP servers](./run-mcp-servers.mdx) -- [Run MCP servers in Kubernetes](../guides-k8s/run-mcp-k8s.md) +- [Run MCP servers in Kubernetes](../guides-k8s/run-mcp-k8s.mdx) - [Custom permissions](./custom-permissions.mdx) ## Troubleshooting diff --git a/docs/toolhive/guides-k8s/deploy-operator-helm.md b/docs/toolhive/guides-k8s/deploy-operator-helm.md index d8686e5d..224a4e3c 100644 --- a/docs/toolhive/guides-k8s/deploy-operator-helm.md +++ b/docs/toolhive/guides-k8s/deploy-operator-helm.md @@ -257,9 +257,9 @@ create it. ## Next steps -See [Run MCP servers in Kubernetes](./run-mcp-k8s.md) to learn how to create and -manage MCP servers using the ToolHive operator in your Kubernetes cluster. The -operator supports deploying MCPServer resources based on the deployment mode +See [Run MCP servers in Kubernetes](./run-mcp-k8s.mdx) to learn how to create +and manage MCP servers using the ToolHive operator in your Kubernetes cluster. +The operator supports deploying MCPServer resources based on the deployment mode configured during installation. ## Related information diff --git a/docs/toolhive/guides-k8s/intro.md b/docs/toolhive/guides-k8s/intro.md index 50e593bc..2bcb6d37 100644 --- a/docs/toolhive/guides-k8s/intro.md +++ b/docs/toolhive/guides-k8s/intro.md @@ -57,4 +57,4 @@ Kubernetes cluster. Helm simplifies the installation process and lets you manage the operator using Helm charts. Once the operator is installed, you can create and manage MCP servers using the -[`MCPServer` custom resource](./run-mcp-k8s.md). +[`MCPServer` custom resource](./run-mcp-k8s.mdx). diff --git a/docs/toolhive/guides-k8s/run-mcp-k8s.md b/docs/toolhive/guides-k8s/run-mcp-k8s.mdx similarity index 83% rename from docs/toolhive/guides-k8s/run-mcp-k8s.md rename to docs/toolhive/guides-k8s/run-mcp-k8s.mdx index 75f0b8bf..7597fad2 100644 --- a/docs/toolhive/guides-k8s/run-mcp-k8s.md +++ b/docs/toolhive/guides-k8s/run-mcp-k8s.mdx @@ -255,10 +255,25 @@ process. ### Run a server with secrets -For MCP servers that require authentication tokens or other secrets, add the -`secrets` field to the `MCPServer` resource. This example shows how to use a -Kubernetes secret to pass a GitHub personal access token to the `github` MCP -server. +When your MCP servers require authentication tokens or other secrets, ToolHive +supports multiple secrets management methods to fit your existing +infrastructure. Choose the method that best suits your needs: + + + + +ToolHive can reference existing Kubernetes secrets to inject sensitive data into +your MCP server pods as environment variables. This example demonstrates how to +pass a GitHub personal access token to the `github` MCP server. + +First, create the secret. The secret must exist in the same namespace as your +MCP server and the key must match what you specify in the `MCPServer` resource. + +```bash +kubectl -n production create secret generic github-token --from-literal=token= +``` + +Next, define the `MCPServer` resource to reference the secret: ```yaml {13-16} title="my-mcpserver-with-secrets.yaml" apiVersion: toolhive.stacklok.dev/v1alpha1 @@ -279,20 +294,88 @@ spec: targetEnvName: GITHUB_PERSONAL_ACCESS_TOKEN ``` -First, create the secret. Note that the secret must be created in the same -namespace as the MCP server and the key must match the one specified in the -`MCPServer` resource. +Finally, apply the MCPServer resource: ```bash -kubectl -n production create secret generic github-token --from-literal=token= +kubectl apply -f my-mcpserver-with-secrets.yaml ``` -Apply the MCPServer resource: + + + +[External Secrets Operator](https://external-secrets.io/) is a Kubernetes +operator that integrates external secret management systems and syncs secrets +into Kubernetes as native resources. This example demonstrates how to use +ESO-managed secrets with your MCP server. + +:::note + +When you use the External Secrets Operator, your MCP server definition will look +the same as the Kubernetes-native example. This is because the External Secrets +Operator creates standard Kubernetes secrets from external sources. + +::: + +First, create a secret using the +[ExternalSecret resource](https://external-secrets.io/latest/api/externalsecret/). +The exact configuration depends on your external secret management system. The +secret must exist in the same namespace as your MCP server and the key must +match what you specify in the `MCPServer` resource. + +Next, define the `MCPServer` resource to reference the secret: + +```yaml {13-16} title="my-mcpserver-with-secrets-eso.yaml" +apiVersion: toolhive.stacklok.dev/v1alpha1 +kind: MCPServer +metadata: + name: github + namespace: production # Can be any namespace +spec: + image: ghcr.io/github/github-mcp-server + transport: stdio + port: 8080 + permissionProfile: + type: builtin + name: network + secrets: + - name: github-token + key: token + targetEnvName: GITHUB_PERSONAL_ACCESS_TOKEN +``` + +Finally, apply the MCPServer resource: ```bash -kubectl apply -f my-mcpserver-with-secrets.yaml +kubectl apply -f my-mcpserver-with-secrets-eso.yaml ``` + + + +HashiCorp Vault provides multiple integration methods for Kubernetes +environments: + +1. [Vault Sidecar Agent Injector](https://developer.hashicorp.com/vault/docs/deploy/kubernetes/injector), + which injects a sidecar container into your pod to fetch and renew secrets +2. [Vault Secrets Operator](https://developer.hashicorp.com/vault/docs/deploy/kubernetes/vso), + which creates Kubernetes secrets from Vault secrets (similar to the External + Secrets Operator) +3. [Vault CSI Provider](https://developer.hashicorp.com/vault/docs/deploy/kubernetes/csi), + which mounts secrets directly into your pod as files + +ToolHive supports the first two methods. When you use the Vault Secrets +Operator, your MCP server definition will look the same as the Kubernetes-native +example because the Vault Secrets Operator creates standard Kubernetes secrets +from Vault. + +The Vault Sidecar Agent Injector requires additional configuration in your +`MCPServer` resource to add the required annotations. For a complete example, +see the +[HashiCorp Vault integration tutorial](../tutorials/vault-integration.mdx). + + + + ### Mount a volume You can mount volumes into the MCP server pod to provide persistent storage or diff --git a/docs/toolhive/guides-mcp/filesystem.mdx b/docs/toolhive/guides-mcp/filesystem.mdx index 06949859..ebe89ba6 100644 --- a/docs/toolhive/guides-mcp/filesystem.mdx +++ b/docs/toolhive/guides-mcp/filesystem.mdx @@ -109,7 +109,7 @@ outbound network access (see the Create a Kubernetes manifest to deploy the Filesystem MCP server with a -[persistent volume](../guides-k8s/run-mcp-k8s.md#mount-a-volume). +[persistent volume](../guides-k8s/run-mcp-k8s.mdx#mount-a-volume). Update the `podTemplateSpec` section to include your specific volume claim and mount path: diff --git a/docs/toolhive/tutorials/quickstart-k8s.mdx b/docs/toolhive/tutorials/quickstart-k8s.mdx index 86304040..405e30bb 100644 --- a/docs/toolhive/tutorials/quickstart-k8s.mdx +++ b/docs/toolhive/tutorials/quickstart-k8s.mdx @@ -432,8 +432,9 @@ operator. Here are some next steps to explore: -- Learn about [advanced MCP server configurations](../guides-k8s/run-mcp-k8s.md) - for production deployments +- Learn about + [advanced MCP server configurations](../guides-k8s/run-mcp-k8s.mdx) for + production deployments - Learn more about [Helm deployment options](../guides-k8s/deploy-operator-helm.md) and configuration