When running ToolHive in a Kubernetes environment, you can customize the Kubernetes pod template used to deploy MCP servers. This is useful when you need to add specific Kubernetes configurations to your MCP server pods, such as:

- Volume mounts
- Environment variables
- Resource limits and requests
- Node selectors
- Tolerations
- Security contexts
- Service accounts
- And more

The `--k8s-pod-patch` flag allows you to provide a JSON string that will be used to patch the Kubernetes pod template. This flag is only applicable when using the Kubernetes runtime.

```bash
thv run my-server --k8s-pod-patch '{"spec":{"volumes":[{"name":"my-volume","emptyDir":{}}]}}'
```

When ToolHive deploys an MCP server in Kubernetes, it creates a pod with a single container named **"mcp"**. This is important to know when you want to modify container-specific settings in your pod template patch.

For example, to add environment variables or volume mounts to the container, you need to target the "mcp" container specifically:

```bash
thv run my-server --k8s-pod-patch '{
  "spec": {
    "containers": [
      {
        "name": "mcp",
        "env": [
          {
            "name": "CUSTOM_ENV",
            "value": "custom-value"
          }
        ]
      }
    ]
  }
}'
```

```bash
thv run my-server --k8s-pod-patch '{
  "spec": {
    "volumes": [
      {
        "name": "data-volume",
        "emptyDir": {}
      }
    ],
    "containers": [
      {
        "name": "mcp",
        "volumeMounts": [
          {
            "name": "data-volume",
            "mountPath": "/data"
          }
        ]
      }
    ]
  }
}'
```

```bash
thv run my-server --k8s-pod-patch '{
  "spec": {
    "tolerations": [
      {
        "key": "dedicated",
        "operator": "Equal",
        "value": "mcp-server",
        "effect": "NoSchedule"
      }
    ]
  }
}'
```

```bash
thv run my-server --k8s-pod-patch '{
  "spec": {
    "containers": [
      {
        "name": "mcp",
        "resources": {
          "limits": {
            "cpu": "500m",
            "memory": "512Mi"
          },
          "requests": {
            "cpu": "100m",
            "memory": "128Mi"
          }
        }
      }
    ]
  }
}'
```

```bash
thv run my-server --k8s-pod-patch '{
  "spec": {
    "serviceAccountName": "my-service-account"
  }
}'
```

```bash
thv run my-server --k8s-pod-patch '{
  "spec": {
    "containers": [
      {
        "name": "mcp",
        "env": [
          {
            "name": "DATABASE_URL",
            "value": "postgres://user:password@localhost:5432/db"
          },
          {
            "name": "API_KEY",
            "valueFrom": {
              "secretKeyRef": {
                "name": "api-secrets",
                "key": "api-key"
              }
            }
          }
        ]
      }
    ]
  }
}'
```

```bash
thv run my-server --k8s-pod-patch '{
  "spec": {
    "containers": [
      {
        "name": "mcp",
        "securityContext": {
          "runAsUser": 1000,
          "runAsGroup": 1000,
          "allowPrivilegeEscalation": false
        }
      }
    ]
  }
}'
```

When you provide a JSON patch via the `--k8s-pod-patch` flag:

1. ToolHive creates a base pod template spec
2. The JSON patch is applied to the base template
3. ToolHive then applies its own required configurations (container name, image, command, etc.)
4. The final pod template is used to create a StatefulSet in Kubernetes

This approach allows you to customize the pod template while ensuring that ToolHive's required configurations are still applied.

- The JSON patch must be valid JSON and conform to the Kubernetes pod template spec structure
- The patch is applied before ToolHive's own configurations, so some fields may be overridden by ToolHive
- This feature is only applicable when running ToolHive in a Kubernetes environment
- Always target the container named "mcp" when modifying container-specific settings
- Some container settings like image, command, and args will be overridden by ToolHive's configurations

Signed-off-by: Juan Antonio Osorio <ozz@stacklok.com>