Helm Installation

The Helm chart is the recommended way to install Nantian Gateway. It packages the control plane, data plane, dashboard, RBAC, NetworkPolicies, services, ConfigMaps, and the default GatewayClass into one release.

Prerequisites

Install the Gateway API standard CRDs first:

kubectl apply -f https://github.com/kubernetes-sigs/gateway-api/releases/download/v1.5.1/standard-install.yaml
kubectl get crd gateways.gateway.networking.k8s.io

You also need Helm 3.x and kubectl access to the target cluster.

Add The Chart Repository

Use the current chart repository URL:

helm repo add nantian-gw https://chart.nantian.dev
helm repo update

Do not use the legacy plural chart host.

Stable chart versions are shown by default. Per-commit snapshot charts are published as prerelease versions such as 0.2.3-<git-sha>, so include --devel when you need to inspect or install those versions:

helm search repo nantian-gw/nantian-gw --versions --devel

Recommended Helm Workflow

For repeatable environments, prefer a render-first workflow with persistent values files:

helm show values nantian-gw/nantian-gw > values-reference.yaml
helm template nantian-gw nantian-gw/nantian-gw \
  --namespace nantian-gw \
  -f my-values.yaml > rendered.yaml
helm upgrade --install nantian-gw nantian-gw/nantian-gw \
  --namespace nantian-gw \
  --create-namespace \
  -f my-values.yaml

Use helm upgrade --install even for the first deployment so the same command works for both initial rollout and subsequent updates. Prefer layered values files over long --set chains when the change needs to live beyond one terminal session.

When you change CRD ownership, TLS, admin auth, or network policies, render manifests before rollout and review the diff with your normal change process. For recommended values file structure, see Helm Values Guide.

Install With Defaults

helm upgrade --install nantian-gw nantian-gw/nantian-gw \
  --namespace nantian-gw \
  --create-namespace

The default release creates namespace nantian-gw, two control plane replicas, two data plane replicas, one dashboard replica, the fixed services listed in the installation overview, and a GatewayClass named nantian-gw.

Preview the rendered manifests before installing:

helm template nantian-gw nantian-gw/nantian-gw \
  --namespace nantian-gw > rendered.yaml
helm upgrade --install nantian-gw nantian-gw/nantian-gw \
  --namespace nantian-gw \
  --create-namespace \
  --dry-run

Key Default Values

These snippets match the current chart defaults.

Feature Mode And Gateway API CRDs

featureMode: standard
gatewayAPI:
  installCRDs: false
  channel: standard

featureMode controls Nantian Gateway runtime feature gates. gatewayAPI.installCRDs controls whether this chart renders official Gateway API CRDs. The production default keeps runtime mode standard and expects Gateway API CRDs to be managed before install.

Global And GatewayClass

global:
  imageRegistry: "ghcr.io"
  imagePullSecrets: []
  commonLabels: {}

gatewayClass:
  enabled: true
  controllerName: "gateway.networking.k8s.io/nantian-gw"

The chart derives the default GatewayClass name from the controller name, so gateway.networking.k8s.io/nantian-gw becomes nantian-gw.

Control Plane

controlplane:
  enabled: true
  replicas: 2
  image:
    repository: "nantian-gw/nantian-controlplane"
    tag: "latest"
    pullPolicy: IfNotPresent
  config:
    grpcAddr: ":18080"
    adminAddr: ":18081"
    metricsAddr: ":18082"
    healthProbeAddr: ":18083"
    features:
      enableExperimentalGateway: false
      enableAiGateway: false

The chart pins an immutable release tag (v2026.06.0) with pullPolicy: IfNotPresent by default. In production, override this with a specific release tag or an image digest in your values file.

The control plane service split is:

Service	Port
nantian-gw-controlplane-grpc	18080
nantian-gw-controlplane-admin	18081
nantian-gw-controlplane-metrics	18082

Data Plane

dataplane:
  enabled: true
  replicas: 2
  image:
    repository: "nantian-gw/dataplane"
    tag: "latest"
    pullPolicy: IfNotPresent
  resources:
    requests:
      cpu: "1000m"
      memory: "256Mi"
    limits:
      cpu: "2000m"
      memory: "1Gi"
  config:
    adminAddr: "0.0.0.0:19080"
    runtime:
      httpListenAddr: "0.0.0.0:80"
  accessLogVolume:
    enabled: true
    name: access-logs
    mountPath: /var/log/nantian-gw
    sizeLimit: 256Mi

The data plane services are nantian-gw-dataplane-admin and nantian-gw-dataplane-metrics; both use service port 19080. Runtime HTTP traffic is handled by the configured listener 0.0.0.0:80.

