Custom And Experimental Resources

Nantian Gateway uses standard Gateway API resources for routing. It also understands experimental extension resources when the relevant feature flags and CRDs are installed.

Overview

Resource	API version	Scope	Purpose
`AIService`	`gateway.nantian.dev/v1alpha1`	Namespaced	Configure one AI provider/model target for AI gateway routing.
`TokenPolicy`	`gateway.nantian.dev/v1alpha1`	Namespaced	Attach token and request limits to local Gateway API target resources.
`WasmPlugin`	`gateway.nantian.dev/v1alpha1`	Namespaced	Load a Wasm module and bind it to target resources.
`BackendLBPolicy`	`gateway.networking.k8s.io/v1alpha2`	Namespaced	Configure backend load-balancing strategy and session persistence.

Read Experimental Features before creating these resources.

AIService

AIService configures one AI provider/model target.

Field	Required	Notes
`spec.provider`	Yes	Provider name, such as `openai`, `anthropic`, or `ollama`.
`spec.format`	No	Request/response format hint.
`spec.model`	Yes	Model name used by the provider.
`spec.auth.type`	No	Auth type understood by the runtime.
`spec.auth.secret`	No	Kubernetes Secret name.
`spec.auth.key`	No	Key inside the Secret.
`spec.auth.header`	No	Header used for credentials.
`spec.timeout`	No	Timeout duration string.
`spec.retry.maxRetries`	No	Retry count.
`spec.retry.backoff`	No	Retry backoff duration string.
`spec.observability.langfuse.*`	No	Langfuse integration fields.
`spec.observability.otel.*`	No	OpenTelemetry integration fields.

Example:

apiVersion: gateway.nantian.dev/v1alpha1
kind: AIService
metadata:
  name: openai-gpt4o
  namespace: nantian-demo
spec:
  provider: openai
  format: openai
  model: gpt-4o
  auth:
    type: bearer
    secret: openai-api-key
    key: token
    header: Authorization
  timeout: 60s
  retry:
    maxRetries: 2
    backoff: 500ms

TokenPolicy

TokenPolicy attaches token and request limits to local Gateway API target resources.

Field	Required	Notes
`spec.targetRefs`	Yes	List of `LocalPolicyTargetReference`; `group`, `kind`, and `name` are required.
`spec.tokensPerMinute`	No	Token limit per minute.
`spec.tokensPerHour`	No	Token limit per hour.
`spec.requestsPerMinute`	No	Request limit per minute.
`spec.scope`	No	Scope string interpreted by runtime policy.
`spec.burst`	No	Burst multiplier.
`spec.onLimit`	No	Limit behavior such as `reject`.

Example:

apiVersion: gateway.nantian.dev/v1alpha1
kind: TokenPolicy
metadata:
  name: ai-route-quota
  namespace: nantian-demo
spec:
  targetRefs:
    - group: gateway.networking.k8s.io
      kind: HTTPRoute
      name: ai-route
  tokensPerMinute: 100000
  tokensPerHour: 5000000
  requestsPerMinute: 1000
  scope: route
  burst: 1.5
  onLimit: reject

WasmPlugin

WasmPlugin declares a Wasm source and optional target bindings.

Field	Required	Notes
`spec.wasm`	Yes	Wasm source object.
`spec.wasm.url`	No	URL source for a Wasm module.
`spec.wasm.configMap.name`	No	ConfigMap source name.
`spec.wasm.configMap.key`	No	ConfigMap data key; default behavior depends on translator.
`spec.wasm.inline`	No	Inline base64 module content.
`spec.wasm.sha256`	No	SHA-256 checksum.
`spec.targetRefs`	No	Target refs with `group`, `kind`, and `name`.
`spec.hooks`	No	`onRequest`, `onResponse`, `onStreamChunk`.
`spec.config`	No	Plugin config string.
`spec.sandbox.*`	No	Runtime sandbox limits.

Example:

apiVersion: gateway.nantian.dev/v1alpha1
kind: WasmPlugin
metadata:
  name: request-audit
  namespace: nantian-demo
spec:
  wasm:
    url: https://example.com/plugins/request-audit.wasm
    sha256: 0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef
  targetRefs:
    - group: gateway.networking.k8s.io
      kind: HTTPRoute
      name: echo
  hooks:
    - onRequest
    - onResponse
  config: |
    {"mode":"audit"}
  sandbox:
    maxMemoryBytes: 67108864
    maxExecutionTimeMs: 100
    allowNetwork: false
    allowFileSystem: false

BackendLBPolicy

BackendLBPolicy is a Gateway API experimental policy, not a Nantian API group resource.

Field	Required	Notes
`spec.targetRefs`	Yes	Local policy target refs.
`spec.loadBalancing.type`	No	`RoundRobin`, `ConsistentHash`, `LeastRequest`, or `Random`.
`spec.loadBalancing.consistentHash.keyType`	No	`SourceIP`, `Header`, or `Hostname`.
`spec.loadBalancing.consistentHash.headerName`	No	Required when key type is `Header`.
`spec.sessionPersistence`	No	Gateway API v1alpha2 session persistence object.

Example:

apiVersion: gateway.networking.k8s.io/v1alpha2
kind: BackendLBPolicy
metadata:
  name: echo-lb
  namespace: nantian-demo
spec:
  targetRefs:
    - group: ""
      kind: Service
      name: echo
  loadBalancing:
    type: ConsistentHash
    consistentHash:
      keyType: Header
      headerName: x-session-id

Custom And Experimental Resources

Overview

AIService

TokenPolicy

WasmPlugin

BackendLBPolicy

Next Steps