adds docs for using different secrets managers in k8s (#171)

* adds docs for using different secrets managers in k8s

Signed-off-by: ChrisJBurns <[email protected]>

* adds vault secret injection docs

Signed-off-by: ChrisJBurns <[email protected]>

* corrects name of k8s docs

Signed-off-by: ChrisJBurns <[email protected]>

* Update wording, rewrite the Vault section

Signed-off-by: Dan Barr <[email protected]>

---------

Signed-off-by: ChrisJBurns <[email protected]>
Signed-off-by: Dan Barr <[email protected]>
Co-authored-by: Dan Barr <[email protected]>

Author: ChrisJBurns

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)

docs/toolhive/guides-cli/build-containers.mdx

@@ -316,15 +316,15 @@ 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)
 
 ## Related information
 
 - [`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

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

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

docs/toolhive/guides-k8s/run-mcp-k8s.md renamed to 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:
+
+<Tabs groupId='secret-manager' queryString='secret-manager'>
+<TabItem value='kubernetes-native' label='Kubernetes secrets' default>
+
+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=<YOUR_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=<YOUR_TOKEN>
+kubectl apply -f my-mcpserver-with-secrets.yaml
 ```
 
-Apply the MCPServer resource:
+</TabItem>
+<TabItem value='eso' label='External Secrets Operator'>
+
+[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
 ```
 
+</TabItem>
+<TabItem value='vault' label='HashiCorp Vault'>
+
+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).
+
+</TabItem>
+</Tabs>
+
 ### Mount a volume
 
 You can mount volumes into the MCP server pod to provide persistent storage or

docs/toolhive/guides-mcp/filesystem.mdx

@@ -109,7 +109,7 @@ outbound network access (see the
 <TabItem value='k8s' label='Kubernetes'>
 
 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:

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