For Kubernetes installs, the chart injects NANTIAN_GW_NODE_ID from Pod metadata.name, so each replica gets a unique runtime nodeId even though dataplane.config.nodeId still defaults to dp-kubernetes as a fallback. If you install from older manifests, verify they do not override this with a fixed value or the obsolete PGW_NODE_ID variable.

When you run more than one data plane replica, configure stable session-persistence secrets instead of relying on the runtime’s auto-generated key:

dataplane:
  sessionPersistence:
    existingSecret: nantian-gw-dataplane-session-persistence
    secretKey: session-persistence

dataplane.sessionPersistence.sharedSecret is acceptable for quick tests, but production environments should prefer existingSecret. When either value is set, the chart mounts the Secret and wires the dataplane runtime sessionPersistence.secretKeyFile automatically.

Dashboard

dashboard:
  enabled: true
  replicas: 2
  image:
    repository: "nantian-gw/dashboard"
    tag: "latest"
    pullPolicy: IfNotPresent

The chart pins the v2026.06.0 release tag for control plane, data plane, and dashboard by default. Production environments should still pin a specific release tag or digest explicitly in their values files.

Disable the dashboard when you do not need the web UI:

helm upgrade --install nantian-gw nantian-gw/nantian-gw \
  --namespace nantian-gw \
  --create-namespace \
  --set dashboard.enabled=false

HPA, ServiceMonitor, And NetworkPolicy

hpa:
  enabled: false

serviceMonitor:
  enabled: false

networkPolicies:
  enabled: true

Enable serviceMonitor.enabled only when the Prometheus Operator CRDs are installed. HPA is off by default; enable it when your cluster has metrics-server and you have validated data plane resource requests.

Common Overrides

Use a values file for changes you want to keep:

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

Example private registry and replica override:

global:
  imageRegistry: "registry.example.com"
  imagePullSecrets:
    - name: registry-credentials

dataplane:
  replicas: 4

Common Install Scenarios

Platform-Managed Gateway API CRDs

Use this when your platform already installs CRDs once at cluster bootstrap time:

gatewayAPI:
  installCRDs: false
  channel: standard

This keeps the application release scoped to namespaced resources plus the optional GatewayClass.

Chart-Managed Standard Gateway API CRDs

Use this when the chart should install the standard Gateway API CRD bundle for the cluster:

gatewayAPI:
  installCRDs: true
  channel: standard

This is convenient for disposable clusters and smaller environments, but remember that CRDs are cluster-scoped resources.

Dashboard Disabled

Disable the dashboard workload when you only want the control plane and data plane:

helm upgrade --install nantian-gw nantian-gw/nantian-gw \
  --namespace nantian-gw \
  --create-namespace \
  --set dashboard.enabled=false

Experimental Gateway Runtime And AI Gateway

Experimental Gateway runtime behavior is controlled by featureMode. AI Gateway remains an explicit control plane feature and requires experimental mode:

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

gatewayAPI.installCRDs and gatewayAPI.channel control CRD rendering only. Use gatewayAPI.channel: experimental when the chart should render the official experimental Gateway API CRD bundle.

See Experimental Features for the complete startup, CRD, and verification flow.

Helm Test And Cleanup

The chart renders a Helm test hook by default:

tests:
  enabled: true
  image:
    repository: "public.ecr.aws/docker/library/busybox"
    tag: "1.36.1"
    pullPolicy: IfNotPresent

Run it after install or upgrade:

helm test nantian-gw --namespace nantian-gw

The hook checks the gateway health endpoints using a small BusyBox image hosted on Amazon ECR Public. If your cluster cannot pull that public image source, override tests.image.repository, tests.image.tag, and tests.image.pullPolicy to point at an internal mirror or another compatible image.

The chart hook policy deletes the test Pod before recreation and after both successful and failed runs. Repeated helm test, uninstall, or retry flows should not leave stale failed hook Pods behind.

Verify The Release

kubectl get pods -n nantian-gw
kubectl get gatewayclass nantian-gw
kubectl get svc -n nantian-gw
helm status nantian-gw -n nantian-gw
helm test nantian-gw --namespace nantian-gw

If the data plane does not become ready, check whether it can connect to nantian-gw-controlplane-grpc:18080, confirm your xDS TLS settings if enabled, and read the control plane and data plane logs.

Upgrade And Uninstall

Upgrade an existing release:

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

Remove the release:

helm uninstall nantian-gw -n nantian-gw
kubectl delete namespace nantian-gw

Helm uninstall removes chart-managed resources. Gateway API CRDs and application resources you created outside the chart are not removed by the chart uninstall.