You are browsing unreleased documentation. See the latest documentation here.

decK

Manage Kong Konnect, Kong Gateway, and Kong Ingress Controller configuration declaratively

Quick links

Introducing decK

decK is a command line tool that facilitates API Lifecycle Automation (APIOps) by offering a comprehensive toolkit of commands designed to orchestrate and automate the entire process of API delivery. APIOps involves leveraging automation frameworks to streamline and enforce best practices throughout the API lifecycle. This enables developers and operations teams to manage APIs from development through deployment, ensuring consistency, reliability, and speed in API integrations.

decK operates on state files. decK state files describe the configuration of Kong API Gateway. State files encapsulate the complete configuration of Kong in a declarative format, including services, routes, plugins, consumers, and other entities that define how requests are processed and routed through Kong.

Check out our KongAir use case to learn how decK can be used to streamline API management processes for an airline.

decK is compatible with Kong Gateway (OSS) >= 1.x and Kong Gateway Enterprise >= 0.35.

decK commands

The decK commands are structured into three main categories:

1. Configuration Generation: This category focuses on the initial creation of decK state files from industry-standard API specification formats. This category includes the following command:
   • deck file openapi2kong: Converts OpenAPI specification files into decK state files.
2. Configuration Transformation: This set of commands provides the tools needed to refine and restructure decK configuration files. It allows for the segmentation of a full configuration into smaller, manageable parts and their subsequent reassembly. This category includes the following commands:
   • deck file add-plugins: Incorporates plugins into decK objects.
   • deck file add-tags: Attaches tags to decK objects for enhanced organization.
   • deck file list-tags: Enumerates tags associated with decK objects.
   • deck file remove-tags: Eliminates tags from decK objects.
   • deck file lint: Assesses a decK file against a set of linting rules, identifying any discrepancies.
   • deck file patch: Applies modifications to a decK file without overhauling the entire configuration.
   • deck file merge: Combines several partial decK files into a comprehensive one.
   • deck file namespace: Apply a namespace to routes in a decK file by prefixing the path.
   • deck file render: Fuses multiple complete decK files, rendering a singular, unified configuration.
   • deck file validate: Conducts an offline validation of the state file, pinpointing potential issues.
   • deck file kong2kic: Converts decK state files into Kong Ingress Controller manifests.
   • deck file kong2tf: Converts decK state files into Terraform resources.
3. Gateway State Management: This category encompasses commands that facilitate the synchronization of the final decK file with the target platform, be it Kong Konnect, Kong Gateway, or Kong Ingress Controller. This category includes:
   • deck gateway ping: Confirms connectivity with Kong’s Admin API.
   • deck gateway validate: Validates the state file against the Kong Admin API in an online setting.
   • deck gateway dump: Extracts all entities from Kong and archives them in a local file.
   • deck gateway diff: Executes a trial run of the deck gateway sync command to preview changes.
   • deck gateway sync: Synchronizes the state file with Kong, ensuring alignment.
   • deck gateway reset: Purges all entities from Kong, resetting its state.

Through these categories and their associated commands, decK offers a comprehensive suite of tools for configuration and management within the Kong platform.

Looking for help or need to report an issue?

Find help

One of the design goals of decK is to deliver a good developer experience. To find help, use the following resources:

• The --help flag gives you the necessary help in the terminal itself and should solve most of your problems.
• If you still need help, open a Github issue to ask your question.
• decK has very wide adoption by Kong’s community and you can seek help from the larger community at Kong Nation.

Report a bug

If you believe you have run into a bug with decK, open a Github issue.

If you think you’ve found a security issue with decK, read the Security section.

Security

decK does not offer to secure your Kong deployment but only configures it. It encourages you to protect your Kong Admin API implementation with authentication but doesn’t offer such a service itself.

decK’s state file can contain sensitive data such as private keys of certificates, credentials, etc. It is up to the user to manage and store the state file in a secure fashion.

If you believe that you have found a security vulnerability in decK, submit a detailed report, along with reproducible steps to security@konghq.com.

Licensing

decK is licensed with Apache License Version 2.0. Read the LICENSE file for more details.

More resources

• decK FAQs
• Use case: Streamlining KongAir APIs, based on the KongAir demo app
• References: The command line --help flag on the main command or a subcommand (like diff, sync, reset, and so on) shows the help text along with supported flags for those commands. You can also see the references for all commands available with decK in the decK documentation.
• Video: Kong Summit motivation behind decK. Harry Bagdi gave a talk on the motivation behind decK and demonstrated a few key features of decK at Kong Summit 2019.
• Changelog: See the CHANGELOG file in the Kong/deck repository.