このページは、まだ日本語ではご利用いただけません。翻訳中です。
旧バージョンのドキュメントを参照しています。 最新のドキュメントはこちらをご参照ください。
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: 3.7.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 servicefoo
to443
- Change the
protocol
of servicefoo
tohttps
- Add another string element
/baz
to thepaths
attribute of routebar
.
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/3.7.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
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 :