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.
`RoutePolicy`	`gateway.nantian.dev/v1alpha1`	Namespaced	Configure per-route timeout, body limit, proxy buffering, and connection keepalive.

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.endpoint`	No	Custom provider endpoint or base URL.
`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.
`spec.circuitBreaker.maxInflightRequests`	No	Maximum concurrent inflight requests to the backend; excess requests are rejected.

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

RoutePolicy

RoutePolicy attaches per-route defaults for timeout, body limit, proxy buffering, and connection keepalive to local Gateway API target resources.

Field	Required	Notes
`spec.targetRefs`	Yes	List of `LocalPolicyTargetReference`; `group`, `kind`, and `name` are required.
`spec.default.timeout.request`	No	Timeout for the entire request-response cycle.
`spec.default.timeout.backendRequest`	No	Timeout for a single backend request attempt.
`spec.default.timeout.connect`	No	Timeout to establish a TCP connection to the backend.
`spec.default.timeout.nextUpstream`	No	Time spent finding a viable upstream during retries.
`spec.default.bodyLimit.maxRequestBodyBytes`	No	Maximum request body size in bytes.
`spec.default.bodyLimit.requestBodyBufferBytes`	No	Buffer size for reading the request body before spilling to a temporary file.
`spec.default.bodyLimit.maxRequestHeaderBytes`	No	Maximum combined size of all request headers in bytes.
`spec.default.proxy.requestBuffering`	No	Whether to buffer the client request body before proxying.
`spec.default.proxy.responseBuffering`	No	Whether to buffer the backend response before sending to the client.
`spec.default.proxy.bufferSize`	No	Size of each response buffer in bytes.
`spec.default.proxy.bufferCount`	No	Number of response buffers to allocate.
`spec.default.connection.keepaliveRequests`	No	Maximum requests on a single keepalive client connection.
`spec.default.connection.upstreamKeepalivePoolSize`	No	Maximum idle upstream keepalive connections to maintain in the pool.
`spec.default.connection.keepaliveTime`	No	Maximum lifetime of a keepalive client connection.
`spec.default.connection.keepaliveTimeout`	No	Maximum idle time before closing a keepalive client connection.
`spec.default.connection.upstreamKeepaliveIdle`	No	Maximum idle time before closing an upstream keepalive connection.

Example:

apiVersion: gateway.nantian.dev/v1alpha1
kind: RoutePolicy
metadata:
  name: echo-route-policy
  namespace: nantian-demo
spec:
  targetRefs:
    - group: gateway.networking.k8s.io
      kind: HTTPRoute
      name: echo
  default:
    timeout:
      request: 30s
      backendRequest: 15s
      connect: 2s
      nextUpstream: 5s
    bodyLimit:
      maxRequestBodyBytes: 2097152
      requestBodyBufferBytes: 65536
      maxRequestHeaderBytes: 8192
    proxy:
      requestBuffering: false
      responseBuffering: true
      bufferSize: 16384
      bufferCount: 4
    connection:
      keepaliveRequests: 1000
      upstreamKeepalivePoolSize: 128
      keepaliveTime: 1h
      keepaliveTimeout: 75s
      upstreamKeepaliveIdle: 60s

Custom And Experimental Resources

Overview

AIService

TokenPolicy

WasmPlugin

BackendLBPolicy

RoutePolicy

Next Steps