APIOps with decK
API Lifecycle Automation (APIOps) is the process of applying
automation frameworks to API best practices. decK enables APIOps by
providing a tool with varied commands that can be coordinated to build
API delivery automations.
decK commands break down into the following categories:
- Configuration generation
- Configuration transformation
- Gateway state management
This guide walks you through using the configuration
generation and transformation commands to build an API automation delivery pipeline.
OpenAPI is the most commonly used standard
for defining API behavior. OpenAPI Specifications (OAS) are useful
for many API development related tasks including generating documentation
and API client code. With decK, you can also generate Kong Gateway
configuration from OAS files.
Let’s assume you have the following minimal OAS in a file named
title: httpbin API
description: Simple API for testing purposes
- url: http://httpbin.org
summary: Get a simple response from the /request resource of the httpbin API
description: Successful response
You can generate a Kong Gateway configuration with the following:
deck file openapi2kong \
--spec oas.yaml \
Which produces a complete decK configuration file:
- host: httpbin.org
- id: 803b324e-98ed-5ec5-aecf-b4ce973036f4
Note: The Kong Gateway getting started guide
can help you quickly run a gateway in Docker to follow along with these instructions.
You can synchronize this directly to the gateway using
deck sync -s httpbin.yaml
Which creates the service and route:
creating service httpbin-api
creating route httpbin-api_request_get
This is a very simple example. In reality, you will generally want to configure more sophisticated Kong Gateway capabilities
for your API. Maybe you want to secure your API with an
or protect it with traffic management.
These API Gateway concepts are usually orthogonal to the OAS, and a clearer
separation of concerns is achieved if they are configured independently of the specification.
This can be accomplished with decK file transformations.
If you are building microservices or an API platform for multiple teams, you likely have
multiple services and code repositories with their own decK configuration files.
Using decK file transformation commands, you can organize your decK configuration files into partial segments
of the full configuration and assemble them prior to synchronizing with Kong Gateway.
This allows you to organize different aspects of the configuration in alignment with the rest of your
software development artifacts.
Continuing the example above, let’s take a look at how commands can be pipelined to create API lifecycle automations.
Let’s assume you have a second team that builds a different API, and
provides a Kong Gateway decK configuration segment for their service and route. Copy the
following configuration into a file named
- host: httpbin.org
- id: 08ac3482-843a-40f8-a277-a4e73baf19d9
You can use the decK
file merge command to bring these two configurations into one:
deck file merge httpbin.yaml another-httpbin.yaml \
You now have a file named
merged-kong.yaml, which is a single decK file with both services and routes merged. This file is
also a complete deck file and could be synchronized to a gateway. Before doing that, let’s take the example one step further.
Now assume you want to ensure that all services in your configuration communicate with the upstream endpoint
https only. You can use the deck
file patch command to accomplish this:
deck file patch --state merged-kong.yaml \
--selector "$.services[*]" \
--value 'protocol: "https"' \
kong.yaml file is a full configuration you can synchronize to the gateway:
Here is an example of putting the above together in a Unix-style pipeline:
deck file openapi2kong --spec oas.yaml --output-file httpbin.yaml &&
deck file merge httpbin.yaml another-httpbin.yaml |
deck file patch --selector "$.services[*]" --value 'protocol: "https"' |
deck sync -s -
Most commonly, you will use the commands from CI/CD tools built into your version control system
to bring full and partial Kong Gateway configurations together to create APIOps for your
See the example file at Kong/go-apiops
for extensive annotations explaining the conversion process, as well as all supported custom