Kubernetes Gateway Object Management

Kubernetes Gateway Object Management is the discipline of creating, configuring, and operating Gateway resources within the Kubernetes Gateway API, the mechanism through which namespaced teams request a network listener — bound to a specific GatewayClass and a set of protocols, ports, and hostnames — that route resources such as HTTPRoute, TLSRoute, or TCPRoute can attach to. Whereas GatewayClass defines the reusable template supplied by infrastructure teams, the Gateway object is the concrete, namespace-scoped instantiation that provisions a listener and, typically, a backing load balancer or proxy deployment.

Gateway Resource Structure

spec.gatewayClassName

Every Gateway must reference an existing GatewayClass by name via spec.gatewayClassName. This binding determines which controller reconciles the object, what infrastructure gets provisioned, and which implementation-specific defaults apply. Changing this field after creation is treated as re-parenting the Gateway to a different controller and is rejected or strongly discouraged by most implementations.

spec.listeners

The listeners array is the core of a Gateway specification. Each listener declares a name, protocol (HTTP, HTTPS, TLS, TCP, or UDP), port, and an optional hostname used for SNI-based or Host-header-based matching. Listeners also carry an allowedRoutes block that restricts which namespaces and route kinds may attach to them.

apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: public-web
  namespace: gateway-infra
spec:
  gatewayClassName: external-gateway
  listeners:
    - name: https
      protocol: HTTPS
      port: 443
      hostname: "*.example.com"
      tls:
        mode: Terminate
        certificateRefs:
          - kind: Secret
            name: example-com-tls
      allowedRoutes:
        namespaces:
          from: Selector
          selector:
            matchLabels:
              gateway-access: "public-web"

spec.addresses

Some implementations allow requesting specific static IP addresses or hostnames through spec.addresses, useful when a Gateway must be reachable at a predictable address for DNS records configured outside the cluster.

Route Attachment Model

allowedRoutes and Namespace Selection

Route attachment is deliberately inverted compared to classic Ingress: a Gateway listener decides who may attach, rather than a route unilaterally claiming a hostname. The allowedRoutes.namespaces.from field accepts Same (only the Gateway's own namespace), All (any namespace in the cluster), or Selector (namespaces matching a label selector), giving platform teams fine-grained control over which application teams can publish routes on shared infrastructure.

Route Kind Restrictions

The allowedRoutes.kinds field can further restrict a listener to accept only specific route types, for example allowing only HTTPRoute on an HTTPS listener while rejecting TCPRoute or GRPCRoute attempts, preventing protocol mismatches at the attachment level rather than at runtime.

Cross-Namespace Reference Grants

When a route in one namespace references a backend Service in another namespace, or a Gateway listener references a TLS Secret in another namespace, a ReferenceGrant object must exist in the target namespace explicitly permitting the cross-namespace reference, closing a security gap that plain Ingress left implicit.

apiVersion: gateway.networking.k8s.io/v1beta1
kind: ReferenceGrant
metadata:
  name: allow-tls-secret
  namespace: gateway-infra
spec:
  from:
    - group: gateway.networking.k8s.io
      kind: Gateway
      namespace: apps-team
  to:
    - group: ""
      kind: Secret

Status Reporting and Health

Gateway-Level Conditions

The status.conditions field on a Gateway reports overall health through conditions such as Accepted (the spec was validated by the controller) and Programmed (the underlying data plane has been configured to match the spec). Both should read True before traffic is expected to flow.

Listener-Level Status

Because a single Gateway can host multiple listeners with independent lifecycles, status.listeners provides a per-listener breakdown including attachedRoutes (a count of routes currently bound) and its own Accepted, Programmed, and ResolvedRefs conditions. A listener can be healthy even while a sibling listener on the same Gateway is failing.

Diagnosing ResolvedRefs Failures

The ResolvedRefs condition turning False typically indicates a dangling reference — a missing TLS Secret, an unresolvable backend Service, or a route referencing a port that does not exist — and is the first place to check when traffic unexpectedly returns errors despite the Gateway appearing Programmed.

kubectl get gateway public-web -n gateway-infra -o yaml
kubectl describe gateway public-web -n gateway-infra

Provisioning and Infrastructure Coupling

Automatic Load Balancer Provisioning

Most cloud-integrated controllers provision an external load balancer automatically when a Gateway is created, mirroring the behavior of a Service of type LoadBalancer. The provisioned address appears under status.addresses once available, and DNS automation tools such as external-dns can watch this field to create matching records.

Shared vs. Dedicated Data Planes

Implementations vary in whether each Gateway gets a dedicated proxy deployment or shares a data plane with other Gateways of the same class. This choice affects blast radius: a shared data plane amortizes resource cost across many Gateways but means a misbehaving listener can, in some implementations, affect co-located traffic.

Resource Scaling

Because a Gateway can back significant production traffic, its GatewayClassParameters or Gateway-specific annotations often control replica counts, autoscaling thresholds, and node placement for the underlying proxy pods, and these should be sized independently from application workloads.

Operational Practices

Naming and Namespace Conventions

A common convention places infrastructure-owned Gateways in a dedicated namespace (such as gateway-infra) separate from application namespaces, with naming reflecting the traffic domain served, for example public-web, internal-api, or partner-mtls.

Change Management

Because listener changes can affect every attached route simultaneously, teams typically require the same review rigor for Gateway modifications as for GatewayClass changes — particularly for hostname, TLS certificate, and allowedRoutes edits, which can silently detach or expose routes.

Monitoring Attachment Drift

Regularly comparing status.listeners[].attachedRoutes against the expected set of routes helps detect drift, such as a route silently failing to attach due to a label change on its namespace that no longer matches a listener's allowedRoutes selector.

kubectl get gateway -A -o custom-columns=NAME:.metadata.name,NAMESPACE:.metadata.namespace,PROGRAMMED:.status.conditions[?(@.type==\"Programmed\")].status