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

Revisions

  1. toopay revised this gist Jun 14, 2018. 1 changed file with 170 additions and 1 deletion.
    171 changes: 170 additions & 1 deletion kongfig-schema.md
    View file
    Original file line number Diff line number Diff line change
    @@ -122,4 +122,173 @@ The `consumers` contains an array of your consumer definition. There are 4 top l
    | `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 |
    | `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.
  2. toopay revised this gist Jun 14, 2018. 1 changed file with 1 addition and 2 deletions.
    3 changes: 1 addition & 2 deletions kongfig-schema.md
    View file
    Original file line number Diff line number Diff line change
    @@ -120,7 +120,6 @@ The `consumers` contains an array of your consumer definition. There are 4 top l
    | 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.
    Permalink |
    | `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 |
  3. toopay revised this gist Jun 14, 2018. 1 changed file with 19 additions and 1 deletion.
    20 changes: 19 additions & 1 deletion kongfig-schema.md
    View file
    Original file line number Diff line number Diff line change
    @@ -29,6 +29,8 @@ Most of the time, you will only need to specifiy `apis` and `consumers`, and we'

    ## `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 |
    @@ -59,6 +61,8 @@ You can define more deeply about your API attributes, available keys are :

    ### `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 |
    @@ -105,4 +109,18 @@ We use `oidc` plugin to protect our API with OpenID authorization. Most used par
    | `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`
    ## `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.
    Permalink |
    | `acls` | Declare your consumer acls |
    | `credentials` | Declare your consumer credentials |
  4. toopay revised this gist Jun 14, 2018. 1 changed file with 2 additions and 9 deletions.
    11 changes: 2 additions & 9 deletions kongfig-schema.md
    View file
    Original file line number Diff line number Diff line change
    @@ -93,15 +93,8 @@ We use `jwt-claim-headers` plugin to add unencrypted, base64-decoded claims from
    #### `oidc`

    We use `oidc` plugin to protect our API with OpenID authorization. Most used parameters are :
    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
    Parameter | Default | Required | description |

    | Parameter | Default | Required | description |
    | --- | --- | --- | --- |
    | `config.client_id` || true | OIDC Client ID |
    | `config.client_secret` || true | OIDC Client secret |
  5. toopay revised this gist Jun 14, 2018. 1 changed file with 19 additions and 1 deletion.
    20 changes: 19 additions & 1 deletion kongfig-schema.md
    View file
    Original file line number Diff line number Diff line change
    @@ -92,6 +92,24 @@ We use `jwt-claim-headers` plugin to add unencrypted, base64-decoded claims from

    #### `oidc`

    We use `oidc` plugin to protect our API with OpenID authorization.
    We use `oidc` plugin to protect our API with OpenID authorization. Most used parameters are :
    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
    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`
  6. toopay revised this gist Jun 14, 2018. No changes.
  7. toopay revised this gist Jun 14, 2018. 1 changed file with 6 additions and 1 deletion.
    7 changes: 6 additions & 1 deletion kongfig-schema.md
    View file
    Original file line number Diff line number Diff line change
    @@ -59,13 +59,14 @@ You can define more deeply about your API attributes, available keys are :

    ### `plugins`

    The `plugins` contains an array of your API's plugin definition. There are 3 top level keys available for each plugin definition :
    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`.

    @@ -85,6 +86,10 @@ We use `jwt` plugin to verify requests containing HS256 or RS256 signed JSON Web

    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.
  8. toopay revised this gist Jun 14, 2018. 1 changed file with 1 addition and 2 deletions.
    3 changes: 1 addition & 2 deletions kongfig-schema.md
    View file
    Original file line number Diff line number Diff line change
    @@ -72,15 +72,14 @@ Most of Kong plugins are supported, but here we try to cover the ones that usual
    #### `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`

  9. toopay revised this gist Jun 14, 2018. 1 changed file with 10 additions and 1 deletion.
    11 changes: 10 additions & 1 deletion kongfig-schema.md
    View file
    Original file line number Diff line number Diff line change
    @@ -71,7 +71,16 @@ Most of Kong plugins are supported, but here we try to cover the ones that usual

    #### `jwt`

    We use `jwt` plugin to verify requests containing HS256 or RS256 signed JSON Web Tokens.
    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`

  10. toopay revised this gist Jun 14, 2018. 1 changed file with 8 additions and 0 deletions.
    8 changes: 8 additions & 0 deletions kongfig-schema.md
    View file
    Original file line number Diff line number Diff line change
    @@ -70,7 +70,15 @@ The `plugins` contains an array of your API's plugin definition. There are 3 top
    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.

    #### `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.

    #### `oidc`

    We use `oidc` plugin to protect our API with OpenID authorization.

    ## `consumers`
  11. toopay revised this gist Jun 14, 2018. 1 changed file with 14 additions and 0 deletions.
    14 changes: 14 additions & 0 deletions kongfig-schema.md
    View file
    Original file line number Diff line number Diff line change
    @@ -59,4 +59,18 @@ You can define more deeply about your API attributes, available keys are :

    ### `plugins`

    The `plugins` contains an array of your API's plugin definition. There are 3 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 |

    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`
    #### `jwt-claim-headers`
    #### `oidc`

    ## `consumers`
  12. toopay revised this gist Jun 14, 2018. 1 changed file with 17 additions and 0 deletions.
    17 changes: 17 additions & 0 deletions kongfig-schema.md
    View file
    Original file line number Diff line number Diff line change
    @@ -40,6 +40,23 @@ The `apis` contains an array of your APIs definition. There are 4 top level keys

    ### `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`

    ## `consumers`
  13. toopay revised this gist Jun 14, 2018. 1 changed file with 4 additions and 0 deletions.
    4 changes: 4 additions & 0 deletions kongfig-schema.md
    View file
    Original file line number Diff line number Diff line change
    @@ -38,4 +38,8 @@ The `apis` contains an array of your APIs definition. There are 4 top level keys
    | `attributes` | List of API attributes |
    | `plugins` | List of API plugins |

    ### `attributes`

    ### `plugins`

    ## `consumers`
  14. toopay revised this gist Jun 14, 2018. 1 changed file with 10 additions and 0 deletions.
    10 changes: 10 additions & 0 deletions kongfig-schema.md
    View file
    Original file line number Diff line number Diff line change
    @@ -21,11 +21,21 @@ There are 4 top level keys available :
    | --- | --- |
    | `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 `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 |

    ## `consumers`
  15. toopay revised this gist Jun 14, 2018. 1 changed file with 7 additions and 1 deletion.
    8 changes: 7 additions & 1 deletion kongfig-schema.md
    View file
    Original file line number Diff line number Diff line change
    @@ -22,4 +22,10 @@ There are 4 top level keys available :
    | `apis` | List all of your micros APIs |
    | `consumers` | List of required consumers |
    | `host` | Kong Admin API Host |
    | `headers` | List of custom headers to be included with every request made by Kongfig |
    | `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`

    ## `consumers`
  16. toopay revised this gist Jun 14, 2018. 1 changed file with 10 additions and 1 deletion.
    11 changes: 10 additions & 1 deletion kongfig-schema.md
    View file
    Original file line number Diff line number Diff line change
    @@ -13,4 +13,13 @@ At the simplest form, your `config.yml` can be just :
    request_host: "mockbin.com"
    ```

    # Schema Reference
    # Schema Reference

    There are 4 top level keys available :

    | Key | Description |
    | --- | --- |
    | `apis` | List all of your micros APIs |
    | `consumers` | List of required consumers |
    | `host` | Kong Admin API Host |
    | `headers` | List of custom headers to be included with every request made by Kongfig |
  17. toopay created this gist Jun 14, 2018.
    16 changes: 16 additions & 0 deletions kongfig-schema.md
    View file
    Original file line number Diff line number Diff line change
    @@ -0,0 +1,16 @@
    # 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