You are browsing documentation for an outdated version. See the latest documentation here.

Get Started with decK

Once you have installed decK, use this guide to get started with it.

You can find help in the terminal for any command using the --help flag, or see the CLI reference.

Install Kong Gateway

Make sure you have Kong Gateway installed and have access to Kong’s Admin API.

This guide assumes that Kong Gateway is running at http://localhost:8001. If your URL is different, change the URL to the network address where the gateway is running.

Configure Kong Gateway

First, make a few calls to configure Kong Gateway.

If you already have Kong Gateway set up with the configuration of your choice, you can skip to exporting the configuration.

Create a service:

 curl -s -X POST http://localhost:8001/services -d 'name=foo' -d 'url=http://example.com' | jq
 {
   "host": "example.com",
   "created_at": 1573161698,
   "connect_timeout": 60000,
   "id": "9e36a21e-3e92-44e3-8810-4fb8d80d3518",
   "protocol": "http",
   "name": "foo",
   "read_timeout": 60000,
   "port": 80,
   "path": null,
   "updated_at": 1573161698,
   "retries": 5,
   "write_timeout": 60000,
   "tags": null,
   "client_certificate": null
 }

Create a route associated with the service:

 curl -s -X POST http://localhost:8001/services/foo/routes -d 'name=bar' -d 'paths[]=/bar' | jq
 {
   "id": "83c2798d-6bd8-4182-a799-2632c9f670a5",
   "tags": null,
   "updated_at": 1573161777,
   "destinations": null,
   "headers": null,
   "protocols": [
     "http",
     "https"
   ],
   "created_at": 1573161777,
   "snis": null,
   "service": {
     "id": "9e36a21e-3e92-44e3-8810-4fb8d80d3518"
   },
   "name": "bar",
   "preserve_host": false,
   "regex_priority": 0,
   "strip_path": true,
   "sources": null,
   "paths": [
     "/bar"
   ],
   "https_redirect_status_code": 426,
   "hosts": null,
   "methods": null
 }

Create a global plugin:

 curl -s -X POST http://localhost:8001/plugins -d 'name=prometheus' | jq
 {
     "config": {},
     "consumer": null,
     "created_at": 1573161872,
     "enabled": true,
     "id": "fba8015e-97d0-45ef-9f27-0ad76fef68c8",
     "name": "prometheus",
     "protocols": [
         "grpc",
         "grpcs",
         "http",
         "https"
     ],
     "route": null,
     "run_on": "first",
     "service": null,
     "tags": null
 }

Export the configuration

Check that decK recognizes your Kong Gateway installation:
```
 deck ping
```
If the connection is successful, the terminal displays your gateway version:
```
 Successfully connected to Kong!
 Kong version:  2.5.1
```
Export Kong Gateway’s configuration:
```
 deck dump
```

Open the generated kong.yaml file. If you’re using the sample configuration in this guide, the file should look like this:

 _format_version: "3.0"
 services:
 - connect_timeout: 60000
   host: example.com
   name: foo
   port: 80
   protocol: http
   read_timeout: 60000
   retries: 5
   write_timeout: 60000
   routes:
   - name: bar
     paths:
     - /bar
     preserve_host: false
     protocols:
     - http
     - https
     regex_priority: 0
     strip_path: true
     https_redirect_status_code: 426
 plugins:
 - name: prometheus
   enabled: true
   run_on: first
   protocols:
   - grpc
   - grpcs
   - http
   - https

You’ve successfully backed up the configuration of your Kong Gateway installation.

Change the configuration

Edit the kong.yaml file, making the following changes:

Change the port of service foo to 443
Change the protocol of service foo to https
Add another string element /baz to the paths attribute of route bar.

Your kong.yaml file should now look like this:

_format_version: "3.0"
services:
- connect_timeout: 60000
  host: example.com
  name: foo
  port: 443
  protocol: https
  read_timeout: 60000
  retries: 5
  write_timeout: 60000
  routes:
  - name: bar
    paths:
    - /bar
    - /baz
    preserve_host: false
    protocols:
    - http
    - https
    regex_priority: 0
    strip_path: true
    https_redirect_status_code: 426
plugins:
- name: prometheus
  enabled: true
  run_on: first
  protocols:
  - grpc
  - grpcs
  - http
  - https

diff and sync the configuration to Kong Gateway

Run the diff command:
```
 deck diff
```
You should see decK reporting that the properties you had changed in the file are going to be changed by decK in Kong Gateway’s database.
Apply the changes:
```
 deck sync
```
Curl Kong’s Admin API to see the updated route and service in Kong Gateway:
```
 curl -i -X GET http://localhost:8001/services
```
Run the diff command again, which should report no changes:
```
 deck diff
```

Drift detection using decK

Create a consumer in Kong Gateway:

 curl -s -X POST http://localhost:8001/consumers -d 'username=example-consumer' | jq

Response:

 {
   "custom_id": null,
   "created_at": 1573162649,
   "id": "ed32faa1-9105-488e-8722-242e9d266717",
   "tags": null,
   "username": "example-consumer"
 }

This command creates a consumer in Kong Gateway, but the consumer doesn’t exist in the kong.yaml file saved on disk.

Check what decK reports on a diff now:
```
 deck diff
```
Response:
```
 deleting consumer example-consumer
```
Since the file does not contain the consumer definition, decK reports that a sync run will delete the consumer from Kong Gateway’s database.
Run the sync process:
```
 deck sync
```

Now, looking up the consumer in Kong Gateway’s database returns a 404:

 curl -i -X GET http://localhost:8001/consumers/example-consumer

Response:

 HTTP/1.1 404 Not Found
 Date: Mon, 04 Oct 2021 17:00:50 GMT
 Content-Type: application/json; charset=utf-8
 Connection: keep-alive
 Access-Control-Allow-Origin: *
 Content-Length: 23
 X-Kong-Admin-Latency: 2
 Server: kong/2.5.1

 {"message":"Not found"}

This shows how decK can detect changes done directly using Kong’s Admin API can be detected by decK. You can configure your CI or run a cronjob in which decK detects if any changes exist in Kong Gateway that are not part of your configuration file, and alert your teams if such a discrepancy is present.

Reset your configuration

You can reset the configuration of using decK.

Warning: The changes performed by this command are irreversible (unless you’ve created a backup using deck dump), so be careful.

deck reset

Response:

This will delete all configuration from Kong's database.
> Are you sure? y

Next steps

See decK best practices, and check out the individual guides for getting :

Backup and restore of Kong Gateway’s configuration
Deduplicate plugin configuration