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.

Bridging the Gap: Common Communication Challenges

Let’s be honest – when you’re learning professional English as a developer, particularly within the nuanced world of Kubernetes and networking, there are going to be communication gaps. It’s not just about knowing the definitions of terms like GatewayClass or HTTPRoute; it’s about how those terms are used in conversations, documentation, and especially when explaining your work. A frequent challenge for non-native speakers isn’t necessarily understanding the technical meaning but navigating the typical phrasing and expectations around clarity and detail.

For example, imagine you’ve spent hours configuring traffic splitting based on HTTP headers within a GatewayClass using the Kubernetes Gateway API. You’re writing a pull request to update the deployment. A reviewer might respond with something like, “This looks good overall, but can you add more context about why you chose this specific split? What metrics are you tracking?” The issue isn’t that the configuration is technically correct – it’s that the reviewer is implicitly asking for a justification, an explanation of the decision-making process. Simply stating “traffic splitting based on headers” isn’t sufficient; it lacks the business rationale and expected level of detail found in production environments. Similarly, during code reviews, you might see comments like “Consider adding a descriptive comment explaining this reference grant’s purpose” – this is more about documenting intent than just describing the technical implementation.

Another area where nuances arise is around migration strategies. Let’s say you’re migrating traffic from an Ingress controller to a Gateway API setup. The discussion might involve phrases like “zero-downtime,” “blue/green deployments,” and “rollback procedures.” These terms aren’t always straightforward in translation, and misunderstandings can easily occur regarding the level of complexity involved or the potential risks. Clear communication here is absolutely critical – it’s not enough to say “we moved the traffic.” You need to articulate how you achieved that movement while minimizing disruption and having a robust plan for reverting if necessary.

Finally, remember that documentation itself often employs specific phrasing related to API design and limitations. Pay close attention to how terms like “request validation” or “rate limiting” are described; these concepts frequently have more sophisticated implications than their literal translations suggest.

apiVersion: networking.k8s.io/v1
kind: GatewayClass
metadata:
  name: my-gatewayclass
spec:
  ...
    trafficSplits:
    - name: header-split
      httpRoute:
        path: "/api"
        matchHeaders:
          - key: "X-User-ID"
            test: "equals"
            value: "admin"
      weight: 80

This example shows a GatewayClass configuration with a traffic split based on the X-User-ID header. When discussing this in a meeting, you’d likely explain why this specific header is being used for routing – perhaps to direct administrative requests to a separate service or environment. The key takeaway is that effective communication goes beyond simply knowing the syntax; it’s about understanding the context and expectations surrounding the terms within your team’s workflow.