AIPolicy

AIPolicy binds a set of principal matchers (the access list) and a forward-compatible MCP policy to a target AIGateway. It is meant to be edited frequently, so its RBAC is scoped separately from AIGateway and the management API can change policy without touching gateway infrastructure.

API: ai-gateway.stacklok.dev/v1alpha1 · Scope: Namespaced · Short names: aipol

Example

aipolicy.yaml

apiVersion: ai-gateway.stacklok.dev/v1alpha1
kind: AIPolicy
metadata:
  name: my-aipolicy
  namespace: default
spec:
  gatewayRef:
    name: <string>
  principalMatchers:
    - claims: {}

Schema

spec

AIPolicySpec defines the desired state of an AIPolicy.

Field	Type	Description
description	string	Description is a free-form human-readable description of this policy. maxLength 2048
gatewayRefrequired	object	GatewayRef is the AIGateway in the same namespace this policy targets.
mcpPolicy	object	MCPPolicy binds matched principals to a set of MCP servers. Present for forward compatibility; the Phase 8 operator does not enforce MCP access. The field is named mcpPolicy (not allowedMCPServers) so the schema can expand to tool- and resource-level bindings without churn when MCP enforcement lands.
principalMatchersrequired	object[]	PrincipalMatchers identifies the principals this policy applies to. Matchers combine as OR; claims within a matcher combine as AND.

spec.gatewayRef

GatewayRef is the AIGateway in the same namespace this policy targets.

Field	Type	Description
namerequired	string	Name of the referenced resource.

↑ Back to spec

spec.mcpPolicy

MCPPolicy binds matched principals to a set of MCP servers. Present for forward compatibility; the Phase 8 operator does not enforce MCP access. The field is named mcpPolicy (not allowedMCPServers) so the schema can expand to tool- and resource-level bindings without churn when MCP enforcement lands.

Field	Type	Description
servers	string[]	Servers is the list of MCP server names matched principals may use.

↑ Back to spec

spec.principalMatchers[]

PrincipalMatchers identifies the principals this policy applies to. Matchers combine as OR; claims within a matcher combine as AND.

Field	Type	Description
claimsrequired	map<string, string>	Claims maps claim name to the expected value. At least one claim is required.

↑ Back to spec

status

AIPolicyStatus defines the observed state of an AIPolicy.

Field	Type	Description
appliedToSecurityPolicy	string	AppliedToSecurityPolicy is the name of the SecurityPolicy into which this policy's authorization rules were fanned out.
conditions	object[]	Conditions represent the latest available observations of the AIPolicy's state.
observedGeneration	integer	ObservedGeneration is the most recent generation observed by the controller. format int64

status.conditions[]

Conditions represent the latest available observations of the AIPolicy's state.

Field	Type	Description
lastTransitionTimerequired	string	lastTransitionTime is the last time the condition transitioned from one status to another. This should be when the underlying condition changed. If that is not known, then using the time when the API field changed is acceptable. format date-time
messagerequired	string	message is a human readable message indicating details about the transition. This may be an empty string. maxLength 32768
observedGeneration	integer	observedGeneration represents the .metadata.generation that the condition was set based upon. For instance, if .metadata.generation is currently 12, but the .status.conditions[x].observedGeneration is 9, the condition is out of date with respect to the current state of the instance. format int64 · min 0
reasonrequired	string	reason contains a programmatic identifier indicating the reason for the condition's last transition. Producers of specific condition types may define expected values and meanings for this field, and whether the values are considered a guaranteed API. The value should be a CamelCase string. This field may not be empty. pattern ^[A-Za-z]([A-Za-z0-9_,:]*[A-Za-z0-9_])?$ · minLength 1 · maxLength 1024
statusrequired	string	status of the condition, one of True, False, Unknown. enum: True | False | Unknown
typerequired	string	type of condition in CamelCase or in foo.example.com/CamelCase. pattern ^([a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*/)?(([A-Za-z0-9][-A-Za-z0-9_.]*)?[A-Za-z0-9])$ · maxLength 316

↑ Back to status

Related resources

References:

• AIGateway - via spec.gatewayRef