Soften PrimaryUpstreamProvider docs for non-vMCP CRDs

Tightens the docstrings on the two locations of `PrimaryUpstreamProvider`
to match the actual code paths and addresses F4 (and the cascading F5)
from the multi-agent review on PR #5290.

`EmbeddedAuthServerConfig.PrimaryUpstreamProvider`: previously claimed
that the field was validated against `UpstreamProviders` on MCPServer
and MCPRemoteProxy as well. No code references the field on those
paths: the proxyrunner pipeline does not read it, and the existing
`AuthzPrimaryUpstreamProviderIgnored` advisory inspects only the
legacy inline location. The new docstring says the field is meaningful
only on `VirtualMCPServer`; on single-upstream consumers it is
structurally present (the struct is shared) but silently ignored.

`InlineAuthzConfig.PrimaryUpstreamProvider` (deprecated): the previous
deprecation block named both `spec.authServerConfig.primaryUpstreamProvider`
(canonical on vMCP) and `embeddedAuthServer.primaryUpstreamProvider`
on a referenced `MCPExternalAuthConfig` as canonical replacements,
then immediately said the field is structurally meaningless on
MCPServer/MCPRemoteProxy. Two sentences pointing in opposite
directions. The new block names only the vMCP canonical location and
makes explicit that on MCPServer/MCPRemoteProxy the deprecated form
was always a structural no-op and the deprecation does not change that
behaviour.

No code changes. Regenerated `deepcopy`, CRD YAML, and CRD reference
docs to pick up the docstring updates.

Author: blkt

cmd/thv-operator/api/v1beta1/mcpexternalauthconfig_types.go

