Services and Routes

Kong Gateway administrators work with an object model to define their desired traffic management policies. Two important objects in that model are services and routes. Services and routes are configured in a coordinated manner to define the routing path that requests and responses will take through the system.

The high level overview below shows requests arriving at routes and being forward to services, with responses taking the opposite pathway:

Services and routes

What is a service

In Kong Gateway, a service is an abstraction of an existing upstream application. Services can store collections of objects like plugin configurations, and policies, and they can be associated with routes.

When defining a service, the administrator provides a name and the upstream application connection information. The connection details can be provided in the url field as a single string, or by providing individual values for protocol, host, port, and path individually.

Services have a one-to-many relationship with upstream applications, which allows administrators to create sophisticated traffic management behaviors.

What is a route

A route is a path to a resource within an upstream application. Routes are added to services to allow access to the underlying application. In Kong Gateway, routes typically map to endpoints that are exposed through the Kong Gateway application. Routes can also define rules that match requests to associated services. Because of this, one route can reference multiple endpoints. A basic route should have a name, path or paths, and reference an existing service.

You can also configure routes with:

  • Protocols: The protocol used to communicate with the upstream application.
  • Hosts: Lists of domains that match a route
  • Methods: HTTP methods that match a route
  • Headers: Lists of values that are expected in the header of a request
  • Redirect status codes: HTTPS status codes
  • Tags: Optional set of strings to group routes with

Managing services and routes

The following tutorial walks through managing and testing services and routes using the Kong Gateway Admin API. Kong Gateway also offers other options for configuration management including Kong Kong Konnect and decK.

In this section of the tutorial, you will complete the following steps:

  • Create a service pointing to the Mockbin API, which provides testing facilities for HTTP requests and responses.
  • Define a route by providing a URL path that will be available to clients on the running Kong Gateway.
  • Use the new Mockbin service to echo a test request, helping you understand how Kong Gateway proxies API requests.

Prerequisites

This chapter is part of the Get Started with Kong series. For the best experience, it is recommended that you follow the series from the beginning.

The introduction, Get Kong, includes tool prerequisites and instructions for running a local Kong Gateway.

If you haven’t completed the Get Kong step already, complete that before proceeding.

Managing services

  1. Creating services

    To add a new service, send a POST request to Kong Gateway’s Admin API /services route:

    1. curl -i -s -X POST http://localhost:8001/services \
    2.   --data name=example_service \
    3.   --data url='http://mockbin.org'

    This request instructs Kong Gateway to create a new service mapped to the upstream URL http://mockbin.org.

    In our example, the request body contained two strings:

    • name: The name of the service
    • url : An argument that populates the host, port, and path attributes of the service

    If your request was successful, you will see a 201 response header from Kong Gateway confirming that your service was created and the response body will be similar to:

    1. {
    2.   "host": "mockbin.org",
    3.   "name": "example_service",
    4.   "enabled": true,
    5.   "connect_timeout": 60000,
    6.   "read_timeout": 60000,
    7.   "retries": 5,
    8.   "protocol": "http",
    9.   "path": null,
    10.   "port": 80,
    11.   "tags": null,
    12.   "client_certificate": null,
    13.   "tls_verify": null,
    14.   "created_at": 1661346938,
    15.   "updated_at": 1661346938,
    16.   "tls_verify_depth": null,
    17.   "id": "3b2be74e-335b-4f25-9f08-6c41b4720315",
    18.   "write_timeout": 60000,
    19.   "ca_certificates": null
    20. }

    Fields that are not explicitly provided in the create request are automatically given a default value based on the current Kong Gateway configuration.

  2. Viewing service configuration

    When you create a service, Kong Gateway assigns it a unique id as shown in the response above. The id field, or the name provided when creating the service, can be used to identify the service in subsequent requests. This is the service URL and takes the form of /services/{service name or id}.

    To view the current state of a service, make a GET request to the service URL.

    1. curl -X GET http://localhost:8001/services/example_service

    A successful request will contain the current configuration of your service in the response body and will look something like the following snippet:

    1. {
    2.   "host": "mockbin.org",
    3.   "name": "example_service",
    4.   "enabled": true,
    5.   ...
    6. }

  3. Updating services

    Existing service configurations can be updated dynamically by sending a PATCH request to the service URL.

    To dynamically set the service retries from 5 to 6, send this PATCH request:

    1. curl --request PATCH \
    2.   --url localhost:8001/services/example_service \
    3.   --data retries=6

    The response body contains the full service configuration including the updated value:

    1. {
    2.   "host": "mockbin.org",
    3.   "name": "example_service",
    4.   "enabled": true,
    5.   "retries": 6,
    6.   ...
    7. }

  4. Listing services

    You can list all current services by sending a GET request to the base /services URL.

    1. curl -X GET http://localhost:8001/services

