Apache APISIX Ingress Controller with Kubernetes Gateway API

Learn how the APISIX Ingress Controller 2.x runs as a Gateway API implementation, how GatewayProxy connects it to the data plane, and what to plan before running Gateway API beside existing Ingress resources.

Book a callTalk to us
On this page

Why teams running APISIX on Kubernetes choose Gateway API

The APISIX Ingress Controller 2.x translates Gateway API resources into APISIX configuration, so teams can express routing through the standard Kubernetes Gateway API objects while APISIX handles the data plane. Most teams arrive here from one of two situations: an Ingress NGINX estate that must move because Kubernetes SIG Network has retired the project, with no further releases, bug fixes or security updates after its best-effort maintenance window ended in March 2026, or a new APISIX cluster that needs a standard API surface instead of controller-specific annotations. Existing Ingress NGINX deployments keep running, but the retirement sets a planning deadline for the move.

According to the controller overview, the same controller reads three kinds of input: Kubernetes Ingress v1 resources, Gateway API resources such as GatewayClass, Gateway and HTTPRoute, and APISIX custom resources. It converts all three into APISIX configuration and treats the controller as the source of truth, so manual Admin API edits are overwritten on the next full sync. Gateway API fits best when you want portable route definitions that other Gateway API implementations can also read, when platform and application teams need role separation between Gateway owners and route owners, or when you are replacing Ingress NGINX and want a vendor-neutral model. Ingress v1 is the simpler choice for a small, stable set of host and path rules. APISIX custom resources are the better fit when you need plugin-rich route definitions that Gateway API does not express cleanly.

Before you commit, confirm which capabilities your routes need from each model and record that decision per route group. Check that the APISIX version you plan to run is supported by controller 2.x (the overview recommends 3.13), and confirm how your Gateway API version and the controller's supported resource versions line up with your cluster. The decision to make first is whether one controller will own all three input types or whether teams will run Gateway API beside existing Ingress resources during a staged cutover.

Which Gateway API setup fits your cluster

A greenfield cluster has no Ingress resources to preserve, so the controller can be built around Gateway API from the start. The APISIX Ingress Controller 2.x translates Gateway API resources into APISIX configuration, and releases 2.0.0 and 2.1.0 support APISIX 3.0 and later, with 3.13 as the recommended version. Your design choices are mostly about how the data plane is connected and where routing state lives.

  • Version pairing: Pin the controller release and the APISIX image together, and start from APISIX 3.13 as the recommended baseline.
  • GatewayClass and Gateway: Define one GatewayClass for the controller, then one or more Gateway objects that reference a GatewayProxy resource, which connects the controller to the APISIX data plane.
  • Data plane connection: Point the GatewayProxy at the APISIX Admin API service in traditional mode, so etcd remains part of the design.
  • Route resources: Express HTTPRoute objects for standard matching, and use APISIX custom resources only where you need plugin-rich routes.
  • Global policy: Use ApisixGlobalRule for global rules, since the 2.0 upgrade guide removed the older cluster configuration resource.

Before you commit, confirm with the APISIX Ingress Controller overview which Gateway API features your chosen controller release supports, and check the etcd sizing your platform team will run.

How to install and verify the Gateway API setup

