Skip to content
Nantian Gateway

Core Concepts

This section introduces the fundamental concepts behind Nantian Gateway and the Kubernetes Gateway API. If you are new to API gateways, Kubernetes ingress, or the Gateway API specification, start here.

These pages explain the what and why before the how. For implementation details, see the Getting Started and Configuration sections.

What is an API Gateway?

Section titled “What is an API Gateway?”

An API gateway is a reverse proxy that sits between clients and backend services, managing how traffic enters your system. It handles concerns that individual services should not need to address:

  • Traffic routing — directing requests to the correct backend based on path, headers, or other attributes
  • TLS termination — decrypting HTTPS traffic at the edge before forwarding to services
  • Rate limiting — protecting services from excessive traffic
  • Authentication — validating credentials before requests reach backend services
  • Observability — generating metrics, logs, and traces for all traffic flowing through the system

In Kubernetes, an API gateway typically replaces or augments the built-in Ingress resource, providing a richer routing model and more advanced traffic management capabilities.

How Nantian Gateway Works

Section titled “How Nantian Gateway Works”
┌───────────────────────────────────────────────────────────┐
│                   Kubernetes API Server                   │
│  GatewayClass, Gateway, HTTPRoute, GRPCRoute, TLSRoute... │
└──────────────────────┬────────────────────────────────────┘
                       │ watch
                       ▼
┌───────────────────────────────────────────────────────────┐
│                    Go Control Plane                        │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐  │
│  │ Watcher  │  │Translator│  │  Status  │  │Admin API │  │
│  │          │──│ (K8s→IR) │  │ Reporter │  │  :18081  │  │
│  └──────────┘  └──────────┘  └──────────┘  └──────────┘  │
│                                                            │
│  ┌──────────────────────────────────────────────────────┐  │
│  │           gRPC/xDS Stream (bidirectional)            │  │
│  └──────────────────────────────────────────────────────┘  │
└──────────────────────┬────────────────────────────────────┘
                       │ push IR snapshots
                       ▼
┌───────────────────────────────────────────────────────────┐
│                    Rust Data Plane                         │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐  │
│  │  HTTP    │  │   AI     │  │   Wasm   │  │ Metrics  │  │
│  │  Proxy   │  │ Gateway  │  │  Runtime │  │  :19080  │  │
│  └──────────┘  └──────────┘  └──────────┘  └──────────┘  │
└──────────────────────┬────────────────────────────────────┘
                       │ forward
                       ▼
              ┌─────────────────┐
              │    Backends     │
              │  (Services,     │
              │  AI Providers)  │
              └─────────────────┘

The flow:

  1. Create resources — You define Gateway, HTTPRoute, and other Gateway API resources via kubectl apply.
  2. Control plane watches — The Go control plane detects changes and translates them into an intermediate representation (IR).
  3. Status is reported — The control plane updates the status fields on Gateway and Route resources, indicating whether they are accepted, programmed, and ready.
  4. Configuration is pushed — The IR snapshot is pushed to all connected data plane instances over gRPC/xDS.
  5. Data plane serves traffic — The Rust data plane applies the new configuration and handles client requests without restarts.

Personas

Section titled “Personas”

Nantian Gateway is designed for three distinct personas, each with different responsibilities:

PersonaResponsibilityResources They Manage
Infrastructure ProviderInstalls and configures the gateway controller. Creates GatewayClass.GatewayClass, Helm values, control plane configuration
Cluster OperatorManages Gateway resources, listeners, and TLS certificates. Maintains the gateway deployment.Gateway, ReferenceGrant, Secrets, TLS configuration
Application DeveloperDefines routing rules for their services. Manages route resources and backend references.HTTPRoute, GRPCRoute, TCPRoute, TLSRoute, UDPRoute, BackendTLSPolicy, BackendLBPolicy

This role separation — inspired by the Gateway API specification — lets each team own their piece without stepping on each other’s configuration.

Resource Relationships

Section titled “Resource Relationships”

Gateway API resources follow a hierarchical ownership model:

GatewayClass (infrastructure provider)
  └── Gateway (cluster operator)
        ├── Listener (port + protocol + TLS)
        │     └── Route (application developer)
        │           └── BackendRef (Service reference)
        │                 └── BackendTLSPolicy (TLS for backend connection)
        │                 └── BackendLBPolicy (load balancing)
        └── ListenerSet (extension: adds listeners without modifying Gateway)
  • A GatewayClass selects which controller manages the gateways.
  • A Gateway defines entry points (listeners).
  • A Route attaches to a Gateway’s listener and defines matching rules.
  • A BackendRef within a route points to a Kubernetes Service.
  • Policies (BackendTLSPolicy, BackendLBPolicy) attach to backend Services and modify connection behavior.
  • ListenerSets allow adding listeners to a Gateway without direct Gateway modification.

Next Steps

Section titled “Next Steps”