Kubernetes Gateway API

The main decision in this split is which fields the platform team controls and which fields application teams can change without a ticket. In Gateway API, the platform team usually owns the GatewayClass that names the controller implementation and the Gateway objects that define the shared entry point. On each Gateway, the platform team sets listener ports and protocols, the TLS certificate references each listener presents, and the rules that decide which namespaces may attach routes. Application teams own the HTTPRoute objects in their own namespaces, including host matching, path and header rules, and the backendRefs that point to their Services. Write this boundary down before the first route is created, and confirm with your chosen implementation which fields it validates and which it accepts without checks.

Route attachment is controlled from the Gateway side. Each listener carries an allowedRoutes setting that accepts routes from the same namespace, from namespaces matching a label selector, or from all namespaces. A label selector is often the practical middle ground, because the platform team can admit only namespaces labeled for a given product area, and a team that loses the label stops attaching. References that cross a namespace boundary are a separate control. A route that points to a Service in another namespace, or a Gateway that points to a TLS Secret elsewhere, needs a ReferenceGrant created in the target namespace by the owner of that resource. The owner of the target therefore decides what can be reached, and the platform team should not create those grants on behalf of application teams without review.

Gateway API objects are ordinary Kubernetes resources, so the RBAC already in the cluster governs them. Bind the platform group to create and update GatewayClass, Gateway and listener configuration in the gateway namespace, and bind application groups to HTTPRoute verbs in their own namespaces only. Secrets need separate attention. The controller resolves each certificateRefs entry, so its service account must be able to read the referenced Secret, and that access should be scoped to the namespaces where certificates live. Application teams should have no list or get access to those TLS Secrets. Existing Secrets controls still apply, including encryption at rest and least-privilege list and watch access, because Secrets are stored unencrypted in etcd by default unless you configure encryption.

Illustrative example: the platform team creates a Gateway named public in an edge namespace, with an HTTPS listener for shop.example.com, a certificate Secret in edge, and allowedRoutes set to namespaces labeled product=storefront. The storefront team creates an HTTPRoute in its own namespace that matches the hostname and the /api path prefix and points to a Service in the same namespace, so no ReferenceGrant is needed. A route from a namespace without that label should be reported as not accepted, and a route that points to a Service in another team's namespace should fail until that team creates a ReferenceGrant. Before go-live, check the attachment status conditions on each route, run access checks for each group, and confirm how your implementation reports rejected routes.

The safe way to leave Ingress is to run the old and new routing paths side by side, prove the new one with real traffic under test names, and only then move production hostnames across in steps. Retiring the Ingress object comes last, not first. Start by inventorying every Ingress resource in the cluster and in each namespace, including the IngressClass it uses, its TLS secrets, its backends and every annotation. Annotations are where most of the work hides. They are defined by the ingress controller implementation, not by the Ingress API itself, so an annotation that rewrites paths, sets timeouts, controls body size or configures authentication on one controller has no automatic equivalent on another. Record what each annotation does, which teams depend on it and whether it is still needed.

Next, map each Ingress to Gateway API resources. The platform team typically owns the GatewayClass and the Gateway, which define the listeners, ports, TLS certificates and which namespaces may attach routes. Application teams own HTTPRoute objects that match hostnames and paths and forward to Services. Filters and policies that an annotation used to express must be translated into the features your chosen implementation supports for HTTPRoute filters or its own policy resources. Where a behavior has no supported equivalent, decide whether to change the application, accept the difference or keep that one route on the old controller until the gap is closed. Write this mapping down as a table per application so reviewers can check it line by line.

Run both paths in parallel. Give the new Gateway and its routes a separate test hostname, point it at the new implementation's address and send synthetic and manual test traffic through it while production stays on Ingress. Verify TLS chains, redirects, header handling, timeouts, large uploads, WebSocket or gRPC traffic where used, and authentication behavior against the same backend. Before any production hostname is shared between two controllers, confirm how your ingress controller and Gateway implementation handle overlapping hostnames during the transition. Some combinations will reject or ignore a route that claims a hostname already served elsewhere, and some will accept both and split traffic in ways you did not intend. Check this in a non-production cluster and record the result. Confirm also which controller owns the load balancer address and whether both can coexist on the same ports.

Shift traffic in steps. Lower DNS TTLs well ahead of the change, then move one non-critical hostname at a time by changing its DNS record or the weight at your load balancer. Keep the previous target available so the change can be reversed by one DNS or weight edit. Watch error rates, latency, certificate status and application logs after each step before moving the next, and set in advance what counts as a rollback signal. Once every hostname has run on the Gateway path for a full business cycle agreed with the application owners, remove the Ingress objects, then the old controller and its IngressClass. Keep the Ingress manifests in version control until the cutover has been accepted, so the previous configuration can be recovered and audited.