The Admin API documentation provides the full service update specification.

Managing routes

  1. Creating routes

    Routes define how requests are proxied by Kong Gateway. You can create a route associated with a specific service by sending a POST request to the service URL.

    Configure a new route on the /mock path to direct traffic to the example_service service created earlier:

    1. curl -i -X POST http://localhost:8001/services/example_service/routes \
    2.   --data 'paths[]=/mock' \
    3.   --data name=example_route

    If the route was successfully created, the API returns a 201 response code and a response body like this:

    1. {
    2.   "paths": [
    3.     "/mock"
    4.   ],
    5.   "methods": null,
    6.   "sources": null,
    7.   "destinations": null,
    8.   "name": "example_route",
    9.   "headers": null,
    10.   "hosts": null,
    11.   "preserve_host": false,
    12.   "regex_priority": 0,
    13.   "snis": null,
    14.   "https_redirect_status_code": 426,
    15.   "tags": null,
    16.   "protocols": [
    17.     "http",
    18.     "https"
    19.   ],
    20.   "path_handling": "v0",
    21.   "id": "52d58293-ae25-4c69-acc8-6dd729718a61",
    22.   "updated_at": 1661345592,
    23.   "service": {
    24.     "id": "c1e98b2b-6e77-476c-82ca-a5f1fb877e07"
    25.   },
    26.   "response_buffering": true,
    27.   "strip_path": true,
    28.   "request_buffering": true,
    29.   "created_at": 1661345592
    30. }

  2. Viewing route configuration

    Like services, when you create a route, Kong Gateway assigns it a unique id as shown in the response above. The id field, or the name provided when creating the route, can be used to identify the route in subsequent requests. The route URL can take either of the following forms:

    • /services/{service name or id}/routes/{route name or id}
    • /routes/{route name or id}

    To view the current state of the example_route route, make a GET request to the route URL:

    1. curl -X GET http://localhost:8001/services/example_service/routes/example_route

    The response body contains the current configuration of your route:

    1. {
    2.   "paths": [
    3.     "/mock"
    4.   ],
    5.   "methods": null,
    6.   "sources": null,
    7.   "destinations": null,
    8.   "name": "example_route",
    9.   "headers": null,
    10.   "hosts": null,
    11.   "preserve_host": false,
    12.   "regex_priority": 0,
    13.   "snis": null,
    14.   "https_redirect_status_code": 426,
    15.   "tags": null,
    16.   "protocols": [
    17.     "http",
    18.     "https"
    19.   ],
    20.   "path_handling": "v0",
    21.   "id": "189e0a57-205a-4f48-aec6-d57f2e8a9985",
    22.   "updated_at": 1661347991,
    23.   "service": {
    24.     "id": "3b2be74e-335b-4f25-9f08-6c41b4720315"
    25.   },
    26.   "response_buffering": true,
    27.   "strip_path": true,
    28.   "request_buffering": true,
    29.   "created_at": 1661347991
    30. }

  3. Updating routes

    Like services, routes can be updated dynamically by sending a PATCH request to the route URL.

    Tags are an optional set of strings that can be associated with the route for grouping and filtering. You can assign tags by sending a PATCH request to the services endpoint and specifying a route.

    Update the route by assigning it a tag with the value tutorial:

    1. curl --request PATCH \
    2.   --url localhost:8001/services/example_service/routes/example_route \
    3.   --data tags="tutorial"

    The above example used the service and route name fields for the route URL.

    If the tag was successfully applied, the response body will contain the following JSON value:

    1. ...
    2. "tags":["tutorial"]
    3. ...

  4. Listing routes

    The Admin API also supports the listing of all routes currently configured:

    1. curl http://localhost:8001/routes

    This request returns an HTTP 200 status code and a JSON response body object array with all of the routes configured on this Kong Gateway instance. Your response should look like the following:

    1. {
    2.   "next": null,
    3.   "data": [
    4.     {
    5.       "paths": [
    6.         "/mock"
    7.       ],
    8.       "methods": null,
    9.       "sources": null,
    10.       "destinations": null,
    11.       "name": "example_route",
    12.       "headers": null,
    13.       "hosts": null,
    14.       "preserve_host": false,
    15.       "regex_priority": 0,
    16.       "snis": null,
    17.       "https_redirect_status_code": 426,
    18.       "tags": [
    19.         "tutorial"
    20.       ],
    21.       "protocols": [
    22.         "http",
    23.         "https"
    24.       ],
    25.       "path_handling": "v0",
    26.       "id": "52d58293-ae25-4c69-acc8-6dd729718a61",
    27.       "updated_at": 1661346132,
    28.       "service": {
    29.         "id": "c1e98b2b-6e77-476c-82ca-a5f1fb877e07"
    30.       },
    31.       "response_buffering": true,
    32.       "strip_path": true,
    33.       "request_buffering": true,
    34.       "created_at": 1661345592
    35.     }
    36.   ]
    37. }