@@ -235,10 +235,17 @@ type EmbeddedAuthServerConfig struct {
 	// PrimaryUpstreamProvider names the upstream IDP whose access token Cedar
 	// should read claims from when authorising a request. Must match the name
 	// of one of the entries in UpstreamProviders. When empty, the controller
-	// auto-selects the first entry of UpstreamProviders. Only meaningful when
-	// at least one upstream is configured; on MCPServer and MCPRemoteProxy
-	// (single-upstream consumers) the only validated values are empty or the
-	// name of the sole upstream.
+	// auto-selects the first entry of UpstreamProviders.
+	//
+	// Only meaningful on VirtualMCPServer, where multiple upstream providers
+	// can be configured and Cedar needs to pick which token's claims to
+	// evaluate. The VirtualMCPServer controller validates this field against
+	// UpstreamProviders at admission and rejects unresolvable values.
+	//
+	// On MCPServer and MCPRemoteProxy this field is structurally present (the
+	// EmbeddedAuthServerConfig struct is shared) but has no runtime effect:
+	// those CRDs are restricted to a single upstream so there is no choice to
+	// make. Setting it on those CRDs is silently ignored.
 	// +optional
 	// +kubebuilder:validation:MinLength=1
 	// +kubebuilder:validation:MaxLength=63

cmd/thv-operator/api/v1beta1/mcpserver_types.go

@@ -788,16 +788,17 @@ type InlineAuthzConfig struct {
 	// PrimaryUpstreamProvider names the upstream IDP whose access token's
 	// claims Cedar should evaluate.
 	//
-	// Deprecated: this field has moved to
-	// spec.authServerConfig.primaryUpstreamProvider on VirtualMCPServer (or to
-	// the embeddedAuthServer.primaryUpstreamProvider field of a referenced
-	// MCPExternalAuthConfig for MCPServer and MCPRemoteProxy). The old
-	// location is read for one release for backward compatibility and a
-	// Warning event is emitted whenever it is consumed; planned removal in
-	// the release after the deprecation cycle. On MCPServer and MCPRemoteProxy
-	// the field remains structurally meaningless (no embedded auth server
-	// runtime) and continues to surface the AuthzPrimaryUpstreamProviderIgnored
-	// advisory.
+	// Deprecated: on VirtualMCPServer this field has moved to
+	// spec.authServerConfig.primaryUpstreamProvider. The old location is
+	// still read for one release for backward compatibility; the
+	// VirtualMCPServer controller emits an AuthzPrimaryUpstreamProviderDeprecated
+	// Warning event whenever it is consumed, and removal is planned for the
+	// release after the deprecation cycle.
+	//
+	// On MCPServer and MCPRemoteProxy this field has always been a structural
+	// no-op (those CRDs do not run an embedded auth server). Setting it
+	// continues to surface the AuthzPrimaryUpstreamProviderIgnored advisory
+	// condition; the deprecation does not change that behaviour.
 	// +optional
 	// +kubebuilder:validation:MinLength=1
 	// +kubebuilder:validation:MaxLength=63

deploy/charts/operator-crds/files/crds/toolhive.stacklok.dev_mcpexternalauthconfigs.yaml

@@ -272,10 +272,17 @@ spec:
                       PrimaryUpstreamProvider names the upstream IDP whose access token Cedar
                       should read claims from when authorising a request. Must match the name
                       of one of the entries in UpstreamProviders. When empty, the controller
-                      auto-selects the first entry of UpstreamProviders. Only meaningful when
-                      at least one upstream is configured; on MCPServer and MCPRemoteProxy
-                      (single-upstream consumers) the only validated values are empty or the
-                      name of the sole upstream.
+                      auto-selects the first entry of UpstreamProviders.
+
+                      Only meaningful on VirtualMCPServer, where multiple upstream providers
+                      can be configured and Cedar needs to pick which token's claims to
+                      evaluate. The VirtualMCPServer controller validates this field against
+                      UpstreamProviders at admission and rejects unresolvable values.
+
+                      On MCPServer and MCPRemoteProxy this field is structurally present (the
+                      EmbeddedAuthServerConfig struct is shared) but has no runtime effect:
+                      those CRDs are restricted to a single upstream so there is no choice to
+                      make. Setting it on those CRDs is silently ignored.
                     maxLength: 63
                     minLength: 1
                     pattern: ^[a-z0-9]([a-z0-9-]*[a-z0-9])?$
@@ -1527,10 +1534,17 @@ spec:
                       PrimaryUpstreamProvider names the upstream IDP whose access token Cedar
                       should read claims from when authorising a request. Must match the name
                       of one of the entries in UpstreamProviders. When empty, the controller
-                      auto-selects the first entry of UpstreamProviders. Only meaningful when
-                      at least one upstream is configured; on MCPServer and MCPRemoteProxy
-                      (single-upstream consumers) the only validated values are empty or the
-                      name of the sole upstream.
+                      auto-selects the first entry of UpstreamProviders.
+
+                      Only meaningful on VirtualMCPServer, where multiple upstream providers
+                      can be configured and Cedar needs to pick which token's claims to
+                      evaluate. The VirtualMCPServer controller validates this field against
+                      UpstreamProviders at admission and rejects unresolvable values.
+
+                      On MCPServer and MCPRemoteProxy this field is structurally present (the
+                      EmbeddedAuthServerConfig struct is shared) but has no runtime effect:
+                      those CRDs are restricted to a single upstream so there is no choice to
+                      make. Setting it on those CRDs is silently ignored.
                     maxLength: 63
                     minLength: 1
                     pattern: ^[a-z0-9]([a-z0-9-]*[a-z0-9])?$

deploy/charts/operator-crds/files/crds/toolhive.stacklok.dev_mcpremoteproxies.yaml

@@ -160,16 +160,17 @@ spec:
                           PrimaryUpstreamProvider names the upstream IDP whose access token's
                           claims Cedar should evaluate.
 
-                          Deprecated: this field has moved to
-                          spec.authServerConfig.primaryUpstreamProvider on VirtualMCPServer (or to
-                          the embeddedAuthServer.primaryUpstreamProvider field of a referenced
-                          MCPExternalAuthConfig for MCPServer and MCPRemoteProxy). The old
-                          location is read for one release for backward compatibility and a
-                          Warning event is emitted whenever it is consumed; planned removal in
-                          the release after the deprecation cycle. On MCPServer and MCPRemoteProxy
-                          the field remains structurally meaningless (no embedded auth server
-                          runtime) and continues to surface the AuthzPrimaryUpstreamProviderIgnored
-                          advisory.
+                          Deprecated: on VirtualMCPServer this field has moved to
+                          spec.authServerConfig.primaryUpstreamProvider. The old location is
+                          still read for one release for backward compatibility; the
+                          VirtualMCPServer controller emits an AuthzPrimaryUpstreamProviderDeprecated
+                          Warning event whenever it is consumed, and removal is planned for the
+                          release after the deprecation cycle.
+
+                          On MCPServer and MCPRemoteProxy this field has always been a structural
+                          no-op (those CRDs do not run an embedded auth server). Setting it
+                          continues to surface the AuthzPrimaryUpstreamProviderIgnored advisory
+                          condition; the deprecation does not change that behaviour.
                         maxLength: 63
                         minLength: 1
                         pattern: ^[a-z0-9]([a-z0-9-]*[a-z0-9])?$
@@ -778,16 +779,17 @@ spec:
                           PrimaryUpstreamProvider names the upstream IDP whose access token's
                           claims Cedar should evaluate.
 
-                          Deprecated: this field has moved to
-                          spec.authServerConfig.primaryUpstreamProvider on VirtualMCPServer (or to
-                          the embeddedAuthServer.primaryUpstreamProvider field of a referenced
-                          MCPExternalAuthConfig for MCPServer and MCPRemoteProxy). The old
-                          location is read for one release for backward compatibility and a
-                          Warning event is emitted whenever it is consumed; planned removal in
-                          the release after the deprecation cycle. On MCPServer and MCPRemoteProxy
-                          the field remains structurally meaningless (no embedded auth server
-                          runtime) and continues to surface the AuthzPrimaryUpstreamProviderIgnored
-                          advisory.
+                          Deprecated: on VirtualMCPServer this field has moved to
+                          spec.authServerConfig.primaryUpstreamProvider. The old location is
+                          still read for one release for backward compatibility; the
+                          VirtualMCPServer controller emits an AuthzPrimaryUpstreamProviderDeprecated
+                          Warning event whenever it is consumed, and removal is planned for the
+                          release after the deprecation cycle.
+
+                          On MCPServer and MCPRemoteProxy this field has always been a structural
+                          no-op (those CRDs do not run an embedded auth server). Setting it
+                          continues to surface the AuthzPrimaryUpstreamProviderIgnored advisory
+                          condition; the deprecation does not change that behaviour.
                         maxLength: 63
                         minLength: 1
                         pattern: ^[a-z0-9]([a-z0-9-]*[a-z0-9])?$

deploy/charts/operator-crds/files/crds/toolhive.stacklok.dev_mcpservers.yaml

@@ -167,16 +167,17 @@ spec:
                           PrimaryUpstreamProvider names the upstream IDP whose access token's
                           claims Cedar should evaluate.
 
-                          Deprecated: this field has moved to
-                          spec.authServerConfig.primaryUpstreamProvider on VirtualMCPServer (or to
-                          the embeddedAuthServer.primaryUpstreamProvider field of a referenced
-                          MCPExternalAuthConfig for MCPServer and MCPRemoteProxy). The old
-                          location is read for one release for backward compatibility and a
-                          Warning event is emitted whenever it is consumed; planned removal in
-                          the release after the deprecation cycle. On MCPServer and MCPRemoteProxy
-                          the field remains structurally meaningless (no embedded auth server
-                          runtime) and continues to surface the AuthzPrimaryUpstreamProviderIgnored
-                          advisory.
+                          Deprecated: on VirtualMCPServer this field has moved to
+                          spec.authServerConfig.primaryUpstreamProvider. The old location is
+                          still read for one release for backward compatibility; the
+                          VirtualMCPServer controller emits an AuthzPrimaryUpstreamProviderDeprecated
+                          Warning event whenever it is consumed, and removal is planned for the
+                          release after the deprecation cycle.
+
+                          On MCPServer and MCPRemoteProxy this field has always been a structural
+                          no-op (those CRDs do not run an embedded auth server). Setting it
+                          continues to surface the AuthzPrimaryUpstreamProviderIgnored advisory
+                          condition; the deprecation does not change that behaviour.
                         maxLength: 63
                         minLength: 1
                         pattern: ^[a-z0-9]([a-z0-9-]*[a-z0-9])?$
@@ -1083,16 +1084,17 @@ spec:
                           PrimaryUpstreamProvider names the upstream IDP whose access token's
                           claims Cedar should evaluate.
 
-                          Deprecated: this field has moved to
-                          spec.authServerConfig.primaryUpstreamProvider on VirtualMCPServer (or to
-                          the embeddedAuthServer.primaryUpstreamProvider field of a referenced
-                          MCPExternalAuthConfig for MCPServer and MCPRemoteProxy). The old
-                          location is read for one release for backward compatibility and a
-                          Warning event is emitted whenever it is consumed; planned removal in
-                          the release after the deprecation cycle. On MCPServer and MCPRemoteProxy
-                          the field remains structurally meaningless (no embedded auth server
-                          runtime) and continues to surface the AuthzPrimaryUpstreamProviderIgnored
-                          advisory.
+                          Deprecated: on VirtualMCPServer this field has moved to
+                          spec.authServerConfig.primaryUpstreamProvider. The old location is
+                          still read for one release for backward compatibility; the
+                          VirtualMCPServer controller emits an AuthzPrimaryUpstreamProviderDeprecated
+                          Warning event whenever it is consumed, and removal is planned for the
+                          release after the deprecation cycle.
+
+                          On MCPServer and MCPRemoteProxy this field has always been a structural
+                          no-op (those CRDs do not run an embedded auth server). Setting it
+                          continues to surface the AuthzPrimaryUpstreamProviderIgnored advisory
+                          condition; the deprecation does not change that behaviour.
                         maxLength: 63
                         minLength: 1
                         pattern: ^[a-z0-9]([a-z0-9-]*[a-z0-9])?$