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.