From be487eddcdc41d0537513c67937d77905df037ba Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" <41898282+github-actions[bot]@users.noreply.github.com> Date: Thu, 18 Dec 2025 13:04:04 +0000 Subject: [PATCH] Update ToolHive reference docs for toolhive-operator-crds-0.0.88 --- static/api-specs/toolhive-crd-api.md | 83 ++++++++++++++++++++++++++++ 1 file changed, 83 insertions(+) diff --git a/static/api-specs/toolhive-crd-api.md b/static/api-specs/toolhive-crd-api.md index 743d4de..598fb94 100644 --- a/static/api-specs/toolhive-crd-api.md +++ b/static/api-specs/toolhive-crd-api.md @@ -116,6 +116,7 @@ AuditConfig defines audit logging configuration for the MCP server _Appears in:_ - [MCPRemoteProxySpec](#mcpremoteproxyspec) - [MCPServerSpec](#mcpserverspec) +- [VirtualMCPServerSpec](#virtualmcpserverspec) | Field | Description | Default | Validation | | --- | --- | --- | --- | @@ -740,6 +741,40 @@ _Appears in:_ | `status` _[MCPRegistryStatus](#mcpregistrystatus)_ | | | | +#### MCPRegistryAuthConfig + + + +MCPRegistryAuthConfig defines authentication configuration for the registry API server. + + + +_Appears in:_ +- [MCPRegistrySpec](#mcpregistryspec) + +| Field | Description | Default | Validation | +| --- | --- | --- | --- | +| `mode` _[MCPRegistryAuthMode](#mcpregistryauthmode)_ | Mode specifies the authentication mode (anonymous or oauth)
Defaults to "anonymous" if not specified.
Use "oauth" to enable OAuth/OIDC authentication. | anonymous | Enum: [anonymous oauth]
| +| `oauth` _[MCPRegistryOAuthConfig](#mcpregistryoauthconfig)_ | OAuth defines OAuth/OIDC specific authentication settings
Only used when Mode is "oauth" | | | + + +#### MCPRegistryAuthMode + +_Underlying type:_ _string_ + +MCPRegistryAuthMode represents the authentication mode for the registry API server + + + +_Appears in:_ +- [MCPRegistryAuthConfig](#mcpregistryauthconfig) + +| Field | Description | +| --- | --- | +| `anonymous` | MCPRegistryAuthModeAnonymous allows unauthenticated access
| +| `oauth` | MCPRegistryAuthModeOAuth enables OAuth/OIDC authentication
| + + #### MCPRegistryConfig @@ -810,6 +845,52 @@ MCPRegistryList contains a list of MCPRegistry | `items` _[MCPRegistry](#mcpregistry) array_ | | | | +#### MCPRegistryOAuthConfig + + + +MCPRegistryOAuthConfig defines OAuth/OIDC specific authentication settings + + + +_Appears in:_ +- [MCPRegistryAuthConfig](#mcpregistryauthconfig) + +| Field | Description | Default | Validation | +| --- | --- | --- | --- | +| `resourceUrl` _string_ | ResourceURL is the URL identifying this protected resource (RFC 9728)
Used in the /.well-known/oauth-protected-resource endpoint | | | +| `providers` _[MCPRegistryOAuthProviderConfig](#mcpregistryoauthproviderconfig) array_ | Providers defines the OAuth/OIDC providers for authentication
Multiple providers can be configured (e.g., Kubernetes + external IDP) | | MinItems: 1
| +| `scopesSupported` _string array_ | ScopesSupported defines the OAuth scopes supported by this resource (RFC 9728)
Defaults to ["mcp-registry:read", "mcp-registry:write"] if not specified | | | +| `realm` _string_ | Realm is the protection space identifier for WWW-Authenticate header (RFC 7235)
Defaults to "mcp-registry" if not specified | | | + + +#### MCPRegistryOAuthProviderConfig + + + +MCPRegistryOAuthProviderConfig defines configuration for an OAuth/OIDC provider + + + +_Appears in:_ +- [MCPRegistryOAuthConfig](#mcpregistryoauthconfig) + +| Field | Description | Default | Validation | +| --- | --- | --- | --- | +| `name` _string_ | Name is a unique identifier for this provider (e.g., "kubernetes", "keycloak") | | MinLength: 1
Required: \{\}
| +| `issuerUrl` _string_ | IssuerURL is the OIDC issuer URL (e.g., https://accounts.google.com)
The JWKS URL will be discovered automatically from .well-known/openid-configuration
unless JwksUrl is explicitly specified | | MinLength: 1
Pattern: `^https?://.*`
Required: \{\}
| +| `jwksUrl` _string_ | JwksUrl is the URL to fetch the JSON Web Key Set (JWKS) from
If specified, OIDC discovery is skipped and this URL is used directly
Example: https://kubernetes.default.svc/openid/v1/jwks | | Pattern: `^https?://.*`
| +| `audience` _string_ | Audience is the expected audience claim in the token (REQUIRED)
Per RFC 6749 Section 4.1.3, tokens must be validated against expected audience
For Kubernetes, this is typically the API server URL | | MinLength: 1
Required: \{\}
| +| `clientId` _string_ | ClientID is the OAuth client ID for token introspection (optional) | | | +| `clientSecretRef` _[SecretKeySelector](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.27/#secretkeyselector-v1-core)_ | ClientSecretRef is a reference to a Secret containing the client secret
The secret should have a key "clientSecret" containing the secret value | | | +| `caCertRef` _[ConfigMapKeySelector](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.27/#configmapkeyselector-v1-core)_ | CACertRef is a reference to a ConfigMap containing the CA certificate bundle
for verifying the provider's TLS certificate.
Required for Kubernetes in-cluster authentication or self-signed certificates | | | +| `caCertPath` _string_ | CaCertPath is the path to the CA certificate bundle for verifying the provider's TLS certificate.
Required for Kubernetes in-cluster authentication or self-signed certificates | | | +| `authTokenRef` _[SecretKeySelector](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.27/#secretkeyselector-v1-core)_ | AuthTokenRef is a reference to a Secret containing a bearer token for authenticating
to OIDC/JWKS endpoints. Useful when the OIDC discovery or JWKS endpoint requires authentication.
Example: ServiceAccount token for Kubernetes API server | | | +| `authTokenFile` _string_ | AuthTokenFile is the path to a file containing a bearer token for authenticating to OIDC/JWKS endpoints.
Useful when the OIDC discovery or JWKS endpoint requires authentication.
Example: /var/run/secrets/kubernetes.io/serviceaccount/token | | | +| `introspectionUrl` _string_ | IntrospectionURL is the OAuth 2.0 Token Introspection endpoint (RFC 7662)
Used for validating opaque (non-JWT) tokens
If not specified, only JWT tokens can be validated via JWKS | | Pattern: `^https?://.*`
| +| `allowPrivateIP` _boolean_ | AllowPrivateIP allows JWKS/OIDC endpoints on private IP addresses
Required when the OAuth provider (e.g., Kubernetes API server) is running on a private network
Example: Set to true when using https://kubernetes.default.svc as the issuer URL | false | | + + #### MCPRegistryPhase _Underlying type:_ _string_ @@ -849,6 +930,7 @@ _Appears in:_ | `enforceServers` _boolean_ | EnforceServers indicates whether MCPServers in this namespace must have their images
present in at least one registry in the namespace. When any registry in the namespace
has this field set to true, enforcement is enabled for the entire namespace.
MCPServers with images not found in any registry will be rejected.
When false (default), MCPServers can be deployed regardless of registry presence. | false | | | `podTemplateSpec` _[RawExtension](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.27/#rawextension-runtime-pkg)_ | PodTemplateSpec defines the pod template to use for the registry API server
This allows for customizing the pod configuration beyond what is provided by the other fields.
Note that to modify the specific container the registry API server runs in, you must specify
the `registry-api` container name in the PodTemplateSpec.
This field accepts a PodTemplateSpec object as JSON/YAML. | | Type: object
| | `databaseConfig` _[MCPRegistryDatabaseConfig](#mcpregistrydatabaseconfig)_ | DatabaseConfig defines the PostgreSQL database configuration for the registry API server.
If not specified, defaults will be used:
- Host: "postgres"
- Port: 5432
- User: "db_app"
- MigrationUser: "db_migrator"
- Database: "registry"
- SSLMode: "prefer"
- MaxOpenConns: 10
- MaxIdleConns: 2
- ConnMaxLifetime: "30m" | | | +| `authConfig` _[MCPRegistryAuthConfig](#mcpregistryauthconfig)_ | AuthConfig defines the authentication configuration for the registry API server.
If not specified, defaults to anonymous authentication. | | | #### MCPRegistryStatus @@ -1999,6 +2081,7 @@ _Appears in:_ | `serviceType` _string_ | ServiceType specifies the Kubernetes service type for the Virtual MCP server | ClusterIP | Enum: [ClusterIP NodePort LoadBalancer]
| | `podTemplateSpec` _[RawExtension](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.27/#rawextension-runtime-pkg)_ | PodTemplateSpec defines the pod template to use for the Virtual MCP server
This allows for customizing the pod configuration beyond what is provided by the other fields.
Note that to modify the specific container the Virtual MCP server runs in, you must specify
the 'vmcp' container name in the PodTemplateSpec.
This field accepts a PodTemplateSpec object as JSON/YAML. | | Type: object
| | `telemetry` _[TelemetryConfig](#telemetryconfig)_ | Telemetry configures OpenTelemetry-based observability for the Virtual MCP server
including distributed tracing, OTLP metrics export, and Prometheus metrics endpoint | | | +| `audit` _[AuditConfig](#auditconfig)_ | Audit configures audit logging for the Virtual MCP server
When enabled, audit logs include MCP protocol operations | | | #### VirtualMCPServerStatus