This sequence takes a cluster from prerequisite checks to a working HTTPRoute served by APISIX through the Kubernetes Gateway API. Each step closes with a check, so the team knows the layer below is healthy before building on it.

  1. Confirm Kubernetes and Gateway API prerequisites

    The platform team checks that the cluster runs a Kubernetes version the APISIX Ingress Controller 2.x release supports, and that the Gateway API CustomResourceDefinitions are installed at a version the controller expects. Confirm the exact compatibility matrix in the Ingress Controller overview before choosing versions, because the supported range is set by the release notes, not by this page. Check that the cluster's version falls within the support window listed on the Kubernetes releases page. Done means kubectl get crd lists the Gateway API resources (GatewayClass, Gateway, HTTPRoute) and kubectl version reports a supported server version.

  2. Choose APISIX and controller versions

    Select the APISIX data plane version and the APISIX Ingress Controller 2.x release together, using the downloads page as the reference for current releases and the Ingress Controller overview for the matching APISIX version. The controller 2.0 release changed how the data plane is connected and how global rules are handled, so the platform team should record the chosen pair in the change record. Confirm whether the chosen APISIX release is intended for production use, since the downloads page does not mark releases as long-term support. Done means a written version pair is approved and the matching Helm chart or image tags are identified.

  3. Install the Ingress Controller and its admin key

    Install the APISIX Ingress Controller with its Helm chart into a dedicated namespace, and set the Admin API key through a Kubernetes Secret rather than a values file committed to Git. Read the upgrade guide before this step if the cluster previously ran a 1.x controller, because 2.0 makes the controller the source of truth and overwrites manual Admin API changes on the next full sync. Note that global rules move to ApisixGlobalRule and the GatewayProxy resource connects the data plane. Done means the controller pod is Running, its logs show a successful connection to the data plane, and no errors appear in the first sync.

  4. Create the GatewayProxy and GatewayClass

    Create a GatewayProxy resource that points the controller at the APISIX data plane and its Admin API endpoint, then create a GatewayClass that references the controller and the GatewayProxy. The GatewayProxy holds the connection details, so keep the Admin API reachable only from the controller and not from client networks. Confirm the GatewayClass reports an accepted condition. Done means kubectl get gatewayclass shows the class with Accepted set to True, and the controller log records the GatewayProxy being loaded.

  5. Create the Gateway resource

    Create a Gateway that references the GatewayClass and declares the listeners the team needs, such as HTTP on port 80 or HTTPS with a certificate reference in a Secret. Decide which namespaces may attach routes, because that boundary is set here. Confirm the Gateway reports Programmed and that the data plane service has an address the cluster or load balancer can reach. Done means kubectl get gateway shows Accepted and Programmed as True and the data plane service has an external or internal address assigned.

  6. Create an HTTPRoute with a test backend

    Deploy a simple test backend in a non-production namespace, then create an HTTPRoute that attaches to the Gateway and matches a hostname and path prefix. Where the team later adds plugins for authentication or rate limiting, those are attached through the APISIX custom resources and filters, so keep the first route minimal to isolate problems. Confirm the route reports Accepted and that its parent Gateway lists it as attached. Done means kubectl get httproute shows Accepted as True for the parent Gateway.

  7. Verify routing and the admin path

    Send a request through the data plane address with the Host header set to the route hostname, and confirm the test backend responds with the expected status and body. Then repeat with a non-matching path to confirm a 404 from the gateway rather than a pass-through. Confirm that the Admin API port is not reachable from client networks. Check the controller log after a config change to confirm a sync completed. Done means the expected response returns for the matching route, the non-matching request is rejected, and the team has recorded the test commands in the runbook.

  8. Run Gateway API beside existing Ingress resources

    If the cluster still serves Ingress resources, confirm which controller handles each Ingress class before moving any host to a Gateway API route, so two controllers do not claim the same hostname. Migrate one hostname at a time, verify each with the same request checks from the previous step, and keep the old Ingress in place until the new route is confirmed. The Kubernetes project has announced the retirement of Ingress NGINX, so record which ingress controller each host uses in the migration plan. Done means each migrated hostname returns the same responses through the new route, and the old Ingress is removed only after that check passes.

How HTTPRoute fields map to APISIX routes and plugins

A Gateway API HTTPRoute is translated by the Ingress Controller into APISIX routes, upstreams and plugins. The cards below cover the mappings you will rely on most and the points where a plugin needs an APISIX custom resource instead.

Host and path matching

The hostnames and path matches in an HTTPRoute become the matching conditions of the APISIX routes the controller generates. Confirm how each path match type (exact, prefix, regular expression) is rendered in the controller's generated configuration, because prefix semantics are where gateways most often differ. Test with real request paths, including trailing slashes and encoded characters, before you move traffic. Check that a route attached to the wrong listener or hostname fails closed rather than matching a broader route.

Header and method matches

Header and method conditions in an HTTPRoute rule narrow which requests reach a backend, so a misread match can send write methods to a read-only service. Verify each header and method match against the APISIX route it produces, and confirm which match features the controller version you deploy supports. Keep a test matrix that covers allowed and denied methods and header combinations, and run it again after each controller upgrade.

Backend references to upstreams

Each backendRefs entry resolves to a Kubernetes Service that the controller turns into an APISIX upstream, including endpoint discovery and weights. Confirm how weighted backends are expressed, how ports are resolved and how endpoint changes propagate. Check that the controller keeps the upstream in sync when pods scale or are replaced, and test a rollout in a non-production cluster.

