Configure Routes

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

A route is a routing path to upstream targets. In Apache APISIX, routes are responsible for matching client's requests based on defined rules, loading and executing the corresponding plugins, as well as forwarding requests to the specified upstream services. A simple route can be set up with a path-matching URI and a corresponding upstream address.

An upstream is a set of target nodes with the same work. It defines a virtual host abstraction that performs load balancing on a given set of service nodes according to the configured rules.

This tutorial guides you through how to create a route and verify it. You will:

1. Create a route with a sample upstream that points to an httpbin service.
2. Send a request to the route to see how APISIX proxies the request.

Prerequisite(s)

1. Complete Get APISIX to install APISIX in Docker or on Kubernetes.
2. Install ADC or APISIX-MCP if you are using these tools.
3. Apply resources that configure the CP endpoint and admin key, as well as the controller and gateway if you are using ingress controller.

Create a Route

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

Admin API

curl -i "http://127.0.0.1:9180/apisix/admin/routes" -X PUT -d '
{
  "id": "getting-started-ip",
  "uri": "/ip",
  "upstream": {
    "type": "roundrobin",
    "nodes": {
      "httpbin.org:80": 1
    }
  }
}'

You will receive an HTTP/1.1 201 Created response if the route was created successfully.

ADC

adc.yaml

services:
  - name: httpbin Service
    routes:
      - uris:
          - /ip
        name: getting-started-ip
    upstream:
      type: roundrobin
      nodes:
        - host: httpbin.org
          port: 80
          weight: 1

Synchronize the configuration to APISIX:

adc sync -f adc.yaml

You will receive a similar response if the configuration was synchronized successfully:

[11:25:49 AM] [ADC] › ✔  success   Sync configuration
[11:25:49 AM] [ADC] › ★  star      All is well, see you next time!

Ingress Controller

It is recommended to use the Gateway API or APISIX CRDs over the Ingress resource when working with the APISIX Ingress Controller, as they offer greater flexibility and extensibility. For demonstration purposes, this tutorial shows all three configuration approaches. Subsequent tutorials will only use the Gateway API and APISIX CRDs.

While this section demonstrates creating a route to the publicly hosted httpbin service, you can modify it accordingly to proxy requests to services within your Kubernetes cluster.

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:
  name: apisix
spec:
  controllerName: apisix.apache.org/apisix-ingress-controller
---
apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: apisix
spec:
  gatewayClassName: apisix
  listeners:
  - name: http
    protocol: HTTP
    port: 80
  infrastructure:
    parametersRef:
      group: apisix.apache.org
      kind: GatewayProxy
      name: apisix-config

If you are using Ingress or APISIX custom resources, you can proceed without additional configuration.

Gateway API

Create a Kubernetes manifest file for a route that proxy requests to httpbin.org:

httpbin-route.yaml

apiVersion: v1
kind: Service
metadata:
  name: httpbin-external-domain
spec:
  type: ExternalName
  externalName: httpbin.org
---
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: getting-started-ip
spec:
  parentRefs:
  - name: apisix
  rules:
  - matches:
    - path:
        type: Exact
        value: /ip
    backendRefs:
    - name: httpbin-external-domain
      port: 80

Ingress

Create a Kubernetes manifest file for a route that proxy requests to httpbin.org:

httpbin-route.yaml

apiVersion: v1
kind: Service
metadata:
  name: httpbin-external-domain
spec:
  type: ExternalName
  externalName: httpbin.org
---
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: getting-started-ip
spec:
  ingressClassName: apisix
  rules:
  - http:
      paths:
      - path: /ip
        pathType: Exact
        backend:
          service:
            name: httpbin-external-domain
            port:
              number: 80

APISIX CRD

Create a Kubernetes manifest file for a route that proxy requests to httpbin.org:

httpbin-route.yaml

apiVersion: apisix.apache.org/v2
kind: ApisixUpstream
metadata:
  name: httpbin-external-domain
spec:
  externalNodes:
  - type: Domain
    name: httpbin.org
---
apiVersion: apisix.apache.org/v2
kind: ApisixRoute
metadata:
  name: getting-started-ip
spec:
  ingressClassName: apisix
  http:
    - name: getting-started-ip
      match:
        paths:
          - /ip
      upstreams:
      - name: httpbin-external-domain

Apply the configurations to your cluster:

kubectl apply -f httpbin-route.yaml

APISIX-MCP

Enter the following prompt in your AI client:

Create a route with the ID getting-started-ip that matches requests to the URI /ip, and forward them to an upstream using round-robin load balancing with a single node at httpbin.org on port 80.

You should see a response similar to the following:

Successfully created route "getting-started-ip" with the following configuration:

URI: /ip
Upstream: http://httpbin.org:80 (roundrobin load balancing)
Route ID: getting-started-ip
Status: Active (1)
Created at: 1744183830 (2025-04-09 07:30:30 UTC)
The route is now ready to accept requests at the /ip path, which will be forwarded to httpbin.org on port 80.

Verify

Admin API

Send a request to the route:

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

You should see a response similar to the following:

{
  "origin": "183.94.122.205"
}

ADC

Send a request to the route:

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

You should see a response similar to the following:

{
  "origin": "183.94.122.205"
}

Ingress Controller

First, expose the service port to your local machine by port forwarding:

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

The command above runs in the background and maps port 80 of the apisix-gateway service to port 9080 on the local machine.

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

APISIX-MCP

Enter the following prompt in your AI client:

Send a request to the route for verification.

You should see a response similar to the following:

Successfully verified the route "getting-started-ip":

Received HTTP 200 response from httpbin.org
Response shows origin IP address (192.168.107.1, 103.97.2.159)
The route is properly configured and forwarding requests to httpbin.org
The upstream service is responding correctly to requests

What's Next

This tutorial creates a route pointing to one upstream node. In the next tutorial, you will learn how to configure load balancing with multiple upstream nodes.