Skip to main content
Version: Next

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:

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

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