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.

Start a Sample Upstream Service

If you are running APISIX in Kubernetes, you will be deploying an httpbin application to your cluster in this section. Otherwise, skip to the next section where you will be using the hosted httpbin application as the upstream.

Start a sample httpbin application:

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

You should see a pod/httpbin created response.

Expose the application's port 80 through a service:

kubectl expose pod httpbin --port 80

You should see a service/httpbin exposed response.

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

Create a Kubernetes manifest file to configure a route using the ApisixRoute custom resource:

httpbin-route.yaml

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

Apply the configuration to your cluster:

kubectl apply -f httpbin-route.yaml

You should see a response of the following:

apisixroute.apisix.apache.org/httpbin-route created

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.

Alternatively, you can use a load balancer to expose the service on the kind cluster. See load balancer kind documentation for more details.

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

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.