Kongfig

A tool for Kong to allow declarative configuration.

Simply define your list of APIs and consumers in json and then run kongfig to ensure that your Kong is configured correctly.

Install

Manually

We recommend installing Kongfig globally

npm install -g kongfig

Puppet

Use our Puppet-Kongfig module to install and configure Kongfig

puppet module install mybuilder-kongfig

Quick start

You can follow the quick start to get going in 5 minutes.

Apply config

You can have your config in json, yaml, or js if you need to support multiple environments.

kongfig apply --path config.yml --host localhost:8001

Dump config

You can dump the existing configuration to a file or view it on a screen

kongfig dump --host localhost:8001 > config.yml

You can omit the --host option if kong is on localhost:8001 as this is the default value

You can specify the desired format by giving --format option with possible options of json, yaml, or screen that prints the config with colours.

kongfig dump --format screen

For APIs which uses custom consumer credential plugins, specify plugin and id name in : format with --credential-schema option.

kongfig apply --path config.yml --host localhost:8001 --credential-schema custom_jwt:key

For multiple plugins use --credential-schema as many as necessary

kongfig apply --path config.yml --host localhost:8001 --credential-schema "custom_jwt:key" --credential-schema "custom_oauth2:client_id"

Schema

Note: If you change the name of an API/Plugin/Consumer and want to ensure the old one is removed automatically, do not delete or modify the old API/Plugin/Consumer section, other than to add the ensure: "removed" flag. Examples shown below.

Notice the attributes.username config parameter below, this is used to map given username to consumer uuid

Api schema:

apis:
  - name: mockbin # unique api name
    ensure: "present" # Set to "removed" to have Kongfig ensure the API is removed. Default is present.
    attributes:
      upstream_url: string # (required)
      hosts: [string]
      uris: [string]
      methods: ["POST", "GET"]
      strip_uri: bool
      preserve_host: bool
      retries: int
      upstream_connect_timeout: int
      upstream_read_timeout: int
      upstream_send_timeout: int
      https_only: bool # (required)
      http_if_terminated: bool

Api plugin schema:

apis:
  - name: mockbin # unique api name
    attributes: # ...
    plugins:
      - name: rate-limiting # kong plugin name
        ensure: "present" # Set to "removed" to have Kongfig ensure the plugin is removed. Default is present.
        attributes: # the plugin attributes
          username: # optional, to reference a consumer, same as consumer_id in kong documentation
          config:

Global plugin schema:

plugins:
  - name: cors
    attributes:
      username: # optional, to reference a consumer, same as consumer_id in kong documentation
      enabled: true
      config:
        credentials: false
        preflight_continue: false
        max_age: 7000

All of the kong plugins should be supported if you find one that doesn't work please add an issue.

Consumer schema:

consumers:
  - username: iphone-app
    custom_id: foobar-1234 # optional

Consumer credential schema:

consumers:
  - username: iphone-app
    credentials:
      - name: key-auth
        attributes: # credential config attributes

Consumer ACL schema:

consumers:
  - username: iphone-app
    acls:
      - group: acl-group-name

Supported consumer credentials

Notice the anonymous_username config parameter below, this is used to map username to consumer uuid

Key Authentication

apis:
  - name: mockbin # unique api name
    attributes: # ...
    plugins:
      - name: key-auth
        attributes:
          config:
            anonymous_username: # optional, same as just anonymous in kong api, maps given username to consumer uuid
            key_names:
            hide_credentials:

consumers:
  - username: iphone-app
    credentials:
      - name: key-auth
        attributes:
          key: # required

Basic Authentication

apis:
  - name: mockbin
    attributes: # ...
    plugins:
      - name: basic-auth
        attributes:
          config:
            hide_credentials:

consumers:
  - username: iphone-app
    credentials:
      - name: basic-auth
        attributes:
          username: # required
          password:

OAuth 2.0 Authentication

apis:
  - name: mockbin
    attributes: # ...
    plugins:
      - name: oauth2
        attributes:
          config:
            scopes:
            mandatory_scope:
            token_expiration:
            enable_authorization_code:
            enable_client_credentials:
            enable_implicit_grant:
            enable_password_grant:
            hide_credentials:

