[Gap]: Kubernetes Operator guides gap analysis

[danbarr]

Summary

A systematic comparison of the Kubernetes Operator guides (docs/toolhive/guides-k8s/) against the auto-generated CRD reference (docs/toolhive/reference/crd-spec.md) and the ToolHive operator source code reveals a number of documentation gaps and inaccuracies. This analysis is scoped to the MCPServer CRD and the operator itself - VirtualMCPServer and ToolHiveRegistryServer CRDs are excluded since they have their own guide sections.

Related issues and PRs

• Docs update needed: Document caBundleRef for custom CA certificates in OIDC config #466 - Document caBundleRef for custom CA certificates in OIDC config
• [Bug]: Logging guide: wrong namespace, missing container guidance, outdated shipper examples #625 - Logging guide: wrong namespace, missing container guidance, outdated shipper examples
• Update docs for ToolHive v0.12.3–v0.13.0 #641 - Open PR adding horizontal scaling, session storage for scaling, cross-references to redis guide
• [Gap]: CLI guides gap analysis #654 - Companion CLI guides gap analysis

---

Inaccuracies in existing docs

#	Issue	Location	Details
1	permissionProfile in YAML examples	auth-k8s.mdx (5 instances, lines 103, 189, 253, 494, 682)	This CRD field is not implemented in the operator - it does nothing. Network isolation in K8s is left to users' existing network security / service mesh capabilities. Remove from all examples to avoid implying it has an effect.
2	Deprecated port field in examples	auth-k8s.mdx (lines 102, 188, 252, 682)	4 of 5 auth examples use deprecated port instead of proxyPort. The 5th (line 493) already uses proxyPort.

---

High-priority gaps

#	Gap	Details
1	MCPGroup / groupRef for MCPServer	groupRef on MCPServer is not documented. Only shown for MCPRemoteProxy (remote-mcp-proxy.mdx) and in a generic logging example. No guide for creating an MCPGroup and associating MCPServer resources for vMCP aggregation.
2	Pod restart mechanism	Operator supports mcpserver.toolhive.stacklok.dev/restarted-at annotation with rolling (default) and immediate strategies. Completely undocumented.
3	ResourceOverrides	Override annotations, labels, env vars, and image pull secrets on the proxy Deployment and Service. Not documented.
4	ServiceAccount customization	serviceAccount field to use an existing SA instead of auto-created. run-mcp-k8s.mdx documents auto-created RBAC but not this option.
5	OpenShift support	Operator auto-detects OpenShift and applies appropriate security contexts. Not documented.
6	Inline authorization for MCPServer	auth-k8s.mdx only shows ConfigMap-based Cedar policies for MCPServer. CRD also supports type: inline with policies directly in the spec (shown for MCPRemoteProxy in remote-mcp-proxy.mdx but not for MCPServer).
7	Helm feature flags	features.server, features.registry, features.virtualMCP, features.experimental control which controllers are enabled. deploy-operator.mdx covers CRD group selection but not these operator-level flags.

---

Medium-priority gaps

CRD fields missing from guides

#	Field	Description
1	proxyMode	Proxy mode for stdio transport (sse vs streamable-http)
2	endpointPrefix	Path prefix for SSE endpoint URLs - relevant for path-based ingress but absent from connect-clients.mdx
3	trustProxyHeaders	Trust X-Forwarded-* headers - relevant when behind ingress
4	sessionAffinity	Service session affinity (ClientIP vs None) - only in vMCP scaling guide, not MCPServer guides
5	oidcConfig.resourceUrl	RFC 9728 OAuth resource URL for discovery
6	oidcConfig.kubernetes.useClusterAuth	Use cluster auth paths for JWKS validation
7	Advanced oidcConfig.inline fields	jwksAuthTokenPath, jwksAllowPrivateIP, insecureAllowHTTP, scopes, etc. (partial overlap with #466)
8	telemetry.openTelemetry.headers	Auth headers for OTEL endpoint
9	telemetry.openTelemetry.useLegacyAttributes	Legacy OTEL attribute names

Operator features missing from guides

#	Feature	Description
1	Image validation	Operator validates images against enforced registries; sets ImageValidated condition
2	Status conditions reference	7 condition types (ImageValidated, GroupRefValidated, PodTemplateValid, CABundleRefValidated, ExternalAuthConfigValidated, StdioReplicaCapped, SessionStorageWarning) - not documented as a troubleshooting/operational reference
3	HPA configuration	Helm chart HPA settings (disabled by default); only briefly mentioned in deploy-operator.mdx
4	Operator resource tuning	Go memory tuning (gomemlimit, gogc) in Helm values

---

Lower-priority gaps

#	Gap
1	resourceOverrides sub-fields (proxy env vars, image pull secrets)
2	RunConfig ConfigMap internals and checksum-based rollout
3	Finalizer behavior during cleanup
4	Operator leader election config

---

Deprecated fields in guides

Deprecated	Replacement	Action needed
port	proxyPort	4 examples in auth-k8s.mdx still use deprecated field
targetPort	mcpPort	Audit all K8s guide YAML examples
tools (inline list)	toolConfigRef	customize-tools.mdx already notes this
thvCABundlePath	caBundleRef	Tracked in #466

---

Methodology

This analysis compared three sources:

1. K8s guides in docs/toolhive/guides-k8s/ (13 files)
2. Auto-generated CRD reference in docs/toolhive/reference/crd-spec.md (MCPServer section)
3. ToolHive operator source code (CRD type definitions, controller logic, Helm values)

Out of scope: VirtualMCPServer and ToolHiveRegistryServer CRDs (covered by their own guide sections).