What is deck and How can it be used in Kong? A Hands-on Guide

Deck

Deck is a tool that helps you manage your Kong configuration in a declarative way. This configuration can be conveniently stored in the code repository. Deck is responsible for synchronizing the Kong configuration in the code repository with the running Kong instance. It was created mainly to make it easy to automate Kong configuration management in CI/CD processes.

In the world of Kong, Deck is a tool that helps manage configurations using declarative files. These files describe how Kong's API Gateway should be set up, including things like services, routes, and plugins.

Overall, Deck simplifies managing Kong clusters by providing a clear and manageable way to define and apply configurations.

Why Use Deck?

There are several benefits to using Deck for managing configurations in Kong:

• Version control: Deck uses declarative files, which can be version controlled using tools like Git. This allows you to track changes to your Kong configuration over time, revert to previous versions if needed, and collaborate with others on configuration management.

• Repeatability and automation: With Deck, you can define your desired Kong configuration in a file. This makes it easy to deploy the same configuration across multiple environments (e.g., development, staging, production) or automate deployments using CI/CD pipelines.

• Reduced errors: Manual configuration changes in Kong can be prone to errors. Deck allows you to define your configuration declaratively, reducing the risk of typos or inconsistencies.
• Improved collaboration: Deck's declarative files make it easier for teams to collaborate on Kong configuration management. Everyone can see the desired state of the configuration in a single file.

• Backup and disaster recovery: Deck allows you to easily export your Kong configuration to a file. This file can be used to back up your configuration or restore it in case of a disaster.

• Simplified configuration management: Overall, Deck simplifies the process of managing Kong configurations by providing a centralized and automated approach. This can save time and effort for administrators.

Install Deck:

Want to get started with Deck?

The official installation guide is available here:

https://docs.konghq.com/deck/latest/installation/

As I am on Windows, here are the specific commands to install Deck:

1. download https://github.com/kong/deck/releases/download/v1.35.0/deck_1.35.0_windows_amd64.tar.gz

2. curl -sL https://github.com/kong/deck/releases/download/v1.35.0/deck_1.35.0_windows_amd64.tar.gz -o deck.tar.gz

3. mkdir deck

4. tar -xf deck_1.35.0_windows_amd64.tar.gz -C deck

5. powershell -command "[Environment]::SetEnvironmentVariable('Path', [Environment]::GetEnvironmentVariable('Path', 'User') + [IO.Path]::PathSeparator + [System.IO.Directory]::GetCurrentDirectory() + '\deck', 'User')"

Ready to see Deck in action? Let's try out some commands and see how they interact with Kong.

deck gateway ping:

deck gateway ping is a specific command used to verify connectivity between Deck and Kong's Admin API.

Now Let us create a service and a route.

Here's how to define a service in your Deck state file:

command:

curl -i -X POST --url http://localhost:8001/services/ --data 'name=Testing1' --data 'url=http://httpbin.org\get'

The Deck state file now includes the service definition for Kong.

Let's define a route in Kong.

curl -i -X POST --url http://localhost:8001/services/Testing1/routes --data 'name=Testing1_route' --data 'hosts[]=localhost:8000'

Perfect! With the route definition in your Deck state file.

deck gateway dump:

deck gateway dump --workspace default --output-file deck.yaml

What this command will do it?

The deck gateway dump command in Kong is used to export the entire configuration of your Kong Gateway instance into a local file. This file serves as a snapshot of your current Kong configuration, containing details about all entities like services, routes, plugins, consumers, and more.

There is a slight change in command which is described below.

• deck gateway dump: This specifies using the deck tool to perform a "dump" operation on your Kong Gateway configuration. Dumping refers to exporting the configuration data.

• --workspace default: This option (with the flag --workspace) defines the workspace you want to target for the dump operation. Here, it's set to "default," which likely refers to the default workspace used by Deck in your environment.

Workspaces are a Kong Gateway Enterprise feature that allows managing multiple configurations within the same Kong instance. If you're not using Kong Gateway Enterprise, this flag might be omitted.

• --output-file deck.yaml: This option (with the flag --output-file) specifies the destination for the dumped configuration. Here, it's set to a file named "deck.yaml." This tells Deck to write the exported configuration data in YAML format to the "deck.yaml" file.

The deck.yaml file containing our Kong configuration has been successfully saved to our local machine.

Checking the deck.yaml file confirms that the configuration for our Testing1 service has been successfully exported.

Service

Route

Let's modify some aspects of the Testing1 service and its route within the Deck state file.

The deck.yaml file has been updated! I've made some changes to the Testing1 service and route configuration, which are likely highlighted in yellow for clarity. Additionally, I've added a new path (/deck_testing) to the route definition.

I've refreshed the Kong Gateway, but the changes in the deck.yaml file don't seem to be reflected yet.

Service configuration:

Route configuration

Let's now switch gears and talk about the deck gateway diff command.

deck gateway diff:

The deck gateway diff command in Kong is a vital tool for understanding the discrepancies between your desired Kong configuration and its current state.

deck gateway diff essentially performs a dry run by comparing the configuration defined in your Deck state file with the actual configuration running on your Kong instance. It highlights any differences between:

• Existing entities: Services, routes, plugins, consumers, and other entities defined in Kong.

• Missing entities: Entities present in your Deck state file but not yet configured in Kong.

• Modified entities: Entities that have different properties in your Deck state file compared to the running Kong instance.

Benefits of using deck gateway diff:

• Prevents unintended changes: By identifying differences beforehand, you can avoid accidentally applying unwanted configuration changes to your Kong instance.

• Highlights configuration drift: It helps detect any manual modifications made directly to Kong's configuration, which can lead to inconsistencies with your desired state defined in the Deck file.

• Improves debugging: If you encounter issues with your Kong setup, deck gateway diff can help pinpoint discrepancies between your intended configuration and the actual state.

command:

deck gateway diff --workspace default

Thus, this command will create a service “Testing1_New” and route “Testing1_routeNew” which we had edited in the deck.yaml configuration file in the above steps.

Let's move on to step 4, where we'll use the deck gateway sync command

deck gateway sync:

The deck gateway sync command updates our Kong Gateway to reflect the settings we've defined in a separate file.

command:

deck gateway sync --workspace default deck.yaml

This command utilizes the deck tool to manage configurations in Kong Gateway and specifically targets a workspace and a state file. Let's break it down:

• deck gateway sync: This specifies using the deck tool to perform a "sync" operation on your Kong Gateway configuration. Sync refers to synchronizing the configuration with the state file.

• --workspace default: This option (with the flag --workspace) defines the workspace you want to target for the synchronization. Here, it's set to "default," which means Deck will focus on the default workspace within your Kong Gateway instance (if applicable). Workspaces are a Kong Gateway Enterprise feature for managing multiple configurations. If you're not using Kong Gateway Enterprise, this flag might be omitted.

• deck.yaml: This refers to the state file containing your desired Kong Gateway configuration. It likely resides in the current directory where you're running the command.

And now, if we sign in to Kong Manager, we can check whether or not the new route and service have been created.

Thus, it is evident that Kong has invented a new service and route.

deck gateway validate:

The deck gateway validate command acts as a quality check for your Kong Gateway configuration defined in a Deck state file. Here's a breakdown:

validate: This keyword indicates the action you want to perform, which is validation.

What deck gateway validate does:

1. Reads the State File: The command reads the configuration details entirely from the specified Deck state file.

2. Checks for Errors: It performs various checks on the configuration data within the file. Here are some potential validations:

a. Syntax Errors: Ensures the YAML or JSON format of the file is valid and free of any typos or syntax errors.

b. Missing References: Checks if all entities referenced in the configuration (e.g., a route referencing a specific service) actually exist in the state file itself. This helps identify potential configuration inconsistencies.

c. Internal Consistency: Validates if the configuration adheres to Kong's internal rules and logic. For example, checking if plugin configurations are compatible with the referenced services or routes.

command:

deck gateway validate --workspace default deck.yaml

deck gateway reset:

The deck gateway reset command in Kong is a powerful but potentially destructive operation. It's used to completely wipe out the existing configuration of our Kong Gateway instance.

What deck gateway reset does?

This command essentially deletes all entities (services, routes, plugins, consumers, etc.) currently configured in our Kong Gateway instance. It essentially resets Kong to a blank slate, removing any existing API definitions, access controls, or plugin configurations.

Important Considerations:

• Irreversible Action: Unlike some other deck commands, deck gateway reset is an irreversible operation. Once executed, there's no way to recover the previous configuration without backups.

• Use with Caution: Due to its destructive nature, it's crucial to use this command with extreme caution. It's recommended only for scenarios where you absolutely need to start fresh with a clean Kong Gateway configuration.

• Alternative Approaches: Depending on your situation, alternative approaches might be more suitable:

a. deck gateway sync with an empty state file: If we want to remove all configurations from Kong, we can create a blank Deck state file (containing no entities) and use deck gateway sync with that file. This achieves the same outcome as deck gateway reset but allows us to potentially recover from accidental execution by keeping the blank state file as a reference.

b. Manual Configuration Removal: For smaller deployments, we might consider manually removing configurations through the Kong Admin API or the Kong Gateway interface.

command:

deck gateway reset --workspace default deck.yaml

Deck documentation for Kong is available here: https://docs.konghq.com/deck/latest/

Conclusion:

This is an article about a tool called Deck. It helps manage Kong's configuration in a declarative way. Deck offers a variety of commands to accomplish this. Some of these commands help generate configuration files. Others help transform existing configurations. Still others help synchronize configurations with Kong. Overall, Deck seems to be a useful tool for managing Kong configurations.