Experimental Features

Nantian Gateway ships several experimental features that are disabled by default. These APIs are useful for testing AI routing, token policies, Wasm extensions, and experimental Gateway API policies, but their schemas and runtime behavior may change.

Experimental APIs

Enable these features deliberately. Install the required CRDs, select the matching chart feature mode, enable the specific control plane feature flags you need, and test the full route path before relying on experimental behavior.

Feature Flags

Scope	Helm value	Default	Controls
Chart runtime mode	featureMode	standard	Renders standard or experimental Nantian Gateway runtime integration points.
Gateway API CRD rendering	gatewayAPI.installCRDs	false	Controls whether the chart renders official Gateway API CRDs.
Gateway API CRD channel	gatewayAPI.channel	standard	Selects the official standard or experimental CRD bundle when CRD rendering is enabled.
Control plane AI Gateway	controlplane.config.features.enableAiGateway	false	Enables AIService support when featureMode: experimental is also set.

featureMode: experimental renders the experimental Gateway runtime integration points. gatewayAPI.installCRDs and gatewayAPI.channel only control CRD rendering. AI Gateway support is still explicit: set controlplane.config.features.enableAiGateway: true together with featureMode: experimental.

Enable With Helm

Create experimental-values.yaml:

featureMode: experimental
gatewayAPI:
  installCRDs: true
  channel: experimental
controlplane:
  config:
    features:
      enableAiGateway: true

Apply it during install or upgrade:

helm upgrade --install nantian-gw nantian-gw/nantian-gw \
  --namespace nantian-gw \
  --create-namespace \
  -f experimental-values.yaml

Restarted pods should pick up the rendered ConfigMaps. Check logs after the rollout to confirm the release started with the intended feature mode and control plane configuration.

Enable With Kustomize

Kustomize users should edit or replace the ConfigMaps generated by the base manifests. The base gateway/deploy/kubernetes/base/kustomization.yaml uses:

• gateway/configs/controlplane/config.yaml
• gateway/configs/dataplane/config.yaml

Experimental feature gates live in the control plane config. Use this fragment for Kustomize overlays:

features:
  enableExperimentalGateway: true
  enableAiGateway: true

Use an overlay when possible instead of editing base files in-place.

Required CRDs

Install the standard Gateway API CRDs for core resources such as Gateway and HTTPRoute. For experimental resources, you also need the relevant CRDs:

• Gateway API experimental CRDs for BackendLBPolicy.
• Nantian CRDs from the gateway base manifests:
  • aiservices.gateway.nantian.dev
  • tokenpolicies.gateway.nantian.dev
  • wasmplugins.gateway.nantian.dev

The Nantian CRDs are namespaced extension resources under gateway.nantian.dev/v1alpha1. BackendLBPolicy is a Gateway API experimental resource under gateway.networking.k8s.io/v1alpha2.

Verify

Check CRDs first:

kubectl get crd aiservices.gateway.nantian.dev
kubectl get crd tokenpolicies.gateway.nantian.dev
kubectl get crd wasmplugins.gateway.nantian.dev
kubectl get crd backendlbpolicies.gateway.networking.k8s.io

Then check running configuration through logs:

kubectl logs -n nantian-gw deploy/nantian-gw-controlplane --tail=100
kubectl logs -n nantian-gw deploy/nantian-gw-dataplane --tail=100

Missing CRDs cause resource creation failures. Disabled control plane feature flags can make resources unavailable to the manager scheme or prevent AI gateway resources from being accepted.

Use The APIs

After the CRDs and flags are in place, create resources that match the current schemas. Start with Custom And Experimental Resources for examples of AIService, TokenPolicy, WasmPlugin, and BackendLBPolicy.

Feature Stability Roadmap

Experimental features graduate to stable on independent timelines. The table below tracks current status and expected graduation:

Feature	CRD	API Version	Status	Expected Stable
AIService	aiservices.gateway.nantian.dev	v1alpha1	Experimental	TBD
TokenPolicy	tokenpolicies.gateway.nantian.dev	v1alpha1	Experimental	TBD
WasmPlugin	wasmplugins.gateway.nantian.dev	v1alpha1	Experimental	TBD
BackendLBPolicy	backendlbpolicies.gateway.networking.k8s.io	v1alpha2	Upstream experimental	Follows Gateway API
RoutePolicy	routepolicies.gateway.nantian.dev	v1alpha1	Experimental	TBD

Migration from Experimental to Stable

When a feature graduates to stable:

1. The stable CRD version is installed alongside the experimental one
2. Existing experimental resources continue to work during a deprecation window (typically 2 releases)
3. New resources should use the stable API version
4. The experimental CRD and feature flag are removed in a subsequent release

Monitor the changelog for deprecation notices and migration instructions.

Known Limitations

• AIService: Model routing uses round-robin by default. Custom routing strategies require RoutePolicy overrides.
• TokenPolicy: Token counting is approximate for streaming responses. The count may differ from the provider’s billing report.
• WasmPlugin: Plugins run in a single-threaded Wasmtime instance per worker. CPU-intensive plugins impact proxy throughput.
• BackendLBPolicy: Session persistence requires a configured shared secret for multi-replica deployments. Without it, sessions are lost on replica restart.