Get started with Kong Gateway

We’ll be using decK for this tutorial, so let’s check that Kong Gateway is running and that decK can access it:

deck gateway ping

If everything is running, then you should get the following response:

Successfully connected to Kong!
Kong version: 3.9.0.0

Successfully Konnected to the Kong organization!

Kong Gateway administrators work with an object model to define their desired traffic management policies. Two important objects in that model are Gateway Services and Routes. Together, Services and Routes define the path that requests and responses will take through the system.

Run the following command to create a Service mapped to the upstream URL https://httpbin.konghq.com:

echo '
_format_version: "3.0"
services:
  - name: example_service
    url: https://httpbin.konghq.com
' | deck gateway apply -

In this example, you are configuring the following attributes:

• name: The name of the Service
• url : An attribute that populates the host, port, and path of the Service

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 URL defined in the Service.

Configure a new Route on the /mock path to direct traffic to the example_service Service:

echo '
_format_version: "3.0"
routes:
  - name: example_route
    service:
      name: example_service
    paths:
    - "/mock"
' | deck gateway apply -

Validate the Gateway Service and Route by proxying a request

Using the Service and Route, you can now access https://httpbin.konghq.com/ using the /mock path.

Httpbin provides an /anything resource which will return information about requests made to it. Proxy a request through Kong Gateway to the /anything resource:

curl "$KONNECT_PROXY_URL/mock/anything"

curl "http://localhost:8000/mock/anything"

You should get a 200 response back.

Authentication is the process of verifying that the requester has permissions to access a resource. As its name implies, API gateway authentication authenticates the flow of data to and from your upstream services.

Enable Key Auth plugin

For this example, we’ll use the Key Authentication plugin. In key authentication, Kong Gateway generates and associates an API key with a Consumer. That key is the authentication secret presented by the client when making subsequent requests. Kong Gateway approves or denies requests based on the validity of the presented key.

echo '
_format_version: "3.0"
plugins:
  - name: key-auth
    config:
      key_names:
      - apikey
' | deck gateway apply -

The key_names configuration field defines the name of the field that the plugin looks for to read the key when authenticating requests. The plugin looks for the field in headers, query string parameters, and the request body.

Create a Consumer

Consumers let you identify the client that’s interacting with Kong Gateway. You need to create a Consumer for key authentication to work.

Create a new Consumer with the username luka and the key top-secret-key:

echo '
_format_version: "3.0"
consumers:
  - username: luka
    keyauth_credentials:
    - key: top-secret-key
' | deck gateway apply -

For the purposes of this tutorial, we have assigned an example key value. In production, it is recommended that you let the API gateway autogenerate a complex key for you. Only specify a key for testing or when migrating existing systems.

Validate using key authentication

Try to access the Service without providing the key:

curl -i $KONNECT_PROXY_URL/mock/anything 

curl -i http://localhost:8000/mock/anything 

This request returns a 401 error with the message No API key found in request.

Since you enabled key authentication globally, you will receive an unauthorized response:

HTTP/1.1 401 Unauthorized
...
{
    "message": "No API key found in request"
}

Now, let’s send a request with the valid key in the apikey header:

curl "$KONNECT_PROXY_URL/mock/anything" \
     -H "apikey:top-secret-key"

curl "http://localhost:8000/mock/anything" \
     -H "apikey:top-secret-key"

You will receive a 200 OK response.

Load balancing is a method of distributing API request traffic across multiple upstream services. Load balancing improves overall system responsiveness and reduces failures by preventing overloading of individual resources.

In the following example, you’ll use an application deployed across two different hosts, or upstream targets. Kong Gateway needs to load balance across the upstreams, so that if one of them is unavailable, it automatically detects the problem and routes all traffic to the working upstream.

You’ll need to configure two new types of entities: an Upstream and two Targets. Create an Upstream named example_upstream and add two Targets to it:

echo '
_format_version: "3.0"
upstreams:
  - name: example_upstream
    targets:
    - target: httpbun.com:80
      weight: 100
    - target: httpbin.konghq.com:80
      weight: 100
' | deck gateway apply -

Let’s update the example_service Service to point to this Upstream, instead of pointing directly to a URL:

echo '
_format_version: "3.0"
services:
  - name: example_service
    host: example_upstream
' | deck gateway apply -

You now have an Upstream with two Targets, httpbin.konghq.com and httpbun.com, and a Gateway Service pointing to that Upstream.

For the purposes of our example, the Upstream is pointing to two different Targets. More commonly, Targets will be instances of the same upstream service running on different host systems.

Validate load balancing

Validate that the Upstream you configured is working by visiting the /mock route several times, waiting a few seconds between each time. You will see the hostname change between httpbin and httpbun:

curl -s http://localhost:8000/mock/headers \
  -H 'apikey:top-secret-key' | grep -i -A1 '"host"'

curl -s $KONNECT_PROXY_URL/mock/headers \
  -H 'apikey:top-secret-key' | grep -i -A1 '"host"'

One of the ways Kong delivers performance is through caching. The Proxy Cache plugin accelerates performance by caching responses based on configurable response codes, content types, and request methods. When caching is enabled, upstream services are not bogged down with repetitive requests, because Kong Gateway responds on their behalf with cached results.

Let’s enable the Proxy Cache plugin globally:

echo '
_format_version: "3.0"
plugins:
  - name: proxy-cache
    config:
      request_method:
      - GET
      response_code:
      - 200
      content_type:
      - application/json
      cache_ttl: 30
      strategy: memory
' | deck gateway apply -

This configures a Proxy Cache plugin with the following attributes:

• Kong Gateway will cache all GET requests that result in response codes of 200
• It will also cache responses with the Content-Type headers that equal application/json
• cache_ttl instructs the plugin to flush values after 30 seconds
• config.strategy=memory specifies the backing data store for cached responses. More information on strategy can be found in the parameter reference for the Proxy Cache plugin.

Validate caching

You can check that the Proxy Cache plugin is working by sending GET requests and examining the returned headers.

Run the following command to send 2 mock requests. The Proxy Cache plugin returns status information headers prefixed with X-Cache, so you can use grep to filter for that information:

for _ in {1..2}; do \
  curl -s -i http://localhost:8000/mock/anything \
    -H 'apikey:top-secret-key'; \
  echo; sleep 1; \
done | grep -E 'X-Cache'

for _ in {1..2}; do \
  curl -s -i $KONNECT_PROXY_URL/mock/anything \
    -H 'apikey:top-secret-key'; \
  echo; sleep 1; \
done | grep -E 'X-Cache'

On the initial request, there should be no cached responses, and the headers will indicate this with X-Cache-Status: Miss:

X-Cache-Key: c9e1d4c8e5fd8209a5969eb3b0e85bc6
X-Cache-Status: Miss

The following response will be cached and show X-Cache-Status: Hit:

X-Cache-Key: c9e1d4c8e5fd8209a5969eb3b0e85bc6
X-Cache-Status: Hit

Rate limiting is used to control the rate of requests sent to an upstream service. It can be used to prevent DoS attacks, limit web scraping, and other forms of overuse. Without rate limiting, clients have unlimited access to your upstream services, which may negatively impact availability.

In this example, we’ll use the Rate Limiting plugin. Installing the plugin globally means that every proxy request to Kong Gateway will be subject to rate limit enforcement:

echo '
_format_version: "3.0"
plugins:
  - name: rate-limiting
    config:
      minute: 5
      policy: local
' | deck gateway apply -

In this example, you configured a limit of 5 requests per minute for all Routes, Services, and Consumers.

Validate rate limiting

You can check that the Rate Limiting plugin is working by sending GET requests and examining the returned headers.

Run the following command to send 6 mock requests:

for _ in {1..6}; do
  curl  -i $KONNECT_PROXY_URL/mock/anything \
       -H "apikey:top-secret-key" 
  echo
done

for _ in {1..6}; do
  curl  -i http://localhost:8000/mock/anything \
       -H "apikey:top-secret-key" 
  echo
done

On the last request, you should get a 429 response with the message API rate limit exceeded.

After the 6th request, you should receive a 429 error, which means your requests were rate limited according to the policy:

HTTP/1.1 429 Too Many Requests