Configure Routes

APISIX Ingress Controller translates Kubernetes routing resources into Apache APISIX configuration. You can use Gateway API, Kubernetes Ingress, or the APISIX-native ApisixRoute custom resource to define request matching and target services.

This tutorial creates the same HTTP route with each API and verifies how APISIX proxies traffic to an httpbin Service. See APISIX Ingress Controller Resources for a comparison of the supported resource types and the ApisixRoute API reference for field-level details.

Prerequisites

1. Complete Get APISIX and APISIX Ingress Controller.

Set Up a Sample Upstream

Install the httpbin example application on the cluster to test the configuration:

kubectl apply -f https://raw.githubusercontent.com/apache/apisix-ingress-controller/refs/heads/v2.1.0/examples/httpbin/deployment.yaml

Configure a Route

In this section, you will create a Route that forwards client requests to the httpbin example application, an HTTP request and response service.

Choose the resource that matches how your Kubernetes platform manages traffic:

• Gateway API HTTPRoute provides a portable Kubernetes routing API.
• Kubernetes Ingress supports the standard Ingress API.
• ApisixRoute exposes APISIX-specific routing capabilities through a custom resource.

important

If you are using Gateway API, you should first configure the GatewayClass and Gateway resources:

Show configuration

apiVersion: gateway.networking.k8s.io/v1
kind: GatewayClass
metadata:
  namespace: ingress-apisix
  name: apisix
spec:
  controllerName: apisix.apache.org/apisix-ingress-controller
---
apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  namespace: ingress-apisix
  name: apisix
spec:
  gatewayClassName: apisix
  listeners:
  - name: http
    protocol: HTTP
    port: 80
  infrastructure:
    parametersRef:
      group: apisix.apache.org
      kind: GatewayProxy
      name: apisix-config

The port in the Gateway listener can be used for route matching based on listener_port_match_mode (off by default; auto or explicit opt in). The controller cannot dynamically open new ports on the data plane, so ensure APISIX is configured to listen on the port.

If you are using Ingress or APISIX custom resources, you can proceed without additional configuration, as the IngressClass resource below is already applied with installation:

Show configuration

apiVersion: networking.k8s.io/v1
kind: IngressClass
metadata:
  name: apisix
spec:
  controller: apisix.apache.org/apisix-ingress-controller
  parameters:
    apiGroup: apisix.apache.org
    kind: GatewayProxy
    name: apisix-config
    namespace: ingress-apisix
    scope: Namespace

See Define Controller and Gateway for more information on parameters.

Create a Kubernetes manifest file for a Route that proxy requests to httpbin:

Gateway API

httpbin-route.yaml

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  namespace: ingress-apisix
  name: getting-started-ip
spec:
  parentRefs:
  - name: apisix
  rules:
  - matches:
    - path:
        type: Exact
        value: /ip
    backendRefs:
    - name: httpbin
      port: 80

Ingress

httpbin-route.yaml

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  namespace: ingress-apisix
  name: getting-started-ip
spec:
  ingressClassName: apisix
  rules:
    - http:
        paths:
          - backend:
              service:
                name: httpbin
                port:
                  number: 80
            path: /ip
            pathType: Exact

APISIX CRD

Use ApisixRoute when you need APISIX-native route configuration. For all available fields, see the ApisixRoute API reference.

httpbin-route.yaml

apiVersion: apisix.apache.org/v2
kind: ApisixRoute
metadata:
  namespace: ingress-apisix
  name: getting-started-ip
spec:
  ingressClassName: apisix
  http:
    - name: getting-started-ip
      match:
        paths:
          - /ip
      backends:
        - serviceName: httpbin
          servicePort: 80

Apply the configurations to your cluster:

kubectl apply -f httpbin-route.yaml

Verify

Expose the service port to your local machine by port forwarding:

kubectl port-forward svc/apisix-gateway 9080:80 &

Send a request to the Route:

curl "http://127.0.0.1:9080/ip"

You should see a response similar to the following:

{
  "origin": "127.0.0.1"
}