Get Started with decK

This page teaches you how to use decK to create a service, route, plugins, and consumers. It uses the deck gateway apply command to build the configuration up incrementally. At any point, you can run deck gateway dump to see the entire configuration of Kong Gateway at once.

Prerequisites

Before working through this guide, ensure that you have Kong Gateway running and decK installed.

Run Kong Gateway

The quickest way to run Kong Gateway is using the quickstart script:

curl -Ls https://get.konghq.com/quickstart | bash

Install decK

To complete this guide, you’ll need decK v1.43.0 or above installed.

If you don’t have decK installed, copy the following line in to your terminal to run decK using Docker for the purposes of this guide:

alias deck='docker run --rm -v .:/files -w /files -e DECK_KONG_ADDR=http://host.docker.internal:8001 kong/deck'

Create a Service

You can use decK to configure a Service by providing a name and a url. Any requests made to this Service will be proxied to http://httpbin.konghq.com:

echo '_format_version: "3.0"
services:
 - name: example-service
   url: http://httpbin.konghq.com' | deck gateway apply

Create a Route

To access this Service, you need to configure a Route. Create a Route that matches incoming requests that start with /, and attach it to the service that was previously created by specifying service.name:

echo '_format_version: "3.0"
routes:
  - name: example-route
    service: 
      name: example-service
    paths:
      - "/"' | deck gateway apply

You can now make a HTTP request to your running Kong Gateway instance and see it proxied to httpbin:

curl http://localhost:8000/anything

Add rate limiting

At this point, Kong Gateway is a transparent layer that proxies requests to the upstream httpbin instance. Let’s add the Rate Limiting plugin to make sure that people only make five requests per minute:

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

To see this in action, make six requests in rapid succession by pasting the following in to your terminal:

for _ in {1..6}; do 
  curl http://localhost:8000/anything
done

Add authentication

You may have noticed that the rate limiting plugin used the limit_by: consumer configuration option. This means that each uniquely identified consumer is allowed 5 requests per minute.

To identify a consumer, let’s add the Key Auth plugin and create a test user named alice:

echo '_format_version: "3.0"
plugins:
  - name: key-auth
    service: example-service
consumers:
  - username: alice
    keyauth_credentials:
      - key: hello_world' | deck gateway apply

After applying the key-auth plugin, you need to provide the apikey header to authenticate your request:

curl http://localhost:8000/anything -H 'apikey: hello_world'

If you make a request without the authentication header, you will see a No API key found in request message.

See your decK file

This page provided each configuration snippet separately to focus on what each snippet provides. For production usage, you should apply the whole configuration each time.

To export the complete configuration, run deck gateway dump -o kong.yaml, then open kong.yaml in your favorite editor.

Try changing Alice’s authentication key to test and then run deck gateway sync kong.yaml to sync the entire configuration. You’ll see the following output:

creating key-auth test for consumer alice
deleting key-auth world for consumer alice
Summary:
  Created: 1
  Updated: 0
  Deleted: 1

Congratulations! You just went from zero to a configured Kong Gateway using decK in no time at all.