You are browsing documentation for an older version. See the latest documentation here.
Getting Started with decK
Once you’ve installed decK, let’s get started with it.
You can find help in the terminal itself for any command using the -help
flag.
Install Kong
Make sure you’ve Kong installed and have access to Kong’s Admin API.
In this guide, we’re assuming that Kong is running at http://localhost:8001
.
Please change it to the network address where Kong is running in your case.
Configuring Kong
First, make a few calls to configure Kong. If you already have Kong configured with the configuration of your choice, you can skip this step.
# create a service
$ curl -s -XPOST 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 above service
$ curl -s -XPOST 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 -XPOST 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
Export Kong’s configuration:
$ deck dump
# look at the kong.yaml file that is generated:
$ cat kong.yaml
_format_version: "1.1"
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 installation.
Change the configuration
Let’s edit the kong.yaml
file now. We’re going to make the following changes:
- Change the
port
of servicefoo
to443
- Change the
protocol
of servicefoo
tohttps
- Add another string element
/baz
to thepaths
attribute of routebar
.
# your kong.yaml file should look like:
$ cat kong.yaml
_format_version: "1.1"
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
# let's perform a diff
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's database.
# apply the changes
deck sync
# curl Kong's Admin API to see the updated route and service in Kong.
# you can also run the diff command, which will report no changes
deck diff
Drift detection using decK
Create a consumer in Kong:
$ curl -s -XPOST http://localhost:8001/consumers -d 'username=dodo' | jq
{
"custom_id": null,
"created_at": 1573162649,
"id": "ed32faa1-9105-488e-8722-242e9d266717",
"tags": null,
"username": "dodo"
}
Note that we have created this consumer in Kong but the consumer doesn’t exist
in the kong.yaml
file we’ve saved on disk.
Let’s see what decK reports on a diff now:
$ deck diff
deleting consumer dodo
Since the file does not contain the consumer definition, decK reports that
a sync
run will delete the consumer from Kong’s database.
Let’s go ahead and run the sync process.
$ deck sync
Now, looking up the consumer in Kong’s database will return a 404
:
$ curl http://localhost:8001/consumers/dodo
{"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 that are not part of your configuration
file, and alert your teams if such a discrepancy is present.
Reset your configuration
Finally, you can reset the configuration of Kong using decK.
The changes performed by this command are irreversible (unless you’ve created a
backup using deck dump
), so please be careful.
$ deck reset
This will delete all configuration from Kong's database.
> Are you sure? y
And that’s it. Start using decK to declaratively configure your Kong installation today!