Get Started - Services, Routes, Plugins and Consumers

Description

Kong core entities are Services, Routes, Plugins and Consumers. In this learning lab, you will enable and configure these entities to:

  1. Forward requests through Kong to a Microservice (API)
  2. Protect the Microservice with a Kong Authentication plugin (key-auth)

The Topics and Tasks are as follows.

Scenario

High Level Tasks

  • Step 1: Setup the environment
  • Step 2: Add a Service using the Admin API
  • Step 3: Add a Route for the Service
  • Step 4: Verify requests are forwarded through Kong to the Service
  • Step 5: Add the Key-Auth Plugin for Authentication
  • Step 6: Add and Provision a Consumer
  • Step 7: Verify your microservice is protected with the Key-Auth plugin

Step 1: Setup the environment

Let’s setup the environment that will load the following

  1. Creates a Docker Network called kong-net
  2. Installs and starts the database
  3. Prepares your database (Kong migration)
  4. Installs and starts Kong with environment variables and configurations

Launch Setup Script

Run this script in the terminal to setup your environment (~30 seconds).

launch.sh

Verify Setup

This learning lab utilizes the Kong Enterprise command line. Verify that your environment is up and running.

http get localhost:8001/

Step 2: Add a Service using the Admin API​

Overview

APIs configurations instruct Kong when, where, and how to route traffic. In our example you’ll create an API that routes traffic for example.com to an upstream server at mockbin.com. If you have your own API already, you can use it as the upstream URL instead of httpbin.

One of the first configurations to allow for access to our API is to specific a service.

You create a Service pointing to the Httpbin. Httpbin is an “echo” type public website which returns the requests it gets back to the requester, as responses. This makes it helpful for learning how Kong proxies your API requests.

Add a Service using the Admin API Add a service to Kong named httpbin that will proxy request going to the URL httpbin.org/anything.

Run this command to add the service:

curl -i -X POST \
--url http://localhost:8001/services/ \
--data 'name=httpbin' \
--data 'url=http://httpbin.org/anything'

http post localhost:8001/services name=httpbin url=http://httpbin.org/anything

Alternatively: Add the Service in the Kong Manager, via Services & Routes:

Verify Service is Created

You can verify all the services configured on Kong by issuing this command:

http get localhost:8001/services

Step 3: Add a Route for the Service

Overview

For the service to be accessible, you’ll need to add a Route to it. Routes specify how (and if) requests are sent to their Services after they reach Kong. A single Service can have many Routes.

Add a Route for the Service Add a route to the service that you created by running this command.

curl -i -X POST \
--url http://localhost:8001/services/httpbin/routes \
--data 'hosts[]=example.com'

http post localhost:8001/services/httpbin/routes hosts:='["example.com"]'

Verify Route is Created Kong is now aware of your Service and ready to proxy requests.

Let’s verify the route has been created

http get localhost:8001/routes

Step 4: Verify requests are forwarded through Kong to the Service

Overview

After you add a Service and Route, you should be able to make requests through Kong using them.

Verify

Issue the following request to verify that Kong is properly forwarding requests to your Service. Note that by default Kong handles proxy requests on port :8000:

curl -i -X GET \
--url http://localhost:8000/ \
--header 'Host: example.com'

http get localhost:8000/  host:example.com

Great!

A successful response means Kong is now forwarding requests made to http://localhost:8000 to the url we configured in step #1, and is forwarding the response back to us. Kong knows to do this through the header defined in the above cURL request:

Step 5: Add a Plugin for Authentication

Overview

Plugins provide a modular system for modifying and controlling Kong’s capabilities. For example, to secure your API, you could require an access key. Plugins provide a wide array of functionality, including access control, caching, rate limiting, logging, and more.

In most cases, you will want to restrict access to your microservices. Here is where you can add various Kong plugins to protect your API. In this example, you’ll add the Key-Auth Plugin to Authenticate consumers to your microservice.

Add the Key-Auth Plugin

Let’s add a Plugin to authenticate users to your Microservice. In this example, you add the Key-Auth Plugin to the httpbin service you created previously.

curl -i -X POST \
--url http://localhost:8001/services/httpbin/plugins/ \
--data 'name=key-auth'

http post localhost:8001/services/httpbin/plugins  name=key-auth

Note: This plugin also accepts a config.key_names parameter, which defaults to [‘apikey’]. It is a list of headers and parameters names (both are supported) that are supposed to contain the apikey during a request.

Verify that the plugin is properly configured

Verify that the key-auth plugin was properly configured on the Service.

Run this command

http get localhost:8000/ host:example.com

Step 6: Add and Provision a Consumer

Introduction

In the last section, we learned how to add plugins to Kong, in this section we’re going to learn how to add consumers to your Kong instances. Consumers are associated to individuals using your API, and can be used for tracking, access management, and more.

Note: This section assumes you have enabled the key-auth plugin. If you haven’t, you can either enable the plugin or skip steps two and three.

Overview

Consumers represent end users of your API. For example, once you’ve added the Key Authentication plugin above, you’ll need to create a consumer and associated credentials. Consumers allow you to control who can access your APIs. They also allow you report on consumer traffic using logging plugins and Kong Vitals.

Once you add a the plugin, you add and provision a consumer for this plugin. This allows access to the microservice only if the consumer has the correct credentials.

Add a Consumer

Let’s create a user named Jason by issuing the following request:$

curl -i -X POST \
--url http://localhost:8001/consumers/ \
--data "username=Jason"

http post localhost:8001/consumers  username=Jason

Provision key credentials for your Consumer

Now, let’s create a key credential for the consumer Jason. You can use any key but in this example the key=jasonkey

curl -i -X POST \
--url http://localhost:8001/consumers/Jason/key-auth/ \
--data 'key=jasonkey'

http post localhost:8001/consumers/Jason/key-auth  key=jasonkey

Great!

You have just added a consumer named Jason and provisioned the key-auth key to jasonkey.

Step 7: Verify your microservice is protected with the Key-Auth plugin

Overview

Now that you’ve added valid credentials, only consumers that are allowed are able to access your microservice.

In summary, you created a service and a route to it. This allowed for Kong to forward request to this microservice. You then enabled authentication to this microservice and provisioned a consumer so that only users with valid credentials are able to access the microservice.

Verify

Verify that your Consumer credentials are valid. Run this command:

curl -i -X GET \
--url http://localhost:8000 \
--header "Host:  example.com" \
--header "apikey: jasonkey"

http get localhost:8000/ host:example.com apikey:jasonkey

Great!

A valid response indicates that consumer Jason with a valid authentication key is able to access the Microservice named httpbin through Kong. The response is the result of:

  1. Kong forwarding your request to the microservice

  2. The microservice responding to Kong

  3. Kong reverse proxying the response back to you

Edit this page