API Reference¶
Packages¶
agentic.networking.x-k8s.io/v0alpha0¶
Resource Types¶
AccessPolicySpec¶
AccessPolicySpec defines the desired state of AccessPolicy.
Appears in: - XAccessPolicy
| Field | Description | Default | Validation |
|---|---|---|---|
targetRefs LocalPolicyTargetReferenceWithSectionName array |
TargetRefs specifies the targets of the AccessPolicy. An AccessPolicy must target at least one resource. |
MaxItems: 10 MinItems: 1 Required: {} |
|
rules AccessRule array |
Rules defines a list of rules to be applied to the target. An AccessPolicy must have at least one rule. |
MaxItems: 10 MinItems: 1 Required: {} |
AccessPolicyStatus¶
AccessPolicyStatus defines the observed state of AccessPolicy.
Appears in: - XAccessPolicy
| Field | Description | Default | Validation |
|---|---|---|---|
ancestors PolicyAncestorStatus array |
Ancestors is a list of ancestor resources (usually Backend) that are associated with the policy, and the status of the policy with respect to each ancestor. This field is inherited from the Gateway API Policy status definition. For more details, see the upstream documentation: https://gateway-api.sigs.k8s.io/reference/spec/#policyancestorstatus |
MaxItems: 16 Required: {} |
AccessRule¶
AccessRule specifies an authorization rule for the targeted backend. If the tool list is empty, the rule denies access to all tools from Source.
Appears in: - AccessPolicySpec
| Field | Description | Default | Validation |
|---|---|---|---|
name string |
Name specifies the name of the rule. | MaxLength: 63 MinLength: 1 Pattern: ^[a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*$ Required: {} |
|
source Source |
Source specifies the source of the request. | Required: {} |
|
authorization AuthorizationRule |
Authorization specifies the authorization rule to be applied to requests from the source. | Optional: {} |
AuthorizationRule¶
Appears in: - AccessRule
| Field | Description | Default | Validation |
|---|---|---|---|
type AuthorizationRuleType |
Enum: [InlineTools ExternalAuth] Required: {} |
||
tools string array |
Tools specifies a list of tools inline. | Optional: {} |
|
externalAuth HTTPExternalAuthFilter |
ExternalAuth specifies an external auth filter to be used for authorization. Support: Extended |
Optional: {} |
AuthorizationRuleType¶
Underlying type: string
AuthorizationRuleType identifies a type of authorization rule.
Validation: - Enum: [InlineTools ExternalAuth]
Appears in: - AuthorizationRule
| Field | Description |
|---|---|
InlineTools |
AuthorizationRuleTypeInlineTools is used to identify authorization rules declared as an inline list of authorized tools. |
ExternalAuth |
AuthorizationRuleTypeExternalAuth is used to identify authorization rules evaluated by an external auth service. |
AuthorizationSourceSPIFFE¶
Underlying type: string
Validation:
- Pattern: ^spiffe://[a-z0-9._-]+(?:/[A-Za-z0-9._-]+)*$
Appears in: - Source
AuthorizationSourceServiceAccount¶
Appears in: - Source
| Field | Description | Default | Validation |
|---|---|---|---|
namespace string |
Namespace is the namespace of the ServiceAccount If not specified, current namespace (the namespace of the policy) is used. |
Optional: {} |
|
name string |
Name is the name of the ServiceAccount. | Required: {} |
AuthorizationSourceType¶
Underlying type: string
AuthorizationSourceType identifies a type of source for authorization.
Validation: - Enum: [ServiceAccount SPIFFE]
Appears in: - Source
| Field | Description |
|---|---|
SPIFFE |
AuthorizationSourceTypeSPIFFE is used to identify a request matches a SPIFFE Identity. |
ServiceAccount |
AuthorizationSourceTypeServiceAccount is used to identify a request matches a ServiceAccount from within the cluster. |
BackendSpec¶
BackendSpec defines the desired state of Backend.
Appears in: - XBackend
| Field | Description | Default | Validation |
|---|---|---|---|
mcp MCPBackend |
MCP defines a MCP backend. | ExactlyOneOf: [serviceName hostname] Required: {} |
BackendStatus¶
BackendStatus defines the observed state of Backend.
Appears in: - XBackend
| Field | Description | Default | Validation |
|---|---|---|---|
conditions Condition array |
conditions represent the current state of the Backend resource. Each condition has a unique type and reflects the status of a specific aspect of the resource. Standard condition types include: - "Available": the resource is fully functional - "Progressing": the resource is being created or updated - "Degraded": the resource failed to reach or maintain its desired state The status of each condition is one of True, False, or Unknown. |
Optional: {} |
MCPBackend¶
MCPBackend describes a MCP Backend. ServiceName and Hostname cannot be defined at the same time.
Validation: - ExactlyOneOf: [serviceName hostname]
Appears in: - BackendSpec
| Field | Description | Default | Validation |
|---|---|---|---|
serviceName string |
ServiceName defines the Kubernetes Service name of a MCP backend. | Optional: {} |
|
hostname string |
Hostname defines the hostname of the external MCP service to connect to. | Optional: {} |
|
port integer |
Port defines the port of the backend endpoint. | Maximum: 65535 Minimum: 1 Required: {} |
|
path string |
Path is the URL path of the MCP backend for MCP traffic. A MCP backend may serve both MCP traffic and non-MCP traffic. If not specified, the default is /mcp. |
/mcp | Optional: {} |
Source¶
Source specifies the source of a request.
Type must be set to indicate the type of source type. Similarly, either SPIFFE or Serviceaccount can be set based on the type.
Appears in: - AccessRule
| Field | Description | Default | Validation |
|---|---|---|---|
type AuthorizationSourceType |
Enum: [ServiceAccount SPIFFE] Required: {} |
||
spiffe AuthorizationSourceSPIFFE |
spiffe specifies an identity that is matched by this rule. spiffe identities must be specified as SPIFFE-formatted URIs following the pattern: spiffe:// The exact workload identifier structure is implementation-specific. This will likely change in the future. SPIFFE identities for authorization can be derived in various ways by the underlying implementation. Common methods include: - From peer mTLS certificates: The identity is extracted from the client's mTLS certificate presented during connection establishment. - From IP-to-identity mappings: The implementation might maintain a dynamic mapping between source IP addresses (pod IPs) and their associated identities (e.g., Service Account, SPIFFE IDs). - From JWTs or other request-level authentication tokens. |
Pattern: ^spiffe://[a-z0-9._-]+(?:/[A-Za-z0-9._-]+)*$ Optional: {} |
|
serviceAccount AuthorizationSourceServiceAccount |
serviceAccount specifies a Kubernetes Service Account that is matched by this rule. A request originating from a pod associated with this Service Account will match the rule. The Service Account listed here is expected to exist within the same trust domain as the targeted workload. Cross-trust-domain access should instead be expressed using the SPIFFE field. |
Optional: {} |
XAccessPolicy¶
XAccessPolicy is the Schema for the accesspolicies API.
| Field | Description | Default | Validation |
|---|---|---|---|
apiVersion string |
agentic.networking.x-k8s.io/v0alpha0 |
||
kind string |
XAccessPolicy |
||
metadata ObjectMeta |
Refer to Kubernetes API documentation for fields of metadata. |
Optional: {} |
|
spec AccessPolicySpec |
spec defines the desired state of AccessPolicy. | Required: {} |
|
status AccessPolicyStatus |
status defines the observed state of AccessPolicy. | Optional: {} |
XBackend¶
XBackend is the Schema for the backends API.
| Field | Description | Default | Validation |
|---|---|---|---|
apiVersion string |
agentic.networking.x-k8s.io/v0alpha0 |
||
kind string |
XBackend |
||
metadata ObjectMeta |
Refer to Kubernetes API documentation for fields of metadata. |
Optional: {} |
|
spec BackendSpec |
spec defines the desired state of Backend. | Required: {} |
|
status BackendStatus |
status defines the observed state of Backend. | Optional: {} |
agentic.networking.x-k8s.io/v1alpha1¶
Resource Types¶
AccessPolicyActionType¶
Underlying type: string
AccessPolicyActionType identifies a type of action for access policy.
Validation: - Enum: [Allow ExternalAuth]
Appears in: - AccessPolicySpec
| Field | Description |
|---|---|
Allow |
ActionTypeAllow is used to identify that the request should be allowed if rules match. |
ExternalAuth |
ActionTypeExternalAuth is used to identify that the request should be delegated to an external auth service if rules match. |
AccessPolicySpec¶
AccessPolicySpec defines the desired state of AccessPolicy.
Implementations SHOULD return a regular HTTP formatted response if the policy is enforced against non-MCP traffic. Implementations MAY return a JSON-RPC formatted response if the policy is enforced against MCP traffic.
Appears in: - XAccessPolicy
| Field | Description | Default | Validation |
|---|---|---|---|
targetRefs LocalPolicyTargetReferenceWithSectionName array |
TargetRefs specifies the targets of the AccessPolicy. An AccessPolicy must target at least one resource. There is one kind of TargetRef with "Core" support: * Gateway This API may be extended in the future to support additional kinds of targetRefs. Implementations may support additional kinds in an implementation specific manner. |
MaxItems: 10 MinItems: 1 Required: {} |
|
action AccessPolicyActionType |
Action specifies the action to be taken when rules match. Evaluation logic: 1. ExternalAuth runs before all other Allow policies. 2. If an ExternalAuth server denies the request, the request is denied. 3. If it allows the request, processing continues for all other allow policies for that target. 4. The request is allowed only if all allow policies allow it. |
Enum: [Allow ExternalAuth] Required: {} |
|
externalAuth HTTPExternalAuthFilter |
ExternalAuth specifies an external auth filter to be used for authorization. Core support is limited to 1 ExternalAuth callout per target. |
Optional: {} |
|
rules AccessRule array |
Rules defines a list of rules to be applied to the target. An AccessPolicy must have at least one rule. |
MaxItems: 10 MinItems: 1 Required: {} |
AccessPolicyStatus¶
AccessPolicyStatus defines the observed state of AccessPolicy.
Appears in: - XAccessPolicy
| Field | Description | Default | Validation |
|---|---|---|---|
ancestors PolicyAncestorStatus array |
MaxItems: 16 Required: {} |
AccessRule¶
AccessRule specifies an authorization rule for a specified target.
Appears in: - AccessPolicySpec
| Field | Description | Default | Validation |
|---|---|---|---|
name string |
Name specifies the name of the rule. This follows the DNS Subdomain naming convention. See: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#dns-subdomain-names |
MaxLength: 63 MinLength: 1 Pattern: ^[a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*$ Required: {} |
|
source AccessRuleSource |
Source specifies the source of the request. | Required: {} |
|
authorization AuthorizationRule |
Authorization specifies the authorization rule to be applied to requests from the source. If omitted, all access from the specified source is allowed. |
Optional: {} |
AccessRuleSource¶
AccessRuleSource specifies the source of a request.
Type must be set to indicate the source type. Similarly, either SPIFFE or Serviceaccount can be set based on the type.
Appears in: - AccessRule
| Field | Description | Default | Validation |
|---|---|---|---|
type AuthorizationSourceType |
Enum: [ServiceAccount SPIFFE] Required: {} |
||
spiffe AuthorizationSourceSPIFFE |
spiffe specifies an identity that is matched by this rule. spiffe identities must be specified as SPIFFE-formatted URIs following the pattern: spiffe:// The exact workload identifier structure is implementation-specific. This will likely change in the future. SPIFFE identities for authorization can be derived in various ways by the underlying implementation. Common methods include: - From peer mTLS certificates: The identity is extracted from the client's mTLS certificate presented during connection establishment. - From IP-to-identity mappings: The implementation might maintain a dynamic mapping between source IP addresses (pod IPs) and their associated identities (e.g., Service Account, SPIFFE IDs). - From JWTs or other request-level authentication tokens. |
Pattern: ^spiffe://[a-z0-9._-]+(?:/[A-Za-z0-9._-]+)*$ Optional: {} |
|
serviceAccount AuthorizationSourceServiceAccount |
serviceAccount specifies a Kubernetes Service Account that is matched by this rule. A request originating from a pod associated with this Service Account will match the rule. The Service Account listed here is expected to exist within the same trust domain as the targeted workload. Cross-trust-domain access should instead be expressed using the SPIFFE field. |
Optional: {} |
AuthorizationRule¶
AuthorizationRule defines the specific authorization criteria that requests must meet.
Appears in: - AccessRule
| Field | Description | Default | Validation |
|---|---|---|---|
type AuthorizationRuleType |
Enum: [Inline] Required: {} |
||
mcp MCPAttributes |
MCP defines MCP-specific matching criteria. If omitted, the policy does not check MCP-level parameters, allowing all MCP traffic that successfully passes through the matched HTTP routing envelope. |
Optional: {} |
AuthorizationRuleType¶
Underlying type: string
AuthorizationRuleType identifies a type of authorization rule.
Validation: - Enum: [Inline]
Appears in: - AuthorizationRule
| Field | Description |
|---|---|
Inline |
AuthorizationRuleTypeInline is used to identify authorization rules declared as attributes inside the policy (inline) |
AuthorizationSourceSPIFFE¶
Underlying type: string
Validation:
- Pattern: ^spiffe://[a-z0-9._-]+(?:/[A-Za-z0-9._-]+)*$
Appears in: - AccessRuleSource
AuthorizationSourceServiceAccount¶
Appears in: - AccessRuleSource
| Field | Description | Default | Validation |
|---|---|---|---|
namespace string |
Namespace is the namespace of the ServiceAccount If not specified, current namespace (the namespace of the policy) is used. |
Optional: {} |
|
name string |
Name is the name of the ServiceAccount. | Required: {} |
AuthorizationSourceType¶
Underlying type: string
AuthorizationSourceType identifies a type of source for authorization.
Validation: - Enum: [ServiceAccount SPIFFE]
Appears in: - AccessRuleSource
| Field | Description |
|---|---|
SPIFFE |
AuthorizationSourceTypeSPIFFE is used to identify a request matches a SPIFFE Identity. |
ServiceAccount |
AuthorizationSourceTypeServiceAccount is used to identify a request matches a ServiceAccount from within the cluster. |
MCPAttributes¶
MCPAttributes defines the protocol-specific attributes for MCP authorization.
Appears in: - AuthorizationRule
| Field | Description | Default | Validation |
|---|---|---|---|
methods MCPMethod array |
Methods is a list of specific MCP functional methods to match. If specified, only MCP requests with a method that matches one of these items will be authorized. If empty or omitted, no method-level allowlisting is applied, meaning all MCP methods (e.g., all tools, prompts, and resources) are permitted. |
MaxItems: 10 Optional: {} |
MCPMethod¶
MCPMethod defines a specific MCP method and its associated parameters.
Appears in: - MCPAttributes
| Field | Description | Default | Validation |
|---|---|---|---|
name MCPMethodName |
Name is the MCP method to match against (e.g., 'tools/call'). Allowed values: 1. 'tools', 'prompts', 'resources': Matches all sub-methods under these categories. 2. 'prompts/list', 'tools/list', 'resources/list', 'resources/templates/list'. 3. 'prompts/get', 'tools/call', 'resources/subscribe', 'resources/unsubscribe', 'resources/read'. Parameters cannot be specified for categories 1 and 2. |
Enum: [tools prompts resources prompts/list tools/list resources/list resources/templates/list prompts/get tools/call resources/subscribe resources/unsubscribe resources/read] Required: {} |
|
params MCPMethodParam array |
Params allows matching against specific arguments in the MCP request. Only valid for 'get', 'call', 'subscribe', 'unsubscribe', and 'read' methods. If empty or omitted, parameter-level allowlisting is not applied, meaning the method is authorized regardless of the arguments passed in the request. |
MaxItems: 10 MaxLength: 20 Optional: {} |
MCPMethodName¶
Underlying type: string
MCPMethodName defines the allowed MCP methods for matching.
Validation: - Enum: [tools prompts resources prompts/list tools/list resources/list resources/templates/list prompts/get tools/call resources/subscribe resources/unsubscribe resources/read]
Appears in: - MCPMethod
MCPMethodParam¶
Underlying type: string
Validation: - MaxLength: 20
Appears in: - MCPMethod
XAccessPolicy¶
XAccessPolicy is the Schema for the accesspolicies API.
| Field | Description | Default | Validation |
|---|---|---|---|
apiVersion string |
agentic.networking.x-k8s.io/v1alpha1 |
||
kind string |
XAccessPolicy |
||
metadata ObjectMeta |
Refer to Kubernetes API documentation for fields of metadata. |
Optional: {} |
|
spec AccessPolicySpec |
spec defines the desired state of AccessPolicy. | Required: {} |
|
status AccessPolicyStatus |
status defines the observed state of AccessPolicy. | Optional: {} |