consumers:
  - username: iphone-app
    credentials:
      - name: oauth2
        attributes:
          name:
          client_id: # required
          client_secret:
          redirect_uri: string | [string] # required by kong

HMAC Authentication

apis:
  - name: mockbin
    attributes: # ...
    plugins:
      - name: hmac-auth
        attributes:
          config:
            hide_credentials:
            clock_skew:

consumers:
  - username: iphone-app
    credentials:
      - name: hmac-auth
        attributes:
          username: # required
          secret:

JWT

apis:
  - name: mockbin
    attributes: # ...
    plugins:
      - name: jwt
        attributes:
          config:
            uri_param_names:
            claims_to_verify:

consumers:
  - username: iphone-app
    credentials:
      - name: jwt
        attributes:
          key: # required
          secret:

Custom Credential Schemas

It is possible to work with custom consumer credential plugins.

apis:
  - name: mockbin
    attributes: # ...
    plugins:
      - name: custom_jwt
        attributes:
          config:
            uri_param_names:
            claims_to_verify:

consumers:
  - username: iphone-app
    credentials:
      - name: custom_jwt
        attributes:
          key: # required
          secret:

credentialSchema:
  custom_jwt:
    id: "key" # credential id name

ACL Support

Kong ACL documentation

apis:
  - name: mockbin
    attributes: # ...
    plugins:
      - name: "acl"
        ensure: "present"
        attributes:
          config.whitelist: "foo-group"

consumers:
  - username: "some-username"
    ensure: "present"
    acls:
      - group: "foo-group"
        ensure: "present"

      - group: "bar-group"
        ensure: "present"

Upstream/Target Schema

Kong Upstream Load Balancing Reference

upstreams:
  - name: "mockbinUpstream"
    ensure: "present"
    targets:
      - target: "server1.mockbin:3001"
        attributes:
          weight: 50
      - target: "server2.mockbin:3001"
        attributes:
          weight: 50
    attributes:
      slots: 100

Certificates & SNIs

A certificate object represents a public certificate/private key pair for an SSL certificate. These objects are used by Kong to handle SSL/TLS termination for encrypted requests. Certificates are optionally associated with SNI objects to tie a cert/key pair to one or more hostnames.

Kong Certificate Object Reference

An SNI object represents a many-to-one mapping of hostnames to a certificate. That is, a certificate object can have many hostnames associated with it; when Kong receives an SSL request, it uses the SNI field in the Client Hello to lookup the certificate object based on the SNI associated with the certificate.

Kong SNI Objects Reference

certificates:
  - ensure: present
    cert: >-
      -----BEGIN CERTIFICATE-----
      MIIDMjCCAhqgAwIBAgIJAPgRdnOdnX/SMA0GCSqGSIb3DQEBBQUAMBoxGDAWBgNV
      ....
    key: >-
      -----BEGIN RSA PRIVATE KEY-----
      MIIEpAIBAAKCAQEAo5BpOQY2AV/1L2QEdSip75rHh3Khs2knNtMLIrP26MHyidtX
      ....
    snis:
      - name: example.com
        ensure: present
      - name: www.example.com
        ensure: present

Notice that SNIs are an list of object e.g. { name: example.com, ensure: present } different Kong api itself where it is a list of hostnames

Migrating from Kong <=0.9 to >=0.10

kongfig translates pre >=0.10 kong config files automatically when applying them.

So you can export your config from <=0.9 kong instance by running:

kongfig dump --host kong_9:8001 > config.v9.yml

Then apply it to kong 0.10 instance

kongfig apply --path config.v9.yml --host kong_10:8001

apis endpoint changed between <=0.9 and >=0.10:

• request_host: string to hosts: [string]
• request_path: string to uris: [string]
• strip_request_path: bool -> strip_uri: bool
• Adds methods, retries, upstream_connect_timeout, upstream_read_timeout, upstream_send_timeout, https_only, http_if_terminated

Created by MyBuilder - Check out our blog for more information and our other open-source projects.

Contributing to Kongfig

We are very grateful for any contributions you can make to the project.

Visit the Contributing documentation for submission guidelines.