After go-live, the Gateway API stack needs the same recurring care as any other cluster component, and the most common failure is treating it as finished once routes work. The implementation controller, its data plane proxy or load balancer, and the Gateway API CRDs each follow their own release cadence, and all three must stay compatible with the Kubernetes version running in your clusters. Schedule these as planned operational work with named owners, a regular upgrade review and a non-production environment that runs each upgrade before production does.

Kubernetes ships roughly three minor releases a year on a cycle of about 14 weeks, and the project maintains the three most recent minors. The version skew policy requires kube-apiserver to be upgraded one minor version at a time, before kube-controller-manager, kube-scheduler and kubelets, and allows kubelets to be up to three minor versions older than kube-apiserver. Schedule controller upgrades into the same change windows. Gateway API upgrades can also depend on CRD version changes that must be applied before the controller is upgraded. Confirm the required order, the CRD versions, any storage version steps and any minimum Kubernetes version in the implementation's release notes before each upgrade, then rehearse the sequence in a non-production cluster.

Routine health checks should cover three layers. First, the controller: pod restarts, leader election, and reconciliation errors in its logs. Second, the Gateway API objects: GatewayClass, Gateway and route status conditions, particularly the Accepted and Programmed conditions on Gateways and the parent status on routes. A route that is accepted but not programmed usually points to a data plane problem, while a route that is not accepted often points to a parent reference, namespace permission or listener mismatch. Third, the data plane: request rates, error codes, upstream latency and configuration reload failures from the proxy or load balancer, exported to your monitoring system with alerts. Alerting on condition changes, not only pod state, catches problems before route owners report them.

Gateway listeners that terminate TLS usually reference certificates stored in Kubernetes Secrets, so each certificate has an expiry date the platform team must track. Decide who issues and renews these certificates, whether that is cert-manager, an internal certificate authority or a documented manual process. Confirm how your chosen implementation picks up a renewed Secret, since some reload automatically and others need a restart or rollout. Alert well before expiry, and test renewal in staging, including client trust chains and any backend TLS settings. Keep listener references stable so that renewal does not force changes to route resources, and record which application teams depend on each hostname.

Ownership needs to be written down before the first incident. The platform team typically owns the controller installation, GatewayClass, shared Gateways, the proxy or load balancer, certificates and the upgrade calendar. Application teams own their route objects, backend services and the hostnames they request, within the namespaces and attachment rules the platform team allows. Each team needs its own runbook. The platform runbook covers controller restart, rollback, CRD upgrade steps, certificate rotation and load balancer failover. The application runbook covers checking route status, reading condition messages and escalating to the platform team. Review both runbooks after each Kubernetes or controller upgrade, and rehearse them at least once before go-live is considered complete.

Effort in a Gateway API project depends less on writing GatewayClass, Gateway and route manifests than on the work around them. The one-time components are discovery and inventory of the existing ingress estate, including Ingress objects, controller-specific annotations, TLS secrets, DNS records and external load balancers. Next come implementation selection and a proof of concept against a representative route, followed by the platform build: installing the Gateway API CRDs at the version your chosen implementation supports, deploying its controller, configuring networking to the cluster's load balancer and issuing certificates. Ask each bidder to show which of these items their quote covers and which they expect your team to provide.

Migration is the largest one-time block and it is usually priced per route group, not per cluster. Each group needs its routes translated, its TLS configuration checked, its health checks confirmed and its cutover sequenced. A security review sits across all of them: who may attach routes to a Gateway, which namespaces may use which listeners, how TLS versions and cipher settings are set, and how backend access is limited with network policies. Testing and cutover then confirm behavior under real traffic, usually with old and new paths running side by side until the old ingress can be retired. Ask for the test plan and rollback steps as deliverables, not as informal practice.

Some costs recur for as long as the gateway runs. Gateway API CRDs and the controller need upgrades, and the Kubernetes version skew policy requires kube-apiserver to move one minor version at a time, so gateway upgrades must be planned against each cluster upgrade. Kubernetes ships roughly three minor releases per year, which means the platform team will schedule this work repeatedly. Certificate rotation is another recurring task, and it must be automated or owned by a named team. Ongoing support, monitoring of the controller and periodic review of route ownership are recurring too. Request a support model that states who handles each of these items and how fast a change request is handled.

Several factors push effort up. The number of applications and hostnames sets the size of the migration inventory and the testing matrix. Heavy use of implementation-specific annotations raises effort because each one must be mapped to a standard field or to a custom policy, and some may have no direct equivalent. Multi-cluster designs add gateway placement, shared certificate management and consistent policy across clusters. Compliance evidence requirements add the work of recording configuration, access decisions and change history in a form an auditor can review. Before accepting a quote, confirm which of these drivers your environment has, and ask the partner to list the assumptions their scope depends on.