API gateways serve as the final checkpoint for your APIs. As such, gateway configuration is critical to ensuring that your APIs remain secure, available, and responsive. Ensuring that all changes to these configurations are intentional and follow your organization's best practices is key to maintaining a robust API gateway deployment. 

decK 1.28 adds a brand new feature that allows you to natively validate your gateway configurations against custom rule sets. This helps ensure that best practices are followed and further fortifies your gateway deployments.

Linting is a common development process for validating code against a set of rules by looking for potential errors, stylistic issues, or deviations from standards. The code is flagged when rule violations are detected, allowing developers to intervene before potentially damaging changes make their way into production systems. Often, linting is performed within code editors and integrated development environments (IDEs). However, its integration into CI/CD pipelines is equally vital, to ensure that all changes — regardless of their source — adhere to established coding standards before merging into the codebase. 

We have introduced linting capabilities directly into the decK command line tool, allowing you to perform a linting process for your API gateway configurations without introducing additional tools into your CI/CD pipelines.

deck file lint

The deck file lint command at its core is a flexible JSON/YAML linter that allows you to build rules to validate any file in these formats.

There are a few key concepts to understand for linting with decK:

• Rules are named configurations that filter values from the incoming file and specify how to validate their contents.
• Selectors define a filter to apply to the input file which selects the objects to validate. Selectors are specified in the given keyword on a Rule. Selectors are expressed using JSONPath syntax which is consistent with other APIOps commands provided by decK.
• Functions accept the filtered values and perform a validation returning information when there are violations.
• Rulesets are collections of Rules.

Rules also provide the flexibility to define severity levels and output formats adding to the command’s versatility. Let’s look at an example usage of the command to validate a common Kong Gateway configuration value.

Example

Kong Gateway services are defined in the services block in the decK file. Services support a number of configuration values including a protocol field which specifies the communication protocol used between the gateway and the upstream service. To ensure this traffic is secure, you may want to validate that only https protocols are used. Here is a sample Ruleset file containing a single Rule that accomplishes this.

In the given field, a JSONPath selector is specified that reads the protocol field in every service under the services key from the incoming file. With each of those values, the pattern function is applied which evaluates the value against a regular expression pattern specified in the match field. In this example, we assert that the string value in the protocol field must match the string https exactly. Let’s assume the example Ruleset file is stored in a file named ruleset.yaml, and look at the deck file lint command in practice.

Assume you have the following decK declarative configuration file (kong.yaml) that defines a service and a route for a simple task tracking system:

Validating this configuration against the example ruleset results in the following violations: 

Modifying the declarative configuration as follows resolves this violation:

Notice that the command results in a 0 (Success) return code. In situations where violations are detected, a non-zero return code is emitted allowing you to abort automated processes and help prevent problematic configurations from leaking into your production codebase and systems.

Deck uses the GoLang-based Vacuum library for the linting implementation. For more details on the library's support for Rules, Rulesets, and more examples of what can be done, see the Vacuum documentation. For APIOps and Kong-specific use cases, we hope to add more helpful examples to our APIOps library documentation. Please feel free to reach out in the GitHub repository by filing an issue for any common use cases you’d like to see documented.

Starting with Kong Gateway and decK is easy with Kong Konnect. Try this new decK feature with your Kong Konnect free trial today!