Skip to content
2023 API Summit Hackathon: Experiment with AI for APIs (August 28 - September 27) Learn More →
Kong Logo | Kong Docs Logo
search
  • We're Hiring!
  • Docs
    • Kong Gateway
      Lightweight, fast, and flexible cloud-native API gateway
      Kong Konnect
      Single platform for SaaS end-to-end connectivity
      Kong Mesh
      Enterprise service mesh based on Kuma and Envoy
      decK
      Helps manage Kong’s configuration in a declarative fashion
      Kong Ingress Controller
      Works inside a Kubernetes cluster and configures Kong to proxy traffic
      Insomnia
      Collaborative API development platform
      Kuma
      Open-source distributed control plane with a bundled Envoy Proxy integration
      Docs Contribution Guidelines
      Want to help out, or found an issue in the docs and want to let us know?
  • API Specs
  • Plugin Hub
    • Explore the Plugin Hub
      View all plugins View all plugins View all plugins arrow image
    • Functionality View all View all arrow image
      View all plugins
      Authentication's icon
      Authentication
      Protect your services with an authentication layer
      Security's icon
      Security
      Protect your services with additional security layer
      Traffic Control's icon
      Traffic Control
      Manage, throttle and restrict inbound and outbound API traffic
      Serverless's icon
      Serverless
      Invoke serverless functions in combination with other plugins
      Analytics & Monitoring's icon
      Analytics & Monitoring
      Visualize, inspect and monitor APIs and microservices traffic
      Transformations's icon
      Transformations
      Transform request and responses on the fly on Kong
      Logging's icon
      Logging
      Log request and response data using the best transport for your infrastructure
  • Support
  • Community
  • Kong Academy
Get a Demo Start Free Trial
decK
1.11.x
  • Home icon
  • decK
  • Guides
  • Getting Started
  • Get Started with decK
github-edit-pageEdit this page
report-issueReport an issue
  • Kong Gateway
  • Kong Konnect
  • Kong Mesh
  • Plugin Hub
  • decK
  • Kong Ingress Controller
  • Insomnia
  • Kuma

  • Docs contribution guidelines
  • 1.27.x (latest)
  • 1.26.x
  • 1.25.x
  • 1.24.x
  • 1.23.x
  • 1.22.x
  • 1.21.x
  • 1.20.x
  • 1.19.x
  • 1.18.x
  • 1.17.x
  • 1.16.x
  • 1.15.x
  • 1.14.x
  • 1.13.x
  • 1.12.x
  • 1.11.x
  • 1.10.x
  • 1.9.x
  • 1.8.x
  • 1.7.x
  • pre-1.7
enterprise-switcher-icon Switch to OSS
On this pageOn this page
  • Install Kong Gateway
  • Configure Kong Gateway
  • Export the configuration
  • Change the configuration
  • diff and sync the configuration to Kong Gateway
  • Drift detection using decK
  • Reset your configuration
  • Next steps
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.

  1. 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
     }
    
  2. 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
     }
    
  3. 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

  1. 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
    
  2. Export Kong Gateway’s configuration:

     deck dump
    
  3. 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

  1. 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.

  2. Apply the changes:

     deck sync
    
  3. Curl Kong’s Admin API to see the updated route and service in Kong Gateway:

     curl -i -X GET http://localhost:8001/services
    
  4. Run the diff command again, which should report no changes:

     deck diff
    

Drift detection using decK

  1. 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.

  2. 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.

  3. Run the sync process:

     deck sync
    
  4. 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
Thank you for your feedback.
Was this page useful?
Too much on your plate? close cta icon
More features, less infrastructure with Kong Konnect. 1M requests per month for free.
Try it for Free
  • Kong
    THE CLOUD CONNECTIVITY COMPANY

    Kong powers reliable digital connections across APIs, hybrid and multi-cloud environments.

    • Company
    • Customers
    • Events
    • Investors
    • Careers Hiring!
    • Partners
    • Press
    • Contact
  • Products
    • Kong Konnect
    • Kong Gateway
    • Kong Mesh
    • Get Started
    • Pricing
  • Resources
    • eBooks
    • Webinars
    • Briefs
    • Blog
    • API Gateway
    • Microservices
  • Open Source
    • Install Kong Gateway
    • Kong Community
    • Kubernetes Ingress
    • Kuma
    • Insomnia
  • Solutions
    • Decentralize
    • Secure & Govern
    • Create a Dev Platform
    • API Gateway
    • Kubernetes
    • Service Mesh
Star
  • Terms•Privacy
© Kong Inc. 2023