What needs documentation?
The ToolHive Kubernetes operator applies readOnlyRootFilesystem: true by default to the mcp container in MCPServer-managed pods (it only skips this if the user's podTemplateSpec already sets the field explicitly). This default isn't documented anywhere on the site. The Kubernetes operator quickstart now mentions it in passing (as the reason the toolhive-docs.yaml example mounts an emptyDir volume at /tmp), but that's the only place it's asserted, and it's not backed up by the reference guide where podTemplateSpec is actually explained.
Context and references
Confirmed in the operator source:
pkg/container/kubernetes/security.go, BuildContainerSecurityContext() sets ReadOnlyRootFilesystem: ptr.To(true) unconditionally, to satisfy the restricted Pod Security Standard.pkg/container/kubernetes/client.go, configureContainer() applies that default specifically to the container named mcp, filling in the field only when it's not already set in the user's pod template.- Reached via
cmd/thv-operator/controllers/mcpserver_controller.go, which is the control path for the MCPServer CRD.
Relevant doc: docs/toolhive/guides-k8s/run-mcp-k8s.mdx, "Customize the MCP server pod" / "Mount a volume" sections, where podTemplateSpec is documented.
Use case
MCP server images that write to disk (temp files, caches, SQLite databases, etc.) will fail at runtime with a read-only filesystem error unless the user proactively mounts a writable volume (typically emptyDir) via podTemplateSpec. Right now there's no way to know this default exists until you hit that error. Documenting it up front in the reference guide would let readers plan for it instead of debugging it after deployment.
Additional context
Suggest adding a short note near the existing "Mount a volume" section in run-mcp-k8s.mdx describing the default and the emptyDir workaround, with a mention that the field can be overridden explicitly in podTemplateSpec for images that require a writable root filesystem (not recommended, but possible).
What needs documentation?
The ToolHive Kubernetes operator applies
readOnlyRootFilesystem: trueby default to themcpcontainer in MCPServer-managed pods (it only skips this if the user'spodTemplateSpecalready sets the field explicitly). This default isn't documented anywhere on the site. The Kubernetes operator quickstart now mentions it in passing (as the reason thetoolhive-docs.yamlexample mounts anemptyDirvolume at/tmp), but that's the only place it's asserted, and it's not backed up by the reference guide wherepodTemplateSpecis actually explained.Context and references
Confirmed in the operator source:
pkg/container/kubernetes/security.go,BuildContainerSecurityContext()setsReadOnlyRootFilesystem: ptr.To(true)unconditionally, to satisfy the restricted Pod Security Standard.pkg/container/kubernetes/client.go,configureContainer()applies that default specifically to the container namedmcp, filling in the field only when it's not already set in the user's pod template.cmd/thv-operator/controllers/mcpserver_controller.go, which is the control path for theMCPServerCRD.Relevant doc:
docs/toolhive/guides-k8s/run-mcp-k8s.mdx, "Customize the MCP server pod" / "Mount a volume" sections, wherepodTemplateSpecis documented.Use case
MCP server images that write to disk (temp files, caches, SQLite databases, etc.) will fail at runtime with a read-only filesystem error unless the user proactively mounts a writable volume (typically
emptyDir) viapodTemplateSpec. Right now there's no way to know this default exists until you hit that error. Documenting it up front in the reference guide would let readers plan for it instead of debugging it after deployment.Additional context
Suggest adding a short note near the existing "Mount a volume" section in
run-mcp-k8s.mdxdescribing the default and theemptyDirworkaround, with a mention that the field can be overridden explicitly inpodTemplateSpecfor images that require a writable root filesystem (not recommended, but possible).