Filters that become plugins

HTTPRoute filters such as header modification, redirects and URL rewrites are applied by the controller as APISIX plugins on the generated route. Confirm which filter types the controller supports in the version you deploy, and review the resulting plugin list in the generated configuration. Filters with no supported equivalent should be treated as a gap to resolve before go-live, not ignored.

Global rules through ApisixGlobalRule

Plugins that should apply to every route cannot be expressed in one HTTPRoute, so the controller 2.x uses the ApisixGlobalRule resource for global rules. Under controller 2.0, the controller is the source of truth, so a global plugin edited directly through the Admin API is overwritten on the next full sync. Keep global rules in version control, review changes as you would any cluster-wide policy, and confirm the resource's scope with the controller documentation.

Plugins without a Gateway API equivalent

When an APISIX plugin you need has no Gateway API field, use an APISIX custom resource such as ApisixRoute alongside the Gateway API objects, if the controller version supports the combination. Confirm the supported pairing and precedence rules before you split one application across both resource types. Record which team owns each resource type so a change to one does not silently alter the other.

Running Gateway API beside existing Ingress resources

The APISIX Ingress Controller 2.x translates Kubernetes Ingress v1, Gateway API resources and APISIX custom resources into one APISIX configuration, so the same data plane can serve both. The risk is ownership. If an Ingress and an HTTPRoute both claim the same host and path, the controller will generate routes from both, and the winning rule is whichever resource the controller processes last for that match, which is hard to predict in a busy cluster. Before anything is applied, record every host and path currently served by Ingress resources, assign each host to exactly one resource type for each cutover stage, and confirm the precedence behavior for overlapping matches in your controller version against the APISIX Ingress Controller overview.

Keep the existing NGINX ingress in place while you move hosts one at a time. Build the Gateway and HTTPRoute objects for a single low-risk host, point its DNS or load balancer target at the APISIX data plane only after you have tested it with a host-header override, and then remove the matching Ingress in the same change window. Rollback should be a prepared step, not a rebuild: keep the old Ingress manifest in Git, and confirm that restoring it does not conflict with the HTTPRoute you are backing out. Because the controller is the source of truth in 2.0 and later, a manual Admin API edit to fix a route during the cutover will be overwritten on the next full sync, so make every fix in the manifests.

The timeline is shaped by Ingress NGINX. Kubernetes SIG Network announced that Ingress NGINX would receive best-effort maintenance until March 2026, with no further releases, bug fixes or security updates afterwards. Existing installations keep running, but they carry growing exposure, so the coexistence period should be a bounded plan rather than an open-ended state. Ask your team to confirm the current support status and the Kubernetes minor version your clusters run before setting a cutover calendar, and check the Kubernetes release page for end-of-life dates that affect the same window. Agree the rollback criteria and the date Ingress NGINX is removed before the first host moves.

Security and operations to plan for Gateway API on APISIX

Running the APISIX Ingress Controller with Gateway API changes who owns gateway configuration, where credentials sit and how pods are permitted to run. The cards below cover the decisions to settle before the first HTTPRoute goes live, and the checks to repeat after each upgrade.

Controller as source of truth

In Ingress Controller 2.0 and later, the controller is the source of truth for APISIX configuration. A change made directly through the Admin API is overwritten on the next full sync, so a routing fix applied by hand during an incident can disappear without warning. Agree before go-live which changes go through Gateway API resources and Git, and who may touch the Admin API at all. Confirm the sync behavior for your chosen controller release in the upgrade guide.

Controller RBAC scope

The controller reads Gateway API objects, Ingress resources, Services, Endpoints and its own custom resources across the namespaces it watches. Limit the cluster role to the resource types and namespaces you actually use, and review which namespaces are watched before adding new tenants. Restrict who can create or edit Gateway, HTTPRoute and GatewayProxy objects, since those changes reach the gateway directly. Verify the effective permissions with a Kubernetes access review rather than trusting the chart defaults.

Secrets stored unencrypted in etcd

Kubernetes stores Secrets unencrypted in etcd by default. Credentials used by the gateway, such as upstream TLS keys, plugin secrets and GatewayProxy admin credentials, need encryption at rest on the control plane, or an external store delivered through the Secrets Store CSI Driver. Restrict list and watch access on Secrets with least-privilege RBAC, because those verbs expose values to anyone who holds them. Confirm the encryption configuration on your distribution before loading production keys.

TLS certificates on Gateway listeners

Each HTTPS listener on a Gateway references certificate Secrets that must exist in the right namespace before the listener is accepted. Decide who issues and renews these certificates, whether cert-manager or your internal PKI, and how renewal is tested without downtime. Check which namespaces may reference a certificate from another namespace, and whether TLS versions and cipher settings are set at the gateway rather than per route. Record expiry dates in your monitoring so a lapsed certificate does not stop traffic silently.

Pod Security Standards posture

Apply the Pod Security Standards to the namespaces that run the controller and the gateway pods, and start with the restricted profile where the images allow it. Confirm that the pods run as non-root, drop unneeded capabilities and do not mount host paths. Test the labels in audit or warn mode first, because a profile that blocks the controller can stop route syncing. Repeat the check after each chart or image upgrade, since default security contexts can change between releases.

Questions teams ask before running APISIX Gateway API

What does an APISIX Gateway API implementation cost, and what drives the effort?

The cost is mostly the labor to design and verify the setup, because the software itself is free under the Apache License 2.0. Effort rises with the number of routes, the number of authentication schemes, how many plugins each route needs, the number of clusters and environments, and how much existing Ingress NGINX configuration must be translated. Costs split into one-time work (design, build, migration, testing, documentation) and recurring work (upgrades, patching, monitoring, on-call). Ask any provider for a written scope listing the route inventory, the plugins in use, the clusters covered and the handover items, and compare quotes on that basis. A fixed-scope quote from DeployOpen follows the written scope; DeployOpen does not publish a price list.

How long does a migration from Ingress NGINX to Gateway API take?

The duration depends on how much of the existing behavior has to be reproduced, not on the Gateway API resources themselves. Kubernetes SIG Network announced that Ingress NGINX would receive best-effort maintenance until March 2026, with no releases, bug fixes or security updates afterwards, so the deadline is a planning input. The main drivers are the count of Ingress objects and their annotations, custom snippets that need an equivalent plugin configuration, authentication and rate-limit rules, the number of environments, and how long you need to run both controllers in parallel with a rollback path. Ask for a migration inventory and a cutover plan before agreeing a timeline. No duration is given here because none was supplied for this migration.

What does our team need to provide before an engagement starts?

You need to provide access and decisions, not only documents. The usual inputs are:

  • A Kubernetes cluster and version that the APISIX Ingress Controller supports, with admin access to create GatewayClass, Gateway and GatewayProxy resources
  • An inventory of existing Ingress resources, annotations, TLS certificates and the upstream services they reach
  • The authentication model, such as the identity provider and the OpenID Connect settings for each protected route
  • A decision on the APISIX data plane mode, whether etcd or standalone API-driven mode, which requires APISIX 3.13 or later
  • Environments, change windows, a Git repository for manifests, and named owners for approvals and on-call

Confirm the exact Kubernetes and APISIX versions with the vendor release notes before you start.

Can our internal platform team run this without an outside partner?

Yes, a capable platform team can do it alone if it has time, Kubernetes depth and an agreed owner for the gateway. The work is manageable when the route count is small and the team already runs Kubernetes ingress. The risks rise when the team has to learn the controller's source-of-truth model at the same time as migrating live traffic, because controller 2.0 overwrites manual Admin API changes on the next full sync. Assess your team on three points: whether someone can own the gateway after go-live, whether there is capacity for parallel running and rollback testing, and whether security testing and documentation will happen. A partner can fill any of those gaps through a fixed-scope engagement or a retainer for ongoing support.

When should we use APISIX custom resources instead of Gateway API routes?

Use APISIX custom resources when a route needs plugin configuration that the standard Gateway API resources do not express cleanly. Gateway API handles the common routing model well, while APISIX CRDs such as ApisixRoute, ApisixConsumer and ApisixGlobalRule give direct access to APISIX features. A common split is to keep simple HTTP routing in HTTPRoute and move plugin-heavy routes or consumer credentials into APISIX resources. Keep one source of truth per route, because the controller overwrites manual changes. The separate sibling topic on APISIX custom resources covers this decision in more detail.

What breaks most often when Gateway API runs beside existing Ingress resources?

The most common failures come from two controllers claiming the same host or path, or from TLS certificates that differ between the old and new paths. Check that each hostname is owned by one routing object at a time, that DNS points to the correct load balancer during cutover, and that headers and timeouts match the old behavior. Test with real client traffic before moving DNS, and keep the previous Ingress path ready for rollback. Verify metrics and logs on both paths so that a failed cutover shows up quickly.

How do we know the gateway setup is secure before go-live?

Security depends on how the gateway, the Kubernetes cluster and the secrets are configured, and none of it is verified by default. Review how the APISIX Admin API is exposed and who can change routes, since manual edits are overwritten by the controller. Kubernetes stores Secrets unencrypted in etcd by default, so confirm encryption at rest, least-privilege RBAC for Secrets, and an external store if your policy requires one. Apply Pod Security Standards to the gateway namespace and run an independent security test against the exposed routes. DeployOpen runs application, API and infrastructure security testing, and can scope that work in writing.

Where to confirm the controller behavior

Start with the APISIX Ingress Controller overview to settle which resource types the controller translates into APISIX configuration: Ingress v1, Gateway API resources and APISIX custom resources. The same page settles the supported data plane range for the 2.x releases, which is APISIX 3.0 and later with 3.13 as the recommended version, and the 3.13 minimum for the standalone API-driven mode. Read the release you plan to install, not the latest branch, because the 2.0.0 and 2.1.0 notes are the ones that match this design. Record the exact controller and APISIX image tags in your change request so the reviewer can trace the behavior to a specific document.

Read the APISIX Ingress Controller upgrade guide before you copy any older example. It settles the 2.0 changes that affect this design: the controller is the source of truth, so manual Admin API edits are overwritten on the next full sync, and the GatewayProxy resource is how the controller connects to the data plane. Confirm in your own cluster that no team still edits routes through the Admin API or expects the removed mock-etcd mode. Then check that your global rules are expressed as ApisixGlobalRule objects, since the guide replaces the older cluster config resource.

The Kubernetes blog post on Ingress NGINX retirement explains why many teams are moving to Gateway API now. It states that best-effort maintenance ended in March 2026 with no further releases, bug fixes or security updates, while existing deployments keep working. Use it to justify the migration timeline, not to judge your current controller's behavior. For Kubernetes version support, check the Kubernetes releases page against the minor version in your cluster, and the version skew policy against your node upgrade order. Verify the Gateway API CRD version your cluster serves and confirm it with your platform team, because the sources above do not settle that for your environment.

How DeployOpen works on this

DeployOpen plans, implements, documents and supports self-hosted open-source platforms inside your own infrastructure. For Apache APISIX Ingress Controller with Kubernetes Gateway API, the work starts with a written scope that maps your existing Ingress resources and routes to Gateway API objects, then builds and tests that mapping in your clusters.

How we scope

  • Inventory existing Ingress resources, routes, plugins and TLS certificates that must map to Gateway API objects.
  • Confirm the Kubernetes version, the APISIX version and the Ingress Controller 2.x release your clusters will run.
  • Agree in writing which routes move to HTTPRoute, which stay on Ingress, and which need APISIX custom resources.

How we build

  • Configure the GatewayClass, Gateway and GatewayProxy objects in a non-production cluster before touching live traffic.
  • Map each HTTPRoute to its APISIX route and attached plugins, and test every mapping against expected responses.
  • Run Gateway API beside existing Ingress resources during a parallel period, with the cutover order and rollback steps written down.

How we hand over

  • Deliver manifests in your version control system, with a record of which Ingress resources were converted and why.
  • Document how the controller overwrites manual Admin API changes, so your operators do not edit the gateway by hand.
  • Walk your platform and security teams through routing, certificate rotation and the rollback procedure.

How we support

  • Ongoing support, upgrades and continuous testing are available as a retainer after handover.
  • Plan controller and APISIX upgrades against the upgrade guide and re-run route tests before each change.
  • Ask in the quote how Ingress NGINX retirement timing and your Kubernetes upgrade schedule affect the support scope.

Sources and further reading

Related

Talk to our team.

Tell us what you're working on, whether it's a deployment, an audit, a security test or a cyber range. You'll speak with an engineer who can help you scope it.

  • 30-minute call: free, with no obligation.
  • NDA on request: we can sign before you share details.
  • Clear next steps: a scope and plan after the call.
Book a callhello@deployopen.com