The Admin API documentation has the full specification for managing route objects.

Proxy a request

Kong is an API Gateway, it takes requests from clients and routes them to the appropriate upstream application based on a the current configuration. Using the service and route that was previously configured, you can now access https://mockbin.org/ using http://localhost:8000/mock.

By default, Kong Gateway’s Admin API listens for administrative requests on port 8001, this is sometimes referred to as the control plane. Clients use port 8000 to make data requests, and this is often referred to as the data plane.

Mockbin provides a /requests resource which will echo back to clients information about requests made to it. Proxy a request through Kong Gateway to the /requests resource:

  1. curl -X GET http://localhost:8000/mock/requests

You should see a response similar to the following:

  1. {
  2.   "startedDateTime": "2022-08-24T13:44:28.449Z",
  3.   "clientIPAddress": "172.19.0.1",
  4.   "method": "GET",
  5.   "url": "http://localhost/requests",
  6.   "httpVersion": "HTTP/1.1",
  7.   "cookies": {},
  8.   "headers": {
  9.     "host": "mockbin.org",
  10.     "connection": "close",
  11.     "accept-encoding": "gzip",
  12.     "x-forwarded-for": "172.19.0.1,98.63.188.11, 162.158.63.41",
  13.     "cf-ray": "73fc85d999f2e6b0-EWR",
  14.     "x-forwarded-proto": "http",
  15.     "cf-visitor": "{\"scheme\":\"http\"}",
  16.     "x-forwarded-host": "localhost",
  17.     "x-forwarded-port": "80",
  18.     "x-forwarded-path": "/mock/requests",
  19.     "x-forwarded-prefix": "/mock",
  20.     "user-agent": "curl/7.79.1",
  21.     "accept": "*/*",
  22.     "cf-connecting-ip": "00.00.00.00",
  23.     "cdn-loop": "cloudflare",
  24.     "x-request-id": "1dae4762-5d7f-4d7b-af45-b05720762878",
  25.     "via": "1.1 vegur",
  26.     "connect-time": "0",
  27.     "x-request-start": "1661348668447",
  28.     "total-route-time": "0"
  29.   },
  30.   "queryString": {},
  31.   "postData": {
  32.     "mimeType": "application/octet-stream",
  33.     "text": "",
  34.     "params": []
  35.   },
  36.   "headersSize": 588,
  37.   "bodySize": 0
  38. }

Previous Get Kong

Next Rate Limiting