Configure Routes

Apache APISIX provides flexible gateway management capabilities based on routes, in which routing paths and target upstreams are defined.

This tutorial guides you through creating a Route using the APISIX Ingress Controller and verifying its behavior. You’ll configure a Route to a sample Upstream pointing to an httpbin service, then send a request to observe how APISIX proxies the traffic.

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.0.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.

You can use either Gateway API, Ingress, or APISIX CRD resources to configure the route.

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

Note that the port in the Gateway listener is required but ignored. This is due to limitations in the data plane: it cannot dynamically open new ports. Since the Ingress Controller does not manage the data plane deployment, it cannot automatically update the configuration or restart the data plane to apply port changes.

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

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"
}