Skip to content

Instantly share code, notes, and snippets.

@toopay

toopay/kongfig-schema.md

Last active September 1, 2020 09:44
Show Gist options
  • Save toopay/a3d9892db38f1eed10a80c196e2da31c to your computer and use it in GitHub Desktop.
Save toopay/a3d9892db38f1eed10a80c196e2da31c to your computer and use it in GitHub Desktop.
Download ZIP
Kongfig Schema
Raw
kongfig-schema.md

Overview

Kongfig allow declarative configuration. We can define our list of APIs and consumers in json/yaml and then run kongfig to ensure that our Kong is configured correctly. At the simplest form, your config.yml can be just :

---
  apis:
    -
      name: "mockbin"
      attributes:
        upstream_url: "http://mockbin.com/"
        request_host: "mockbin.com"

Schema Reference

There are 4 top level keys available :

Key Description
apis List all of your micros APIs
consumers List of required consumers
plugins List of global plugins
host Kong Admin API Host
headers List of custom headers to be included with every request made by Kongfig

Most of the time, you will only need to specifiy apis and consumers, and we'll walkthrough them below.

apis

The API object describes an API that's being exposed by Kong. Kong needs to know how to retrieve the API when a consumer is calling it from the Proxy port. Each API object must specify some combination of hosts, uris, and methods. Kong will proxy all requests to the API to the specified upstream URL.

The apis contains an array of your APIs definition. There are 4 top level keys available for each API definition :

Key Description
name The API name.
ensure The flag of the API. Available values are present and removed, default to present
attributes List of API attributes
plugins List of API plugins

attributes

You can define more deeply about your API attributes, available keys are :

Key Requirement Description
upstream_url required The base target URL that points to your API server. This URL will be used for proxying requests. For example: https://example.com.
hosts semi-optional A list of domain names that point to your API. For example: example.com. At least one of hosts, uris, or methods should be specified.
uris semi-optional A list of URIs prefixes that point to your API. For example: /my-path. At least one of hosts, uris, or methods should be specified.
methods semi-optional A list of HTTP methods that point to your API. For example: GET,POST. At least one of hosts, uris, or methods should be specified.
strip_uri optional When matching an API via one of the uris prefixes, strip that matching prefix from the upstream URI to be requested. Default: true.
preserve_host optional When matching an API via one of the hosts domain names, make sure the request Host header is forwarded to the upstream service. By default, this is false, and the upstream Host header will be extracted from the configured upstream_url.
retries optional The number of retries to execute upon failure to proxy. The default is 5.
upstream_connect_timeout optional The timeout in milliseconds for establishing a connection to your upstream service. Defaults to 60000.
upstream_send_timeout optional The timeout in milliseconds between two successive write operations for transmitting a request to your upstream service Defaults to 60000.
upstream_read_timeout optional The timeout in milliseconds between two successive read operations for transmitting a request to your upstream service Defaults to 60000.
https_only optional To be enabled if you wish to only serve an API through HTTPS, on the appropriate port (8443 by default). Default: false.
http_if_terminated optional Consider the X-Forwarded-Proto header when enforcing HTTPS only traffic. Default: false.

plugins

A Plugin entity represents a plugin configuration that will be executed during the HTTP request/response lifecycle. It is how you can add functionalities to Services that run behind Kong, like Authentication or Rate Limiting for example.

The plugins contains an array of your API's plugin definition. There are 4 top level keys available for each plugin definition :

Key Description
name The plugin name.
ensure The flag of the plugin. Available values are present and removed, default to present
attributes List of plugin attributes
enabled Plugin flag whether to enable or disabled

Most of Kong plugins are supported, but here we try to cover the ones that usually in-use, which is jwt, jwt-claim-headers and oidc.

jwt

We use jwt plugin to verify requests containing HS256 or RS256 signed JSON Web Tokens. Most used attributes are :

Key Requirement Description
config.uri_param_names optional A list of querystring parameters that Kong will inspect to retrieve JWTs.
config.key_claim_name optional The name of the claim in which the key identifying the secret must be passed. Starting with version 0.13.1, the plugin will attempt to read this claim from the JWT payload and the header, in this order.
config.secret_is_base64 optional If true, the plugin assumes the credential's secret to be base64 encoded. You will need to create a base64 encoded secret for your Consumer, and sign your JWT with the original secret. Default to false
config.anonymous optional An optional string (consumer uuid) value to use as an "anonymous" consumer if authentication fails. If empty (default), the request will fail with an authentication failure 4xx.
config.run_on_preflight optional A boolean value that indicates whether the plugin should run (and try to authenticate) on OPTIONS preflight requests, if set to false then OPTIONS requests will always be allowed. default to true

jwt-claim-headers

We use jwt-claim-headers plugin to add unencrypted, base64-decoded claims from a JWT payload as request headers to the upstream service.

