Kongrations

Description

Kongrations is a migrations like for Kong APIs and its associations like consumers and plugins.
You configure an environment and start creating files that will reproduce the specified changes into Kong using Kong Admin API.

Example of a migration to create an API:

create_api do |api|
  api.payload = {
    name: 'my-api',
    uris: '/myapi'
    upstream_url: 'https://myapi.mycompany.com',
  }
end

Why Kongrations?

• Control what happens into Kong APIs.
• Keep track of every change.
• Apply same changes to different environments.

All of this using a readable Ruby syntax to describe the migrations.

Compatibility

Kongrations was built upon Kong 0.13.x documentation.

Getting Started

Kongrations depends on Ruby 2.2 or greater. Make sure you have it installed, then install Kongrations gem.

gem install kongrations

Configuring environments

You need to create a file called kongrations.yml and specify the desired environments of Kong. You can use environments variables on the file too.

environments:
  - name: default
    kong-admin-url: kong-admin-url.domain.com # Do not include HTTP or HTTPS here.
    kong-admin-api-key: 123456789

  - name: production
    kong-admin-url: kong-admin-url-for-production.domain.com
    kong-admin-api-key: <%= ENV['MY_ENV_VARIABLE'] %>

Working with environments

Kongrations allows you to use parameters to specify differences across environments. You can do it as follows:

config_env 'default' do |env|
  env.upstream_url = 'https://myapi-staging.mycompany.com'
  env.retries = 0
end

config_env 'production' do |env|
  env.upstream_url = 'https://myapi.mycompany.com'
  env.retries = 2
end

create_api do |api|
  api.payload = {
    name: 'my-api',
    uris: '/myapi',
    upstream_url: env.upstream_url,
    retries: env.retries
  }
end

First, you need to set the variables for your existing environments specified on kongrations.yml file.
Then, you use them through env name, like: env.defined_variable.

Basic usage of the migrations

Defined migrations are mapped into HTTP requests to Kong Admin API accordingly to the documentation.
Every request body described oh the Kong Admin API documentation must be set using the payload name.

After running the migration, Kongrations create a file on ./migrations-data for each Kong environment to store its state. This file should be commited into your version control system. Also, it's extremely important not to touch this file directly, since it's crucial for Kongrations to work normally.

Place your migration files inside ./migrations folder. You can change the default folder putting a path key on kongrations.yml file.
You also need to use .rb extension on them.

To run the migrations, use Kongrations cli, passing an optional parameter to specify the environment name (default environment name is default).
Examples:

$ kongrations # runs for default environment
$ kongrations production

Available migrations

Create API

• Kong Admin API Reference
• Usage: pass the request body through api.payload.
• Example:

create_api do |api|
  api.payload = {
    name: 'my-api',
    uris: '/myapi',
    upstream_url: 'https://myapi.mycompany.com'
  }
end

Update API

• Kong Admin API Reference
• Usage: pass your API name right after change_api method, then pass the request body through api.payload.
• Example:

change_api 'api-name' do |api|
  api.payload = {
    upstream_url: 'https://my-api.mycompany.com'
  }
end

Delete API

• Kong Admin API Reference
• Usage: pass your API name right after delete_api method.
• Example:

delete_api 'api-name'

Create Consumer

• Kong Admin API Reference
• Usage: pass the request body through consumer.payload.
• Example:

create_consumer do |consumer|
  consumer.payload = {
    username: 'my-username'
  }
end

Update Consumer

• Kong Admin API Reference
• Usage: pass your consumer username or custom_id right after change_consumer method, then pass the request body through consumer.payload.
• Example:

change_consumer 'username' do |consumer|
  consumer.payload = {
    username: 'new-username'
  }
end

Delete Consumer

• Kong Admin API Reference
• Usage: pass your username or custom_id right after delete_consumer method.
• Example:

delete_consumer 'username'

Create Plugin

• Kong Admin API Reference
• Usage: pass your API name right after create_plugin_for_api method, then pass the request body through plugin.payload.
• Example:

create_plugin_for_api 'api-name' do |plugin|
  plugin.payload = {
    name: 'cors',
    config: {
      origins: '*',
      methods: 'GET, POST'
    }
  }
end

Update Plugin

• Kong Admin API Reference
• Usage: pass your API and plugin names right after change_plugin_for_api method, then pass the request body through plugin.payload.
• Example:

change_plugin_for_api 'api-name', 'cors' do |plugin|
  plugin.payload = {
    config: {
      methods: 'GET'
    }
  }
end

Delete Plugin

• Kong Admin API Reference
• Usage: pass your API and plugin names right after delete_plugin_for_api method.
• Example:

delete_plugin_for_api 'api-name', 'cors'