English Vocabulary for Kubernetes Gateway API

The Kubernetes Gateway API is the modern successor to the Ingress resource, designed to be more expressive, extensible, and role-oriented. As it reaches general availability and replaces Ingress in more clusters, engineers working in Kubernetes networking need the precise vocabulary used in Gateway API documentation, CNCF talks, and Kubernetes Slack channels.

Key Vocabulary

GatewayClass A GatewayClass is a cluster-scoped resource that defines a class of Gateways managed by a specific controller (such as Envoy Gateway, Nginx, or Istio). Infrastructure teams “define,” “register,” or “configure” GatewayClasses. It is analogous to IngressClass. Example: “The platform team defined a GatewayClass backed by Envoy Gateway and shared it with all application teams in the cluster.”

Gateway A Gateway resource is created by infrastructure teams to provision a load balancer or proxy instance. It references a GatewayClass and defines listeners (protocols, ports, certificates). Operators “provision,” “create,” and “configure” Gateways. Example: “We created a Gateway resource with an HTTPS listener on port 443 and attached our wildcard TLS certificate.”

HTTPRoute An HTTPRoute defines routing rules for HTTP and HTTPS traffic to backend services. Application teams “define,” “attach,” and “configure” HTTPRoutes. Rules can match on host, path, headers, or query parameters. Example: “I defined an HTTPRoute that routes /api/v2/ traffic to the new service version and leaves all other paths on the stable version.”

GRPCRoute A GRPCRoute provides native routing for gRPC traffic with method and service matching. It is similar to HTTPRoute but optimized for gRPC. Teams “configure” GRPCRoutes for gRPC backends. Example: “Instead of using an HTTPRoute with custom headers for gRPC, we migrated to a GRPCRoute resource for cleaner method-level routing.”

ReferenceGrant A ReferenceGrant allows a resource in one namespace to reference a resource in another namespace. Without it, cross-namespace references are denied by default for security. Infrastructure teams “create” or “grant” ReferenceGrants. Example: “The application team needed to reference the shared TLS Secret from the tls-certs namespace, so the platform team created a ReferenceGrant to permit it.”

Backend TLS Policy A BackendTLSPolicy configures TLS settings for traffic between the Gateway and the backend service (upstream TLS). This is distinct from the listener TLS which covers traffic from the client to the Gateway. Teams “configure” or “apply” backend TLS policies. Example: “We applied a BackendTLSPolicy to ensure that traffic between the load balancer and the order service pods is encrypted, not just client-to-gateway.”

Traffic Splitting Traffic splitting uses an HTTPRoute to distribute traffic between multiple backend services by weight. It is commonly used for canary deployments and blue/green rollouts. Engineers “configure,” “implement,” or “set up” traffic splitting. Example: “We configured traffic splitting to send 10% of requests to the canary version and 90% to the stable version, then gradually increased the canary weight.”

Migration from Ingress Many teams are currently moving from the Ingress resource to Gateway API. This involves converting Ingress rules to HTTPRoutes and replacing IngressClasses with GatewayClasses. Teams “migrate from Ingress,” “convert Ingress rules,” or “adopt the Gateway API.” Example: “We are migrating from Ingress to Gateway API in stages — starting with the development cluster before touching production.”

Common Phrases and Collocations

“configure the Gateway resource” The standard phrase when setting up a Gateway. Always “configure the Gateway resource” in formal documentation. Example: “Configure the Gateway resource to listen on port 80 and 443, and set the allowed routes to reference namespaces with the app-team label.”

“define an HTTPRoute” The action of creating routing rules. “Define” implies a declarative resource; prefer it over “create” or “write” in architecture discussions. Example: “Define an HTTPRoute that matches requests with the X-Feature-Flag: beta header and routes them to the beta service.”

“the Gateway class provisions” Describes the automated provisioning action taken by the Gateway controller when a Gateway resource is created. Example: “When you apply the Gateway resource, the GatewayClass provisions a new Envoy proxy pod and attaches it to the cluster’s load balancer.”

“attach a route” Routes are “attached” to Gateways using the parentRefs field. This is the standard verb in Gateway API documentation. Example: “Attach the HTTPRoute to the production Gateway by setting the parentRefs field to point to the Gateway name and namespace.”

“cross-namespace reference” When a resource in one Kubernetes namespace refers to a resource in a different namespace. The Gateway API restricts these by default and requires explicit ReferenceGrants. Example: “The HTTPRoute backend service is in a different namespace, so this is a cross-namespace reference — you need to create a ReferenceGrant first.”

Practical Sentences to Practice

1. “The GatewayClass is provisioned by the platform team; application teams only need to define their HTTPRoutes.”
2. “We use traffic splitting to roll out the new payment service — currently at 5% canary weight and increasing daily.”
3. “A ReferenceGrant is required because the HTTPRoute in the apps namespace references a Service in the shared namespace.”
4. “After migrating from Ingress, we removed 200 lines of annotation-based configuration and replaced them with explicit HTTPRoute rules.”
5. “The BackendTLSPolicy ensures encryption in transit even inside the cluster, which is a requirement for our compliance audit.”

Common Mistakes to Avoid

Calling HTTPRoute an “Ingress rule” HTTPRoute and Ingress are different resources. If you have migrated to Gateway API, call them “HTTPRoute rules” not “Ingress rules.” Mixing the two vocabularies in the same document causes confusion.

Saying “the Gateway routes traffic” Technically, Routes define the routing rules and are attached to the Gateway. The Gateway is the infrastructure attachment point. In precise discussions, say “the HTTPRoute defines the routing rule” and “the Gateway provides the listener.”

Confusing “listener TLS” and “backend TLS” Listener TLS (on the Gateway) secures client-to-gateway traffic. Backend TLS (BackendTLSPolicy) secures gateway-to-service traffic. These are separate configurations. Always specify which segment you are referring to.

Summary

The Kubernetes Gateway API introduces a layered vocabulary — GatewayClass, Gateway, HTTPRoute, GRPCRoute, ReferenceGrant, and backend TLS policy — that reflects its role-oriented design. Operators manage Gateways; application teams manage Routes. Understanding this vocabulary helps you participate in Kubernetes networking discussions, write accurate runbooks, and communicate clearly with SRE and platform engineering teams. The official Gateway API documentation at gateway-api.sigs.k8s.io is well-written and uses consistent terminology throughout, making it an excellent English learning resource alongside the technical content.