Get started with decK

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 -

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 an HTTP request to your running Kong Gateway instance and see it proxied to httpbin:

curl "$KONNECT_PROXY_URL/anything"

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

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
      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  -i $KONNECT_PROXY_URL/anything  
  echo
done

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

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

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 "$KONNECT_PROXY_URL/anything" \
     -H "apikey:hello_world"

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.

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

Open the newly created kong.yaml in your favorite editor.

Try changing Alice’s authentication key to test and then sync the entire configuration back up:

deck gateway sync kong.yaml

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.