Key Requirement Description
config.uri_param_names optional A list of querystring parameters that Kong will inspect to retrieve JWTs. Defaults to jwt.

oidc

We use oidc plugin to protect our API with OpenID authorization. Most used parameters are :

Parameter Default Required description
config.client_id true OIDC Client ID
config.client_secret true OIDC Client secret
config.discovery https://.well-known/openid-configuration false OIDC Discovery Endpoint (/.well-known/openid-configuration)
config.scope oidc false OAuth2 Token scope. Most likely you will need to set to openid email profile
config.ssl_verify "no" false Enable SSL verification to OIDC Provider
config.introspection_endpoint false Token introspection endpoint
config.response_type false Grant type. Most likely you will need to set to token
config.token_endpoint_auth_method false Most likely you will need to set to client_secret_basic

consumers

The Consumer object represents a consumer - or a user - of a Service. You can either rely on Kong as the primary datastore, or you can map the consumer list with your database to keep consistency between Kong and your existing primary datastore.

In Kongfig, we usually define consumers in conjuntion with the usage of some plugins. I.e, if you define anonymous user for jwt, you will need to ensure you have list that as mandatory consumer in your config.yml.

The consumers contains an array of your consumer definition. There are 4 top level keys available for each consumer definition :

Key Description
username The unique username of the consumer. You must send either this field or custom_id with the request.
custom_id Field for storing an existing unique ID for the consumer - useful for mapping Kong with users in your existing database. You must send either this field or username with the request.
acls Declare your consumer acls
credentials Declare your consumer credentials

Example

Here is an example of actual config.yml for Contact Microservice :

# Mandatory Consumer
consumers:
- acls: []
  credentials: []
  custom_id: "0"
  username: anonymous
apis:

# Main Endpoint
- attributes:
    methods:
    - OPTIONS
    - GET
    - POST
    - PUT
    - PATCH
    - DELETE
    upstream_url: http://$upstream_host/api/v1/contacts
    uris:
    - /contacts
  name: contacts
  plugins:
  - attributes:
      config:
        anonymous_username: anonymous
        key_claim_name: iss
        run_on_preflight: true
        secret_is_base64: false
        uri_param_names:
        - jwt
      enabled: true
    name: jwt
  - attributes:
      config:
        client_id: $client_id
        client_secret: $client_secret
        discovery: $discovery_url
        introspection_endpoint: $introspection_url
        response_type: token
        scope: openid email profile
        ssl_verify: "no"
        token_endpoint_auth_method: client_secret_basic
      enabled: true
    name: oidc
  - attributes:
      config:
        uri_param_names:
        - jwt
      enabled: true
    name: jwt-claim-headers


# Gmail Webhook
- attributes:
    methods:
    - OPTIONS
    - POST
    upstream_url: http://$upstream_host/gmail/webhook
    uris:
    - /contacts/gmail/webhook
  name: contacts.gmail.webhook
  plugins: []

# Calendar Webhook
- attributes:
    methods:
    - OPTIONS
    - POST
    upstream_url: http://$upstream_host/calendar/webhook
    uris:
    - /contacts/calendar/webhook
  name: contacts.calendar.webhook
  plugins: []

# Health check
- attributes:
    methods:
    - OPTIONS
    - GET
    upstream_url: http://$upstream_host/health_check
    uris:
    - /contacts/health_check
  name: contacts.health_check
  plugins: []

# API Info
- attributes:
    methods:
    - OPTIONS
    - GET
    upstream_url: http://$upstream_host/
    uris:
    - /contacts/api-info
  name: contacts.api-info
  plugins: []

# Apiary
- attributes:
    methods:
    - OPTIONS
    - GET
    upstream_url: http://$upstream_host/apiary
    uris:
    - /contacts/apiary
  name: contacts.apiary
  plugins: []

# Logs
- attributes:
    methods:
    - OPTIONS
    - GET
    upstream_url: http://$upstream_host/logs
    uris:
    - /contacts/logs
  name: contacts.logs
  plugins: []

# Test piesync
- attributes:
    methods:
    - OPTIONS
    - GET
    upstream_url: http://$upstream_host/test-piesync
    uris:
    - /contacts/test-piesync
  name: contacts.test-piesync
  plugins: []


# Version
- attributes:
    methods:
    - OPTIONS
    - GET
    upstream_url: http://$upstream_host/version.txt
    uris:
    - /contacts/version.txt
  name: contacts.version
  plugins: []

# Version
- attributes:
    methods:
    - OPTIONS
    - GET
    upstream_url: http://$upstream_host/download
    uris:
    - /contacts/download
  name: contacts.download
  plugins: []

# Version
- attributes:
    methods:
    - OPTIONS
    - GET
    upstream_url: http://$upstream_host/assets
    uris:
    - /contacts/assets
  name: contacts.assets
  plugins: []

Any of $variable defined in the config.yml is an environment variables that will be resolved when this config has been added to Kong Publisher.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment