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"
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.
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 |
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. |
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
.
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 |
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 . |
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 |
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 |
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.