How to Use Gateway API in APISIX Ingress Controller

Yeqi Peng

November 11, 2022


What Is Kubernetes Gateway API

Gateway API is another community-initiated specification (managed by sig-network) to help users expose services in Kubernetes outside the cluster, in addition to native Service and Ingress.

Gateway API supports many common network protocols (e.g., HTTP, TCP, UDP) as well as TLS. Moreover, Gateway API includes Gateway resources that make it possible to manage the lifecycle of a proxy or gateway through the Kubernetes API.

Why Need Gateway API

Compared to Ingress, Gateway API represents the functional superset of Ingress, with the following improvements:

  • Role-oriented: Gateway is composed of API resources that model organizational roles that use and configure Kubernetes service networking.
  • Expressive: Gateway API resources support core functionality for things like header-based matching, traffic weighting, and other capabilities that were only possible in Ingress through custom annotations.
  • Extensible: Gateway API allows for custom resources to be linked at various layers of the API, which makes granular customization possible at the appropriate places within the API structure.

In addition, the standard includes features such as portability, shared gateways, and cross-namespace references.

As shown in the diagram, the role-oriented design allows for the sharing of network infrastructure within a cluster between different teams and the sharing of policies and constraints set by the cluster administrator. This allows different types of roles, such as infrastructure providers, cluster administrators, and application developers, to focus on their own work and not on what other roles are responsible for.


Different roles configure different levels of Gateway API resources, and the different levels work together:


Current Status of Gateway API

Currently, with the release of Gateway API v0.5.0, some important core APIs come into Beta for the first time, including GatewayClass, Gateway, and HTTPRoute.

How to use Gateway API in APISIX Ingress

APISIX Ingress Controller support for the Gateway API is under development and is at the Alpha stage, and supports resources like HTTPRoute, TCPRoute at present.

Install Gateway API CRD

To use the Gateway API, you need to install the CRD for the Gateway API first, either through a copy under the APISIX Ingress Controller repository or the official repository kubernetes-sigs/gateway-api. A copy of the CRD from the APISIX Ingress Controller repository is used here as an example.

Execute the following command to install the CRD for Gateway API.

git pull
cd apisix-ingress-controller

kubectl apply -f ./samples/deploy/gateway-api/

Install APISIX Ingress Controller

Gateway API support is not enabled by default in APISIX Ingress Controller and can be enabled with the parameter -enable-gateway-api=true.

When installing with Helm, you can enable it by configuring values.

Use the following command to install APISIX and APISIX Ingress Controller.

helm repo add apisix
helm repo add bitnami
helm repo update
kubectl create ns apisix-ingress

helm install apisix apisix/apisix --namespace apisix-ingress \
--set gateway.type=NodePort \
--set ingress-controller.enabled=true \
--set ingress-controller.config.apisix.serviceNamespace=apisix-ingress \
--set ingress-controller.config.kubernetes.enableGatewayAPI=true

Note the parameter -set ingress-controller.config.kubernetes.enableGatewayAPI=true which is used to enable Gateway API support.

These commands will create a complete test environment under the apisix-ingress namespace, including APISIX, etcd and APISIX Ingress Controller.

Deploy Test Load

Use the kennethreitz/httpbin image as a test load.

Use the following command to deploy these loads under the default namespace.

kubectl run httpbin --image kennethreitz/httpbin --port 80
kubectl expose pod httpbin --port 80

Config HTTPRoute

Currently, the APISIX Ingress Controller supports the v1alpha2 version of the Gateway API resource.

For testing, use the following HTTPRoute configuration and save it to the httproute.yaml file:

# httproute.yaml
kind: HTTPRoute
name: basic-http-route
- backendRefs:
    - name: httpbin
    port: 80
    - path:
        type: PathPrefix
        value: /

Use the following command to deploy this HTTPRoute configuration:

kubectl apply -f ./httproute.yaml


Verification can be done directly in the APISIX Pod by executing the following command:

kubectl -n apisix-ingress exec -it $(kubectl -n apisix-ingress get Pods -l "" -o name) -c apisix -- curl -H "Host:" localhost:9080/ip

The expected output is:

"origin": ""

This indicates that our configuration has successfully taken effect.

How Does APISIX Ingress Support Gateway API

Currently, APISIX Ingress Controller is adding support for Gateway API and supports resources such as HTTPRoute, TCPRoute, etc.

APISIX Ingress Controller's support for Gateway and Gateway Class is under active development, so the configuration of these resources will not take effect for now.


In this article, we introduce Gateway API, a brand new specification in the community for exposing services outside of a cluster, and describe how to use it in the APISIX Ingress Controller.

Full support for Gateway API in APISIX Ingress Controller is under active development.

APISIX Ingress ControllerGateway APIKubernetes