/proxy-cache-advanced/:plugin_id/caches/:cache_id
+
+| Attributes | Description
+| -------------- | -------
+|`plugin_id` | The UUID of the proxy-cache-advanced plugin
+| `cache_id` | The cache entity key as reported by the X-Cache-Key response header
+
+**Endpoint**
+
+/proxy-cache-advanced/:cache_id
+
+| Attributes | Description
+| -------------- | -------
+|`cache_id` | The cache entity key as reported by the X-Cache-Key response header
+
+**Response**
+
+If the cache entity exists
+
+```
+HTTP 200 OK
+```
+
+If the entity with the given key does not exist
+
+```
+HTTP 400 Not Found
+```
+
+### Delete Cache Entity
+
+Two separate endpoints are available: one to look up a known plugin instance, and another that searches all proxy-cache-advanced plugins data stores for the given cache key. Both endpoints have the same return value.
+
+**Endpoint**
+
+/proxy-cache-advanced/:plugin_id/caches/:cache_id
+
+| Attributes | Description
+| -------------- | -------
+|`plugin_id` | The UUID of the proxy-cache-advanced plugin
+|`cache_id` | The cache entity key as reported by the `X-Cache-Key` response header
+
+**Endpoint**
+
+/proxy-cache-advanced/:cache_id
+
+| Attributes | Description
+| -------------- | -------
+|`cache_id` | he cache entity key as reported by the `X-Cache-Key` response header
+
+**Response**
+
+If the cache entity exists
+
+```
+HTTP 204 No Content
+```
+
+If the entity with the given key does not exist
+
+```
+HTTP 400 Not Found
+```
+
+### Purge All Cache Entities
+**Endpoint**
+
+/proxy-cache-advanced/
+
+**Response**
+
+```
+HTTP 204 No Content
+```
+
+Note that this endpoint purges all cache entities across all `proxy-cache-advanced` plugins.
diff --git a/app/_hub/kong-inc/proxy-cache/index.md b/app/_hub/kong-inc/proxy-cache/index.md
index 60ddbb55ddba..004d1ff4b248 100644
--- a/app/_hub/kong-inc/proxy-cache/index.md
+++ b/app/_hub/kong-inc/proxy-cache/index.md
@@ -1,8 +1,8 @@
---
-name: Proxy Caching
+name: Proxy Cache
publisher: Kong Inc.
-version: 0.35-x
+version: 1.3-x
desc: Cache and serve commonly requested responses in Kong
description: |
@@ -20,6 +20,7 @@ kong_version_compatibility:
- 1.2.x
enterprise_edition:
compatible:
+ - 1.3-x
- 0.36-x
- 0.35-x
- 0.34-x
@@ -84,74 +85,19 @@ params:
default:
value_in_examples: memory
description: |
- The backing data store in which to hold cache entities. Accepted values are; `memory`, and `redis`.
+ The backing data store in which to hold cache entities. Accepted values are; `memory`.
- name: memory.dictionary_name
required:
default: kong_cache
value_in_examples:
description: |
The name of the shared dictionary in which to hold cache entities when the memory strategy is selected. Note that this dictionary currently must be defined manually in the Kong Nginx template.
- - name: redis.host
- required: semi
- default:
- value_in_examples:
- description: |
- Host to use for Redis connection when the redis strategy is defined
- - name: redis.port
- required: semi
- default:
- value_in_examples:
- description: |
- Port to use for Redis connection when the redis strategy is defined
- - name: redis.timeout
- required: semi
- default: 2000
- value_in_examples:
- description: |
- Connection timeout to use for Redis connection when the redis strategy is defined
- - name: redis.password
- required: semi
- default:
- value_in_examples:
- description: |
- Password to use for Redis connection when the redis strategy is defined. If undefined, no AUTH commands are sent to Redis.
- - name: redis.database
- required: semi
- default: 0
- value_in_examples:
- description: |
- Database to use for Redis connection when the redis strategy is defined
- - name: redis.sentinel_master
- required: semi
- default:
- value_in_examples:
- description: |
- Sentinel master to use for Redis connection when the redis strategy is defined. Defining this value implies using Redis Sentinel.
- - name: redis.sentinel_role
- required: semi
- default:
- value_in_examples:
- description: |
- Sentinel role to use for Redis connection when the redis strategy is defined. Defining this value implies using Redis Sentinel.
- - name: redis.sentinel_addresses
- required: semi
- default:
- value_in_examples:
- description: |
- Sentinel addresses to use for Redis connection when the redis strategy is defined. Defining this value implies using Redis Sentinel.
- - name: redis.cluster_addresses
- required: semi
- default:
- value_in_examples:
- description: |
- Cluster addresses to use for Redis connection when the `redis` strategy is defined. Defining this value implies using Redis cluster.
---
### Strategies
-`kong-plugin-enterprise-proxy-cache` is designed to support storing proxy cache data in different backend formats. Currently the following strategies are provided:
+`kong-plugin-proxy-cache` is designed to support storing proxy cache data in different backend formats. Currently the following strategies are provided:
- `memory`: A `lua_shared_dict`. Note that the default dictionary, `kong_cache`, is also used by other plugins and elements of Kong to store unrelated database cache entities. Using this dictionary is an easy way to bootstrap the proxy-cache plugin, but it is not recommended for large-scale installations as significant usage will put pressure on other facets of Kong's database caching operations. It is recommended to define a separate `lua_shared_dict` via a custom Nginx template at this time.
-- `redis`: Supports Redis and Redis Sentinel deployments.
### Cache Key
diff --git a/app/_hub/kong-inc/request-size-limiting/index.md b/app/_hub/kong-inc/request-size-limiting/index.md
index e01a4656ce08..e5c941447366 100644
--- a/app/_hub/kong-inc/request-size-limiting/index.md
+++ b/app/_hub/kong-inc/request-size-limiting/index.md
@@ -45,6 +45,7 @@ kong_version_compatibility:
- 0.3.x
enterprise_edition:
compatible:
+ - 1.3-x
- 0.36-x
- 0.35-x
- 0.34-x
@@ -65,5 +66,10 @@ params:
default: "`128`"
value_in_examples: 128
description: Allowed request payload size in megabytes, default is `128` (128000000 Bytes)
+ - name: size_unit
+ required: true
+ default: "`megabytes`"
+ description: Size unit can be set either in `bytes`, `kilobytes`, or `megabytes`.
+ Note- this configuration is only supported in Kong Enterprise 1.3 and above, and may eventually extend to Kong Gateway
---
diff --git a/app/_hub/kong-inc/request-transformer-advanced/0.36-x.md b/app/_hub/kong-inc/request-transformer-advanced/0.36-x.md
new file mode 100644
index 000000000000..416f3472296f
--- /dev/null
+++ b/app/_hub/kong-inc/request-transformer-advanced/0.36-x.md
@@ -0,0 +1,296 @@
+---
+
+name: Request Transformer Advanced
+publisher: Kong Inc.
+version: 0.36-x
+
+desc: Use powerful regular expressions, variables and templates to transform API requests
+description: |
+ The Request Transformer plugin for Kong Enterprise builds on the Kong version of this plugin with enhanced capabilities to match portions of incoming requests using regular expressions, save those matched strings into variables, and substitute those strings into transformed requests via flexible templates.
+
+enterprise: true
+type: plugin
+categories:
+ - transformations
+
+kong_version_compatibility:
+ community_edition:
+ compatible:
+ enterprise_edition:
+ compatible:
+ - 0.36-x
+ - 0.35-x
+ - 0.34-x
+
+params:
+ name: request-transformer-advanced
+ api_id: true
+ service_id: true
+ route_id: true
+ consumer_id: true
+ config:
+ - name: http_method
+ required: false
+ default:
+ value_in_examples:
+ description: |
+ Changes the HTTP method for the upstream request
+ - name: remove.headers
+ required: false
+ default:
+ value_in_examples:
+ description: |
+ List of header names. Unset the headers with the given name.
+ - name: remove.querystring
+ required: false
+ default:
+ value_in_examples:
+ description: |
+ List of querystring names. Remove the querystring if it is present.
+ - name: remove.body
+ required: false
+ default:
+ value_in_examples:
+ description: |
+ List of parameter names. Remove the parameter if and only if content-type is one the following [`application/json`, `multipart/form-data`, `application/x-www-form-urlencoded`] and parameter is present.
+ - name: replace.headers
+ required: false
+ default:
+ value_in_examples:
+ description: |
+ List of headername:value pairs. If and only if the header is already set, replace its old value with the new one. Ignored if the header is not already set.
+ - name: replace.querystring
+ required: false
+ default:
+ value_in_examples:
+ description: |
+ List of queryname:value pairs. If and only if the querystring name is already set, replace its old value with the new one. Ignored if the header is not already set.
+ - name: replace.uri
+ required: false
+ default:
+ value_in_examples:
+ description: |
+ Updates the upstream request URI with given value. This value can only be used to update the path part of the URI, not the scheme, nor the hostname.
+ - name: replace.body
+ required: false
+ default:
+ value_in_examples:
+ description: |
+ List of paramname:value pairs. If and only if content-type is one the following [`application/json`, `multipart/form-data`, `application/x-www-form-urlencoded`] and the parameter is already present, replace its old value with the new one. Ignored if the parameter is not already present.
+ - name: rename.headers
+ required: false
+ default:
+ value_in_examples:
+ description: |
+ List of headername:value pairs. If and only if the header is already set, rename the header. The value is unchanged. Ignored if the header is not already set.
+ - name: rename.querystring
+ required: false
+ default:
+ value_in_examples:
+ description: |
+ List of queryname:value pairs. If and only if the field name is already set, rename the field name. The value is unchanged. Ignored if the field name is not already set.
+ - name: rename.body
+ required: false
+ default:
+ value_in_examples:
+ description: |
+ List of parameter name:value pairs. Rename the parameter name if and only if content-type is one the following [`application/json`, `multipart/form-data`, `application/x-www-form-urlencoded`] and parameter is present.
+ - name: add.headers
+ required: false
+ default:
+ value_in_examples:
+ description: |
+ List of headername:value pairs. If and only if the header is not already set, set a new header with the given value. Ignored if the header is already set.
+ - name: add.querystring
+ required: false
+ default:
+ value_in_examples:
+ description: |
+ List of queryname:value pairs. If and only if the querystring name is not already set, set a new querystring with the given value. Ignored if the querystring name is already set.
+ - name: add.body
+ required: false
+ default:
+ value_in_examples:
+ description: |
+ List of paramname:value pairs. If and only if content-type is one the following [`application/json, multipart/form-data`, `application/x-www-form-urlencoded`] and the parameter is not present, add a new parameter with the given value to form-encoded body. Ignored if the parameter is already present.
+ - name: append.headers
+ required: false
+ default:
+ value_in_examples:
+ description: |
+ List of headername:value pairs. If the header is not set, set it with the given value. If it is already set, a new header with the same name and the new value will be set.
+ - name: append.querystring
+ required: false
+ default:
+ value_in_examples:
+ description: |
+ List of queryname:value pairs. If the querystring is not set, set it with the given value. If it is already set, a new querystring with the same name and the new value will be set.
+ - name: append.body
+ required: false
+ default:
+ value_in_examples:
+ description: |
+ List of paramname:value pairs. If the content-type is one the following [`application/json`, `application/x-www-form-urlencoded`], add a new parameter with the given value if the parameter is not present, otherwise if it is already present, the two values (old and new) will be aggregated in an array.
+ extra: |
+ Note: if the value contains a `,` then the comma separated format cannot be used. The array notation must be used instead.
+
+---
+
+### Template as Value
+
+User can use any of the the current request headers, query params, and captured URI named groups as template to populate above supported config fields.
+
+| Request Param | Template
+| --------- | -----------
+| header | $(headers.+Ex. $('$(some_needs_to_escaped)') + +Note: Plugin creates a non mutable table of request headers, querystrings, and captured URIs before transformation. So any update or removal of params used in template does not affect the rendered value of template. + +#### Examples Using Template as Value + +Add an API `test` with `uris` configured with a named capture group `user_id` + +```bash +$ curl -X POST http://localhost:8001/apis \ + --data 'name=test' \ + --data 'upstream_url=http://mockbin.com' \ + --data-urlencode 'uris=/requests/user/(?
+ Note on transforming bodies: Be aware of the performance of transformations on the response body. In order to parse and modify a JSON body, the plugin needs to retain it in memory, which might cause pressure on the worker's Lua VM when dealing with large bodies (several MBs). Because of Nginx's internals, the `Content-Length` header will not be set when transforming a response body.
+
+
+type: plugin
+categories:
+ - transformations
+
+enterprise: true
+kong_version_compatibility:
+ enterprise_edition:
+ compatible:
+ - 0.36-x
+ - 0.35-x
+
+params:
+ name: response-transformer-advanced
+ service_id: true
+ route_id: true
+ consumer_id: true
+ config:
+ - name: remove.headers
+ required: false
+ value_in_examples: "x-toremove, x-another-one"
+ description: List of header names. Unset the header(s) with the given name.
+ - name: remove.json
+ required: false
+ value_in_examples: "json-key-toremove, another-json-key"
+ description: List of property names. Remove the property from the JSON body if it is present.
+ - name: remove.if_status
+ required: false
+ description: List of response status codes or status code ranges to which the transformation will apply. Empty means all response codes.
+ - name: replace.headers
+ required: false
+ description: List of headername:value pairs. If and only if the header is already set, replace its old value with the new one. Ignored if the header is not already set.
+ - name: replace.json
+ required: false
+ description: List of property:value pairs. If and only if the parameter is already present, replace its old value with the new one. Ignored if the parameter is not already present.
+ - name: replace.body
+ required: false
+ description: String with which to replace the entire response body
+ - name: replace.if_status
+ required: false
+ description: List of response status codes or status code ranges to which the transformation will apply. Empty means all response codes
+ - name: add.headers
+ required: false
+ value_in_examples: "x-new-header:value,x-another-header:something"
+ description: List of headername:value pairs. If and only if the header is not already set, set a new header with the given value. Ignored if the header is already set.
+ - name: add.json
+ required: false
+ value_in_examples: "new-json-key:some_value, another-json-key:some_value"
+ description: List of property:value pairs. If and only if the property is not present, add a new property with the given value to the JSON body. Ignored if the property is already present.
+ - name: add.if_status
+ required: false
+ description: List of response status codes or status code ranges to which the transformation will apply. Empty means all response codes
+ - name: append.headers
+ required: false
+ value_in_examples: "x-existing-header:some_value, x-another-header:some_value"
+ description: List of headername:value pairs. If the header is not set, set it with the given value. If it is already set, a new header with the same name and the new value will be set.
+ - name: append.json
+ required: false
+ description: List of property:value pairs. If the property is not present in the JSON body, add it with the given value. If it is already present, the two values (old and new) will be aggregated in an array.
+ - name: append.if_status
+ required: false
+ description: List of response status codes or status code ranges to which the transformation will apply. Empty means all response codes
+
+---
+
+Note: if the value contains a `,` then the comma separated format for lists cannot be used. The array notation must be used instead.
+
+## Order of execution
+
+Plugin performs the response transformation in following order
+
+remove --> replace --> add --> append
+
+## Examples
+
+In these examples we have the plugin enabled on a Route. This would work
+similar for Services.
+
+- Add multiple headers by passing each header:value pair separately:
+
+```bash
+$ curl -X POST http://localhost:8001/routes/{route id}/plugins \
+ --data "name=response-transformer-advanced" \
+ --data "config.add.headers[1]=h1:v1" \
+ --data "config.add.headers[2]=h2:v1"
+```
+
+| upstream response headers | +proxied response headers | +
|---|---|
| h1: v1 | +
+
|
+
| upstream response headers | +proxied response headers | +
|---|---|
| h1: v1 | +
+
|
+
| upstream response headers | +proxied response headers | +
|---|---|
| h1: v1 | +
+
|
+
| upstream response headers | +proxied response headers | +
|---|---|
| h1: v2 | +
+
|
+
| h3: v1 | +
+
|
+
| upstream response headers | +proxied response headers | +
|---|---|
| h1: v1 | +
+
|
+
*note*: the key names may only contain [a-z], [A-Z], [0-9], [_] and [-]. + - name: key_in_body + required: false + default: "`false`" + description: | + If enabled, the plugin will read the request body (if said request has one and its MIME type is supported) and try to find the key in it. Supported MIME types are `application/www-form-urlencoded`, `application/json`, and `multipart/form-data`. + - name: hide_credentials + required: false + default: "`false`" + description: | + An optional boolean value telling the plugin to show or hide the credential from the upstream service. If `true`, the plugin will strip the credential from the request (i.e. the header or querystring containing the key) before proxying it. + - name: anonymous + required: false + default: + description: | + 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`. Please note that this value must refer to the Consumer `id` attribute which is internal to Kong, and **not** its `custom_id`. + - name: run_on_preflight + required: false + default: "`true`" + description: | + 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. + +--- + +## Usage + +In order to use the plugin, you first need to create a Consumer to associate one or more credentials to. The Consumer represents a developer using the upstream service. Additionally, a Vault object must be created to represent the connection Kong will use to communicate with a Vault server, where access and secret tokens will be stored. + +### Create a Consumer + +You need to associate a credential to an existing [Consumer][consumer-object] object. To create a Consumer, you can execute the following request: + +```bash +$ curl -X POST http://kong:8001/consumers/ \ + --data "username=
*semi-optional* | | The username of the Consumer. Either this field or `custom_id` must be specified. +`custom_id`
*semi-optional* | | A custom identifier used to map the Consumer to another database. Either this field or `username` must be specified. + +A [Consumer][consumer-object] can have many credentials. + +If you are also using the [ACL](/plugins/acl/) plugin and whitelists with this +service, you must add the new consumer to a whitelisted group. See +[ACL: Associating Consumers][acl-associating] for details. + +### Create a Vault + +A Vault object represents the connection between Kong and a Vault server. It defines the connection and authentication information used to communicate with the Vault API. This allows different instances of the `vault-auth` plugin to communicate with different Vault servers, providing a flexible deployment and consumption model. + +Vault objects can be created via the following HTTP request: + +```bash +$ curl -X POST http://kong:8001/vaults \ + --data name=kong-auth \ + --data mount=kong-auth \ + --data protocol=http \ + --data host=127.0.0.1 \ + --data port=8200 + --data token=s.m3w9gdV0uMDYFpMgEWSB2mtM +HTTP/1.1 201 Created + +{ + "created_at": 1550538643, + "host": "127.0.0.1", + "id": "d3da058d-0acb-49c2-b7fe-72b3e9fd4b0a", + "mount": "kong-auth", + "name": "kong-auth", + "port": 8200, + "protocol": "http", + "token": "s.m3w9gdV0uMDYFpMgEWSB2mtM", + "updated_at": 1550538643 +} +``` + +This assumes a Vault server is accessible via `127.0.0.1:8200`, and that a version 1 KV secrets engine has been enabled at `kong-auth`. Vault KV secrets engine documentation is available via the [Vault documentation](https://www.vaultproject.io/docs/secrets/kv/kv-v1.html). + +### Create an Access/Secret Token Pair + +`vault-auth` credentials are defined as a pair of tokens: an `access` token that identifies the owner of the credential, and a `secret` token that is used to authenticate ownership of the `access` token. + +Token pairs can be managed either via the Kong Admin API, or independantly via direct access with Vault. Token pairs must be associated with an existing Kong Consumer. Creating a token pair with the Kong Admin API can be done via the following request: + +```bash +$ curl -X POST http://kong:8001/vaults/{vault}/credentials/{consumer} +HTTP/1.1 201 Created + +{ + "data": { + "access_token": "v3cOV1jWglS0PFOrTcdr85bs1GP0e2yM", + "consumer": { + "id": "64063284-e3b5-48e7-9bca-802251c32138" + }, + "created_at": 1550538920, + "secret_token": "11XYyybbu3Ty0Qt4ImIshPGQ0WsvjLzl", + "ttl": null + } +} +``` + +When the `access_token` or `secret_token` values are not provided, token values will be automatically generated via a cryptographically-secure random number generator (CSPRNG). + +### Integrating Vault objects with Vault-Auth plugins + +Vault objects are treated as foreign references in plugin configs, creating a seamless lifecycle relationship between Vault instances and plugins with which they're associated. `vault-auth` plugins require an association with a Vault object, which can be defined with the following HTTP request during plugin creation: + +```bash +$ curl -X POST http://kong:8001/plugins \ + --data name=vault-auth \ + --data config.vault.id=
*note*: the key names may only contain [a-z], [A-Z], [0-9], [_] and [-]. + - name: key_in_body + required: false + default: "`false`" + description: | + If enabled, the plugin will read the request body (if said request has one and its MIME type is supported) and try to find the key in it. Supported MIME types are `application/www-form-urlencoded`, `application/json`, and `multipart/form-data`. + - name: hide_credentials + required: false + default: "`false`" + description: | + An optional boolean value telling the plugin to show or hide the credential from the upstream service. If `true`, the plugin will strip the credential from the request (i.e. the header or querystring containing the key) before proxying it. + - name: anonymous + required: false + default: + description: | + 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`. Please note that this value must refer to the Consumer `id` attribute which is internal to Kong, and **not** its `custom_id`. + - name: run_on_preflight + required: false + default: "`true`" + description: | + 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. + +--- + +## Usage + +In order to use the plugin, you first need to create a Consumer to associate one or more credentials to. The Consumer represents a developer using the upstream service. Additionally, a Vault object must be created to represent the connection Kong will use to communicate with a Vault server, where access and secret tokens will be stored. + +### Create a Consumer + +You need to associate a credential to an existing [Consumer][consumer-object] object. To create a Consumer, you can execute the following request: + +```bash +$ curl -X POST http://kong:8001/consumers/ \ + --data "username=
*semi-optional* | | The username of the Consumer. Either this field or `custom_id` must be specified. +`custom_id`
*semi-optional* | | A custom identifier used to map the Consumer to another database. Either this field or `username` must be specified. + +A [Consumer][consumer-object] can have many credentials. + +If you are also using the [ACL](/plugins/acl/) plugin and whitelists with this +service, you must add the new consumer to a whitelisted group. See +[ACL: Associating Consumers][acl-associating] for details. + +### Create a Vault + +A Vault object represents the connection between Kong and a Vault server. It defines the connection and authentication information used to communicate with the Vault API. This allows different instances of the `vault-auth` plugin to communicate with different Vault servers, providing a flexible deployment and consumption model. + +Vault objects can be created via the following HTTP request: + +```bash +$ curl -X POST http://kong:8001/vaults \ + --data name=kong-auth \ + --data mount=kong-auth \ + --data protocol=http \ + --data host=127.0.0.1 \ + --data port=8200 + --data token=s.m3w9gdV0uMDYFpMgEWSB2mtM +HTTP/1.1 201 Created + +{ + "created_at": 1550538643, + "host": "127.0.0.1", + "id": "d3da058d-0acb-49c2-b7fe-72b3e9fd4b0a", + "mount": "kong-auth", + "name": "kong-auth", + "port": 8200, + "protocol": "http", + "token": "s.m3w9gdV0uMDYFpMgEWSB2mtM", + "updated_at": 1550538643 +} +``` + +This assumes a Vault server is accessible via `127.0.0.1:8200`, and that a version 1 KV secrets engine has been enabled at `kong-auth`. Vault KV secrets engine documentation is available via the [Vault documentation](https://www.vaultproject.io/docs/secrets/kv/kv-v1.html). + +### Create an Access/Secret Token Pair + +`vault-auth` credentials are defined as a pair of tokens: an `access` token that identifies the owner of the credential, and a `secret` token that is used to authenticate ownership of the `access` token. + +Token pairs can be managed either via the Kong Admin API, or independantly via direct access with Vault. Token pairs must be associated with an existing Kong Consumer. Creating a token pair with the Kong Admin API can be done via the following request: + +```bash +$ curl -X POST http://kong:8001/vaults/{vault}/credentials/{consumer} +HTTP/1.1 201 Created + +{ + "data": { + "access_token": "v3cOV1jWglS0PFOrTcdr85bs1GP0e2yM", + "consumer": { + "id": "64063284-e3b5-48e7-9bca-802251c32138" + }, + "created_at": 1550538920, + "secret_token": "11XYyybbu3Ty0Qt4ImIshPGQ0WsvjLzl", + "ttl": null + } +} +``` + +When the `access_token` or `secret_token` values are not provided, token values will be automatically generated via a cryptographically-secure random number generator (CSPRNG). + +### Integrating Vault objects with Vault-Auth plugins + +Vault objects are treated as foreign references in plugin configs, creating a seamless lifecycle relationship between Vault instances and plugins with which they're associated. `vault-auth` plugins require an association with a Vault object, which can be defined with the following HTTP request during plugin creation: + +```bash +$ curl -X POST http://kong:8001/plugins \ + --data name=vault-auth \ + --data config.vault.id=
Table of Contents
- {% include toc.html html=content anchor_class="scroll-to" h_max=4 %} + {% include toc.html html=content anchor_class="scroll-to" h_max=3 %} + {% endif %} {{ content }} @@ -170,7 +171,7 @@Table of Contents
docsearch({ appId: 'T5JKD83LWT', apiKey: '1390283021f26e36117242934deb8d9d', - indexName: 'prod_EE', + indexName: 'private_RC', inputSelector: '#getkong-algolia-search-input', algoliaOptions: { hitsPerPage: 5, diff --git a/app/enterprise/0.35-x/cli.md b/app/enterprise/0.35-x/cli.md index 25b77821ea32..8af20c6f3e08 100644 --- a/app/enterprise/0.35-x/cli.md +++ b/app/enterprise/0.35-x/cli.md @@ -240,7 +240,6 @@ Options: --- - ### kong start ``` diff --git a/app/enterprise/0.36-x/developer-portal/configuration/smtp.md b/app/enterprise/0.36-x/developer-portal/configuration/smtp.md index 10f90338522c..846e9c1fe871 100644 --- a/app/enterprise/0.36-x/developer-portal/configuration/smtp.md +++ b/app/enterprise/0.36-x/developer-portal/configuration/smtp.md @@ -33,6 +33,15 @@ You have been invited to create a Developer Portal account at %s. Please visit `/admins
+
+**Response**
+
+```
+HTTP 200 OK
+```
+
+```json
+{
+ "data": [{
+ "created_at": 1556638385,
+ "id": "665b4070-541f-48bf-82c1-53030babaa81",
+ "updated_at": 1556638385,
+ "status": 4,
+ "username": "test-admin",
+ "email": "test@test.com"
+ }, {
+ "created_at": 1556563122,
+ "id": "a93ff120-9e6c-4198-b47e-f779104c7eac",
+ "updated_at": 1556563122,
+ "status": 0,
+ "username": "kong_admin"
+ }],
+ "next": null
+}
+```
+
+## Invite an Admin
+**Endpoint**
+
+/admins
+
+| Attribute | Description |
+|-------------|------------------------------------------------------------|
+| `email` | The **Admin**'s email address |
+| `username` | The **Admin**'s username |
+| `custom_id` optional | The **Admin**'s custom ID | + +**Response** + +``` +HTTP 200 OK +``` + +```json +{ + "admin": { + "created_at": 1556638641, + "id": "8f0a742f-07f3-49e0-90d7-4fc7eea7e6a4", + "updated_at": 1556638641, + "status": 4, + "username": "test-case-3", + "email": "test3@test.com" + } +} +``` + +## Register an Admin's Credentials +**Endpoint** + +
/admins/register
+
+| Attribute | Description |
+|-------------|---------------------------|
+| `token` | The authentication token |
+| `username` | The **Admin**'s username |
+| `email` | The **Admin**'s email address |
+| `password` | The **Admin**'s new password |
+
+**Response**
+
+```
+HTTP 201 Created
+```
+
+## Send a Password-Reset Email to an Admin
+**Endpoint**
+
+/admins/password_resets
+
+| Attribute | Description |
+|-------------|------------------------------------------------------------|
+| `email` | The **Admin**'s email address |
+
+**Response**
+
+```
+HTTP 201 Created
+```
+
+## Reset an Admin's Password
+**Endpoint**
+
+/admins/password_resets
+
+| Attribute | Description |
+|-------------|------------------------------------------------------------|
+| `email` | The **Admin**'s email address |
+| `password` | The **Admin**'s new password |
+| `token` | The authentication token |
+
+**Response**
+
+```
+HTTP 200 OK
+```
+
+## Retrieve an Admin
+**Endpoint**
+
+/admins/{name_or_id}
+
+| Attribute | Description |
+|------------|-----------------------------------|
+| `name_or_id` | The **Admin**'s username or ID |
+| `generate_register_url` optional | `true` returns a unique registration URL for the **Admin** | + +**Notes:** +* `generate_register_url` will only generate a URL if the **Admin**'s +invitation status is 4 ("invited"). +* `generate_register_url` will override the preĂĽvious registration URL +for the particular **Admin** each time it is requested. + +**Response** + +``` +HTTP 200 OK +``` + +```json +{ + "created_at": 1556638385, + "id": "665b4070-541f-48bf-82c1-53030babaa81", + "updated_at": 1556638385, + "status": 4, + "username": "test-admin", + "email": "test@test.com" +} +``` + +## Update an Admin +**Endpoint** + +
/admins/{name_or_id}
+
+| Attribute | Description |
+|----------------------|--------------------------------------------|
+| `name_or_id` | The **Admin**'s current username or custom ID |
+| `email` optional | The **Admin**'s new email address | +| `username`
optional | The **Admin**'s new username | +| `custom_id`
optional | The **Admin**'s new custom ID | + +**Response** + +``` +HTTP 200 OK +``` + +```json +{ + "created_at": 1556638385, + "id": "665b4070-541f-48bf-82c1-53030babaa81", + "updated_at": 1556639017, + "status": 4, + "username": "test-renamed", + "email": "test@test.com" +} +``` + +## Delete an Admin +**Endpoint** + +
/admins/{name_or_id}
+
+| Attribute | Description |
+|--------------|-----------------------------------|
+| `name_or_id` | The **Admin**'s username or ID |
+
+**Response**
+
+```
+HTTP 204 No Content
+```
+
+## List an Admin's Roles
+**Endpoint**
+
+/admins/{name_or_id}/roles
+
+| Attribute | Description |
+|--------------|-----------------------------------|
+| `name_or_id` | The **Admin**'s username or ID |
+
+**Response**
+
+```
+HTTP 200 OK
+```
+
+```json
+{
+ "roles": [{
+ "comment": "Read access to all endpoints, across all workspaces",
+ "created_at": 1556563122,
+ "id": "7574eb1d-c9fa-46a9-bd3a-3f1b4b196287",
+ "name": "read-only",
+ "is_default": false
+ }, {
+ "comment": "Full access to all endpoints, across all workspacesâexcept RBAC Admin API",
+ "created_at": 1556563122,
+ "id": "7fdea5c8-2bfa-4aa9-9c21-7bb9e607186d",
+ "name": "admin",
+ "is_default": false
+ }]
+}
+```
+
+## Create or Update an Admin's Roles
+**Endpoint**
+
+/admins/{name_or_id}/roles
+
+| Attribute | Description |
+|--------------|-----------------------------------------------------------|
+| `name_or_id` | The **Admin**'s current username or ID |
+| `roles` | (comma separated) string of names of Roles to create or update for an **Admin** |
+
+**Response**
+
+```
+HTTP 201 OK
+```
+
+
+```json
+{
+ "roles": [{
+ "comment": "Read access to all endpoints, across all workspaces",
+ "created_at": 1556563122,
+ "id": "7574eb1d-c9fa-46a9-bd3a-3f1b4b196287",
+ "name": "read-only",
+ "is_default": false
+ }, {
+ "comment": "Full access to all endpoints, across all workspacesâexcept RBAC Admin API",
+ "created_at": 1556563122,
+ "id": "7fdea5c8-2bfa-4aa9-9c21-7bb9e607186d",
+ "name": "admin",
+ "is_default": false
+ }, {
+ "comment": "Full access to all endpoints, across all workspaces",
+ "created_at": 1556563122,
+ "id": "99bd8d18-f5b6-410e-aefe-d75f4252f13c",
+ "name": "super-admin",
+ "is_default": false
+ }]
+}
+```
+
+## Delete an Admin's Role
+**Endpoint**
+
+/admins/{name_or_id}/roles
+
+| Attribute | Description |
+|--------------|-----------------------------------------------------------|
+| `name_or_id` | The **Admin**'s current username or custom ID |
+| `roles` | (comma separated) string of names of Roles to remove from an **Admin** |
+
+**Response**
+
+```
+HTTP 204 No Content
+```
+
+## List an Admin's Workspaces
+**Endpoint**
+
+/admins/{name_or_id}/workspaces
+
+| Attribute | Description |
+|--------------|-----------------------------------|
+| `name_or_id` | The **Admin**'s username or ID |
+
+**Response**
+
+```
+HTTP 200 OK
+```
+
+```json
+[{
+ "created_at": 1556563122,
+ "config": {
+ "portal": true,
+ "portal_auto_approve": true
+ },
+ "id": "00000000-0000-0000-0000-000000000000",
+ "name": "default",
+ "meta": {}
+}, {
+ "created_at": 1556570807,
+ "config": {
+ "portal": true
+ },
+ "id": "57b3ce24-6d29-427f-af13-15bd60430e56",
+ "name": "sdfgsdfg",
+ "meta": {
+ "color": "#3894f0"
+ }
+}]
+```
+
diff --git a/app/enterprise/1.3-x/admin-api/audit-log.md b/app/enterprise/1.3-x/admin-api/audit-log.md
new file mode 100644
index 000000000000..c8ff51750b12
--- /dev/null
+++ b/app/enterprise/1.3-x/admin-api/audit-log.md
@@ -0,0 +1,427 @@
+---
+title: Admin API Audit Log
+---
+
+## Introduction
+
+Kong Enterprise provides a granular logging facility on its Admin API. This
+allows cluster administrators to keep detailed track of changes made to the
+cluster configuration throughout its lifetime, aiding in compliance efforts and
+providing valuable data points during forensic investigations. Generated audit
+log trails are [Workspace](/enterprise/{{page.kong_version}}/admin-api/workspaces/reference)
+- and [RBAC](/enterprise/{{page.kong_version}}/admin-api/rbac/reference)-aware,
+providing Kong operators a deep and wide look into changes happening within
+the cluster.
+
+[Back to TOC](#table-of-contents)
+
+## Getting Started
+
+Audit logging is disabled by default. It is configured via the Kong configuration:
+
+```bash
+# via Kong configuration file, e.g., kong.conf
+audit_log = on # audit logging is enabled
+audit_log = off # audit logging is disabled
+```
+
+```bash
+# or via environmental variables
+$ export KONG_AUDIT_LOG=on
+$ export KONG_AUDIT_LOG=off
+```
+
+As with other Kong configurations, changes take effect on kong reload or kong
+restart.
+
+[Back to TOC](#table-of-contents)
+
+## Request Audits
+
+### Generating and Viewing Audit Logs
+
+Audit logging provides granular details of each HTTP request that was handled by
+Kong's Admin API. Audit log data is written to Kong's back database. As a result,
+request audit logs are available via the Admin API (in addition to via direct
+database query). For example, consider a query to the Admin API to the `/status`
+endpoint:
+
+```
+vagrant@ubuntu-xenial:/kong$ http :8001/status
+HTTP/1.1 200 OK
+Access-Control-Allow-Origin: *
+Connection: keep-alive
+Content-Type: application/json; charset=utf-8
+Date: Tue, 13 Nov 2018 17:32:47 GMT
+Server: kong/0.34-enterprise-edition
+Transfer-Encoding: chunked
+X-Kong-Admin-Request-ID: ZuUfPfnxNn7D2OTU6Xi4zCnQkavzMUNM
+
+{
+ "database": {
+ "reachable": true
+ },
+ "server": {
+ "connections_accepted": 1,
+ "connections_active": 1,
+ "connections_handled": 1,
+ "connections_reading": 0,
+ "connections_waiting": 0,
+ "connections_writing": 1,
+ "total_requests": 1
+ }
+}
+```
+
+The above interaction with the Admin API would generate a correlating entry in
+the audit log tableâquerying the audit log via the Admin API returns the details
+of of the interaction above:
+
+```
+$ http :8001/audit/requests
+HTTP/1.1 200 OK
+Access-Control-Allow-Origin: *
+Connection: keep-alive
+Content-Type: application/json; charset=utf-8
+Date: Tue, 13 Nov 2018 17:35:24 GMT
+Server: kong/0.34-enterprise-edition
+Transfer-Encoding: chunked
+X-Kong-Admin-Request-ID: VXgMG1Y3rZKbjrzVYlSdLNPw8asVwhET
+
+{
+ "data": [
+ {
+ "client_ip": "127.0.0.1",
+ "expire": 1544722367698,
+ "method": "GET",
+ "path": "/status",
+ "request_id": "ZuUfPfnxNn7D2OTU6Xi4zCnQkavzMUNM",
+ "request_timestamp": 1542130367699,
+ "status": 200,
+ "workspace": "0da4afe7-44ad-4e81-a953-5d2923ce68ae"
+ }
+ ],
+ "total": 1
+}
+```
+
+Note the value of the `request_id` field. This is tied to the
+`X-Kong-Admin-Request-ID` response header received in the first transaction.
+This allows close association of client requests and audit log records within
+the Kong cluster.
+
+Because every audit log entry is made available via Kong's Admin API, it is
+possible to transport audit log entries into existing logging warehouses, SIEM
+solutions, or other remote services for duplication and inspection.
+
+[Back to TOC](#table-of-contents)
+
+### Workspaces and RBAC
+
+Audit log entries are written with an awareness of the requested Workspace, and
+the RBAC user (if present). When RBAC is enforced, the RBAC user's UUID will be
+written to the `rbac_user_id` field in the audit log entry:
+
+```
+{
+ "data": [
+ {
+ "client_ip": "127.0.0.1",
+ "expire": 1544722999857,
+ "method": "GET",
+ "path": "/status",
+ "rbac_user_id": "2e959b45-0053-41cc-9c2c-5458d0964331",
+ "request_id": "QUtUa3RMbRLxomqcL68ilOjjl68h56xr",
+ "request_timestamp": 1542130999858,
+ "status": 200,
+ "workspace": "0da4afe7-44ad-4e81-a953-5d2923ce68ae"
+ }
+ ],
+ "total": 1
+}
+```
+
+Note also the presence of the `workspace` field. This is the UUID of the Workspace with which the request was associated.
+
+[Back to TOC](#table-of-contents)
+
+### Limiting Audit Log Generation
+
+It may be desirable to ignore audit log generation for certain Admin API
+requests, such as innocuous requests to the `/status` endpoint for
+healthchecking, or to ignore requests for a given path prefix (e.g., a given
+Workspace). To this end, the `audit_log_ignore_methods` and
+`audit_log_ignore_paths` configuration options are presented:
+
+```bash
+audit_log_ignore_methods = GET,OPTIONS
+# do not generate an audit log entry for GET or OPTIONS HTTP requests
+audit_log_ignore_paths = /foo,/status
+# do not generate an audit log entry for requests that match the strings '/foo' or '/status'
+```
+
+Note that `audit_log_ignore_paths` values matched via simple string matching;
+regular expression or anchored searching for ignored paths is not supported at
+this time.
+
+[Back to TOC](#table-of-contents)
+
+## Database Audits
+
+### Generating and Viewing Audit Logs
+
+In addition to Admin API request data, Kong will generate granular audit log
+entries for all insertions, updates, and deletions to the cluster database.
+Database updates audit logs are also associated with Admin API request unique
+IDs. Consider the following request to create a Consumer:
+
+```
+$ http :8001/consumers username=bob
+HTTP/1.1 201 Created
+Access-Control-Allow-Origin: *
+Connection: keep-alive
+Content-Type: application/json; charset=utf-8
+Date: Tue, 13 Nov 2018 17:50:18 GMT
+Server: kong/0.34-enterprise-edition
+Transfer-Encoding: chunked
+X-Kong-Admin-Request-ID: 59fpTWlpUtHJ0qnAWBzQRHRDv7i5DwK2
+
+{
+ "created_at": 1542131418000,
+ "id": "16787ed7-d805-434a-9cec-5e5a3e5c9e4f",
+ "type": 0,
+ "username": "bob"
+}
+
+```
+
+As seen before, a request audit log is generated with details about the request.
+Note the presence of the `payload` field, recorded when the request body is
+present:
+
+```
+$ http :8001/audit/requests
+HTTP/1.1 200 OK
+Access-Control-Allow-Origin: *
+Connection: keep-alive
+Content-Type: application/json; charset=utf-8
+Date: Tue, 13 Nov 2018 17:52:41 GMT
+Server: kong/0.34-dev-enterprise-edition
+Transfer-Encoding: chunked
+X-Kong-Admin-Request-ID: SpPaxLTkDNndzKaYiWuZl3xrxDUIiGRR
+
+{
+ "data": [
+ {
+ "client_ip": "127.0.0.1",
+ "expire": 1544723418013,
+ "method": "POST",
+ "path": "/consumers",
+ "payload": "{\"username\": \"bob\"}",
+ "request_id": "59fpTWlpUtHJ0qnAWBzQRHRDv7i5DwK2",
+ "request_timestamp": 1542131418014,
+ "status": 201,
+ "workspace": "fd51ce6e-59c0-4b6b-b991-aa708a9ff4d2"
+ }
+ ],
+ "total": 1
+}
+```
+
+Additionally, additional audit logs are generated to track the creation of the
+database entity:
+
+```
+$ http :8001/audit/objects
+HTTP/1.1 200 OK
+Access-Control-Allow-Origin: *
+Connection: keep-alive
+Content-Type: application/json; charset=utf-8
+Date: Tue, 13 Nov 2018 17:53:27 GMT
+Server: kong/0.34-dev-enterprise-edition
+Transfer-Encoding: chunked
+X-Kong-Admin-Request-ID: ZKra3QT0d3eJKl96jOUXYueLumo0ck8c
+
+{
+ "data": [
+ {
+ "dao_name": "consumers",
+ "entity": "{\"created_at\":1542131418000,\"id\":\"16787ed7-d805-434a-9cec-5e5a3e5c9e4f\",\"username\":\"bob\",\"type\":0}",
+ "entity_key": "16787ed7-d805-434a-9cec-5e5a3e5c9e4f",
+ "expire": 1544723418009,
+ "id": "7ebabee7-2b09-445d-bc1f-2092c4ddc4be",
+ "operation": "create",
+ "request_id": "59fpTWlpUtHJ0qnAWBzQRHRDv7i5DwK2"
+ },
+ ],
+ "total": 1
+}
+```
+
+Object audit entries contain information about the entity updated, including the
+entity body itself, its database primary key, and the type of operation
+performed (`create`, `update`, or `delete`). Note also the associated
+ `request_id` field.
+
+[Back to TOC](#table-of-contents)
+
+### Limiting Audit Log Generation
+
+As with request audit logs, it may be desirable to skip generation of audit logs
+for certain database tables. This is configurable via the
+`audit_log_ignore_tables` Kong config option:
+
+```
+audit_log_ignore_tables = consumers
+# do not generate database audit logs for changes to the consumers table
+```
+
+[Back to TOC](#table-of-contents)
+
+## Digital Signatures
+
+To provide nonrepudiation, audit logs may be signed with a private RSA key. When
+enabled, a lexically sorted representation of each audit log entry is signed by
+the defined private key; the signature is stored in an additional field within
+the record itself. The public key should be stored elsewhere and can be used
+later to validate the signature of the record.
+
+### Setting Up Log Signing
+
+Generate a private key via the `openssl` tool:
+
+```bash
+$ openssl genrsa -out private.pem 2048
+```
+
+Configure Kong to sign audit log records:
+
+```
+audit_log_signing_key = /path/to/private.pem
+```
+
+Audit log entries will now contain a field `signature`:
+
+```
+{
+ "client_ip": "127.0.0.1",
+ "expire": 1544724298663,
+ "method": "GET",
+ "path": "/status",
+ "request_id": "Ka2GeB13RkRIbMwBHw0xqe2EEfY0uZG0",
+ "request_timestamp": 1542132298664,
+ "signature": "ctD8DXJEfuFAVdlYuhay7f4kmcZhfRPjX8Q6HlSJ+67aHjJIzzrlSxWKfmxnJ7WKRvlF7bU8PX/rtu1ytLQwmzW2LpMd/WFt34PKmyOFUByslkxCdfKKNHadZ+FfINzD+JrecFdXNJrSxKKHHTxj8g6vglAcoJMmuSB6cMsAuVUbO+CL6N/WV9RfCquxxkQUfqGoyEA09EeU4uC0xa8gcYAr1FMGcu+TdRbazfBqZayrKxn8iMV/7LUefMgzUrVdC7UFjZORo5Q0wl9U/iQWU5sRGiTo/HTQmU/a7EdyX3c6Wbmg2khYJFzUIkg9JRL/YUla+yfe3AL4KwFSH90xTw==",
+ "status": 200,
+ "workspace": "fd51ce6e-59c0-4b6b-b991-aa708a9ff4d2"
+}
+```
+
+[Back to TOC](#table-of-contents)
+
+### Validating Signatures
+
+Record signatures can be regenerated and verified by `openssl` or other
+cryptographic tools to confirm the validity of the signature. Re-generating the
+signature requires serializing the record into a string format that can be
+signed. The following is a canonical implementation written in Lua:
+
+```lua
+local pl_sort = require "pl.tablex".sort
+
+local function serialize(data)
+ local p = {}
+
+ for k, v in pl_sort(data) do
+ if type(v) == "table" then
+ p[#p + 1] = serialize(v)
+ else
+ p[#p + 1] = v
+ end
+ end
+
+ return p
+end
+
+table.concat(serialize(data), "|")
+```
+
+The contents of the record itself can be fed to this implementation (minus the
+`signature` field) in order to derive the value passed to the RSA key signing
+facility. Note that the `signature` field within each record is a Base-64
+encoded representation of the RSA signature itself.
+
+[Back to TOC](#table-of-contents)
+
+---
+
+## Reference
+
+### API Reference
+
+#### List Request Audit Logs
+
+##### Endpoint
+
+/audit/requests
+
+##### Response
+
+```
+HTTP 200 OK
+```
+
+```json
+{
+ "data": [
+ {
+ "client_ip": "127.0.0.1",
+ "expire": 1544722367698,
+ "method": "GET",
+ "path": "/status",
+ "request_id": "ZuUfPfnxNn7D2OTU6Xi4zCnQkavzMUNM",
+ "request_timestamp": 1542130367699,
+ "status": 200,
+ "workspace": "0da4afe7-44ad-4e81-a953-5d2923ce68ae"
+ }
+ ],
+ "total": 1
+}
+```
+
+#### List Database Audit Logs
+
+##### Endpoint
+
+/audit/objects
+
+##### Response
+
+```
+HTTP 200 OK
+```
+
+```json
+{
+ "data": [
+ {
+ "dao_name": "consumers",
+ "entity": "{\"created_at\":1542131418000,\"id\":\"16787ed7-d805-434a-9cec-5e5a3e5c9e4f\",\"username\":\"bob\",\"type\":0}",
+ "entity_key": "16787ed7-d805-434a-9cec-5e5a3e5c9e4f",
+ "expire": 1544723418009,
+ "id": "7ebabee7-2b09-445d-bc1f-2092c4ddc4be",
+ "operation": "create",
+ "request_id": "59fpTWlpUtHJ0qnAWBzQRHRDv7i5DwK2"
+ },
+ ],
+ "total": 1
+}
+```
+
+[Back to TOC](#table-of-contents)
+
+### Configuration Reference
+
+See the [Data & Admin Audit](/enterprise/{{page.kong_version}}/property-reference#data--admin-audit)
+section of Kong Enterprise's Configuration Property Reference.
+
+[Back to TOC](#table-of-contents)
diff --git a/app/enterprise/1.3-x/admin-api/index.md b/app/enterprise/1.3-x/admin-api/index.md
new file mode 100644
index 000000000000..ac9a1a204f52
--- /dev/null
+++ b/app/enterprise/1.3-x/admin-api/index.md
@@ -0,0 +1,3027 @@
+---
+title: Admin API
+
+service_body: |
+ Attributes | Description
+ ---:| ---
+ `name`*optional* | The Service name. + `retries`
*optional* | The number of retries to execute upon failure to proxy. Defaults to `5`. + `protocol` | The protocol used to communicate with the upstream. It can be one of `http` or `https`. Defaults to `"http"`. + `host` | The host of the upstream server. + `port` | The upstream server port. Defaults to `80`. + `path`
*optional* | The path to be used in requests to the upstream server. + `connect_timeout`
*optional* | The timeout in milliseconds for establishing a connection to the upstream server. Defaults to `60000`. + `write_timeout`
*optional* | The timeout in milliseconds between two successive write operations for transmitting a request to the upstream server. Defaults to `60000`. + `read_timeout`
*optional* | The timeout in milliseconds between two successive read operations for transmitting a request to the upstream server. Defaults to `60000`. + `tags`
*optional* | An optional set of strings associated with the Service, for grouping and filtering. + `url`
*shorthand-attribute* | Shorthand attribute to set `protocol`, `host`, `port` and `path` at once. This attribute is write-only (the Admin API never "returns" the url). + +service_json: | + { + "id": "9748f662-7711-4a90-8186-dc02f10eb0f5", + "created_at": 1422386534, + "updated_at": 1422386534, + "name": "my-service", + "retries": 5, + "protocol": "http", + "host": "example.com", + "port": 80, + "path": "/some_api", + "connect_timeout": 60000, + "write_timeout": 60000, + "read_timeout": 60000, + "tags": ["user-level", "low-priority"] + } + +service_data: | + "data": [{ + "id": "4e3ad2e4-0bc4-4638-8e34-c84a417ba39b", + "created_at": 1422386534, + "updated_at": 1422386534, + "name": "my-service", + "retries": 5, + "protocol": "http", + "host": "example.com", + "port": 80, + "path": "/some_api", + "connect_timeout": 60000, + "write_timeout": 60000, + "read_timeout": 60000, + "tags": ["user-level", "low-priority"] + }, { + "id": "a5fb8d9b-a99d-40e9-9d35-72d42a62d83a", + "created_at": 1422386534, + "updated_at": 1422386534, + "name": "my-service", + "retries": 5, + "protocol": "http", + "host": "example.com", + "port": 80, + "path": "/another_api", + "connect_timeout": 60000, + "write_timeout": 60000, + "read_timeout": 60000, + "tags": ["admin", "high-priority", "critical"] + }], + +route_body: | + Attributes | Description + ---:| --- + `name`
*optional* | The name of the Route. + `protocols` | A list of the protocols this Route should allow. When set to `["https"]`, HTTP requests are answered with a request to upgrade to HTTPS. Defaults to `["http", "https"]`. + `methods`
*semi-optional* | A list of HTTP methods that match this Route. When using `http` or `https` protocols, at least one of `hosts`, `paths`, or `methods` must be set. + `hosts`
*semi-optional* | A list of domain names that match this Route. When using `http` or `https` protocols, at least one of `hosts`, `paths`, or `methods` must be set. With form-encoded, the notation is `hosts[]=example.com&hosts[]=foo.test`. With JSON, use an Array. + `paths`
*semi-optional* | A list of paths that match this Route. When using `http` or `https` protocols, at least one of `hosts`, `paths`, or `methods` must be set. With form-encoded, the notation is `paths[]=/foo&paths[]=/bar`. With JSON, use an Array. + `https_redirect_status_code` | The status code Kong responds with when all properties of a Route match except the protocol i.e. if the protocol of the request is `HTTP` instead of `HTTPS`. `Location` header is injected by Kong if the field is set to 301, 302, 307 or 308. Defaults to `426`. + `regex_priority`
*optional* | A number used to choose which route resolves a given request when several routes match it using regexes simultaneously. When two routes match the path and have the same `regex_priority`, the older one (lowest `created_at`) is used. Note that the priority for non-regex routes is different (longer non-regex routes are matched before shorter ones). Defaults to `0`. + `strip_path`
*optional* | When matching a Route via one of the `paths`, strip the matching prefix from the upstream request URL. Defaults to `true`. + `preserve_host`
*optional* | When matching a Route via one of the `hosts` domain names, use the request `Host` header in the upstream request headers. If set to `false`, the upstream `Host` header will be that of the Service's `host`. + `snis`
*semi-optional* | A list of SNIs that match this Route when using stream routing. When using `tcp` or `tls` protocols, at least one of `snis`, `sources`, or `destinations` must be set. + `sources`
*semi-optional* | A list of IP sources of incoming connections that match this Route when using stream routing. Each entry is an object with fields "ip" (optionally in CIDR range notation) and/or "port". When using `tcp` or `tls` protocols, at least one of `snis`, `sources`, or `destinations` must be set. + `destinations`
*semi-optional* | A list of IP destinations of incoming connections that match this Route when using stream routing. Each entry is an object with fields "ip" (optionally in CIDR range notation) and/or "port". When using `tcp` or `tls` protocols, at least one of `snis`, `sources`, or `destinations` must be set. + `tags`
*optional* | An optional set of strings associated with the Route, for grouping and filtering. + `service`
*optional* | The Service this Route is associated to. This is where the Route proxies traffic to. With form-encoded, the notation is `service.id=
*semi-optional* | The unique username of the consumer. You must send either this field or `custom_id` with the request. + `custom_id`
*semi-optional* | 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. + `tags`
*optional* | An optional set of strings associated with the Consumer, for grouping and filtering. + +consumer_json: | + { + "id": "127dfc88-ed57-45bf-b77a-a9d3a152ad31", + "created_at": 1422386534, + "username": "my-username", + "custom_id": "my-custom-id", + "tags": ["user-level", "low-priority"] + } + +consumer_data: | + "data": [{ + "id": "9aa116fd-ef4a-4efa-89bf-a0b17c4be982", + "created_at": 1422386534, + "username": "my-username", + "custom_id": "my-custom-id", + "tags": ["user-level", "low-priority"] + }, { + "id": "ba641b07-e74a-430a-ab46-94b61e5ea66b", + "created_at": 1422386534, + "username": "my-username", + "custom_id": "my-custom-id", + "tags": ["admin", "high-priority", "critical"] + }], + +plugin_body: | + Attributes | Description + ---:| --- + `name` | The name of the Plugin that's going to be added. Currently the Plugin must be installed in every Kong instance separately. + `route`
*optional* | If set, the plugin will only activate when receiving requests via the specified route. Leave unset for the plugin to activate regardless of the Route being used. Defaults to `null`. With form-encoded, the notation is `route.id=
*optional* | If set, the plugin will only activate when receiving requests via one of the routes belonging to the specified Service. Leave unset for the plugin to activate regardless of the Service being matched. Defaults to `null`. With form-encoded, the notation is `service.id=
*optional* | If set, the plugin will activate only for requests where the specified has been authenticated. (Note that some plugins can not be restricted to consumers this way.). Leave unset for the plugin to activate regardless of the authenticated consumer. Defaults to `null`. With form-encoded, the notation is `consumer.id=
*optional* | The configuration properties for the Plugin which can be found on the plugins documentation page in the [Kong Hub](https://docs.konghq.com/hub/). + `run_on` | Control on which Kong nodes this plugin will run, given a Service Mesh scenario. Accepted values are: * `first`, meaning "run on the first Kong node that is encountered by the request". On an API Getaway scenario, this is the usual operation, since there is only one Kong node in between source and destination. In a sidecar-to-sidecar Service Mesh scenario, this means running the plugin only on the Kong sidecar of the outbound connection. * `second`, meaning "run on the second node that is encountered by the request". This option is only relevant for sidecar-to-sidecar Service Mesh scenarios: this means running the plugin only on the Kong sidecar of the inbound connection. * `all` means "run on all nodes", meaning both sidecars in a sidecar-to-sidecar scenario. This is useful for tracing/logging plugins. Defaults to `"first"`. + `protocols` | A list of the request protocols that will trigger this plugin. Possible values are `"http"`, `"https"`, `"tcp"`, and `"tls"`. The default value, as well as the possible values allowed on this field, may change depending on the plugin type. For example, plugins that only work in stream mode will may only support `"tcp"` and `"tls"`. Defaults to `["http", "https"]`. + `enabled`
*optional* | Whether the plugin is applied. Defaults to `true`. + `tags`
*optional* | An optional set of strings associated with the Plugin, for grouping and filtering. + +plugin_json: | + { + "id": "ec1a1f6f-2aa4-4e58-93ff-b56368f19b27", + "name": "rate-limiting", + "created_at": 1422386534, + "route": null, + "service": null, + "consumer": null, + "config": {"hour":500, "minute":20}, + "run_on": "first", + "protocols": ["http", "https"], + "enabled": true, + "tags": ["user-level", "low-priority"] + } + +plugin_data: | + "data": [{ + "id": "a4407883-c166-43fd-80ca-3ca035b0cdb7", + "name": "rate-limiting", + "created_at": 1422386534, + "route": null, + "service": null, + "consumer": null, + "config": {"hour":500, "minute":20}, + "run_on": "first", + "protocols": ["http", "https"], + "enabled": true, + "tags": ["user-level", "low-priority"] + }, { + "id": "01c23299-839c-49a5-a6d5-8864c09184af", + "name": "rate-limiting", + "created_at": 1422386534, + "route": null, + "service": null, + "consumer": null, + "config": {"hour":500, "minute":20}, + "run_on": "first", + "protocols": ["tcp", "tls"], + "enabled": true, + "tags": ["admin", "high-priority", "critical"] + }], + +certificate_body: | + Attributes | Description + ---:| --- + `cert` | PEM-encoded public certificate of the SSL key pair. + `key` | PEM-encoded private key of the SSL key pair. + `tags`
*optional* | An optional set of strings associated with the Certificate, for grouping and filtering. + `snis`
*shorthand-attribute* | An array of zero or more hostnames to associate with this certificate as SNIs. This is a sugar parameter that will, under the hood, create an SNI object and associate it with this certificate for your convenience. To set this attribute this certificate must have a valid private key associated with it. + +certificate_json: | + { + "id": "ce44eef5-41ed-47f6-baab-f725cecf98c7", + "created_at": 1422386534, + "cert": "-----BEGIN CERTIFICATE-----...", + "key": "-----BEGIN RSA PRIVATE KEY-----...", + "tags": ["user-level", "low-priority"] + } + +certificate_data: | + "data": [{ + "id": "02621eee-8309-4bf6-b36b-a82017a5393e", + "created_at": 1422386534, + "cert": "-----BEGIN CERTIFICATE-----...", + "key": "-----BEGIN RSA PRIVATE KEY-----...", + "tags": ["user-level", "low-priority"] + }, { + "id": "66c7b5c4-4aaf-4119-af1e-ee3ad75d0af4", + "created_at": 1422386534, + "cert": "-----BEGIN CERTIFICATE-----...", + "key": "-----BEGIN RSA PRIVATE KEY-----...", + "tags": ["admin", "high-priority", "critical"] + }], + +sni_body: | + Attributes | Description + ---:| --- + `name` | The SNI name to associate with the given certificate. May contain a single wildcard in the leftmost (suffix) or rightmost (prefix) position. This can be helpful when maintaining multiple subdomains, as a single SNI configured with a wildcard name can be used to match multiple subdomains, instead of creating an SNI entity for each. Valid wildcard positions are `mydomain.*`, `*.mydomain.com`, and `*.www.mydomain.com`. Plain SNI names (no wildcard) take priority when matching, followed by prefix and then suffix. + `tags`
*optional* | An optional set of strings associated with the SNIs, for grouping and filtering. + `certificate` | The id (a UUID) of the certificate with which to associate the SNI hostname. The Certificate must have a valid private key associated with it to be used by the SNI object. With form-encoded, the notation is `certificate.id=
*optional* | What to use as hashing input: `none` (resulting in a weighted-round-robin scheme with no hashing), `consumer`, `ip`, `header`, or `cookie`. Defaults to `"none"`. + `hash_fallback`
*optional* | What to use as hashing input if the primary `hash_on` does not return a hash (eg. header is missing, or no consumer identified). One of: `none`, `consumer`, `ip`, `header`, or `cookie`. Not available if `hash_on` is set to `cookie`. Defaults to `"none"`. + `hash_on_header`
*semi-optional* | The header name to take the value from as hash input. Only required when `hash_on` is set to `header`. + `hash_fallback_header`
*semi-optional* | The header name to take the value from as hash input. Only required when `hash_fallback` is set to `header`. + `hash_on_cookie`
*semi-optional* | The cookie name to take the value from as hash input. Only required when `hash_on` or `hash_fallback` is set to `cookie`. If the specified cookie is not in the request, Kong will generate a value and set the cookie in the response. + `hash_on_cookie_path`
*semi-optional* | The cookie path to set in the response headers. Only required when `hash_on` or `hash_fallback` is set to `cookie`. Defaults to `"/"`. + `slots`
*optional* | The number of slots in the loadbalancer algorithm (`10`-`65536`). Defaults to `10000`. + `healthchecks.active.https_verify_certificate`
*optional* | Whether to check the validity of the SSL certificate of the remote host when performing active health checks using HTTPS. Defaults to `true`. + `healthchecks.active.unhealthy.http_statuses`
*optional* | An array of HTTP statuses to consider a failure, indicating unhealthiness, when returned by a probe in active health checks. Defaults to `[429, 404, 500, 501, 502, 503, 504, 505]`. With form-encoded, the notation is `http_statuses[]=429&http_statuses[]=404`. With JSON, use an Array. + `healthchecks.active.unhealthy.tcp_failures`
*optional* | Number of TCP failures in active probes to consider a target unhealthy. Defaults to `0`. + `healthchecks.active.unhealthy.timeouts`
*optional* | Number of timeouts in active probes to consider a target unhealthy. Defaults to `0`. + `healthchecks.active.unhealthy.http_failures`
*optional* | Number of HTTP failures in active probes (as defined by `healthchecks.active.unhealthy.http_statuses`) to consider a target unhealthy. Defaults to `0`. + `healthchecks.active.unhealthy.interval`
*optional* | Interval between active health checks for unhealthy targets (in seconds). A value of zero indicates that active probes for unhealthy targets should not be performed. Defaults to `0`. + `healthchecks.active.http_path`
*optional* | Path to use in GET HTTP request to run as a probe on active health checks. Defaults to `"/"`. + `healthchecks.active.timeout`
*optional* | Socket timeout for active health checks (in seconds). Defaults to `1`. + `healthchecks.active.healthy.http_statuses`
*optional* | An array of HTTP statuses to consider a success, indicating healthiness, when returned by a probe in active health checks. Defaults to `[200, 302]`. With form-encoded, the notation is `http_statuses[]=200&http_statuses[]=302`. With JSON, use an Array. + `healthchecks.active.healthy.interval`
*optional* | Interval between active health checks for healthy targets (in seconds). A value of zero indicates that active probes for healthy targets should not be performed. Defaults to `0`. + `healthchecks.active.healthy.successes`
*optional* | Number of successes in active probes (as defined by `healthchecks.active.healthy.http_statuses`) to consider a target healthy. Defaults to `0`. + `healthchecks.active.https_sni`
*optional* | The hostname to use as an SNI (Server Name Identification) when performing active health checks using HTTPS. This is particularly useful when Targets are configured using IPs, so that the target host's certificate can be verified with the proper SNI. + `healthchecks.active.concurrency`
*optional* | Number of targets to check concurrently in active health checks. Defaults to `10`. + `healthchecks.active.type`
*optional* | Whether to perform active health checks using HTTP or HTTPS, or just attempt a TCP connection. Possible values are `tcp`, `http` or `https`. Defaults to `"http"`. + `healthchecks.passive.unhealthy.http_failures`
*optional* | Number of HTTP failures in proxied traffic (as defined by `healthchecks.passive.unhealthy.http_statuses`) to consider a target unhealthy, as observed by passive health checks. Defaults to `0`. + `healthchecks.passive.unhealthy.http_statuses`
*optional* | An array of HTTP statuses which represent unhealthiness when produced by proxied traffic, as observed by passive health checks. Defaults to `[429, 500, 503]`. With form-encoded, the notation is `http_statuses[]=429&http_statuses[]=500`. With JSON, use an Array. + `healthchecks.passive.unhealthy.tcp_failures`
*optional* | Number of TCP failures in proxied traffic to consider a target unhealthy, as observed by passive health checks. Defaults to `0`. + `healthchecks.passive.unhealthy.timeouts`
*optional* | Number of timeouts in proxied traffic to consider a target unhealthy, as observed by passive health checks. Defaults to `0`. + `healthchecks.passive.type`
*optional* | Whether to perform passive health checks interpreting HTTP/HTTPS statuses, or just check for TCP connection success. Possible values are `tcp`, `http` or `https` (in passive checks, `http` and `https` options are equivalent.). Defaults to `"http"`. + `healthchecks.passive.healthy.successes`
*optional* | Number of successes in proxied traffic (as defined by `healthchecks.passive.healthy.http_statuses`) to consider a target healthy, as observed by passive health checks. Defaults to `0`. + `healthchecks.passive.healthy.http_statuses`
*optional* | An array of HTTP statuses which represent healthiness when produced by proxied traffic, as observed by passive health checks. Defaults to `[200, 201, 202, 203, 204, 205, 206, 207, 208, 226, 300, 301, 302, 303, 304, 305, 306, 307, 308]`. With form-encoded, the notation is `http_statuses[]=200&http_statuses[]=201`. With JSON, use an Array. + `tags`
*optional* | An optional set of strings associated with the Upstream, for grouping and filtering. + +upstream_json: | + { + "id": "91020192-062d-416f-a275-9addeeaffaf2", + "created_at": 1422386534, + "name": "my-upstream", + "hash_on": "none", + "hash_fallback": "none", + "hash_on_cookie_path": "/", + "slots": 10000, + "healthchecks": { + "active": { + "https_verify_certificate": true, + "unhealthy": { + "http_statuses": [429, 404, 500, 501, 502, 503, 504, 505], + "tcp_failures": 0, + "timeouts": 0, + "http_failures": 0, + "interval": 0 + }, + "http_path": "/", + "timeout": 1, + "healthy": { + "http_statuses": [200, 302], + "interval": 0, + "successes": 0 + }, + "https_sni": "example.com", + "concurrency": 10, + "type": "http" + }, + "passive": { + "unhealthy": { + "http_failures": 0, + "http_statuses": [429, 500, 503], + "tcp_failures": 0, + "timeouts": 0 + }, + "type": "http", + "healthy": { + "successes": 0, + "http_statuses": [200, 201, 202, 203, 204, 205, 206, 207, 208, 226, 300, 301, 302, 303, 304, 305, 306, 307, 308] + } + } + }, + "tags": ["user-level", "low-priority"] + } + +upstream_data: | + "data": [{ + "id": "a2e013e8-7623-4494-a347-6d29108ff68b", + "created_at": 1422386534, + "name": "my-upstream", + "hash_on": "none", + "hash_fallback": "none", + "hash_on_cookie_path": "/", + "slots": 10000, + "healthchecks": { + "active": { + "https_verify_certificate": true, + "unhealthy": { + "http_statuses": [429, 404, 500, 501, 502, 503, 504, 505], + "tcp_failures": 0, + "timeouts": 0, + "http_failures": 0, + "interval": 0 + }, + "http_path": "/", + "timeout": 1, + "healthy": { + "http_statuses": [200, 302], + "interval": 0, + "successes": 0 + }, + "https_sni": "example.com", + "concurrency": 10, + "type": "http" + }, + "passive": { + "unhealthy": { + "http_failures": 0, + "http_statuses": [429, 500, 503], + "tcp_failures": 0, + "timeouts": 0 + }, + "type": "http", + "healthy": { + "successes": 0, + "http_statuses": [200, 201, 202, 203, 204, 205, 206, 207, 208, 226, 300, 301, 302, 303, 304, 305, 306, 307, 308] + } + } + }, + "tags": ["user-level", "low-priority"] + }, { + "id": "147f5ef0-1ed6-4711-b77f-489262f8bff7", + "created_at": 1422386534, + "name": "my-upstream", + "hash_on": "none", + "hash_fallback": "none", + "hash_on_cookie_path": "/", + "slots": 10000, + "healthchecks": { + "active": { + "https_verify_certificate": true, + "unhealthy": { + "http_statuses": [429, 404, 500, 501, 502, 503, 504, 505], + "tcp_failures": 0, + "timeouts": 0, + "http_failures": 0, + "interval": 0 + }, + "http_path": "/", + "timeout": 1, + "healthy": { + "http_statuses": [200, 302], + "interval": 0, + "successes": 0 + }, + "https_sni": "example.com", + "concurrency": 10, + "type": "http" + }, + "passive": { + "unhealthy": { + "http_failures": 0, + "http_statuses": [429, 500, 503], + "tcp_failures": 0, + "timeouts": 0 + }, + "type": "http", + "healthy": { + "successes": 0, + "http_statuses": [200, 201, 202, 203, 204, 205, 206, 207, 208, 226, 300, 301, 302, 303, 304, 305, 306, 307, 308] + } + } + }, + "tags": ["admin", "high-priority", "critical"] + }], + +target_body: | + Attributes | Description + ---:| --- + `target` | The target address (ip or hostname) and port. If the hostname resolves to an SRV record, the `port` value will be overridden by the value from the DNS record. + `weight`
*optional* | The weight this target gets within the upstream loadbalancer (`0`-`1000`). If the hostname resolves to an SRV record, the `weight` value will be overridden by the value from the DNS record. Defaults to `100`. + `tags`
*optional* | An optional set of strings associated with the Target, for grouping and filtering. + +target_json: | + { + "id": "a3ad71a8-6685-4b03-a101-980a953544f6", + "created_at": 1422386534, + "upstream": {"id":"b87eb55d-69a1-41d2-8653-8d706eecefc0"}, + "target": "example.com:8000", + "weight": 100, + "tags": ["user-level", "low-priority"] + } + +target_data: | + "data": [{ + "id": "4e8d95d4-40f2-4818-adcb-30e00c349618", + "created_at": 1422386534, + "upstream": {"id":"58c8ccbb-eafb-4566-991f-2ed4f678fa70"}, + "target": "example.com:8000", + "weight": 100, + "tags": ["user-level", "low-priority"] + }, { + "id": "ea29aaa3-3b2d-488c-b90c-56df8e0dd8c6", + "created_at": 1422386534, + "upstream": {"id":"4fe14415-73d5-4f00-9fbc-c72a0fccfcb2"}, + "target": "example.com:8000", + "weight": 100, + "tags": ["admin", "high-priority", "critical"] + }], + + +--- + +Kong comes with an **internal** RESTful Admin API for administration purposes. +Requests to the Admin API can be sent to any node in the cluster, and Kong will +keep the configuration consistent across all nodes. + +- `8001` is the default port on which the Admin API listens. +- `8444` is the default port for HTTPS traffic to the Admin API. + +This API is designed for internal use and provides full control over Kong, so +care should be taken when setting up Kong environments to avoid undue public +exposure of this API. See [this document][secure-admin-api] for a discussion +of methods to secure the Admin API. + +## Supported Content Types + +The Admin API accepts 2 content types on every endpoint: + +- **application/x-www-form-urlencoded** + +Simple enough for basic request bodies, you will probably use it most of the time. +Note that when sending nested values, Kong expects nested objects to be referenced +with dotted keys. Example: + +``` +config.limit=10&config.period=seconds +``` + +Arrays and sets can be specified in various ways: + +1. Sending same parameter multiple times: + ``` + hosts=example.com&hosts=example.org + ``` +2. Using array notation: + ``` + hosts[1]=example.com&hosts[2]=example.org + ``` + or + ``` + hosts[]=example.com&hosts[]=example.org + ``` + Array and object notation can also be mixed: + + ``` + config.hosts[1]=example.com&config.hosts[2]=example.org + ``` + + +- **application/json** + +Handy for complex bodies (ex: complex plugin configuration), in that case simply send +a JSON representation of the data you want to send. Example: + +```json +{ + "config": { + "limit": 10, + "period": "seconds" + } +} +``` + +JSON arrays can be specified as well: + +```json +{ + "config": { + "limit": 10, + "period": "seconds", + "hosts": [ "example.com", "example.org" ] + } +} +``` + +--- + +## Information Routes + + + +### Retrieve Node Information + +Retrieve generic details about a node. + +
/
+
+*Response*
+
+```
+HTTP 200 OK
+```
+
+```json
+{
+ "hostname": "",
+ "node_id": "6a72192c-a3a1-4c8d-95c6-efabae9fb969",
+ "lua_version": "LuaJIT 2.1.0-beta3",
+ "plugins": {
+ "available_on_server": [
+ ...
+ ],
+ "enabled_in_cluster": [
+ ...
+ ]
+ },
+ "configuration" : {
+ ...
+ },
+ "tagline": "Welcome to Kong",
+ "version": "0.14.0"
+}
+```
+
+* `node_id`: A UUID representing the running Kong node. This UUID
+ is randomly generated when Kong starts, so the node will have a
+ different `node_id` each time it is restarted.
+* `available_on_server`: Names of plugins that are installed on the node.
+* `enabled_in_cluster`: Names of plugins that are enabled/configured.
+ That is, the plugins configurations currently in the datastore shared
+ by all Kong nodes.
+
+
+---
+
+### Retrieve Node Status
+
+Retrieve usage information about a node, with some basic information
+about the connections being processed by the underlying nginx process,
+the status of the database connection, and node's memory usage.
+
+If you want to monitor the Kong process, since Kong is built on top
+of nginx, every existing nginx monitoring tool or agent can be used.
+
+
+/status
+
+*Response*
+
+```
+HTTP 200 OK
+```
+
+```json
+{
+ "database": {
+ "reachable": true
+ },
+ "memory": {
+ "workers_lua_vms": [{
+ "http_allocated_gc": "0.02 MiB",
+ "pid": 18477
+ }, {
+ "http_allocated_gc": "0.02 MiB",
+ "pid": 18478
+ }],
+ "lua_shared_dicts": {
+ "kong": {
+ "allocated_slabs": "0.04 MiB",
+ "capacity": "5.00 MiB"
+ },
+ "kong_db_cache": {
+ "allocated_slabs": "0.80 MiB",
+ "capacity": "128.00 MiB"
+ },
+ }
+ },
+ "server": {
+ "total_requests": 3,
+ "connections_active": 1,
+ "connections_accepted": 1,
+ "connections_handled": 1,
+ "connections_reading": 0,
+ "connections_writing": 1,
+ "connections_waiting": 0
+ }
+}
+```
+
+* `memory`: Metrics about the memory usage.
+ * `workers_lua_vms`: An array with all workers of the Kong node, where each
+ entry contains:
+ * `http_allocated_gc`: HTTP submodule's Lua virtual machine's memory
+ usage information, as reported by `collectgarbage("count")`, for every
+ active worker, i.e. a worker that received a proxy call in the last 10
+ seconds.
+ * `pid`: worker's process identification number.
+ * `lua_shared_dicts`: An array of information about dictionaries that are
+ shared with all workers in a Kong node, where each array node contains how
+ much memory is dedicated for the specific shared dictionary (`capacity`)
+ and how much of said memory is in use (`allocated_slabs`).
+ These shared dictionaries have least recent used (LRU) eviction
+ capabilities, so a full dictionary, where `allocated_slabs == capacity`,
+ will work properly. However for some dictionaries, e.g. cache HIT/MISS
+ shared dictionaries, increasing their size can be beneficial for the
+ overall performance of a Kong node.
+ * The memory usage unit and precision can be changed using the querystring
+ arguments `unit` and `scale`:
+ * `unit`: one of `b/B`, `k/K`, `m/M`, `g/G`, which will return results
+ in bytes, kibibytes, mebibytes, or gibibytes, respectively. When
+ "bytes" are requested, the memory values in the response will have a
+ number type instead of string. Defaults to `m`.
+ * `scale`: the number of digits to the right of the decimal points when
+ values are given in human-readable memory strings (unit other than
+ "bytes"). Defaults to `2`.
+ You can get the shared dictionaries memory usage in kibibytes with 4
+ digits of precision by doing: `GET /status?unit=k&scale=4`
+* `server`: Metrics about the nginx HTTP/S server.
+ * `total_requests`: The total number of client requests.
+ * `connections_active`: The current number of active client
+ connections including Waiting connections.
+ * `connections_accepted`: The total number of accepted client
+ connections.
+ * `connections_handled`: The total number of handled connections.
+ Generally, the parameter value is the same as accepts unless
+ some resource limits have been reached.
+ * `connections_reading`: The current number of connections
+ where Kong is reading the request header.
+ * `connections_writing`: The current number of connections
+ where nginx is writing the response back to the client.
+ * `connections_waiting`: The current number of idle client
+ connections waiting for a request.
+* `database`: Metrics about the database.
+ * `reachable`: A boolean value reflecting the state of the
+ database connection. Please note that this flag **does not**
+ reflect the health of the database itself.
+
+
+---
+
+## Tags
+
+Tags are strings associated to entities in Kong. Each tag must be composed of one or more
+alphanumeric characters, `_`, `-`, `.` or `~`.
+
+Most core entities can be *tagged* via their `tags` attribute, upon creation or edition.
+
+Tags can be used to filter core entities as well, via the `?tags` querystring parameter.
+
+For example: if you normally get a list of all the Services by doing:
+
+```
+GET /services
+```
+
+You can get the list of all the Services tagged `example` by doing:
+
+```
+GET /services?tags=example
+```
+
+Similarly, if you want to filter Services so that you only get the ones tagged `example` *and*
+`admin`, you can do that like so:
+
+```
+GET /services?tags=example,admin
+```
+
+Finally, if you wanted to filter the Services tagged `example` *or* `admin`, you could use:
+
+```
+GET /services?tags=example/admin
+```
+
+Some notes:
+
+* A maximum of 5 tags can be queried simultaneously in a single request with `,` or `/`
+* Mixing operators is not supported: if you try to mix `,` with `/` in the same querystring,
+ you will receive an error.
+* You may need to quote and/or escape some characters when using them from the
+ command line.
+* Filtering by `tags` is not supported in foreign key relationship endpoints. For example,
+ the `tags` parameter will be ignored in a request such as `GET /services/foo/routes?tags=a,b`
+* `offset` parameters are not guaranteed to work if the `tags` parameter is altered or removed
+
+
+### List All Tags
+
+Returns a paginated list of all the tags in the system.
+
+The list of entities will not be restricted to a single entity type: all the
+entities tagged with tags will be present on this list.
+
+If an entity is tagged with more than one tag, the `entity_id` for that entity
+will appear more than once in the resulting list. Similarly, if several entities
+have been tagged with the same tag, the tag will appear in several items of this list.
+
+
+/tags
+
+*Response*
+
+```
+HTTP 200 OK
+```
+
+``` json
+{
+ {
+ "data": [
+ { "entity_name": "services",
+ "entity_id": "acf60b10-125c-4c1a-bffe-6ed55daefba4",
+ "tag": "s1",
+ },
+ { "entity_name": "services",
+ "entity_id": "acf60b10-125c-4c1a-bffe-6ed55daefba4",
+ "tag": "s2",
+ },
+ { "entity_name": "routes",
+ "entity_id": "60631e85-ba6d-4c59-bd28-e36dd90f6000",
+ "tag": "s1",
+ },
+ ...
+ ],
+ "offset" = "c47139f3-d780-483d-8a97-17e9adc5a7ab",
+ "next" = "/tags?offset=c47139f3-d780-483d-8a97-17e9adc5a7ab",
+ }
+}
+```
+
+
+---
+
+### List Entity Ids by Tag
+
+Returns the entities that have been tagged with the specified tag.
+
+The list of entities will not be restricted to a single entity type: all the
+entities tagged with tags will be present on this list.
+
+
+/tags/:tags
+
+*Response*
+
+```
+HTTP 200 OK
+```
+
+``` json
+{
+ {
+ "data": [
+ { "entity_name": "services",
+ "entity_id": "c87440e1-0496-420b-b06f-dac59544bb6c",
+ "tag": "example",
+ },
+ { "entity_name": "routes",
+ "entity_id": "8a99e4b1-d268-446b-ab8b-cd25cff129b1",
+ "tag": "example",
+ },
+ ...
+ ],
+ "offset" = "1fb491c4-f4a7-4bca-aeba-7f3bcee4d2f9",
+ "next" = "/tags/example?offset=1fb491c4-f4a7-4bca-aeba-7f3bcee4d2f9",
+ }
+}
+```
+
+
+---
+
+## Service Object
+
+Service entities, as the name implies, are abstractions of each of your own
+upstream services. Examples of Services would be a data transformation
+microservice, a billing API, etc.
+
+The main attribute of a Service is its URL (where Kong should proxy traffic
+to), which can be set as a single string or by specifying its `protocol`,
+`host`, `port` and `path` individually.
+
+Services are associated to Routes (a Service can have many Routes associated
+with it). Routes are entry-points in Kong and define rules to match client
+requests. Once a Route is matched, Kong proxies the request to its associated
+Service. See the [Proxy Reference][proxy-reference] for a detailed explanation
+of how Kong proxies traffic.
+
+Services can be both [tagged and filtered by tags](#tags).
+
+
+```json
+{{ page.service_json }}
+```
+
+### Add Service
+
+##### Create Service
+
+/services
+
+
+*Request Body*
+
+{{ page.service_body }}
+
+
+*Response*
+
+```
+HTTP 201 Created
+```
+
+```json
+{{ page.service_json }}
+```
+
+
+---
+
+### List Services
+
+##### List All Services
+
+/services
+
+
+*Response*
+
+```
+HTTP 200 OK
+```
+
+```json
+{
+{{ page.service_data }}
+ "next": "http://localhost:8001/services?offset=6378122c-a0a1-438d-a5c6-efabae9fb969"
+}
+```
+
+
+---
+
+### Retrieve Service
+
+##### Retrieve Service
+
+/services/{name or id}
+
+Attributes | Description
+---:| ---
+`name or id`**required** | The unique identifier **or** the name of the Service to retrieve. + + +##### Retrieve Service Associated to a Specific Route + +
/routes/{route name or id}/service
+
+Attributes | Description
+---:| ---
+`route name or id`**required** | The unique identifier **or** the name of the Route associated to the Service to be retrieved. + + +##### Retrieve Service Associated to a Specific Plugin + +
/plugins/{plugin id}/service
+
+Attributes | Description
+---:| ---
+`plugin id`**required** | The unique identifier of the Plugin associated to the Service to be retrieved. + + +*Response* + +``` +HTTP 200 OK +``` + +```json +{{ page.service_json }} +``` + + +--- + +### Update Service + +##### Update Service + +
/services/{name or id}
+
+Attributes | Description
+---:| ---
+`name or id`**required** | The unique identifier **or** the name of the Service to update. + + +##### Update Service Associated to a Specific Route + +
/routes/{route name or id}/service
+
+Attributes | Description
+---:| ---
+`route name or id`**required** | The unique identifier **or** the name of the Route associated to the Service to be updated. + + +##### Update Service Associated to a Specific Plugin + +
/plugins/{plugin id}/service
+
+Attributes | Description
+---:| ---
+`plugin id`**required** | The unique identifier of the Plugin associated to the Service to be updated. + + +*Request Body* + +{{ page.service_body }} + + +*Response* + +``` +HTTP 200 OK +``` + +```json +{{ page.service_json }} +``` + + +--- + +### Update Or Create Service + +##### Create Or Update Service + +
/services/{name or id}
+
+Attributes | Description
+---:| ---
+`name or id`**required** | The unique identifier **or** the name of the Service to create or update. + + +##### Create Or Update Service Associated to a Specific Route + +
/routes/{route name or id}/service
+
+Attributes | Description
+---:| ---
+`route name or id`**required** | The unique identifier **or** the name of the Route associated to the Service to be created or updated. + + +##### Create Or Update Service Associated to a Specific Plugin + +
/plugins/{plugin id}/service
+
+Attributes | Description
+---:| ---
+`plugin id`**required** | The unique identifier of the Plugin associated to the Service to be created or updated. + + +*Request Body* + +{{ page.service_body }} + + +Inserts (or replaces) the Service under the requested resource with the +definition specified in the body. The Service will be identified via the `name +or id` attribute. + +When the `name or id` attribute has the structure of a UUID, the Service being +inserted/replaced will be identified by its `id`. Otherwise it will be +identified by its `name`. + +When creating a new Service without specifying `id` (neither in the URL nor in +the body), then it will be auto-generated. + +Notice that specifying a `name` in the URL and a different one in the request +body is not allowed. + + +*Response* + +``` +HTTP 201 Created or HTTP 200 OK +``` + +See POST and PATCH responses. + + +--- + +### Delete Service + +##### Delete Service + +
/services/{name or id}
+
+Attributes | Description
+---:| ---
+`name or id`**required** | The unique identifier **or** the name of the Service to delete. + + +##### Delete Service Associated to a Specific Route + +
/routes/{route name or id}/service
+
+Attributes | Description
+---:| ---
+`route name or id`**required** | The unique identifier **or** the name of the Route associated to the Service to be deleted. + + +*Response* + +``` +HTTP 204 No Content +``` + + +--- + +## Route Object + +Route entities define rules to match client requests. Each Route is +associated with a Service, and a Service may have multiple Routes associated to +it. Every request matching a given Route will be proxied to its associated +Service. + +The combination of Routes and Services (and the separation of concerns between +them) offers a powerful routing mechanism with which it is possible to define +fine-grained entry-points in Kong leading to different upstream services of +your infrastructure. + +Routes can be both [tagged and filtered by tags](#tags). + + +```json +{{ page.route_json }} +``` + +### Add Route + +##### Create Route + +
/routes
+
+
+##### Create Route Associated to a Specific Service
+
+/services/{service name or id}/routes
+
+Attributes | Description
+---:| ---
+`service name or id`**required** | The unique identifier or the `name` attribute of the Service that should be associated to the newly-created Route. + + +*Request Body* + +{{ page.route_body }} + + +*Response* + +``` +HTTP 201 Created +``` + +```json +{{ page.route_json }} +``` + + +--- + +### List Routes + +##### List All Routes + +
/routes
+
+
+##### List Routes Associated to a Specific Service
+
+/services/{service name or id}/routes
+
+Attributes | Description
+---:| ---
+`service name or id`**required** | The unique identifier or the `name` attribute of the Service whose Routes are to be retrieved. When using this endpoint, only Routes associated to the specified Service will be listed. + + +*Response* + +``` +HTTP 200 OK +``` + +```json +{ +{{ page.route_data }} + "next": "http://localhost:8001/routes?offset=6378122c-a0a1-438d-a5c6-efabae9fb969" +} +``` + + +--- + +### Retrieve Route + +##### Retrieve Route + +
/routes/{name or id}
+
+Attributes | Description
+---:| ---
+`name or id`**required** | The unique identifier **or** the name of the Route to retrieve. + + +##### Retrieve Route Associated to a Specific Plugin + +
/plugins/{plugin id}/route
+
+Attributes | Description
+---:| ---
+`plugin id`**required** | The unique identifier of the Plugin associated to the Route to be retrieved. + + +*Response* + +``` +HTTP 200 OK +``` + +```json +{{ page.route_json }} +``` + + +--- + +### Update Route + +##### Update Route + +
/routes/{name or id}
+
+Attributes | Description
+---:| ---
+`name or id`**required** | The unique identifier **or** the name of the Route to update. + + +##### Update Route Associated to a Specific Plugin + +
/plugins/{plugin id}/route
+
+Attributes | Description
+---:| ---
+`plugin id`**required** | The unique identifier of the Plugin associated to the Route to be updated. + + +*Request Body* + +{{ page.route_body }} + + +*Response* + +``` +HTTP 200 OK +``` + +```json +{{ page.route_json }} +``` + + +--- + +### Update Or Create Route + +##### Create Or Update Route + +
/routes/{name or id}
+
+Attributes | Description
+---:| ---
+`name or id`**required** | The unique identifier **or** the name of the Route to create or update. + + +##### Create Or Update Route Associated to a Specific Plugin + +
/plugins/{plugin id}/route
+
+Attributes | Description
+---:| ---
+`plugin id`**required** | The unique identifier of the Plugin associated to the Route to be created or updated. + + +*Request Body* + +{{ page.route_body }} + + +Inserts (or replaces) the Route under the requested resource with the +definition specified in the body. The Route will be identified via the `name +or id` attribute. + +When the `name or id` attribute has the structure of a UUID, the Route being +inserted/replaced will be identified by its `id`. Otherwise it will be +identified by its `name`. + +When creating a new Route without specifying `id` (neither in the URL nor in +the body), then it will be auto-generated. + +Notice that specifying a `name` in the URL and a different one in the request +body is not allowed. + + +*Response* + +``` +HTTP 201 Created or HTTP 200 OK +``` + +See POST and PATCH responses. + + +--- + +### Delete Route + +##### Delete Route + +
/routes/{name or id}
+
+Attributes | Description
+---:| ---
+`name or id`**required** | The unique identifier **or** the name of the Route to delete. + + +*Response* + +``` +HTTP 204 No Content +``` + + +--- + +## Consumer Object + +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. + +Consumers can be both [tagged and filtered by tags](#tags). + + +```json +{{ page.consumer_json }} +``` + +### Add Consumer + +##### Create Consumer + +
/consumers
+
+
+*Request Body*
+
+{{ page.consumer_body }}
+
+
+*Response*
+
+```
+HTTP 201 Created
+```
+
+```json
+{{ page.consumer_json }}
+```
+
+
+---
+
+### List Consumers
+
+##### List All Consumers
+
+/consumers
+
+
+*Response*
+
+```
+HTTP 200 OK
+```
+
+```json
+{
+{{ page.consumer_data }}
+ "next": "http://localhost:8001/consumers?offset=6378122c-a0a1-438d-a5c6-efabae9fb969"
+}
+```
+
+
+---
+
+### Retrieve Consumer
+
+##### Retrieve Consumer
+
+/consumers/{username or id}
+
+Attributes | Description
+---:| ---
+`username or id`**required** | The unique identifier **or** the username of the Consumer to retrieve. + + +##### Retrieve Consumer Associated to a Specific Plugin + +
/plugins/{plugin id}/consumer
+
+Attributes | Description
+---:| ---
+`plugin id`**required** | The unique identifier of the Plugin associated to the Consumer to be retrieved. + + +*Response* + +``` +HTTP 200 OK +``` + +```json +{{ page.consumer_json }} +``` + + +--- + +### Update Consumer + +##### Update Consumer + +
/consumers/{username or id}
+
+Attributes | Description
+---:| ---
+`username or id`**required** | The unique identifier **or** the username of the Consumer to update. + + +##### Update Consumer Associated to a Specific Plugin + +
/plugins/{plugin id}/consumer
+
+Attributes | Description
+---:| ---
+`plugin id`**required** | The unique identifier of the Plugin associated to the Consumer to be updated. + + +*Request Body* + +{{ page.consumer_body }} + + +*Response* + +``` +HTTP 200 OK +``` + +```json +{{ page.consumer_json }} +``` + + +--- + +### Update Or Create Consumer + +##### Create Or Update Consumer + +
/consumers/{username or id}
+
+Attributes | Description
+---:| ---
+`username or id`**required** | The unique identifier **or** the username of the Consumer to create or update. + + +##### Create Or Update Consumer Associated to a Specific Plugin + +
/plugins/{plugin id}/consumer
+
+Attributes | Description
+---:| ---
+`plugin id`**required** | The unique identifier of the Plugin associated to the Consumer to be created or updated. + + +*Request Body* + +{{ page.consumer_body }} + + +Inserts (or replaces) the Consumer under the requested resource with the +definition specified in the body. The Consumer will be identified via the `username +or id` attribute. + +When the `username or id` attribute has the structure of a UUID, the Consumer being +inserted/replaced will be identified by its `id`. Otherwise it will be +identified by its `username`. + +When creating a new Consumer without specifying `id` (neither in the URL nor in +the body), then it will be auto-generated. + +Notice that specifying a `username` in the URL and a different one in the request +body is not allowed. + + +*Response* + +``` +HTTP 201 Created or HTTP 200 OK +``` + +See POST and PATCH responses. + + +--- + +### Delete Consumer + +##### Delete Consumer + +
/consumers/{username or id}
+
+Attributes | Description
+---:| ---
+`username or id`**required** | The unique identifier **or** the username of the Consumer to delete. + + +*Response* + +``` +HTTP 204 No Content +``` + + +--- + +## Plugin Object + +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. You can find more information about how to install and what values +each plugin takes by visiting the [Kong Hub](https://docs.konghq.com/hub/). + +When adding a Plugin Configuration to a Service, every request made by a client to +that Service will run said Plugin. If a Plugin needs to be tuned to different +values for some specific Consumers, you can do so by creating a separate +plugin instance that specifies both the Service and the Consumer, through the +`service` and `consumer` fields. + +Plugins can be both [tagged and filtered by tags](#tags). + + +```json +{{ page.plugin_json }} +``` + +See the [Precedence](#precedence) section below for more details. + +#### Precedence + +A plugin will always be run once and only once per request. But the +configuration with which it will run depends on the entities it has been +configured for. + +Plugins can be configured for various entities, combination of entities, or +even globally. This is useful, for example, when you wish to configure a plugin +a certain way for most requests, but make _authenticated requests_ behave +slightly differently. + +Therefore, there exists an order of precedence for running a plugin when it has +been applied to different entities with different configurations. The rule of +thumb is: the more specific a plugin is with regards to how many entities it +has been configured on, the higher its priority. + +The complete order of precedence when a plugin has been configured multiple +times is: + +1. Plugins configured on a combination of: a Route, a Service, and a Consumer. + (Consumer means the request must be authenticated). +2. Plugins configured on a combination of a Route and a Consumer. + (Consumer means the request must be authenticated). +3. Plugins configured on a combination of a Service and a Consumer. + (Consumer means the request must be authenticated). +4. Plugins configured on a combination of a Route and a Service. +5. Plugins configured on a Consumer. + (Consumer means the request must be authenticated). +6. Plugins configured on a Route. +7. Plugins configured on a Service. +8. Plugins configured to run globally. + +**Example**: if the `rate-limiting` plugin is applied twice (with different +configurations): for a Service (Plugin config A), and for a Consumer (Plugin +config B), then requests authenticating this Consumer will run Plugin config B +and ignore A. However, requests that do not authenticate this Consumer will +fallback to running Plugin config A. Note that if config B is disabled +(its `enabled` flag is set to `false`), config A will apply to requests that +would have otherwise matched config B. + + +### Add Plugin + +##### Create Plugin + +
/plugins
+
+
+##### Create Plugin Associated to a Specific Route
+
+/routes/{route id}/plugins
+
+Attributes | Description
+---:| ---
+`route id`**required** | The unique identifier of the Route that should be associated to the newly-created Plugin. + + +##### Create Plugin Associated to a Specific Service + +
/services/{service id}/plugins
+
+Attributes | Description
+---:| ---
+`service id`**required** | The unique identifier of the Service that should be associated to the newly-created Plugin. + + +##### Create Plugin Associated to a Specific Consumer + +
/consumers/{consumer id}/plugins
+
+Attributes | Description
+---:| ---
+`consumer id`**required** | The unique identifier of the Consumer that should be associated to the newly-created Plugin. + + +*Request Body* + +{{ page.plugin_body }} + + +*Response* + +``` +HTTP 201 Created +``` + +```json +{{ page.plugin_json }} +``` + + +--- + +### List Plugins + +##### List All Plugins + +
/plugins
+
+
+##### List Plugins Associated to a Specific Route
+
+/routes/{route id}/plugins
+
+Attributes | Description
+---:| ---
+`route id`**required** | The unique identifier of the Route whose Plugins are to be retrieved. When using this endpoint, only Plugins associated to the specified Route will be listed. + + +##### List Plugins Associated to a Specific Service + +
/services/{service id}/plugins
+
+Attributes | Description
+---:| ---
+`service id`**required** | The unique identifier of the Service whose Plugins are to be retrieved. When using this endpoint, only Plugins associated to the specified Service will be listed. + + +##### List Plugins Associated to a Specific Consumer + +
/consumers/{consumer id}/plugins
+
+Attributes | Description
+---:| ---
+`consumer id`**required** | The unique identifier of the Consumer whose Plugins are to be retrieved. When using this endpoint, only Plugins associated to the specified Consumer will be listed. + + +*Response* + +``` +HTTP 200 OK +``` + +```json +{ +{{ page.plugin_data }} + "next": "http://localhost:8001/plugins?offset=6378122c-a0a1-438d-a5c6-efabae9fb969" +} +``` + + +--- + +### Retrieve Plugin + +##### Retrieve Plugin + +
/plugins/{plugin id}
+
+Attributes | Description
+---:| ---
+`plugin id`**required** | The unique identifier of the Plugin to retrieve. + + +*Response* + +``` +HTTP 200 OK +``` + +```json +{{ page.plugin_json }} +``` + + +--- + +### Update Plugin + +##### Update Plugin + +
/plugins/{plugin id}
+
+Attributes | Description
+---:| ---
+`plugin id`**required** | The unique identifier of the Plugin to update. + + +*Request Body* + +{{ page.plugin_body }} + + +*Response* + +``` +HTTP 200 OK +``` + +```json +{{ page.plugin_json }} +``` + + +--- + +### Update Or Create Plugin + +##### Create Or Update Plugin + +
/plugins/{plugin id}
+
+Attributes | Description
+---:| ---
+`plugin id`**required** | The unique identifier of the Plugin to create or update. + + +*Request Body* + +{{ page.plugin_body }} + + +Inserts (or replaces) the Plugin under the requested resource with the +definition specified in the body. The Plugin will be identified via the `name +or id` attribute. + +When the `name or id` attribute has the structure of a UUID, the Plugin being +inserted/replaced will be identified by its `id`. Otherwise it will be +identified by its `name`. + +When creating a new Plugin without specifying `id` (neither in the URL nor in +the body), then it will be auto-generated. + +Notice that specifying a `name` in the URL and a different one in the request +body is not allowed. + + +*Response* + +``` +HTTP 201 Created or HTTP 200 OK +``` + +See POST and PATCH responses. + + +--- + +### Delete Plugin + +##### Delete Plugin + +
/plugins/{plugin id}
+
+Attributes | Description
+---:| ---
+`plugin id`**required** | The unique identifier of the Plugin to delete. + + +*Response* + +``` +HTTP 204 No Content +``` + + +--- + +### Retrieve Enabled Plugins + +Retrieve a list of all installed plugins on the Kong node. + +
/plugins/enabled
+
+*Response*
+
+```
+HTTP 200 OK
+```
+
+```json
+{
+ "enabled_plugins": [
+ "jwt",
+ "acl",
+ "cors",
+ "oauth2",
+ "tcp-log",
+ "udp-log",
+ "file-log",
+ "http-log",
+ "key-auth",
+ "hmac-auth",
+ "basic-auth",
+ "ip-restriction",
+ "request-transformer",
+ "response-transformer",
+ "request-size-limiting",
+ "rate-limiting",
+ "response-ratelimiting",
+ "aws-lambda",
+ "bot-detection",
+ "correlation-id",
+ "datadog",
+ "galileo",
+ "ldap-auth",
+ "loggly",
+ "statsd",
+ "syslog"
+ ]
+}
+```
+
+
+---
+
+### Retrieve Plugin Schema
+
+Retrieve the schema of a plugin's configuration. This is useful to
+understand what fields a plugin accepts, and can be used for building
+third-party integrations to the Kong's plugin system.
+
+
+/plugins/schema/{plugin name}
+
+*Response*
+
+```
+HTTP 200 OK
+```
+
+```json
+{
+ "fields": {
+ "hide_credentials": {
+ "default": false,
+ "type": "boolean"
+ },
+ "key_names": {
+ "default": "function",
+ "required": true,
+ "type": "array"
+ }
+ }
+}
+```
+
+
+---
+
+## Certificate Object
+
+A certificate object represents a public certificate, and can be optionally paired with the
+corresponding private key. These objects are used by Kong to handle SSL/TLS termination for
+encrypted requests, or for use as a trusted CA store when validating peer certificate of
+client/service. Certificates are optionally associated with SNI objects to
+tie a cert/key pair to one or more hostnames.
+
+Certificates can be both [tagged and filtered by tags](#tags).
+
+
+```json
+{{ page.certificate_json }}
+```
+
+### Add Certificate
+
+##### Create Certificate
+
+/certificates
+
+
+*Request Body*
+
+{{ page.certificate_body }}
+
+
+*Response*
+
+```
+HTTP 201 Created
+```
+
+```json
+{{ page.certificate_json }}
+```
+
+
+---
+
+### List Certificates
+
+##### List All Certificates
+
+/certificates
+
+
+*Response*
+
+```
+HTTP 200 OK
+```
+
+```json
+{
+{{ page.certificate_data }}
+ "next": "http://localhost:8001/certificates?offset=6378122c-a0a1-438d-a5c6-efabae9fb969"
+}
+```
+
+
+---
+
+### Retrieve Certificate
+
+##### Retrieve Certificate
+
+/certificates/{certificate id}
+
+Attributes | Description
+---:| ---
+`certificate id`**required** | The unique identifier of the Certificate to retrieve. + + +*Response* + +``` +HTTP 200 OK +``` + +```json +{{ page.certificate_json }} +``` + + +--- + +### Update Certificate + +##### Update Certificate + +
/certificates/{certificate id}
+
+Attributes | Description
+---:| ---
+`certificate id`**required** | The unique identifier of the Certificate to update. + + +*Request Body* + +{{ page.certificate_body }} + + +*Response* + +``` +HTTP 200 OK +``` + +```json +{{ page.certificate_json }} +``` + + +--- + +### Update Or Create Certificate + +##### Create Or Update Certificate + +
/certificates/{certificate id}
+
+Attributes | Description
+---:| ---
+`certificate id`**required** | The unique identifier of the Certificate to create or update. + + +*Request Body* + +{{ page.certificate_body }} + + +Inserts (or replaces) the Certificate under the requested resource with the +definition specified in the body. The Certificate will be identified via the `name +or id` attribute. + +When the `name or id` attribute has the structure of a UUID, the Certificate being +inserted/replaced will be identified by its `id`. Otherwise it will be +identified by its `name`. + +When creating a new Certificate without specifying `id` (neither in the URL nor in +the body), then it will be auto-generated. + +Notice that specifying a `name` in the URL and a different one in the request +body is not allowed. + + +*Response* + +``` +HTTP 201 Created or HTTP 200 OK +``` + +See POST and PATCH responses. + + +--- + +### Delete Certificate + +##### Delete Certificate + +
/certificates/{certificate id}
+
+Attributes | Description
+---:| ---
+`certificate id`**required** | The unique identifier of the Certificate to delete. + + +*Response* + +``` +HTTP 204 No Content +``` + + +--- + +## SNI Object + +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. + +SNIs can be both [tagged and filtered by tags](#tags). + + +```json +{{ page.sni_json }} +``` + +### Add SNI + +##### Create SNI + +
/snis
+
+
+##### Create SNI Associated to a Specific Certificate
+
+/certificates/{certificate name or id}/snis
+
+Attributes | Description
+---:| ---
+`certificate name or id`**required** | The unique identifier or the `name` attribute of the Certificate that should be associated to the newly-created SNI. + + +*Request Body* + +{{ page.sni_body }} + + +*Response* + +``` +HTTP 201 Created +``` + +```json +{{ page.sni_json }} +``` + + +--- + +### List SNIs + +##### List All SNIs + +
/snis
+
+
+##### List SNIs Associated to a Specific Certificate
+
+/certificates/{certificate name or id}/snis
+
+Attributes | Description
+---:| ---
+`certificate name or id`**required** | The unique identifier or the `name` attribute of the Certificate whose SNIs are to be retrieved. When using this endpoint, only SNIs associated to the specified Certificate will be listed. + + +*Response* + +``` +HTTP 200 OK +``` + +```json +{ +{{ page.sni_data }} + "next": "http://localhost:8001/snis?offset=6378122c-a0a1-438d-a5c6-efabae9fb969" +} +``` + + +--- + +### Retrieve SNI + +##### Retrieve SNI + +
/snis/{name or id}
+
+Attributes | Description
+---:| ---
+`name or id`**required** | The unique identifier **or** the name of the SNI to retrieve. + + +*Response* + +``` +HTTP 200 OK +``` + +```json +{{ page.sni_json }} +``` + + +--- + +### Update SNI + +##### Update SNI + +
/snis/{name or id}
+
+Attributes | Description
+---:| ---
+`name or id`**required** | The unique identifier **or** the name of the SNI to update. + + +*Request Body* + +{{ page.sni_body }} + + +*Response* + +``` +HTTP 200 OK +``` + +```json +{{ page.sni_json }} +``` + + +--- + +### Update Or Create SNI + +##### Create Or Update SNI + +
/snis/{name or id}
+
+Attributes | Description
+---:| ---
+`name or id`**required** | The unique identifier **or** the name of the SNI to create or update. + + +*Request Body* + +{{ page.sni_body }} + + +Inserts (or replaces) the SNI under the requested resource with the +definition specified in the body. The SNI will be identified via the `name +or id` attribute. + +When the `name or id` attribute has the structure of a UUID, the SNI being +inserted/replaced will be identified by its `id`. Otherwise it will be +identified by its `name`. + +When creating a new SNI without specifying `id` (neither in the URL nor in +the body), then it will be auto-generated. + +Notice that specifying a `name` in the URL and a different one in the request +body is not allowed. + + +*Response* + +``` +HTTP 201 Created or HTTP 200 OK +``` + +See POST and PATCH responses. + + +--- + +### Delete SNI + +##### Delete SNI + +
/snis/{name or id}
+
+Attributes | Description
+---:| ---
+`name or id`**required** | The unique identifier **or** the name of the SNI to delete. + + +*Response* + +``` +HTTP 204 No Content +``` + +--- + +## Certificate Authority Object + +A certificate authority object represents a public CA certificate. +These objects are used by Kong to verify client certificates presented to the mTLS plugin. + + +```json +{{ page.certificate_authority_json }} +``` + +### Add Certificate Authority + +##### Create Certificate Authority + +
/ca_certificates
+
+
+*Request Body*
+
+{{ page.certificate_authority_body }}
+
+
+*Response*
+
+```
+HTTP 201 Created
+```
+
+```json
+{{ page.certificate_authority_json }}
+```
+
+
+---
+
+### List Certificate Authorities
+
+##### List all Certificate Authorities
+
+/ca_certificates
+
+
+*Response*
+
+```
+HTTP 200 OK
+```
+
+```json
+{
+{{ page.certificate_authority_data }}
+ "next": "http://localhost:8001/ca_certificates?offset=6378122c-a0a1-438d-a5c6-efabae9fb969"
+}
+```
+
+
+---
+
+### Retrieve Certificate Authority
+
+##### Retrieve Certificate Authority
+
+/ca_certificates/{certificate authority id}
+
+Attributes | Description
+---:| ---
+`certificate authority id`**required** | The unique identifier of the certificate authority to retrieve. + + +*Response* + +``` +HTTP 200 OK +``` + +```json +{{ page.certificate_authority_json }} +``` + + +--- + +### Update Certificate Authority + +##### Update Certificate Authority + +
/ca_certificates/{certificate authority id}
+
+Attributes | Description
+---:| ---
+`certificate authority id`**required** | The unique identifier of the certificate authority to update. + + +*Request Body* + +{{ page.certificate_authority_body }} + + +*Response* + +``` +HTTP 200 OK +``` + +```json +{{ page.certificate_authority_json }} +``` + + +--- + +### Update or create Certificate Authority + +##### Create or update Certificate Authority + +
/ca_certificates/{certificate authority id}
+
+Attributes | Description
+---:| ---
+`certificate authority id`**required** | The unique identifier of the certificate authority to create or update. + + +*Request Body* + +{{ page.certificate_authority_body }} + + +Inserts (or replaces) the certificate authority under the requested resource with the +definition specified in the body. The certificate authority will be identified via the ` id` attribute. + +When creating a new certificate authority without specifying `id` (neither in the URL nor in +the body), then it will be auto-generated. + + +*Response* + +``` +HTTP 201 Created or HTTP 200 OK +``` + +See POST and PATCH responses. + + +--- + +### Delete Certificate Authority + +##### Delete Certificate Authority + +
/ca_certificates/{certificate authority id}
+
+Attributes | Description
+---:| ---
+`certificate authority id`**required** | The unique identifier of the certificate authority to delete. + + +*Response* + +``` +HTTP 204 No Content +``` + + + +--- + +## Upstream Object + +The upstream object represents a virtual hostname and can be used to loadbalance +incoming requests over multiple services (targets). So for example an upstream +named `service.v1.xyz` for a Service object whose `host` is `service.v1.xyz`. +Requests for this Service would be proxied to the targets defined within the upstream. + +An upstream also includes a [health checker][healthchecks], which is able to +enable and disable targets based on their ability or inability to serve +requests. The configuration for the health checker is stored in the upstream +object, and applies to all of its targets. + +Upstreams can be both [tagged and filtered by tags](#tags). + + +```json +{{ page.upstream_json }} +``` + +### Add Upstream + +##### Create Upstream + +
/upstreams
+
+
+*Request Body*
+
+{{ page.upstream_body }}
+
+
+*Response*
+
+```
+HTTP 201 Created
+```
+
+```json
+{{ page.upstream_json }}
+```
+
+
+---
+
+### List Upstreams
+
+##### List All Upstreams
+
+/upstreams
+
+
+*Response*
+
+```
+HTTP 200 OK
+```
+
+```json
+{
+{{ page.upstream_data }}
+ "next": "http://localhost:8001/upstreams?offset=6378122c-a0a1-438d-a5c6-efabae9fb969"
+}
+```
+
+
+---
+
+### Retrieve Upstream
+
+##### Retrieve Upstream
+
+/upstreams/{name or id}
+
+Attributes | Description
+---:| ---
+`name or id`**required** | The unique identifier **or** the name of the Upstream to retrieve. + + +##### Retrieve Upstream Associated to a Specific Target + +
/targets/{target host:port or id}/upstream
+
+Attributes | Description
+---:| ---
+`target host:port or id`**required** | The unique identifier **or** the host:port of the Target associated to the Upstream to be retrieved. + + +*Response* + +``` +HTTP 200 OK +``` + +```json +{{ page.upstream_json }} +``` + + +--- + +### Update Upstream + +##### Update Upstream + +
/upstreams/{name or id}
+
+Attributes | Description
+---:| ---
+`name or id`**required** | The unique identifier **or** the name of the Upstream to update. + + +##### Update Upstream Associated to a Specific Target + +
/targets/{target host:port or id}/upstream
+
+Attributes | Description
+---:| ---
+`target host:port or id`**required** | The unique identifier **or** the host:port of the Target associated to the Upstream to be updated. + + +*Request Body* + +{{ page.upstream_body }} + + +*Response* + +``` +HTTP 200 OK +``` + +```json +{{ page.upstream_json }} +``` + + +--- + +### Update Or Create Upstream + +##### Create Or Update Upstream + +
/upstreams/{name or id}
+
+Attributes | Description
+---:| ---
+`name or id`**required** | The unique identifier **or** the name of the Upstream to create or update. + + +##### Create Or Update Upstream Associated to a Specific Target + +
/targets/{target host:port or id}/upstream
+
+Attributes | Description
+---:| ---
+`target host:port or id`**required** | The unique identifier **or** the host:port of the Target associated to the Upstream to be created or updated. + + +*Request Body* + +{{ page.upstream_body }} + + +Inserts (or replaces) the Upstream under the requested resource with the +definition specified in the body. The Upstream will be identified via the `name +or id` attribute. + +When the `name or id` attribute has the structure of a UUID, the Upstream being +inserted/replaced will be identified by its `id`. Otherwise it will be +identified by its `name`. + +When creating a new Upstream without specifying `id` (neither in the URL nor in +the body), then it will be auto-generated. + +Notice that specifying a `name` in the URL and a different one in the request +body is not allowed. + + +*Response* + +``` +HTTP 201 Created or HTTP 200 OK +``` + +See POST and PATCH responses. + + +--- + +### Delete Upstream + +##### Delete Upstream + +
/upstreams/{name or id}
+
+Attributes | Description
+---:| ---
+`name or id`**required** | The unique identifier **or** the name of the Upstream to delete. + + +##### Delete Upstream Associated to a Specific Target + +
/targets/{target host:port or id}/upstream
+
+Attributes | Description
+---:| ---
+`target host:port or id`**required** | The unique identifier **or** the host:port of the Target associated to the Upstream to be deleted. + + +*Response* + +``` +HTTP 204 No Content +``` + + +--- + +### Show Upstream Health for Node + +Displays the health status for all Targets of a given Upstream, according to +the perspective of a specific Kong node. Note that, being node-specific +information, making this same request to different nodes of the Kong cluster +may produce different results. For example, one specific node of the Kong +cluster may be experiencing network issues, causing it to fail to connect to +some Targets: these Targets will be marked as unhealthy by that node +(directing traffic from this node to other Targets that it can successfully +reach), but healthy to all others Kong nodes (which have no problems using that +Target). + +The `data` field of the response contains an array of Target objects. +The health for each Target is returned in its `health` field: + +* If a Target fails to be activated in the ring balancer due to DNS issues, + its status displays as `DNS_ERROR`. +* When [health checks][healthchecks] are not enabled in the Upstream + configuration, the health status for active Targets is displayed as + `HEALTHCHECKS_OFF`. +* When health checks are enabled and the Target is determined to be healthy, + either automatically or [manually](#set-target-as-healthy), + its status is displayed as `HEALTHY`. This means that this Target is + currently included in this Upstream's load balancer ring. +* When a Target has been disabled by either active or passive health checks + (circuit breakers) or [manually](#set-target-as-unhealthy), + its status is displayed as `UNHEALTHY`. The load balancer is not directing + any traffic to this Target via this Upstream. + + +
/upstreams/{name or id}/health/
+
+Attributes | Description
+---:| ---
+`name or id`**required** | The unique identifier **or** the name of the Upstream for which to display Target health. + + +*Response* + +``` +HTTP 200 OK +``` + +```json +{ + "total": 2, + "node_id": "cbb297c0-14a9-46bc-ad91-1d0ef9b42df9", + "data": [ + { + "created_at": 1485524883980, + "id": "18c0ad90-f942-4098-88db-bbee3e43b27f", + "health": "HEALTHY", + "target": "127.0.0.1:20000", + "upstream_id": "07131005-ba30-4204-a29f-0927d53257b4", + "weight": 100 + }, + { + "created_at": 1485524914883, + "id": "6c6f34eb-e6c3-4c1f-ac58-4060e5bca890", + "health": "UNHEALTHY", + "target": "127.0.0.1:20002", + "upstream_id": "07131005-ba30-4204-a29f-0927d53257b4", + "weight": 200 + } + ] +} +``` + + +--- + +## Target Object + +A target is an ip address/hostname with a port that identifies an instance of a backend +service. Every upstream can have many targets, and the targets can be +dynamically added. Changes are effectuated on the fly. + +Because the upstream maintains a history of target changes, the targets cannot +be deleted or modified. To disable a target, post a new one with `weight=0`; +alternatively, use the `DELETE` convenience method to accomplish the same. + +The current target object definition is the one with the latest `created_at`. + +Targets can be both [tagged and filtered by tags](#tags). + + +```json +{{ page.target_json }} +``` + +### Add Target + +##### Create Target Associated to a Specific Upstream + +
/upstreams/{upstream host:port or id}/targets
+
+Attributes | Description
+---:| ---
+`upstream host:port or id`**required** | The unique identifier or the `host:port` attribute of the Upstream that should be associated to the newly-created Target. + + +*Request Body* + +{{ page.target_body }} + + +*Response* + +``` +HTTP 201 Created +``` + +```json +{{ page.target_json }} +``` + + +--- + +### List Targets + +##### List Targets Associated to a Specific Upstream + +
/upstreams/{upstream host:port or id}/targets
+
+Attributes | Description
+---:| ---
+`upstream host:port or id`**required** | The unique identifier or the `host:port` attribute of the Upstream whose Targets are to be retrieved. When using this endpoint, only Targets associated to the specified Upstream will be listed. + + +*Response* + +``` +HTTP 200 OK +``` + +```json +{ +{{ page.target_data }} + "next": "http://localhost:8001/targets?offset=6378122c-a0a1-438d-a5c6-efabae9fb969" +} +``` + + +--- + +### Delete Target + +Disable a target in the load balancer. Under the hood, this method creates +a new entry for the given target definition with a `weight` of 0. + + +
/upstreams/{upstream name or id}/targets/{host:port or id}
+
+Attributes | Description
+---:| ---
+`upstream name or id`**required** | The unique identifier **or** the name of the upstream for which to delete the target. +`host:port or id`
**required** | The host:port combination element of the target to remove, or the `id` of an existing target entry. + + +*Response* + +``` +HTTP 204 No Content +``` + + +--- + +### Set Target As Healthy + +Set the current health status of a target in the load balancer to "healthy" +in the entire Kong cluster. + +This endpoint can be used to manually re-enable a target that was previously +disabled by the upstream's [health checker][healthchecks]. Upstreams only +forward requests to healthy nodes, so this call tells Kong to start using this +target again. + +This resets the health counters of the health checkers running in all workers +of the Kong node, and broadcasts a cluster-wide message so that the "healthy" +status is propagated to the whole Kong cluster. + + +
/upstreams/{upstream name or id}/targets/{target or id}/healthy
+
+Attributes | Description
+---:| ---
+`upstream name or id`**required** | The unique identifier **or** the name of the upstream. +`target or id`
**required** | The host/port combination element of the target to set as healthy, or the `id` of an existing target entry. + + +*Response* + +``` +HTTP 204 No Content +``` + + +--- + +### Set Target As Unhealthy + +Set the current health status of a target in the load balancer to "unhealthy" +in the entire Kong cluster. + +This endpoint can be used to manually disable a target and have it stop +responding to requests. Upstreams only forward requests to healthy nodes, so +this call tells Kong to start skipping this target in the ring-balancer +algorithm. + +This call resets the health counters of the health checkers running in all +workers of the Kong node, and broadcasts a cluster-wide message so that the +"unhealthy" status is propagated to the whole Kong cluster. + +[Active health checks][active] continue to execute for unhealthy +targets. Note that if active health checks are enabled and the probe detects +that the target is actually healthy, it will automatically re-enable it again. +To permanently remove a target from the ring-balancer, you should [delete a +target](#delete-target) instead. + + +
/upstreams/{upstream name or id}/targets/{target or id}/unhealthy
+
+Attributes | Description
+---:| ---
+`upstream name or id`**required** | The unique identifier **or** the name of the upstream. +`target or id`
**required** | The host/port combination element of the target to set as unhealthy, or the `id` of an existing target entry. + + +*Response* + +``` +HTTP 204 No Content +``` + + +--- + +### List All Targets + +Lists all targets of the upstream. Multiple target objects for the same +target may be returned, showing the history of changes for a specific target. +The target object with the latest `created_at` is the current definition. + + +
/upstreams/{name or id}/targets/all/
+
+Attributes | Description
+---:| ---
+`name or id`**required** | The unique identifier **or** the name of the upstream for which to list the targets. + + +*Response* + +``` +HTTP 200 OK +``` + +```json +{ + "total": 2, + "data": [ + { + "created_at": 1485524883980, + "id": "18c0ad90-f942-4098-88db-bbee3e43b27f", + "target": "127.0.0.1:20000", + "upstream_id": "07131005-ba30-4204-a29f-0927d53257b4", + "weight": 100 + }, + { + "created_at": 1485524914883, + "id": "6c6f34eb-e6c3-4c1f-ac58-4060e5bca890", + "target": "127.0.0.1:20002", + "upstream_id": "07131005-ba30-4204-a29f-0927d53257b4", + "weight": 200 + } + ] +} +``` + +## Enterprise Exclusive Admin API + +
+
+
+
+
+
+ 
+
+
+ The following documentation refers to Kong Enterprise specific Admin API functionality. For a complete reference checkout the Kong Admin API Reference.
+
+
+
+---
+
+[clustering]: /enterprise/{{page.kong_version}}/clustering
+[cli]: /enterprise/{{page.kong_version}}/cli
+[active]: /enterprise/{{page.kong_version}}/health-checks-circuit-breakers/#active-health-checks
+[healthchecks]: /enterprise/{{page.kong_version}}/health-checks-circuit-breakers
+[secure-admin-api]: /enterprise/{{page.kong_version}}/secure-admin-api
+[proxy-reference]: /enterprise/{{page.kong_version}}/proxy
+
diff --git a/app/enterprise/1.3-x/admin-api/rbac/examples.md b/app/enterprise/1.3-x/admin-api/rbac/examples.md
new file mode 100644
index 000000000000..fe90252af467
--- /dev/null
+++ b/app/enterprise/1.3-x/admin-api/rbac/examples.md
@@ -0,0 +1,1050 @@
+---
+title: RBAC Examples
+book: rbac
+---
+
+## Introduction
+
+This chapter aims to provide a step-by-step tutorial on how to set up
+RBAC and see it in action, with an end-to-end use case. The chosen
+use case demonstrates how **RBAC with workspaces** can be coupled
+to achieve a flexible organization of teams and users in complex
+hierarchies. Make sure to read the [RBAC Overview][rbac-overview] page
+and to glance over the [RBAC Admin API][rbac-admin] chapter, keeping it
+open as a reference.
+
+## Use Case
+
+For the sake of example, let's say a given company has a Kong Enterprise
+cluster to be shared with 3 teams: teamA, teamB, and teamC. While the Kong
+cluster are shared among these teams, they want to be able to segment
+their entities in such a way that management of entities in one team doesn't
+disrupt operation in some other team. As shown in the
+[Workspaces Examples Page][workspaces-examples], such a use case is possible
+with workspaces. On top of workspaces, though, each team wants to enforce
+access control over their Workspace, which is possible with RBAC. **To sum up,
+Workspaces and RBAC are complementary: Workspaces provide segmentation of
+Admin API entities, while RBAC provides access control**.
+
+## Bootstrapping the first RBAC userâthe Super Admin
+
+**Note:** It is possible to create the first Super Admin at the time
+of migration as described in the [Getting Started Guide][getting-started-guide].
+If you chose this option, skip to [Enforcing RBAC](#enforcing-rbac).
+
+Before anything, we will assume the Kong Adminâor, more interestingly,
+the KongOps Engineerâin charge of operating Kong, will create a Super Admin
+user, before actually enforcing RBAC and restarting Kong with RBAC enabled.
+
+As Kong ships with a handy set of default RBAC Rolesâthe `super-admin`,
+the `admin`, and `read-only`âthe task of creating a Super Admin user is
+quite easy:
+
+Create the RBAC user, named `super-admin`:
+
+```
+http :8001/rbac/users name=super-admin
+{
+ "user_token": "M8J5A88xKXa7FNKsMbgLMjkm6zI2anOY",
+ "id": "da80838d-49f8-40f6-b673-6fff3e2c305b",
+ "enabled": true,
+ "created_at": 1531009435000,
+ "name": "super-admin"
+}
+```
+
+As the `super-admin` user name coincides with an existing `super-admin`
+role, it gets automatically added to the `super-admin` roleâwhich can be
+confirmed with the following command:
+
+```
+http :8001/rbac/users/super-admin/roles
+{
+ "roles": [
+ {
+ "comment": "Full access to all endpoints, across all workspaces",
+ "created_at": 1531009724000,
+ "name": "super-admin",
+ "id": "b924ac91-e83f-4136-a5a4-4a7ff92594a8"
+ }
+ ],
+ "user": {
+ "created_at": 1531009858000,
+ "id": "e6897cc0-0c34-4a9c-9f0b-cc65b4f04d68",
+ "name": "super-admin",
+ "enabled": true,
+ "user_token": "vajeOlkybsn0q0VD9qw9B3nHYOErgY7b8"
+ }
+}
+
+```
+
+## Enforcing RBAC
+
+As the `super-admin` user has just been created, the Kong Admin may now
+restart Kong with RBAC enforced, with, e.g.:
+
+```
+KONG_ENFORCE_RBAC=on kong restart
+```
+
+**NOTE**: This is one of the possible ways of enforcing RBAC and restarting
+Kong; another possibility is editing the Kong configuration file and
+restarting.
+
+Before we move on, note that we will be using the Super Admin user, but we
+could, in fact, be moving without RBAC enabled, and having our Kong Admin do
+all the job of setting up the RBAC hierarchy. We want, however, to stress the
+fact that RBAC is powerful enough to allow a flexible separation of tasks. To
+summarize:
+
+- **Kong Admin**: this user has physical access to Kong infrastructure; her
+task is to bootstrap the Kong cluster as well as its configuration, including
+initial RBAC users;
+- **RBAC Super Admin**: created by the Kong Admin, has the role of managing
+RBAC users, roles, etc; this could all be done by the **Kong Admin**, but let's
+give him a break.
+
+## Super Admin creates the teams Workspaces
+
+The Super Admin will now set up our 3 teams: teamA, teamB, and teamC, creating
+one workspace for each, one admin for each. Enough talking.
+
+Creating workspaces for each teamâthis overlaps a bit with
+[Workspaces Examples][workspaces-examples], yes, but it will make our
+exploration of RBAC + Workspaces easier:
+
+**Team A**:
+
+```
+http :8001/workspaces name=teamA Kong-Admin-Token:vajeOlkbsn0q0VD9qw9B3nHYOErgY7b8
+{
+ "name": "teamA",
+ "created_at": 1531014100000,
+ "id": "1412f3a6-4d9b-4b9d-964e-60d8d63a9d46"
+}
+
+```
+
+**Team B**:
+
+```
+http :8001/workspaces name=teamB Kong-Admin-Token:vajeOlkbsn0q0VD9qw9B3nHYOErgY7b8
+{
+ "name": "teamB",
+ "created_at": 1531014143000,
+ "id": "7dee8c56-c6db-4125-b87a-b508baa33c66"
+}
+```
+
+**Team C**:
+
+```
+http :8001/workspaces name=teamC Kong-Admin-Token:vajeOlkbsn0q0VD9qw9B3nHYOErgY7b8
+{
+ "name": "teamC",
+ "created_at": 1531014171000,
+ "id": "542c8662-17cc-49eb-af50-6eb14f3b2e8a"
+}
+```
+
+**NOTE**: this is the RBAC Super Admin creating workspacesânote his
+token being passed in through the `Kong-Admin-Token` HTTP header.
+
+## Super Admin Creates one Admin for each Team:
+
+**Team A**:
+
+```
+http :8001/teamA/rbac/users name=adminA Kong-Admin-Token:vajeOlkbsn0q0VD9qw9B3nHYOErgY7b8
+{
+ "user_token": "qv1VLIpl8kHj7lC1QOKwRdCMXanqEDii",
+ "id": "4d315ff9-8c1a-4844-9ea2-21b16204a154",
+ "enabled": true,
+ "created_at": 1531015165000,
+ "name": "adminA"
+}
+```
+
+**Team B**:
+
+```
+http :8001/teamB/rbac/users name=adminB Kong-Admin-Token:vajeOlkbsn0q0VD9qw9B3nHYOErgY7b8
+{
+ "user_token": "IX5vHVgYqM40tLcctdmzRtHyfxB4ToYv",
+ "id": "49641fc0-8c9d-4507-bc7a-2acac8f2903a",
+ "enabled": true,
+ "created_at": 1531015221000,
+ "name": "adminB"
+}
+```
+
+**Team C**:
+
+```
+http :8001/teamC/rbac/users name=adminC Kong-Admin-Token:vajeOlkbsn0q0VD9qw9B3nHYOErgY7b8
+{
+ "user_token": "w2f7tsuUW4BerXocZIMRQHE84nK2ZAo7",
+ "id": "74643f69-8852-49f9-b363-21971bac4f52",
+ "enabled": true,
+ "created_at": 1531015304000,
+ "name": "teamC"
+}
+```
+
+With this, all of the teams have one admin and each admin can only be seen
+in his corresponding workspace. To verify:
+
+```
+http :8001/teamA/rbac/users Kong-Admin-Token:vajeOlkbsn0q0VD9qw9B3nHYOErgY7b8
+{
+ "total": 1,
+ "data": [
+ {
+ "created_at": 1531014784000,
+ "id": "1faaacd1-709f-4762-8c3e-79f268ec8faf",
+ "name": "adminA",
+ "enabled": true,
+ "user_token": "n5bhjgv0speXp4N7rSUzUj8PGnl3F5eG"
+ }
+ ]
+}
+```
+
+Similarly, workspaces teamB and teamC only show their respective admins:
+
+```
+http :8001/teamB/rbac/users Kong-Admin-Token:vajeOlkbsn0q0VD9qw9B3nHYOErgY7b8
+{
+ "total": 1,
+ "data": [
+ {
+ "created_at": 1531014805000,
+ "id": "3a829408-c1ee-4764-8222-2d280a5de441",
+ "name": "adminB",
+ "enabled": true,
+ "user_token": "C8b6kTTN10JFyU63ORjmCQwVbvK4maeq"
+ }
+ ]
+}
+```
+
+```
+http :8001/teamC/rbac/users Kong-Admin-Token:vajeOlkbsn0q0VD9qw9B3nHYOErgY7b8
+{
+ "total": 1,
+ "data": [
+ {
+ "created_at": 1531014813000,
+ "id": "84d43cdb-5274-4b74-ad22-615e50f005e3",
+ "name": "adminC",
+ "enabled": true,
+ "user_token": "zN5Nj8U1MiGR7vVQKvl8odaGBDI6mjgY"
+ }
+ ]
+}
+```
+
+## Super Admin Creates Admin Roles for Teams
+
+Super Admin is now done creating RBAC Admin users for each team; his next
+task is to create admin roles that will effectively grant permissions to admin
+users.
+
+The admin role must have access to all of the Admin API, restricted to his
+workspace.
+
+Setting up the Admin roleâpay close attention to the request parameters:
+
+```
+http :8001/teamA/rbac/roles/ name=admin Kong-Admin-Token:vajeOlkbsn0q0VD9qw9B3nHYOErgY7b8
+{
+ "created_at": 1531016728000,
+ "id": "d40e61ab-8dad-4ef2-a48b-d11379f7b8d1",
+ "name": "admin"
+}
+```
+
+Creating role endpoint permissions:
+
+```
+http :8001/teamA/rbac/roles/admin/endpoints/ endpoint=* workspace=teamA actions=* Kong-Admin-Token:vajeOlkbsn0q0VD9qw9B3nHYOErgY7b8
+{
+ "total": 1,
+ "data": [
+ {
+ "endpoint": "*",
+ "created_at": 1531017322000,
+ "role_id": "d40e61ab-8dad-4ef2-a48b-d11379f7b8d1",
+ "actions": [
+ "delete",
+ "create",
+ "update",
+ "read"
+ ],
+ "negative": false,
+ "workspace": "teamA"
+ }
+ ]
+}
+```
+
+Next logical step is to add the adminA userâadmin of Team Aâto the Admin
+role in his workspace:
+
+```
+http :8001/teamA/rbac/users/adminA/roles/ roles=admin Kong-Admin-Token:vajeOlkbsn0q0VD9qw9B3nHYOErgY7b8
+{
+ "roles": [
+ {
+ "comment": "Default user role generated for adminA",
+ "created_at": 1531014784000,
+ "id": "e2941b41-92a4-4f49-be89-f1a452bdecd0",
+ "name": "adminA"
+ },
+ {
+ "created_at": 1531016728000,
+ "id": "d40e61ab-8dad-4ef2-a48b-d11379f7b8d1",
+ "name": "admin"
+ }
+ ],
+ "user": {
+ "created_at": 1531014784000,
+ "id": "1faaacd1-709f-4762-8c3e-79f268ec8faf",
+ "name": "adminA",
+ "enabled": true,
+ "user_token": "n5bhjgv0speXp4N7rSUzUj8PGnl3F5eG"
+ }
+}
+```
+
+Note the admin role in the list above.
+
+With these steps, Team A's admin user is now able to manage his team. To
+validate that, let's try to list RBAC users in Team B using Team A's admin
+user tokenâand see that we are not allowed to do so:
+
+```
+http :8001/teamB/rbac/users Kong-Admin-Token:n5bhjgv0speXp4N7rSUzUj8PGnl3F5eG
+{
+ "message": "Invalid RBAC credentials"
+}
+```
+
+Said admin is, however, allowed to list RBAC users in Team A's workspace:
+
+```
+http :8001/teamA/rbac/users Kong-Admin-Token:n5bhjgv0speXp4N7rSUzUj8PGnl3F5eG
+{
+ "total": 1,
+ "data": [
+ {
+ "created_at": 1531014784000,
+ "id": "1faaacd1-709f-4762-8c3e-79f268ec8faf",
+ "name": "adminA",
+ "enabled": true,
+ "user_token": "n5bhjgv0speXp4N7rSUzUj8PGnl3F5eG"
+ }
+ ]
+}
+```
+
+If the same procedure is repeated for Team B and Team C, they will end up with
+a similar set up, with an admin role and an admin user, both restricted to the
+team's workspace.
+
+And so Super Admin ends his participation; individual team admins are now able
+to set up his teams users and entities!
+
+## Team Admins Create Team Regular Users
+
+From this point on, team admins are able to drive the process; the next logical
+step is for Team users to be created; such team users could be, for example,
+engineers that are part of Team A (or B or C). Let's go ahead and do that,
+using Admin A's user token.
+
+Before regular users can be created, a role needs to be available for them.
+Such a role needs to have permissions to all of Admin API endpoints, except
+RBAC and Workspacesâregular users will not need access to these in general
+and, if they do, the Admin can grant them.
+
+**Creating the regular users role**:
+
+```
+http :8001/teamA/rbac/roles/ name=users Kong-Admin-Token:n5bhjgv0speXp4N7rSUzUj8PGnl3F5eG
+{
+ "created_at": 1531020346000,
+ "id": "9846b92c-6820-4741-ac31-425b3d6abc5b",
+ "name": "users"
+}
+```
+
+**Creating permissions in the regular users role**:
+
+First, permission to all of Admin APIâpositive permission on \*:
+
+```
+http :8001/teamA/rbac/roles/users/endpoints/ endpoint=* workspace=teamA actions=* Kong-Admin-Token:n5bhjgv0speXp4N7rSUzUj8PGnl3F5eG
+{
+ "endpoint": "*",
+ "created_at": 1531020573000,
+ "role_id": "9846b92c-6820-4741-ac31-425b3d6abc5b",
+ "actions": [
+ "delete",
+ "create",
+ "update",
+ "read"
+ ],
+ "negative": false,
+ "workspace": "teamA"
+}
+```
+
+Then, filter out RBAC and workspaces with negative permissions:
+
+```
+http :8001/teamA/rbac/roles/users/endpoints/ endpoint=/rbac/* workspace=teamA actions=* Kong-Admin-Token:n5bhjgv0speXp4N7rSUzUj8PGnl3F5eG
+{
+ "endpoint": "/rbac/*",
+ "created_at": 1531020744000,
+ "role_id": "9846b92c-6820-4741-ac31-425b3d6abc5b",
+ "actions": [
+ "delete",
+ "create",
+ "update",
+ "read"
+ ],
+ "negative": true,
+ "workspace": "teamA"
+}
+```
+
+```
+http :8001/teamA/rbac/roles/users/endpoints/ endpoint=/workspaces/* workspace=teamA actions=* Kong-Admin-Token:n5bhjgv0speXp4N7rSUzUj8PGnl3F5eG
+{
+ "endpoint": "/workspaces/*",
+ "created_at": 1531020778000,
+ "role_id": "9846b92c-6820-4741-ac31-425b3d6abc5b",
+ "actions": [
+ "delete",
+ "create",
+ "update",
+ "read"
+ ],
+ "negative": true,
+ "workspace": "teamA"
+}
+```
+
+**IMPORTANT**: as explained in the [Wildcards in Permissions][rbac-wildcards]
+section, the meaning of `*` is not the expected generic globbing one might
+be used to. As such, `/rbac/*` or `/workspaces/*` do not match all of the
+RBAC and Workspaces endpoints. For example, to cover all of the RBAC API,
+one would have to define permissions for the following endpoints:
+
+- `/rbac/*`
+- `/rbac/*/*`
+- `/rbac/*/*/*`
+- `/rbac/*/*/*/*`
+- `/rbac/*/*/*/*/*`
+
+Team A just got 3 new members: foogineer, bargineer, and bazgineer. Admin A
+will welcome them to the team by creating RBAC users for them and giving them
+access to Kong!
+
+Create foogineer:
+
+```
+http :8001/teamA/rbac/users name=foogineer Kong-Admin-Token:n5bhjgv0speXp4N7rSUzUj8PGnl3F5eG
+{
+ "created_at": 1531019797000,
+ "id": "0b4111da-2827-4767-8651-a327f7a559e9",
+ "name": "foogineer",
+ "enabled": true,
+ "user_token": "dNeYvYAwvjOJdoReVJZXF8vLBXQioKkI"
+}
+```
+
+Add foogineer to the `users` role:
+
+```
+http :8001/teamA/rbac/users/foogineer/roles roles=users Kong-Admin-Token:n5bhjgv0speXp4N7rSUzUj8PGnl3F5eG
+{
+ "roles": [
+ {
+ "comment": "Default user role generated for foogineer",
+ "created_at": 1531019797000,
+ "id": "125c4212-b882-432d-a323-9cbe38b1d0df",
+ "name": "foogineer"
+ },
+ {
+ "created_at": 1531020346000,
+ "id": "9846b92c-6820-4741-ac31-425b3d6abc5b",
+ "name": "users"
+ }
+ ],
+ "user": {
+ "created_at": 1531019797000,
+ "id": "0b4111da-2827-4767-8651-a327f7a559e9",
+ "name": "foogineer",
+ "enabled": true,
+ "user_token": "dNeYvYAwvjOJdoReVJZXF8vLBXQioKkI"
+ }
+}
+```
+
+Create bargineer:
+
+```
+http :8001/teamA/rbac/users name=bargineer Kong-Admin-Token:n5bhjgv0speXp4N7rSUzUj8PGnl3F5eG
+{
+ "created_at": 1531019837000,
+ "id": "25dfa68e-32e8-48d8-815f-6fedfd2fb4a6",
+ "name": "bargineer",
+ "enabled": true,
+ "user_token": "eZj3WUc46wO3zEJbLP3Y4VGvNaUgGlyv"
+}
+```
+
+Add bargineer to the `users` role:
+
+```
+http :8001/teamA/rbac/users/bargineer/roles roles=users Kong-Admin-Token:n5bhjgv0speXp4N7rSUzUj8PGnl3F5eG
+{
+ "roles": [
+ {
+ "comment": "Default user role generated for bargineer",
+ "created_at": 1531019837000,
+ "id": "3edb00c2-9ae1-423d-ac81-bec702c29e37",
+ "name": "bargineer"
+ },
+ {
+ "created_at": 1531020346000,
+ "id": "9846b92c-6820-4741-ac31-425b3d6abc5b",
+ "name": "users"
+ }
+ ],
+ "user": {
+ "created_at": 1531019837000,
+ "id": "25dfa68e-32e8-48d8-815f-6fedfd2fb4a6",
+ "name": "bargineer",
+ "enabled": true,
+ "user_token": "eZj3WUc46wO3zEJbLP3Y4VGvNaUgGlyv"
+ }
+}
+```
+
+Create bazgineer:
+
+```
+http :8001/teamA/rbac/users name=bazgineer Kong-Admin-Token:n5bhjgv0speXp4N7rSUzUj8PGnl3F5eG
+{
+ "created_at": 1531019937000,
+ "id": "ea7207d7-0d69-427b-b288-ce696b7f4690",
+ "name": "bazgineer",
+ "enabled": true,
+ "user_token": "r8NhaT213Zm8o1woQF4ZyQyCVjFRgGp3"
+}
+```
+
+Add bazgineer to the `users` role:
+
+```
+http :8001/teamA/rbac/users/bazgineer/roles roles=users Kong-Admin-Token:n5bhjgv0speXp4N7rSUzUj8PGnl3F5eG
+{
+ "roles": [
+ {
+ "comment": "Default user role generated for bazgineer",
+ "created_at": 1531019937000,
+ "id": "fa409bb6-c86c-45d2-8a6b-ac8e71de2cc9",
+ "name": "bazgineer"
+ },
+ {
+ "created_at": 1531020346000,
+ "name": "users",
+ "id": "9846b92c-6820-4741-ac31-425b3d6abc5b"
+ }
+ ],
+ "user": {
+ "created_at": 1531019937000,
+ "id": "ea7207d7-0d69-427b-b288-ce696b7f4690",
+ "name": "bazgineer",
+ "enabled": true,
+ "user_token": "r8NhaT213Zm8o1woQF4ZyQyCVjFRgGp3"
+ }
+}
+```
+
+## Regular Team Users use their tokens!
+
+foogineer, bargineer, and bazgineer all have gotten their RBAC user tokens
+from their Team A admin, and are now allowed to explore Kongâwithin the
+confines of their Team A workspace. Let's validate they can in fact do anything
+they wish, except over RBAC and Workspaces.
+
+Try listing Workspaces:
+
+```
+http :8001/teamA/workspaces/ Kong-Admin-Token:dNeYvYAwvjOJdoReVJZXF8vLBXQioKkI
+{
+ "message": "foogineer, you do not have permissions to read this resource"
+}
+```
+
+Enable some pluginâe.g., key-auth:
+
+```
+http :8001/teamA/plugins name=key-auth Kong-Admin-Token:dNeYvYAwvjOJdoReVJZXF8vLBXQioKkI
+{
+ "created_at": 1531021732000,
+ "config": {
+ "key_in_body": false,
+ "run_on_preflight": true,
+ "anonymous": "",
+ "hide_credentials": false,
+ "key_names": [
+ "apikey"
+ ]
+ },
+ "id": "cdc85ef0-804b-4f92-aafd-3ff58512e445",
+ "enabled": true,
+ "name": "key-auth"
+}
+```
+
+List currently enabled plugins:
+
+```
+http :8001/teamA/plugins Kong-Admin-Token:dNeYvYAwvjOJdoReVJZXF8vLBXQioKkI
+{
+ "total": 1,
+ "data": [
+ {
+ "created_at": 1531021732000,
+ "config": {
+ "key_in_body": false,
+ "run_on_preflight": true,
+ "anonymous": "",
+ "hide_credentials": false,
+ "key_names": [
+ "apikey"
+ ]
+ },
+ "id": "cdc85ef0-804b-4f92-aafd-3ff58512e445",
+ "name": "key-auth",
+ "enabled": true
+ }
+ ]
+}
+```
+
+This ends our use case tutorial; it demonstrates the power of RBAC and
+workspaces with a real-world scenario. Following, we will approach **Entity-Level
+RBAC**, an extension of our powerful access control to entity-level granularity.
+
+# Entity-Level RBAC: a Primer
+
+Kong Enterprise's new RBAC implementation goes one step further in permissions
+granularity: in addition to "endpoint" permissions, it supports entity-level
+permissions, meaning that particular entities, identified by their unique ID,
+can be allowed or disallowed access in a role.
+
+Refreshing our minds, RBAC is [enforced][rbac-enforce] with the `enforce_rbac`
+configuration directiveâor with its `KONG_ENFORCE_RBAC` environment variable
+counterpart. Such directive is an enum, with 4 possible values:
+
+- `on`: similarly to the previous RBAC implementation, applies Endpoint-level
+access control
+- `entity`: applies **only** Entity-level access control
+- `both`: applies **both Endpoint and Entity level access control**
+- `off`: disables RBAC enforcement
+
+If one sets it to either `entity` or `both`, Kong will enforce entity-level
+access control. However, as with endpoint-level access control, permissions
+must be bootstrapped before enforcement is enabled.
+
+## Creating Entity-Level Permissions
+
+Team A just got one new, temporary, team member: qux. Admin A, the admin of
+Team A, has already created his qux RBAC user; he needs, however, to limit
+access that qux has over entities in Team A workspace, giving him read access
+to only a couple of entitiesâsay, a Service and a Route. For that, he will
+use Entity-Level RBAC.
+
+**Admin A creates a role for the temporary user qux**:
+
+```
+http :8001/teamA/rbac/roles name=qux-role Kong-Admin-Token:n5bhjgv0speXp4N7rSUzUj8PGnl3F5eG
+{
+ "name": "qux-role",
+ "created_at": 1531065975000,
+ "id": "ffe93269-7993-4308-965e-0286d0bc87b9"
+}
+```
+
+We will assume the following entities exist:
+
+A service:
+
+```
+http :8001/teamA/services Kong-Admin-Token:n5bhjgv0speXp4N7rSUzUj8PGnl3F5eG
+{
+ "next": null,
+ "data": [
+ {
+ "host": "httpbin.org",
+ "created_at": 1531066074,
+ "connect_timeout": 60000,
+ "id": "3ed24101-19a7-4a0b-a10f-2f47bcd4ff43",
+ "protocol": "http",
+ "name": "service1",
+ "read_timeout": 60000,
+ "port": 80,
+ "path": null,
+ "updated_at": 1531066074,
+ "retries": 5,
+ "write_timeout": 60000
+ }
+ ]
+}
+```
+
+and a Route to that Service:
+
+```
+http :8001/teamA/routes Kong-Admin-Token:n5bhjgv0speXp4N7rSUzUj8PGnl3F5eG
+{
+ "next": null,
+ "data": [
+ {
+ "created_at": 1531066253,
+ "id": "d25afc46-dc59-48b2-b04f-d3ebe19f6d4b",
+ "hosts": null,
+ "updated_at": 1531066253,
+ "preserve_host": false,
+ "regex_priority": 0,
+ "service": {
+ "id": "3ed24101-19a7-4a0b-a10f-2f47bcd4ff43"
+ },
+ "paths": [
+ "/anything"
+ ],
+ "methods": null,
+ "strip_path": false,
+ "protocols": [
+ "http",
+ "https"
+ ]
+ }
+ ]
+}
+```
+
+**Admin A creates entity permissions in qux-role**:
+
+Add service1âwhose ID is 3ed24101-19a7-4a0b-a10f-2f47bcd4ff43:
+
+```
+http :8001/teamA/rbac/roles/qux-role/entities entity_id=3ed24101-19a7-4a0b-a10f-2f47bcd4ff43 actions=read Kong-Admin-Token:n5bhjgv0speXp4N7rSUzUj8PGnl3F5eG
+{
+ "created_at": 1531066684000,
+ "role_id": "ffe93269-7993-4308-965e-0286d0bc87b9",
+ "entity_id": "3ed24101-19a7-4a0b-a10f-2f47bcd4ff43",
+ "negative": false,
+ "entity_type": "services",
+ "actions": [
+ "read"
+ ]
+}
+```
+
+Add the routeâwhose ID is d25afc46-dc59-48b2-b04f-d3ebe19f6d4b:
+
+```
+http :8001/teamA/rbac/roles/qux-role/entities entity_id=d25afc46-dc59-48b2-b04f-d3ebe19f6d4b actions=read Kong-Admin-Token:n5bhjgv0speXp4N7rSUzUj8PGnl3F5eG
+{
+ "created_at": 1531066728000,
+ "role_id": "ffe93269-7993-4308-965e-0286d0bc87b9",
+ "entity_id": "d25afc46-dc59-48b2-b04f-d3ebe19f6d4b",
+ "negative": false,
+ "entity_type": "routes",
+ "actions": [
+ "read"
+ ]
+}
+```
+
+**Admin A adds qux to his role**:
+
+```
+http :8001/teamA/rbac/users/qux/roles roles=qux-role Kong-Admin-Token:n5bhjgv0speXp4N7rSUzUj8PGnl3F5eG
+{
+ "roles": [
+ {
+ "comment": "Default user role generated for qux",
+ "created_at": 1531065373000,
+ "name": "qux",
+ "id": "31614171-4174-42b4-9fae-43c9ce14830f"
+ },
+ {
+ "created_at": 1531065975000,
+ "name": "qux-role",
+ "id": "ffe93269-7993-4308-965e-0286d0bc87b9"
+ }
+ ],
+ "user": {
+ "created_at": 1531065373000,
+ "id": "4d87bf78-5824-4756-b0d0-ceaa9bd9b2d5",
+ "name": "qux",
+ "enabled": true,
+ "user_token": "sUnv6uBehM91amYRNWESsgX3HzqoBnR5"
+ }
+}
+```
+
+Checking permissions appear listed:
+
+```
+http :8001/teamA/rbac/users/qux/permissions Kong-Admin-Token:n5bhjgv0speXp4N7rSUzUj8PGnl3F5eG
+{
+ "entities": {
+ "d25afc46-dc59-48b2-b04f-d3ebe19f6d4b": {
+ "actions": [
+ "read"
+ ],
+ "negative": false
+ },
+ "3ed24101-19a7-4a0b-a10f-2f47bcd4ff43": {
+ "actions": [
+ "read"
+ ],
+ "negative": false
+ }
+ },
+ "endpoints": {}
+}
+```
+
+That is, 2 entities permissions and no endpoint permissions.
+
+Admin A is done setting up qux, and qux can now use his user token to read
+his two entities over Kong's admin API.
+
+We will assume that Admin A [enabled entity-level enforcement][rbac-enforce].
+Note that as qux has **no endpoint-level permissions**, if both endpoint and
+entity-level enforcement is enabled, he will not be able to read his entities -
+endpoint-level validation comes before entity-level.
+
+**qux tries listing all RBAC users**
+
+```
+http :8001/teamA/rbac/users/ Kong-Admin-Token:sUnv6uBehM91amYRNWESsgX3HzqoBnR5
+{
+ "message": "qux, you do not have permissions to read this resource"
+}
+```
+
+**qux tries listing all Workspaces**
+
+```
+http :8001/teamA/rbac/workspaces/ Kong-Admin-Token:sUnv6uBehM91amYRNWESsgX3HzqoBnR5
+{
+ "message": "qux, you do not have permissions to read this resource"
+}
+```
+
+**qux tries to access service1**
+
+```
+http :8001/teamA/services/service1 Kong-Admin-Token:sUnv6uBehM91amYRNWESsgX3HzqoBnR5
+{
+ "host": "httpbin.org",
+ "created_at": 1531066074,
+ "connect_timeout": 60000,
+ "id": "3ed24101-19a7-4a0b-a10f-2f47bcd4ff43",
+ "protocol": "http",
+ "name": "service1",
+ "read_timeout": 60000,
+ "port": 80,
+ "path": null,
+ "updated_at": 1531066074,
+ "retries": 5,
+ "write_timeout": 60000
+}
+```
+
+Similarly, he can access his Route:
+
+```
+http :8001/teamA/routes/3ed24101-19a7-4a0b-a10f-2f47bcd4ff43 Kong-Admin-Token:sUnv6uBehM91amYRNWESsgX3HzqoBnR5
+{
+ "created_at": 1531066253,
+ "strip_path": false,
+ "hosts": null,
+ "preserve_host": false,
+ "regex_priority": 0,
+ "updated_at": 1531066253,
+ "paths": [
+ "/anything"
+ ],
+ "service": {
+ "id": "3ed24101-19a7-4a0b-a10f-2f47bcd4ff43"
+ },
+ "methods": null,
+ "protocols": [
+ "http",
+ "https"
+ ],
+ "id": "d25afc46-dc59-48b2-b04f-d3ebe19f6d4b"
+}
+```
+
+## Closing Remarks
+
+We will end this chapter with a few closing remarks.
+
+## Wildcards in Permissions
+
+RBAC supports the use of wildcardsârepresented by the `*` characterâin many
+aspects of permissions:
+
+**Creating endpoint permissionsâ`/rbac/roles/:role/endpoints`**
+
+To create an endpoint permission, one must pass the parameters below, all of
+which can be replaced by a * character:
+
+- `endpoint`: `*` matches **any endpoint**
+- `workspace`: `*` matches **any workspace**
+- `actions`: `*` evaluates to **all actionsâread, update, create, delete**
+
+**Special case**: `endpoint`, in addition to a single `*`, also accepts `*`
+within the endpoint itself, replacing a URL segment between `/`; for example,
+all of the following are valid endpoints:
+
+- `/rbac/*`: where `*` replaces any possible segmentâe.g., `/rbac/users`,
+`/rbac/roles`, etc
+- `/services/*/plugins`: `*` matches any Service name or ID
+
+Note, however, that `*` **is not** a generic, shell-like, glob pattern.
+
+If `workspace` is ommitted, it defaults to the current request's workspace. For
+example, a role-endpoint permission created with `/teamA/roles/admin/endpoints`
+is scoped to workspace `teamA`.
+
+**Creating entity permissionsâ`/rbac/roles/:role/entities`**
+
+Similarly, for entity permissions, the following parameters accept a `*`
+character:
+
+- `entity_id`: `*` matches **any entity ID**
+
+## Entities Concealing in Entity-Level RBAC
+
+With Entity-Level RBAC enabled, endpoints that list all entities of a
+particular collection will only list entities that the user has access to;
+in the example above, if user qux listed all Routes, he would only get as
+response the entities he has access toâeven though there could be more:
+
+```
+http :8001/teamA/routes Kong-Admin-Token:sUnv6uBehM91amYRNWESsgX3HzqoBnR5
+{
+ "next": null,
+ "data": [
+ {
+ "created_at": 1531066253,
+ "id": "d25afc46-dc59-48b2-b04f-d3ebe19f6d4b",
+ "hosts": null,
+ "updated_at": 1531066253,
+ "preserve_host": false,
+ "regex_priority": 0,
+ "service": {
+ "id": "3ed24101-19a7-4a0b-a10f-2f47bcd4ff43"
+ },
+ "paths": [
+ "/anything"
+ ],
+ "methods": null,
+ "strip_path": false,
+ "protocols": [
+ "http",
+ "https"
+ ]
+ }
+ ]
+}
+```
+
+Some Kong endpoints carry a `total` field in responses; with Entity-Level RBAC
+enabled, the global count of entities is displayed, but only entities the user
+has access to are themselves shown; for example, if Team A has a number of
+plugins configured, but qux only has access to one of them, the following
+would be the expected output for a GET request to `/teamA/plugins`:
+
+```
+http :8001/teamA/plugins Kong-Admin-Token:sUnv6uBehM91amYRNWESsgX3HzqoBnR5
+{
+ "total": 2,
+ "data": [
+ {
+ "created_at": 1531070344000,
+ "config": {
+ "key_in_body": false,
+ "run_on_preflight": true,
+ "anonymous": "",
+ "hide_credentials": false,
+ "key_names": [
+ "apikey"
+ ]
+ },
+ "id": "8813dd0b-3e9d-4bcf-8a10-3112654f86e7",
+ "name": "key-auth",
+ "enabled": true
+ }
+ ]
+}
+```
+
+Notice the `total` field is 2, but qux only got one entity in the response.
+
+## Creating Entities in Entity-Level RBAC
+
+As entity-level RBAC provides access control to individual existing entities,
+it does not apply to creation of new entities; for that, endpoint-level
+permissions must be configured and enforced. For example, if endpoint-level
+permissions are not enforced, qux will be able to create new entities:
+
+```
+http :8001/teamA/routes paths[]=/anything service.id=3ed24101-19a7-4a0b-a10f-2f47bcd4ff43 strip_path=false Kong-Admin-Token:sUnv6uBehM91amYRNWESsgX3HzqoBnR5
+{
+ "created_at": 1531070828,
+ "strip_path": false,
+ "hosts": null,
+ "preserve_host": false,
+ "regex_priority": 0,
+ "updated_at": 1531070828,
+ "paths": [
+ "/anything"
+ ],
+ "service": {
+ "id": "3ed24101-19a7-4a0b-a10f-2f47bcd4ff43"
+ },
+ "methods": null,
+ "protocols": [
+ "http",
+ "https"
+ ],
+ "id": "6ee76f74-3c96-46a9-ae48-72df0717d244"
+}
+```
+
+and qux will automatically have permissions to perform any actions to entities
+he created.
+
+---
+
+[rbac-overview]: /enterprise/{{page.kong_version}}/rbac/overview
+[rbac-enforce]: /enterprise/{{page.kong_version}}/rbac/overview#enforcing-rbac
+[rbac-wildcard]: /enterprise/{{page.kong_version}}/rbac/examples/#wildcards-in-permissions
+[rbac-admin]: /enterprise/{{page.kong_version}}/rbac/admin-api
+[workspaces-examples]: /enterprise/{{page.kong_version}}/rbac/examples
+[getting-started-guide]: /enterprise/{{page.kong_version}}/getting-started/quickstart/#1-start-kong-enterprise
diff --git a/app/enterprise/1.3-x/admin-api/rbac/reference.md b/app/enterprise/1.3-x/admin-api/rbac/reference.md
new file mode 100644
index 000000000000..5ca178b74a59
--- /dev/null
+++ b/app/enterprise/1.3-x/admin-api/rbac/reference.md
@@ -0,0 +1,952 @@
+---
+title: RBAC Reference
+book: rbac
+---
+
+## Introduction
+
+Kong Enterprise's RBAC feature is configurable through Kong's [Admin
+API] or via the [Kong Manager].
+
+There are 4 basic entities involving RBAC.
+
+- **User**: The entity interacting with the system. Can be associated with
+ zero, one or more roles. Example: user `bob` has token `1234`.
+- **Role**: Set of permissions (`role_endpoint` and
+ `role_entity`). Has a name and can be associated with zero, one or
+ more permissions. Example: user bob is associated with role
+ `developer`.
+- **role_endpoint**: A set of enabled or disabled (see `negative`
+ parameter) actions (`read`, `create`, `update`, `delete`)
+ `endpoint`. Example: Role `developer` has 1 role_endpoint: `read &
+ write` to endpoint `/routes`
+- **role_entity**: A set of enabled or disabled (see `negative`
+ parameter) actions (`read`, `create`, `update`, `delete`)
+ `entity`. Example: Role `developer` has 1 role_entity: `read & write
+ & delete` to entity `283fccff-2d4f-49a9-8730-dc8b71ec2245`.
+
+## Add a User
+**Endpoint**
+
+
+
+
+
+
+
+ 
+ Workspaces
+
+ Segment your cluster into Workspaces for specific teams.
+ + View reference → + +
+
+
+
+
+
+
+
+
+
+
+
+ RBAC
+
+ Authenticate Kong Admins with Basic Auth, OIDC, LDAP, and Sessions. Authorize Admins with RBAC and Workspaces.
+ + Learn more → + +/rbac/users
+
+**Request Body**
+
+| Attribute | Description |
+| --------- | ----------- |
+| `name` | The RBAC user name. |
+| `user_token` | The authentication token to be presented to the Admin API. The value will be hashed and cannot be fetched in plaintext. |
+| `enabled`optional | A flag to enable or disable the user. By default, users are enabled. | +| `comment`
optional | A string describing the RBAC user object. | + +**Response** + +``` +HTTP 201 Created +``` + +```json +{ + "comment": null, + "created_at": 1557522650, + "enabled": true, + "id": "fa6881b2-f49f-4007-9475-577cd21d34f4", + "name": "doc_knight", + "user_token": "$2b$09$Za30VKAAAmyoB9zF2PNEF.9hgKcN2BdKkptPMCubPK/Ps08lzZjYG", + "user_token_ident": "4d870" +} +``` +___ + +## Retrieve a User +**Endpoint** + +
/rbac/users/{name_or_id}
+
+| Attribute | Description |
+| --------- | ----------- |
+| `name_or_id` | The RBAC user name or UUID. |
+
+**Response**
+
+```
+HTTP 200 OK
+```
+
+```json
+{
+ "created_at": 1557522650,
+ "enabled": true,
+ "id": "fa6881b2-f49f-4007-9475-577cd21d34f4",
+ "name": "doc_lord",
+ "user_token": "$2b$09$Za30VKAAAmyoB9zF2PNEF.9hgKcN2BdKkptPMCubPK/Ps08lzZjYG",
+ "user_token_ident": "4d870"
+}
+```
+___
+
+## List Users
+**Endpoint**
+
+/rbac/users/
+
+**Response**
+
+```
+HTTP 200 OK
+```
+
+```json
+{
+ "data": [
+ {
+ "comment": null,
+ "created_at": 1557512629,
+ "enabled": true,
+ "id": "f035f120-a95e-4327-b2ae-8fa264601d75",
+ "name": "doc_lord",
+ "user_token": "$2b$09$TIMneYcTosdG9WbzRsqcweAS2zote8g6I8HqXAtbFHR1pds2ymsh6",
+ "user_token_ident": "88ea3"
+ },
+ {
+ "comment": null,
+ "created_at": 1557522650,
+ "enabled": true,
+ "id": "fa6881b2-f49f-4007-9475-577cd21d34f4",
+ "name": "doc_knight",
+ "user_token": "$2b$09$Za30VKAAAmyoB9zF2PNEF.9hgKcN2BdKkptPMCubPK/Ps08lzZjYG",
+ "user_token_ident": "4d870"
+ }
+ ],
+ "next": null
+}
+```
+
+â ď¸ **Note**: **RBAC Users** associated with **Admins** will _not_ be
+listed with **`GET`** `/rbac/users`. Instead, use
+[**`GET`** `/admins`](/enterprise/{{page.kong_version}}/admin-api/admins/reference/#list-admins)
+to list all **Admins**.
+
+___
+
+## Update a User
+**Endpoint**
+
+/rbac/users/{name_or_id}
+
+| Attribute | Description |
+| --------- | ----------- |
+| `name_or_id` | The RBAC user name or UUID. |
+
+**Request Body**
+
+| Attribute | Description |
+| --------- | ----------- |
+| `user_token`optional | The authentication token to be presented to the Admin API. If this value is not present, the token will automatically be generated. | +| `enabled`
optional | A flag to enable or disable the user. By default, users are enabled. | +| `comment`
optional | A string describing the RBAC user object. | + +**Response** + +``` +HTTP 200 OK +``` + +```json +{ + "comment": "this comment came from a patch request", + "created_at": 1557522650, + "enabled": true, + "id": "fa6881b2-f49f-4007-9475-577cd21d34f4", + "name": "donut_lord", + "user_token": "$2b$09$Za30VKAAAmyoB9zF2PNEF.9hgKcN2BdKkptPMCubPK/Ps08lzZjYG", + "user_token_ident": "4d870" +} +``` +___ + +## Delete a User +**Endpoint** + +
/rbac/users/{name_or_id}
+
+| Attribute | Description |
+| --------- | ----------- |
+| `name_or_id` | The RBAC user name or UUID. |
+
+**Response**
+
+```
+HTTP 204 No Content
+```
+___
+
+## Add a Role
+**Endpoint**
+
+/rbac/roles
+
+| Attribute | Description |
+| --------- | ----------- |
+| `name` | The RBAC role name. |
+| `comment`optional | A string describing the RBAC user object. | + +**Response** + +``` +HTTP 201 Created +``` + +```json +{ + "comment": null, + "created_at": 1557532241, + "id": "b5c5cfd4-3330-4796-9b7b-6026e91e3ad6", + "is_default": false, + "name": "service_reader" +} +``` +___ + +## Retrieve a Role +Endpoint + +
/rbac/roles/{name_or_id}
+
+| Attribute | Description |
+| --------- | ----------- |
+| `name_or_id` | The RBAC role name or UUID. |
+
+**Response**
+
+```
+HTTP 200 OK
+```
+
+```json
+{
+ "created_at": 1557532241,
+ "id": "b5c5cfd4-3330-4796-9b7b-6026e91e3ad6",
+ "is_default": false,
+ "name": "service_reader"
+}
+```
+___
+
+## List Roles
+**Endpoint**
+
+/rbac/roles
+
+**Response**
+
+```
+HTTP 200 OK
+```
+
+```json
+{
+ "data": [
+ {
+ "comment": "Full access to all endpoints, across all workspacesâexcept RBAC Admin API",
+ "created_at": 1557506249,
+ "id": "38a03d47-faae-4366-b430-f6c10aee5029",
+ "name": "admin"
+ },
+ {
+ "comment": "Read access to all endpoints, across all workspaces",
+ "created_at": 1557506249,
+ "id": "4141675c-8beb-41a5-aa04-6258ab2d2f7f",
+ "name": "read-only"
+ },
+ {
+ "comment": "Full access to all endpoints, across all workspaces",
+ "created_at": 1557506249,
+ "id": "888117e0-f2b3-404d-823b-dee595423505",
+ "name": "super-admin"
+ },
+ {
+ "comment": null,
+ "created_at": 1557532241,
+ "id": "b5c5cfd4-3330-4796-9b7b-6026e91e3ad6",
+ "name": "doc_lord"
+ }
+ ],
+ "next": null
+}
+```
+___
+
+## Update or Create a Role
+**Endpoint**
+
+/rbac/roles
+
+**Request Body**
+
+| Attribute | Description |
+| --------- | ----------- |
+| `name` | The RBAC role name. |
+| `comment`optional | A string describing the RBAC user object. | + +The behavior of `PUT` endpoints is the following: if the request payload **does +not** contain an entity's primary key (`id` for Users), the entity will be +created with the given payload. If the request payload **does** contain an +entity's primary key, the payload will "replace" the entity specified by the +given primary key. If the primary key is **not** that of an existing entity, `404 +NOT FOUND` will be returned. + +**Response** + +If creating the entity: + +``` +HTTP 201 Created +``` + +If replacing the entity: + +``` +HTTP 200 OK +``` + +```json +{ + "comment": "the best", + "created_at": 1557532566, + "id": "b5c5cfd4-3330-4796-9b7b-6026e91e3ad6", + "is_default": false, + "name": "doc_lord" +} +``` + +## Update a Role +**Endpoint** + +
/rbac/roles/{name_or_id}
+
+| Attribute | Description |
+| --------- | ----------- |
+| `name_or_id` | The RBAC role or UUID. |
+
+**Request Body**
+
+| Attribute | Description |
+| --------- | ----------- |
+| `comment`optional | A string describing the RBAC role object. | + +**Response** + +``` +HTTP 200 OK +``` + +```json +{ + "comment": "comment from patch request", + "created_at": 1557532566, + "id": "b5c5cfd4-3330-4796-9b7b-6026e91e3ad6", + "is_default": false, + "name": "service_reader" +} +``` +___ + +## Delete a Role +**Endpoint** + +
/rbac/role/{name_or_id}
+
+| Attribute | Description |
+| --------- | ----------- |
+| `name` | The RBAC role name. |
+
+**Response**
+
+```
+HTTP 204 No Content
+```
+___
+
+## Add a Role Endpoint Permission
+**Endpoint**
+
+/rbac/roles/{name_or_id}/endpoints
+
+
+| Attribute | Description |
+| --------- | ----------- |
+| `name_or_id` | The RBAC role name. |
+
+
+**Request Body**
+
+| Attribute | Description |
+| --------- | ----------- |
+| `workspace` | Workspace tied to the endpoint. Defaults to the default permission. Special value of "*" means **all** workspaces are affected |
+| `endpoint` | Endpoint associated with this permission. |
+| `negative` | If true, explicitly disallow the actions associated with the permissions tied to this endpoint. By default this value is false. |
+| `actions` | One or more actions associated with this permission. This is a comma separated string (read,create,update,delete) |
+| `comment`optional | A string describing the RBAC permission object. | + +`endpoint` must be the path of the associated endpoint. They can be +exact matches, or contain wildcards, represented by `*`. + +- Exact matches; eg: + * /apis/ + * /apis/foo + +- Wildcards; eg: + * /apis/* + * /apis/*/plugins + +Where `*` replaces exactly one segment between slashes (or the end of +the path). + +Note that wildcards can be nested (`/rbac/*`, `/rbac/*/*`, +`/rbac/*/*/*` would refer to all paths under `/rbac/`) + +**Response** + +``` +HTTP 201 Created +``` + +```json +{ + "actions": [ + "delete", + "create", + "update", + "read" + ], + "created_at": 1557764505, + "endpoint": "/consumers", + "negative": false, + "role": { + "id": "23df9f20-e7cc-4da4-bc89-d3a08f976e50" + }, + "workspace": "default" +} +``` + +--- + +## Retrieve a Role Endpoint Permission +**Endpoint** + +
/rbac/roles/{name_or_id}/endpoints/{worspace_name_or_id}/{endpoint}
+
+| Attribute | Description |
+| --------- | ----------- |
+| `name_or_id` | The RBAC role name or UUID. |
+| `worspace_name_or_id` | The worspace name or UUID. |
+| `endpoint` | The endpoint associated with this permisson. |
+
+**Response**
+
+```
+HTTP 200 OK
+```
+
+```json
+{
+ "actions": [
+ "delete",
+ "create",
+ "update",
+ "read"
+ ],
+ "created_at": 1557764505,
+ "endpoint": "/consumers",
+ "negative": false,
+ "role": {
+ "id": "23df9f20-e7cc-4da4-bc89-d3a08f976e50"
+ },
+ "workspace": "default"
+}
+```
+
+---
+
+
+
+## List Role Endpoints Permissions
+**Endpoint**
+
+/rbac/roles/{role_name_or_id}/endpoints
+
+| Attribute | Description |
+| --------- | ----------- |
+| `role_name_or_id` | The RBAC role name or UUID. |
+
+**Response**
+
+```
+HTTP 200 OK
+```
+
+```json
+{
+ "data": [
+ {
+ "actions": [
+ "delete",
+ "create",
+ "update",
+ "read"
+ ],
+ "created_at": 1557764505,
+ "endpoint": "/consumers",
+ "negative": false,
+ "role": {
+ "id": "23df9f20-e7cc-4da4-bc89-d3a08f976e50"
+ },
+ "workspace": "default"
+ },
+ {
+ "actions": [
+ "read"
+ ],
+ "created_at": 1557764438,
+ "endpoint": "/services",
+ "negative": false,
+ "role": {
+ "id": "23df9f20-e7cc-4da4-bc89-d3a08f976e50"
+ },
+ "workspace": "default"
+ }
+ ]
+}
+```
+
+---
+
+## Update a Role Endpoint Permission
+**Endpoint**
+
+/rbac/roles/{name_or_id}/endpoints/{worspace_name_or_id}/{endpoint}
+
+| Attribute | Description |
+| --------- | ----------- |
+| `name_or_id` | The RBAC role name or UUID. |
+| `worspace_name_or_id` | The worspace name or UUID. |
+| `endpoint` | The endpoint associated with this permisson. |
+
+**Request Body**
+
+| Attribute | Description |
+| --------- | ----------- |
+| `negative` | If true, explicitly disallow the actions associated with the permissions tied to this resource. By default this value is false. |
+| `actions` | One or more actions associated with this permission. |
+
+**Response**
+
+```
+HTTP 200 OK
+```
+
+```json
+{
+ "actions": [
+ "delete",
+ "create",
+ "update",
+ "read"
+ ],
+ "created_at": 1557764438,
+ "endpoint": "/services",
+ "negative": false,
+ "role": {
+ "id": "23df9f20-e7cc-4da4-bc89-d3a08f976e50"
+ },
+ "workspace": "default"
+}
+```
+
+---
+
+
+
+## Delete a Role Endpoint Permission
+**Endpoint**
+
+/rbac/roles/{name_or_id}/endpoints/{worspace_name_or_id}/{endpoint}
+
+| Attribute | Description |
+| --------- | ----------- |
+| `name_or_id` | The RBAC role name or UUID. |
+| `worspace_name_or_id` | The worspace name or UUID. |
+| `endpoint` | The endpoint associated with this permisson. |
+
+**Response**
+
+```
+HTTP 204 No Content
+```
+
+---
+
+
+
+## Add a Role Entity Permission
+**Endpoint**
+/rbac/roles/{name_or_id}/entities
+
+| Attribute | Description |
+| --------- | ----------- |
+| `name_or_id` | The RBAC role name or UUID. |
+
+**Request Body**
+
+| Attribute | Description |
+| --------- | ----------- |
+| `negative` | If true, explicitly disallow the actions associated with the permissions tied to this resource. By default this value is false. |
+| `entity_id` | id of the entity associated with this permission. |
+| `actions` | One or more actions associated with this permission. |
+| `comment`optional | A string describing the RBAC permission object | + +`entity_id` must be the ID of an entity in Kong; if the ID of a +workspace is given, the permission will apply to all entities in that +workspace. Future entities belonging to that workspace will get the +same permissions. A wildcard `*` will be interpreted as **all +entities** in the system. + + +**Response** + +``` +HTTP 201 Created +``` + +```json +{ + "actions": [ + "delete", + "create", + "read" + ], + "created_at": 1557771505, + "entity_id": "*", + "entity_type": "wildcard", + "negative": false, + "role": { + "id": "bba049fa-bf7e-40ef-8e89-553dda292e99" + } +} +``` + +--- + +## Retrieve a Role Entity Permission +**Endpoint** +
/rbac/roles/{name_or_id}/entities/{entity_id}
+
+| Attribute | Description |
+| --------- | ----------- |
+| `name_or_id` | The RBAC permission name or UUID. |
+| `entity_id` | id of the entity associated with this permission. |
+
+**Response**
+
+```
+HTTP 200 Ok
+```
+
+```json
+{
+ "actions": [
+ "delete",
+ "create",
+ "read"
+ ],
+ "created_at": 1557771505,
+ "entity_id": "*",
+ "entity_type": "wildcard",
+ "negative": false,
+ "role": {
+ "id": "bba049fa-bf7e-40ef-8e89-553dda292e99"
+ }
+}
+```
+
+---
+
+## List Entity Permissons
+
+**Endpoint**
+/rbac/roles/{name_or_id}/entities
+
+| Attribute | Description |
+| --------- | ----------- |
+| `name_or_id` | The RBAC permisson name or UUID. |
+
+**Response**
+
+```
+HTTP 200 Ok
+```
+
+```json
+{
+ "data": [
+ {
+ "actions": [
+ "delete",
+ "create",
+ "read"
+ ],
+ "created_at": 1557771505,
+ "entity_id": "*",
+ "entity_type": "wildcard",
+ "negative": false,
+ "role": {
+ "id": "bba049fa-bf7e-40ef-8e89-553dda292e99"
+ }
+ }
+ ]
+}
+```
+
+---
+## Update an Entity Permission
+**Endpoint**
+
+/rbac/roles/{name_or_id}/entities/{entity_id}
+
+| Attribute | Description |
+| --------- | ----------- |
+| `name_or_id` | The RBAC role name or UUID. |
+| `entity_id` | The entity name or UUID. |
+
+**Request Body**
+
+| Attribute | Description |
+| --------- | ----------- |
+| `negative` | If true, explicitly disallow the actions associated with the permissions tied to this resource. By default this value is false. |
+| `actions` | One or more actions associated with this permission. |
+
+**Response**
+
+```
+HTTP 200 OK
+```
+
+```json
+{
+ "actions": [
+ "update"
+ ],
+ "created_at": 1557771505,
+ "entity_id": "*",
+ "entity_type": "wildcard",
+ "negative": false,
+ "role": {
+ "id": "bba049fa-bf7e-40ef-8e89-553dda292e99"
+ }
+}
+```
+
+---
+
+## Delete an Entity Permission
+**Endpoint**
+
+/rbac/roles/{name_or_id}/entities/{entity_id}
+
+| Attribute | Description |
+| --------- | ----------- |
+| `name_or_id` | The RBAC role name or UUID. |
+| `entity_id` | The entity name or UUID. |
+
+**Response**
+
+```
+HTTP 204 No Content
+```
+
+---
+
+## List Role Permissions
+**Endpoint**
+/rbac/roles/{name_or_id}/permissions/
+
+| Attribute | Description |
+| --------- | ----------- |
+| `name_or_id` | The RBAC role name or UUID. |
+
+
+**Response**
+
+```
+HTTP 200 OK
+```
+```json
+{
+ "endpoints": {
+ "*": {
+ "*": {
+ "actions": [
+ "delete",
+ "create",
+ "update",
+ "read"
+ ],
+ "negative": false
+ },
+ "/*/rbac/*": {
+ "actions": [
+ "delete",
+ "create",
+ "update",
+ "read"
+ ],
+ "negative": true
+ }
+ }
+ },
+ "entities": {}
+}
+```
+
+## Add a User to a Role
+**Endpoint**
+
+/rbac/users/{name_or_id}/roles
+
+| Attribute | Description |
+| --------- | ----------- |
+| `name_or_id` | The RBAC role name or UUID. |
+
+
+**Request Body**
+
+| Attribute | Description |
+| --------- | ----------- |
+| `roles` | Comma-separated list of role names to assign to the user. |
+
+**Response**
+
+```
+HTTP 201 Created
+```
+```json
+{
+ "roles": [
+ {
+ "created_at": 1557772263,
+ "id": "aae80073-095f-4553-ba9a-bee5ed3b8b91",
+ "name": "doc-knight"
+ }
+ ],
+ "user": {
+ "comment": null,
+ "created_at": 1557772232,
+ "enabled": true,
+ "id": "b65ca712-7ceb-4114-87f4-5c310492582c",
+ "name": "gruce-wayne",
+ "user_token": "$2b$09$gZnMKK/mm/d2rAXN7gL63uL43mjdX/62iwMqdyCQwLyC0af3ce/1K",
+ "user_token_ident": "88ea3"
+ }
+}
+```
+
+---
+## List a User's Roles
+**Endpoint**
+
+/rbac/users/{name_or_id}/roles
+
+| Attribute | Description |
+| --------- | ----------- |
+| `name_or_id` | The RBAC role name or UUID. |
+
+
+**Response**
+
+```
+HTTP 200 OK
+```
+```json
+
+{
+ "roles": [
+ {
+ "comment": "Read access to all endpoints, across all workspaces",
+ "created_at": 1557765500,
+ "id": "a1c810ee-8366-4654-ba0c-963ffb9ccf2e",
+ "name": "read-only"
+ },
+ {
+ "created_at": 1557772263,
+ "id": "aae80073-095f-4553-ba9a-bee5ed3b8b91",
+ "name": "doc-knight"
+ }
+ ],
+ "user": {
+ "comment": null,
+ "created_at": 1557772232,
+ "enabled": true,
+ "id": "b65ca712-7ceb-4114-87f4-5c310492582c",
+ "name": "gruce-wayne",
+ "user_token": "$2b$09$gZnMKK/mm/d2rAXN7gL63uL43mjdX/62iwMqdyCQwLyC0af3ce/1K",
+ "user_token_ident": "88ea3"
+ }
+}
+```
+
+---
+## Delete a Role from a User
+**Endpoint**
+
+/rbac/users/{name_or_id}/roles
+
+| Attribute | Description |
+| --------- | ----------- |
+| `name_or_id` | The RBAC role name or UUID. |
+
+
+**Request Body**
+
+| Attribute | Description |
+| --------- | ----------- |
+| `roles` | Comma-separated list of role names to assign to the user. |
+
+**Response**
+
+```
+HTTP 204 No Content
+```
+
+---
+
+## List a User's Permissions
+**Endpoint**
+
+/rbac/users/{name_or_id}/permissions
+
+| Attribute | Description |
+| --------- | ----------- |
+| `name_or_id` | The RBAC role name or UUID. |
+
+**Response**
+
+```
+HTTP 200 OK
+```
+```json
+{
+ "endpoints": {
+ "*": {
+ "*": {
+ "actions": [
+ "read"
+ ],
+ "negative": false
+ }
+ }
+ },
+ "entities": {}
+}
+
+```
diff --git a/app/enterprise/1.3-x/admin-api/vitals/index.md b/app/enterprise/1.3-x/admin-api/vitals/index.md
new file mode 100644
index 000000000000..bd3525e05362
--- /dev/null
+++ b/app/enterprise/1.3-x/admin-api/vitals/index.md
@@ -0,0 +1,197 @@
+---
+title: Kong Vitals
+---
+
+### Introduction
+
+Vitals is a feature within Kong's Admin API and Kong Manager that provides
+metrics about the health and performance of Kong nodes and Kong-proxied APIs.
+
+## Requirements
+
+- PostgresSQL 9.5+ or Cassandra 2.1+
+
+## How to Enable and Disable Vitals
+
+Kong Enterprise ships with Vitals enabled by default.
+
+Vitals can be disabled (or re-enabled) in the configuration file (e.g kong.conf):
+
+```bash
+# via your Kong configuration file; e.g., kong.conf
+vitals = on # vitals is enabled
+vitals = off # vitals is disabled
+```
+
+or by environment variables:
+
+```bash
+# or via environment variables
+$ export KONG_VITALS=on
+$ export KONG_VITALS=off
+```
+
+Kong must be restarted for these changes to take effect.
+
+## Vitals Metrics
+
+Vitals metrics fall into two categories:
+* Health Metrics - for monitoring the health of a Kong cluster
+* Traffic Metrics â for monitoring the usage of upstream services
+
+Within these categories, Vitals collects the following metrics:
+
+- [Health Metrics](#health-metrics)
+ - [Latency](#latency)
+ - [Proxy Latency (Request)](#proxy-latency-request)
+ - [Upstream Latency](#upstream-latency)
+ - [Datastore Cache](#datastore-cache)
+ - [Datastore Cache Hit/Miss](#datastore-cache-hit-miss)
+ - [Datastore Cache Hit Ratio](#datastore-cache-hit-ratio)
+- [Traffic Metrics](#traffic-metrics)
+ - [Request Counts](#request-counts)
+ - [Total Requests](#total-requests)
+ - [Requests per Consumer](#request-per-consumer)
+ - [Status Codes](#status-code)
+ - [Total Status Code Classes](#total-status-code-classes)
+ - [Total Status Codes per Service](#total-status-codes-per-service)
+ - [Total Status Codes per Route](#total-status-codes-per-route)
+ - [Total Status Codes per Consumer](#total-status-codes-per-consumer)
+ - [Total Status Codes per Consumer per Route](#total-status-codes-per-consumer-per-route)
+
+All metrics are collected at 1-second intervals and aggregated into 1-minute
+intervals. The 1-second intervals are retained for one hour. The 1-minute
+intervals are retained for 25 hours.
+
+If longer retention times are needed, the Vitals API can be used to pull metrics
+out of Kong and into a data retention tool.
+
+### Health Metrics
+
+Health metrics give insight into the performance of a Kong cluster; for example,
+how many requests it is processing and the latency on those requests.
+
+Health metrics are tracked for each node in a cluster as well as for the cluster
+as a whole. In Kong, a node is a running process with a unique identifier,
+configuration, cache layout, and connections to both Kongâs datastores and the
+upstream APIs it proxies. Note that node identifiers are unique to the process,
+and not to the host on which the process runs. In other words, each Kong restart
+results in a new node, and therefore a new node ID.
+
+#### Latency
+
+The Vitals API may return null for Latency metricsâthis occurs when no API
+requests were proxied during the timeframe. Null latencies are not graphed in
+Kong Managerâperiods with null latencies appear as gaps in Vitals charts.
+
+##### Proxy Latency (Request)
+
+The Proxy Latency metrics are the min, max, and average values for the time, in milliseconds, that the Kong proxy spends processing API proxy requests. This includes time to execute plugins that run in the access phase as well as DNS lookup time. This does not include time spent in Kongâs load balancer, time spent sending the request to the upstream, or time spent on the response.
+
+These metrics are referenced in the Vitals API with the following labels: `latency_proxy_request_min_ms`, `latency_proxy_request_max_ms`, `latency_proxy_request_avg_ms`
+
+Latency is not reported when a request is prematurely ended by Kong (e.g., bad auth, rate limited, etc.)ânote that this differs from the âTotal Requestsâ metric that does count such requests.
+
+##### Upstream Latency
+
+The Upstream Latency metrics are the min, max, and average values for the time elapsed, in milliseconds, between Kong sending requests upstream and Kong receiving the first bytes of responses from upstream.
+
+These metrics are referenced in the Vitals API with the following labels: `latency_upstream_min_ms`, `latency_upstream_max_ms`, `latency_upstream_avg_ms`
+
+#### Datastore Cache
+
+##### Datastore Cache Hit/Miss
+
+The Datastore Cache Hit/Miss metrics are the count of requests to Kong's node-level datastore cache. When Kong workers need configuration information to respond to a given API proxy request, they first check their worker-specific cache (also known as L1 cache), then if the information isnât available they check the node-wide datastore cache (also known as L2 cache). If neither cache contains the necessary information, Kong requests it from the datastore.
+
+A âHitâ indicates that an entity was retrieved from the data store cache. A âMissâ indicates that the record had to be fetched from the datastore. Not every API request will result in datastore cache accessâsome entities will be retrieved from Kong's worker-specific cache memory.
+
+These metrics are referenced in the Vitals API with the following labels: `cache_datastore_hits_total`, `cache_datastore_misses_total`
+
+##### Datastore Cache Hit Ratio
+
+This metric contains the ratio of datastore cache hits to the total count of datastore cache requests.
+
+> Note: Datastore Cache Hit Ratio cannot be calculated for time indices with no hits and no misses.
+
+### Traffic Metrics
+
+Traffic metrics provide insight into which of your services are being used, and by whom, and how they are responding.
+
+#### Request Counts
+
+##### Total Requests
+
+
+This metric is the count of all API proxy requests received. This includes requests that were rejected due to rate-limiting, failed authentication, etc.
+
+This metric is referenced in the Vitals API with the following label: `requests_proxy_total`
+
+##### Requests Per Consumer
+
+This metric is the count of all API proxy requests received from each specific consumer. Consumers are identified by credentials in their requests (e.g., API key, OAuth token, etc) as required by the Kong Auth plugin(s) in use.
+
+This metric is referenced in the Vitals API with the following label: `requests_consumer_total`
+
+#### Status Codes
+
+##### Total Status Code Classes
+
+This metric is the count of all status codes grouped by status code class (e.g. 4xx, 5xx).
+
+This metric is referenced in the Vitals API with the following label: `status_code_classes_total`
+
+##### Total Status Codes per Service
+
+This metric is the total count of each specific status code for a given service.
+
+This metric is referenced in the Vitals API with the following label: `status_codes_per_service_total`
+
+##### Total Status Codes per Route
+
+This metric is the total count of each specific status code for a given route.
+
+This metric is referenced in the Vitals API with the following label: `status_codes_per_route_total`
+
+##### Total Status Codes per Consumer
+This metric is the total count of each specific status code for a given consumer.
+
+This metric is referenced in the Vitals API with the following label: `status_codes_per_consumer_total`
+
+##### Total Status Codes per Consumer Per Route
+This metric is the total count of each specific status code for a given consumer and route.
+
+This metric is referenced in the Vitals API with the following label: `status_codes_per_consumer_route_total`
+
+## Vitals API
+Vitals data is available via endpoints on Kongâs Admin API. Access to these endpoints may be controlled via Admin API RBAC. The Vitals API is described in the attached OAS (Open API Spec, formerly Swagger) file [vitalsSpec.yaml][vitals_spec]
+
+## Vitals Data Visualization in Kong Manager
+
+Kong Manager includes visualization of Vitals data. Additional visualizations, dashboarding of Vitals data alongside data from other systems, etc., can be achieved using the Vitals API to integrate with common monitoring systems.
+
+### Time Frame Control
+
+A timeframe selector adjacent to Vitals charts in Kong Manager controls the timeframe of data visualized, which indirectly controls the granularity of the data. For example, the âLast 5 Minutesâ choice will display 1-second resolution data, while longer time frames will show 1-minute resolution data.
+
+Timestamps on the x-axis of Vitals charts are displayed either in the browser's local time zone, or in UTC, depending on the UTC option that appears adjacent to Vitals charts.
+
+### Cluster and Node Data
+Metrics can be displayed on Vitals charts at both node and cluster level. Controls are available to show cluster-wide metrics and/or node-specific metrics. Clicking on individual nodes will toggle the display of data from those nodes. Nodes can be identified by a unique Kong node identifier, by hostname, or by a combination of the two.
+
+### Status Code Data
+
+Visualizations of cluster-wide status code classes (1xx, 2xx, 3xx, 4xx, 5xx) can be found in the Status Codes page of Kong Manager. This page contains the counts of status code classes graphed over time, as well as the ratio of code classes to total requests. Note: this page does not include non-standard code classes (6xx, 7xx, etc.) Individual status code data can be viewed in the Consumer, Route, and Service details pages under the Activity tab. Both standard and non-standard status codes are visible in these views.
+
+## Known Issues
+
+Vitals data does not appear in Kong Manager or the Admin API.
+First, make sure Vitals is enabled. (`vitals = on` in your Kong configuration).
+
+Then, check your log files. If you see `[vitals] kong_vitals_requests_consumers cache is full` or `[vitals] error attempting to push to list: no memory`, then Vitals is no longer able to track requests because its cache is full. This condition may resolve itself if traffic to the node subsides long enough for it to work down the cache. Regardless, the node will continue to proxy requests as usual.
+
+### Limitations in Cassandra 2.x
+
+Vitals data is purged regularly: 1-second data is purged after one hour, and 1-minute data is purged after 25 hours. Due to limitations in Cassandra 2.x query options, the counter table vitals_consumers is not purged. If it becomes necessary to prune this table, you will need to do so manually.
+
+[vitals_spec]: /enterprise/{{page.kong_version}}/admin-api/vitals/vitalsSpec.yaml
diff --git a/app/enterprise/1.3-x/admin-api/vitals/vitals-influx-strategy.md b/app/enterprise/1.3-x/admin-api/vitals/vitals-influx-strategy.md
new file mode 100644
index 000000000000..aa142a5f1375
--- /dev/null
+++ b/app/enterprise/1.3-x/admin-api/vitals/vitals-influx-strategy.md
@@ -0,0 +1,135 @@
+---
+title: Kong Vitals with InfluxDB
+---
+
+## Overview
+
+This document covers integrating Kong Vitals with a new or existing InfluxDB
+time series server or cluster. Leveraging a time series database for Vitals data
+can improve request and Vitals performance in very-high traffic Kong Enterprise
+clusters (such as environments handling tens or hundreds of thousands of
+requests per second), without placing addition write load on the database
+backing the Kong cluster.
+
+For using Vitals with a database as the backend (i.e. PostgreSQL, Cassandra),
+please refer to [Kong Vitals](/enterprise/{{page.kong_version}}/admin-api/vitals/).
+
+## Getting Started
+
+### Preparing InfluxDB
+
+This guide assumes an existing InfluxDB server or cluster is already installed
+and is accepting write traffic. Production-ready InfluxDB installations should
+be deployed as a separate effort, but for proof-of-concept testing, running a
+local InfluxDB instance is possible via Docker:
+
+```bash
+$ docker run -p 8086:8086 \
+ -v $PWD:/var/lib/influxdb \
+ influxdb
+```
+
+Writing Vitals data to InfluxDB requires that the `kong` database is created.
+Currently, this operation must be done manually. This can be done via the
+`influx` CLI:
+
+```bash
+influx> create database kong;
+```
+
+Alternatively the [InfluxDB API](https://docs.influxdata.com/influxdb/v1.7/tools/api/#query-http-endpoint)
+may be queried directly to create the database.
+
+### Configuring Kong
+
+In addition to enabling Vitals, Kong must be configured to use InfluxDB as the
+backing strategy for Vitals. The InfluxDB host and port must also be defined:
+
+```
+vitals_strategy = influxdb
+vitals_tsdb_address = 127.0.0.1:8086 # the IP or hostname, and port, of InfluxDB
+```
+
+As with other Kong configurations, changes take effect on kong reload or kong
+restart.
+
+## InfluxDB Measurements
+
+Kong Vitals records metrics in two InfluxDB measurements- `kong_request`, which
+contains field values for request latencies and HTTP, and tags for various Kong
+entities associated with the requests (e.g., the Route and Service in question,
+etc.), and `kong_datastore_cache`, which contains points about cache hits and
+misses. Measurement schemas are listed below:
+
+```
+> show tag keys
+name: kong_request
+tagKey
+------
+consumer
+hostname
+route
+service
+status_f
+wid
+workspace
+
+name: kong_datastore_cache
+tagKey
+------
+hostname
+wid
+```
+
+```
+> show field keys
+name: kong_request
+fieldKey fieldType
+-------- ---------
+kong_latency integer
+proxy_latency integer
+request_latency integer
+status integer
+
+name: kong_datastore_cache
+fieldKey fieldType
+-------- ---------
+
+hits integer
+misses integer
+```
+
+The tag `wid` is used to differentiate the unique worker ID per host, to avoid
+duplicate metrics shipped at the same point in time.
+
+As demonstrated above, the series cardinality of the `kong_request` measurement
+varies based on the cardinality of the Kong cluster configuration - a greater
+number of Service/Route/Consumer/Workspace combinations handled by Kong results
+in a greater series cardinality as written by Vitals. Please consult the
+[InfluxDB sizing guidelines](https://docs.influxdata.com/influxdb/v1.7/guides/hardware_sizing/)
+for reference on appropriately sizing an InfluxDB node/cluster. Note that the
+query behavior when reading Vitals data falls under the "moderate" load
+category as defined by the above document - several `GROUP BY` statements and
+functions are used to generate the Vitals API responses, which can require
+significant CPU resources to execute when hundreds of thousands or millions of
+data points are present.
+
+## Query Behavior
+
+Kong buffers Vitals metrics and writes InfluxDB points in batches to improve
+throughput in InfluxDB and reduce overhead in the Kong proxy path. Each Kong
+worker process flushes its buffer of metrics every 5 seconds or 5000 data points,
+whichever comes first.
+
+Metrics points are written with microsecond (`u`) precision. To comply with
+the [Vitals API](/enterprise/{{page.kong_version}}/admin-api/vitals/#vitals-api), measurement
+values are read back grouped by second. Note that due to limitations in the
+OpenResty API, writing values with microsecond precision requires an additional
+syscall per request.
+
+Currently, Vitals InfluxDB data points are not downsampled or managed via
+retention policy by Kong. InfluxDB operators are encouraged to manually manage
+the retention policy of the `kong` database to reduce the disk space and memory
+needed to manage Vitals data points. Currently, Kong Vitals ignores data points
+older than 25 hours; it is safe to create a retention policy with a 25-hour
+duration for measurements written by Kong.
diff --git a/app/enterprise/1.3-x/admin-api/vitals/vitals-prometheus-strategy.md b/app/enterprise/1.3-x/admin-api/vitals/vitals-prometheus-strategy.md
new file mode 100644
index 000000000000..8403b8015155
--- /dev/null
+++ b/app/enterprise/1.3-x/admin-api/vitals/vitals-prometheus-strategy.md
@@ -0,0 +1,221 @@
+---
+title: Kong Vitals with Prometheus
+---
+
+For using Vitals with a database as the backend (i.e. PostgreSQL, Cassandra),
+please refer to [Kong Vitals](/enterprise/{{page.kong_version}}/admin-api/vitals/).
+
+## Setup Prometheus environment for Vitals
+
+### Download Prometheus
+
+The latest release of Prometheus can be found at the [Prometheus download page](https://prometheus.io/download/#prometheus).
+
+Prometheus should be running on a separate node from the one running Kong.
+For users that are already using Prometheus in their infrastructure, it's
+possible to use existing Prometheus nodes as Vitals storage backend.
+
+In this guide, we assume Prometheus is running on hostname `prometheus-node`
+using default config that listens on port `9090`.
+
+### Download and configure StatsD exporter
+
+The latest release of StatsD exporter can be found at the
+[Bintray](https://bintray.com/kong/statsd-exporter). The binary is distributed
+with some specific features like min/max gauges and Unix domain socket support.
+
+StatsD exporter needed to configured with a set of mapping rules to translate
+the StatsD UDP events to Prometheus metrics. A default set of mapping rules can
+be downloaded at
+[statsd.rules.yaml](/enterprise/{{page.kong_version}}/plugins/statsd.rules.yaml).
+Then start StatsD exporter with
+
+```bash
+$ ./statsd_exporter --statsd.mapping-config=statsd.rules.yaml \
+ --statsd.listen-unixgram=''
+```
+
+The StatsD mapping rules file must be configured to match the metrics sent from
+Kong. To learn how to customize the StatsD events name, please refer to
+[Enable Vitals with Prometheus strategy in Kong](#enable-Vitals-with-prometheus-strategy-in-kong)
+section.
+
+StatsD exporter can run either on a separate node from Kong (to avoid resource
+competition with Kong), or on the same host with Kong (to reduce unnecessary
+network overhead).
+
+In this guide, we assume StatsD exporter is running on hostname `statsd-node`,
+using default config that listens to UDP traffic on port `9125` and the metrics
+in Prometheus Exposition Format are exposed on port `9102`.
+
+### Configure Prometheus to scrape StatsD exporter
+
+To configure Prometheus to scrape StatsD exporter, add the following section to
+`scrape_configs` in `prometheus.yaml`.
+
+```yaml
+scrape_configs:
+ - job_name: 'vitals_statsd_exporter'
+ scrape_interval: "5s"
+ static_configs:
+ - targets: ['statsd-node:9102']
+```
+
+Please update `statsd-node` with the actual hostname that runs StatsD exporter.
+
+If you are using service discovery, it will be more convenient to configure
+multiple StatsD exporters in Prometheus. Please refer to the
+[scape_configs](https://prometheus.io/docs/prometheus/latest/configuration/configuration/#%3Cscrape_config%3E)
+section of Prometheus document for further reading.
+
+By default, the Vitals graph in Kong Manager uses the configured target address
+in the legend, which is named `instance` in the Prometheus metrics label. For some service
+discovery setups where `instance` is `IP:PORT`, the user might want to relabel the `instance`
+label to display a more meaningful hostname in the legend.
+To do so, the user can also refer to the [scape_configs](https://prometheus.io/docs/prometheus/latest/configuration/configuration/#%3Cscrape_config%3E)
+section and rewrite the `instance` label with the corresponding meta label.
+
+For example, in a Kubernetes environment, use the following relabel rules:
+
+```yaml
+scrape_configs:
+ - job_name: 'vitals_statsd_exporter'
+ kubernetes_sd_configs:
+ # your SD config to filter statsd exporter pods
+ relabel_configs:
+ - source_labels: [__meta_kubernetes_pod_name]
+ action: replace
+ target_label: 'instance'
+```
+
+### Enable Vitals with Prometheus strategy in Kong
+
+You can change this in your configuration to enable Vitals with Prometheus:
+
+```bash
+# via your Kong configuration file
+vitals = on
+vitals_strategy = prometheus
+vitals_statsd_address = statsd-node:9125
+vitals_tsdb_address = prometheus-node:9090
+```
+
+```bash
+# or via environment variables
+$ export KONG_VITALS=on
+$ export KONG_VITALS_STRATEGY=prometheus
+$ export KONG_VITALS_STATSD_ADDRESS=statsd-node:9125
+$ export KONG_VITALS_TSDB_ADDRESS=prometheus-node:9090
+```
+
+Please update `statsd-node` and `prometheus-node` with the actual hostname that
+runs StatsD exporter and Prometheus.
+
+As with other Kong configurations, your changes take effect on `kong reload` or
+`kong restart`.
+
+If you set `scrape_interval` in Prometheus other than the default value of `5`
+seconds, you will also need to update the following:
+
+```bash
+# via your Kong configuration file
+vitals_prometheus_scrape_interval = new_value_in_seconds
+```
+
+```bash
+# or via environment variables
+$ export KONG_VITALS_PROMETHEUS_SCRAPE_INTERVAL=new_value_in_seconds
+```
+
+The above option configures `interval` parameter when querying Prometheus.
+The value `new_value_in_seconds` should be equal or larger than
+`scrape_interval` config in Prometheus.
+
+You can also configure Kong to send StatsD events with a different prefix from
+the default value of `kong`. Make sure the prefix in statsd.rules
+is same as that in Kong configuration:
+
+```bash
+# via your Kong configuration file
+vitals_statsd_prefix = kong-vitals
+```
+
+```bash
+# or via environment variables
+$ export KONG_VITALS_STATSD_PREFIX=kong-vitals
+```
+
+```yaml
+# in statsd.rules
+mappings:
+# by API
+- match: kong-vitals.api.*.request.count
+ name: "kong_requests_proxy"
+ labels:
+ job: "kong_metrics"
+# follows other metrics
+# ...
+```
+
+## Tuning and Optimization
+
+### StatsD exporter UDP buffer
+
+As the amount of concurrent requests increases, the length of the queue to store
+unprocessed UDP events will grow as well.
+It's necessary to increase the UDP read buffer size to avoid possible packet
+dropping.
+
+To increase the UDP read buffer for the StatsD exporter process, run the binary
+using the following example to set read buffer to around 3 MB:
+
+```
+$ ./statsd_exporter --statsd.mapping-config=statsd.rules.yaml \
+ --statsd.listen-unixgram='' \
+ --statsd.read-buffer=30000000
+```
+
+To increase the UDP read buffer for the host that's running, adding the
+following example line to `/etc/sysctl.conf`:
+
+```
+net.core.rmem_max = 60000000
+```
+
+And then apply the setting with root privilege:
+
+```
+# sysctl -p
+```
+
+### StatsD exporter with Unix domain socket
+
+It is possible to further reduce network overhead by deploying StatsD exporter
+on the same node with Kong and let the exporter listen on local Unix domain
+socket.
+
+```bash
+$ ./statsd_exporter --statsd.mapping-config=statsd.rules.yaml \
+ --statsd.read-buffer=30000000 \
+ --statsd.listen-unixgram='/tmp/statsd.sock'
+```
+
+By default the socket is created with permission `0755`, so that StatsD exporter
+ has to be running with the same user with Kong to allow Kong to write UDP
+ packets to the socket. To allow the exporter and Kong to run as different
+ users, the socket can be created with permission `0777` with the following:
+
+```bash
+$ ./statsd_exporter --statsd.mapping-config=statsd.rules.yaml \
+ --statsd.read-buffer=30000000 \
+ --statsd.listen-unixgram='/tmp/statsd.sock' \
+ --statsd.unixsocket-umask="777"
+```
+
+
+## Accessing Vitals metrics from Prometheus
+
+You can also access Kong Vitals metrics in Prometheus and display on Grafana
+or setup alerting rules. With the example StatsD mapping rules, all metrics are
+labeled with `exported_job=kong_vitals`. With the above Prometheus scrape config
+above, all metrics are also labeled with `job=vitals_statsd_exporter`.
diff --git a/app/enterprise/1.3-x/admin-api/vitals/vitalsSpec.yaml b/app/enterprise/1.3-x/admin-api/vitals/vitalsSpec.yaml
new file mode 100644
index 000000000000..78ebda2b54b4
--- /dev/null
+++ b/app/enterprise/1.3-x/admin-api/vitals/vitalsSpec.yaml
@@ -0,0 +1,734 @@
+swagger: '2.0'
+info:
+ description: Vitals API
+ version: 1.3.0
+ title: Vitals API
+basePath: /
+tags:
+ - name: health
+ description: Stats about the health of a Kong cluster
+ - name: traffic
+ description: Stats about traffic routed through Kong
+schemes:
+ - http
+paths:
+ /vitals:
+ get:
+ tags:
+ - vitals
+ summary: Get information about stats collected
+ description: ''
+ operationId: getVitalsInfo
+ produces:
+ - application/json
+ responses:
+ '200':
+ description: successful operation
+ schema:
+ $ref: '#/definitions/VitalsInfo'
+ /vitals/cluster:
+ get:
+ tags:
+ - health
+ summary: Get health stats for this Kong cluster
+ description: ''
+ operationId: getClusterStats
+ produces:
+ - application/json
+ parameters:
+ - name: interval
+ in: query
+ description: Granularity of the time series (minutes or seconds)
+ required: true
+ type: string
+ - name: start_ts
+ in: query
+ description: 'Requested start of the time series, in Unix epoch format (seconds)'
+ required: true
+ type: string
+ responses:
+ '200':
+ description: successful operation
+ schema:
+ $ref: '#/definitions/ClusterVitalsTimeSeriesWithMetadata'
+ '400':
+ description: Invalid query params
+ /vitals/cluster/status_codes:
+ get:
+ deprecated: true
+ tags:
+ - traffic
+ summary: Get the status code classes returned across the cluster
+ description: This operation is deprecated. Use /status_code_classes.
+ operationId: getClusterStatusCodeStats
+ produces:
+ - application/json
+ parameters:
+ - name: interval
+ in: query
+ description: Granularity of the time series (minutes or seconds)
+ required: true
+ type: string
+ - name: start_ts
+ in: query
+ description: 'Requested start of the time series, in Unix epoch format (seconds)'
+ required: true
+ type: string
+ responses:
+ '200':
+ description: successful operation
+ schema:
+ $ref: '#/definitions/ClusterVitalsStatusCodesWithMetadata'
+ '400':
+ description: Invalid query params
+ /vitals/nodes:
+ get:
+ tags:
+ - health
+ summary: Get health stats for all nodes
+ description: ''
+ operationId: getAllNodeStats
+ produces:
+ - application/json
+ parameters:
+ - name: interval
+ in: query
+ description: Granularity of the time series (minutes or seconds)
+ required: true
+ type: string
+ - name: start_ts
+ in: query
+ description: 'Requested start of the time series, in Unix epoch format (seconds)'
+ required: true
+ type: string
+ responses:
+ '200':
+ description: successful operation
+ schema:
+ $ref: '#/definitions/NodeVitalsTimeSeriesWithMetadata'
+ '400':
+ description: Invalid query params
+ '/vitals/nodes/{node_id}':
+ get:
+ tags:
+ - health
+ summary: Get stats for a specific node by UUID
+ description: ''
+ operationId: getNodeStatsByID
+ produces:
+ - application/json
+ parameters:
+ - name: node_id
+ type: string
+ in: path
+ description: Node to retrieve stats for
+ required: true
+ - name: interval
+ in: query
+ description: Granularity of the time series (minutes or seconds)
+ required: true
+ type: string
+ - name: start_ts
+ in: query
+ description: 'Requested start of the time series, in Unix epoch format (seconds)'
+ required: true
+ type: string
+ responses:
+ '200':
+ description: successful operation
+ schema:
+ $ref: '#/definitions/NodeVitalsTimeSeriesWithMetadata'
+ '400':
+ description: Invalid query params
+ '404':
+ description: Unable to find requested node
+ '/vitals/consumers/{consumer_id}/cluster':
+ get:
+ tags:
+ - traffic
+ deprecated: true
+ summary: Get count of requests for the given consumer across entire cluster
+ description: This operation is deprecated. Use /vitals/status_codes/by_consumer_and_route
+ operationId: getConsumerClusterStats
+ produces:
+ - application/json
+ parameters:
+ - name: consumer_id
+ type: string
+ in: path
+ description: Consumer to retrieve stats for
+ required: true
+ - name: interval
+ type: string
+ in: query
+ description: Granularity of the time series (minutes or seconds)
+ required: true
+ - name: start_ts
+ in: query
+ description: 'Requested start of the time series, in Unix epoch format (seconds)'
+ required: true
+ type: string
+ responses:
+ '200':
+ description: successful operation
+ schema:
+ $ref: '#/definitions/ClusterConsumersTimeSeriesWithMetadata'
+ '400':
+ description: Invalid query params
+ '404':
+ description: Unable to find requested consumer
+ /{workspace_name}/vitals/status_code_classes:
+ get:
+ tags:
+ - traffic
+ summary: Get status code classes for a cluster or workspace.
+ description: ''
+ operationId: getStatusCodeClassesByWorkspace
+ produces:
+ - application/json
+ parameters:
+ - name: workspace_name
+ type: string
+ in: path
+ description: >-
+ Optional parameter. If provided, returns status code classes for the
+ workspace; otherwise, returns them for the cluster
+ required: true
+ - name: interval
+ type: string
+ in: query
+ description: Granularity of the time series (minutes or seconds)
+ required: true
+ - name: start_ts
+ in: query
+ description: 'Requested start of the time series, in Unix epoch format (seconds)'
+ required: true
+ type: string
+ responses:
+ '200':
+ description: successful operation
+ schema:
+ $ref: '#/definitions/StatusCodesByEntityMetadata'
+ '400':
+ description: Invalid query params
+ '404':
+ description: Unable to find requested consumer
+ /{workspace_name}/vitals/status_codes/by_service:
+ get:
+ tags:
+ - traffic
+ summary: Get a time series of status codes returned by a given service
+ description: ''
+ operationId: getStatusCodesByService
+ produces:
+ - application/json
+ parameters:
+ - name: service_id
+ type: string
+ in: query
+ description: Service to retrieve status codes for
+ required: true
+ - name: interval
+ type: string
+ in: query
+ description: Granularity of the time series (minutes or seconds)
+ required: true
+ - name: start_ts
+ in: query
+ description: 'Requested start of the time series, in Unix epoch format (seconds)'
+ required: true
+ type: string
+ - name: workspace_name
+ type: string
+ in: path
+ description: >-
+ This parameter is optional. When present, it limits the result to a
+ specific workspace.
+ required: true
+ responses:
+ '200':
+ description: successful operation
+ schema:
+ $ref: '#/definitions/StatusCodesByEntityTimeSeriesWithMetadata'
+ '400':
+ description: Invalid query params
+ '404':
+ description: Unable to find requested service
+ /{workspace_name}/vitals/status_codes/by_route:
+ get:
+ tags:
+ - traffic
+ summary: Get cluster-wide count of status for a given route
+ description: ''
+ operationId: getStatusCodesByRoute
+ produces:
+ - application/json
+ parameters:
+ - name: route_id
+ type: string
+ in: query
+ description: Route to retrieve status codes for
+ required: true
+ - name: interval
+ type: string
+ in: query
+ description: Granularity of the time series (minutes or seconds)
+ required: true
+ - name: start_ts
+ in: query
+ description: 'Requested start of the time series, in Unix epoch format (seconds)'
+ required: true
+ type: string
+ - name: workspace_name
+ type: string
+ in: path
+ description: >-
+ This parameter is optional. When present, it limits the result to a
+ specific workspace.
+ required: true
+ responses:
+ '200':
+ description: successful operation
+ schema:
+ $ref: '#/definitions/StatusCodesByEntityTimeSeriesWithMetadata'
+ '400':
+ description: Invalid query params
+ '404':
+ description: Unable to find requested route
+ '/{workspace_name}/vitals/status_codes/by_consumer_and_route':
+ get:
+ tags:
+ - traffic
+ summary: >-
+ Get status codes for all the routes called by the given consumer in the
+ given timeframe
+ description: ''
+ operationId: getStatusCodesByConsumerAndRoute
+ produces:
+ - application/json
+ parameters:
+ - name: consumer_id
+ type: string
+ in: query
+ description: Consumer to retrieve status codes for
+ required: true
+ - name: interval
+ type: string
+ in: query
+ description: Granularity of the time series (minutes or seconds)
+ required: true
+ - name: start_ts
+ in: query
+ description: 'Requested start of the time series, in Unix epoch format (seconds)'
+ required: true
+ type: string
+ - name: workspace_name
+ type: string
+ in: path
+ description: >-
+ This parameter is optional. When present, it limits the result to a
+ specific workspace.
+ required: true
+ responses:
+ '200':
+ description: successful operation
+ schema:
+ $ref: '#/definitions/StatusCodesByEntityTimeSeriesWithMetadata'
+ '400':
+ description: Invalid query params
+ '404':
+ description: Unable to find requested consumer
+definitions:
+ ClusterVitalsMetadata:
+ properties:
+ level:
+ type: string
+ example: cluster
+ enum:
+ - cluster
+ - node
+ workspace_id:
+ type: string
+ description: UUID of workspace this time series is for
+ interval:
+ type: string
+ example: seconds
+ enum:
+ - seconds
+ - minutes
+ interval_width:
+ type: number
+ example: 60
+ earliest_ts:
+ type: integer
+ example: 1514508300
+ latest_ts:
+ type: integer
+ example: 1514508480
+ stat_labels:
+ type: array
+ items:
+ type: string
+ example:
+ - cache_datastore_hits_total
+ - cache_datastore_misses_total
+ - latency_proxy_request_min_ms
+ - latency_proxy_request_max_ms
+ - latency_upstream_min_ms
+ - latency_upstream_max_ms
+ - requests_proxy_total
+ - latency_proxy_request_avg_ms
+ - latency_upstream_avg_ms
+ StatusCodesByEntityMetadata:
+ properties:
+ entity_type:
+ type: string
+ example: service|route
+ entity_id:
+ type: string
+ example: /workspaces/
+
+#### Request Body
+
+{{ page.workspace_body }}
+
+**Response**
+
+```
+HTTP 201 Created
+```
+
+```json
+{
+ "comment": null,
+ "config": {
+ "meta": null,
+ "portal": false,
+ "portal_access_request_email": null,
+ "portal_approved_email": null,
+ "portal_auth": null,
+ "portal_auth_conf": null,
+ "portal_auto_approve": null,
+ "portal_cors_origins": null,
+ "portal_developer_meta_fields": "[{\"label\":\"Full Name\",\"title\":\"full_name\",\"validator\":{\"required\":true,\"type\":\"string\"}}]",
+ "portal_emails_from": null,
+ "portal_emails_reply_to": null,
+ "portal_invite_email": null,
+ "portal_reset_email": null,
+ "portal_reset_success_email": null,
+ "portal_token_exp": null
+ },
+ "created_at": 1557441226,
+ "id": "c663cca5-c6f6-474a-ae44-01f62aba16a9",
+ "meta": {
+ "color": null,
+ "thumbnail": null
+ },
+ "name": "green-team"
+}
+```
+
+### List Workspaces
+
+**Endpoint**
+
+/workspaces/
+
+**Response**
+
+```
+HTTP 200 OK
+```
+
+```json
+{
+ "data": [
+ {
+ "comment": null,
+ "config": {
+ "meta": null,
+ "portal": false,
+ "portal_access_request_email": null,
+ "portal_approved_email": null,
+ "portal_auth": null,
+ "portal_auth_conf": null,
+ "portal_auto_approve": null,
+ "portal_cors_origins": null,
+ "portal_developer_meta_fields": "[{\"label\":\"Full Name\",\"title\":\"full_name\",\"validator\":{\"required\":true,\"type\":\"string\"}}]",
+ "portal_emails_from": null,
+ "portal_emails_reply_to": null,
+ "portal_invite_email": null,
+ "portal_reset_email": null,
+ "portal_reset_success_email": null,
+ "portal_token_exp": null
+ },
+ "created_at": 1557419951,
+ "id": "00000000-0000-0000-0000-000000000000",
+ "meta": {
+ "color": null,
+ "thumbnail": null
+ },
+ "name": "default"
+ },
+ {
+ "comment": null,
+ "config": {
+ "meta": null,
+ "portal": false,
+ "portal_access_request_email": null,
+ "portal_approved_email": null,
+ "portal_auth": null,
+ "portal_auth_conf": null,
+ "portal_auto_approve": null,
+ "portal_cors_origins": null,
+ "portal_developer_meta_fields": "[{\"label\":\"Full Name\",\"title\":\"full_name\",\"validator\":{\"required\":true,\"type\":\"string\"}}]",
+ "portal_emails_from": null,
+ "portal_emails_reply_to": null,
+ "portal_invite_email": null,
+ "portal_reset_email": null,
+ "portal_reset_success_email": null,
+ "portal_token_exp": null
+ },
+ "created_at": 1557441226,
+ "id": "c663cca5-c6f6-474a-ae44-01f62aba16a9",
+ "meta": {
+ "color": null,
+ "thumbnail": null
+ },
+ "name": "green-team"
+ }
+ ],
+ "next": null
+}
+```
+
+### Update or Create a Workspace
+
+**Endpoint**
+
+/workspaces/{id}
+
+Attributes | Description
+---:| ---
+`id`**conditional** | The **Workspace's** unique ID, if replacing it.* + +* The behavior of `PUT` endpoints is the following: if the request payload **does +not** contain an entity's primary key (`id` for Workspaces), the entity will be +created with the given payload. If the request payload **does** contain an +entity's primary key, the payload will "replace" the entity specified by the +given primary key. If the primary key is **not** that of an existing entity, `404 +NOT FOUND` will be returned. + +#### Request Body + +Attribute | Description +---:| --- +`name` | The **Workspace** name. + +**Response** + +If creating the entity: + +``` +HTTP 201 Created +``` + +If replacing the entity: + +``` +HTTP 200 OK +``` + +```json +{ + "comment": null, + "config": { + "meta": null, + "portal": false, + "portal_access_request_email": null, + "portal_approved_email": null, + "portal_auth": null, + "portal_auth_conf": null, + "portal_auto_approve": null, + "portal_cors_origins": null, + "portal_developer_meta_fields": "[{\"label\":\"Full Name\",\"title\":\"full_name\",\"validator\":{\"required\":true,\"type\":\"string\"}}]", + "portal_emails_from": null, + "portal_emails_reply_to": null, + "portal_invite_email": null, + "portal_reset_email": null, + "portal_reset_success_email": null, + "portal_token_exp": null + }, + "created_at": 1557504202, + "id": "c663cca5-c6f6-474a-ae44-01f62aba16a9", + "meta": { + "color": null, + "thumbnail": null + }, + "name": "rocket-team" +} +``` + +### Retrieve a Workspace + +**Endpoint** + +
/workspaces/{name or id}
+
+Attributes | Description
+---:| ---
+`name or id`**required** | The unique identifier **or** the name of the **Workspace** to retrieve + +**Response** + +``` +HTTP 200 OK +``` + +```json +{ + "config": { + "portal": false, + "portal_developer_meta_fields": "[{\"label\":\"Full Name\",\"title\":\"full_name\",\"validator\":{\"required\":true,\"type\":\"string\"}}]" + }, + "created_at": 1557504202, + "id": "c663cca5-c6f6-474a-ae44-01f62aba16a9", + "meta": { }, + "name": "rocket-team" +} +``` + +### Retrieve Workspace Metadata + +#### Endpoint + +
/workspaces/{name or id}/meta
+
+Attributes | Description
+---:| ---
+`name or id`**required** | The unique identifier **or** the name of the **Workspace** to retrieve + +#### Response + +``` +HTTP 200 OK +``` + +```json +{ + "counts": { + "acls": 1, + "apis": 1, + "basicauth_credentials": 1, + "consumers": 1234, + "files": 41, + "hmacauth_credentials": 1, + "jwt_secrets": 1, + "keyauth_credentials": 1, + "oauth2_authorization_codes": 1, + "oauth2_credentials": 1, + "oauth2_tokens": 1, + "plugins": 5, + "rbac_roles": 3, + "rbac_users": 12, + "routes": 15, + "services": 2, + "ssl_certificates": 1, + "ssl_servers_names": 1, + "targets": 1, + "upstreams": 1 + } +} +``` + +### Delete a Workspace + +**Endpoint** + +
/workspaces/{name or id}
+
+Attributes | Description
+---:| ---
+`name or id`**required** | The unique identifier **or** the name of the **Workspace** to delete + +**Note:** All entities within a **Workspace** must be deleted before the +**Workspace** itself can be. + +**Response** + +``` +HTTP 204 No Content +``` + +### Update a Workspace + +**Endpoint** + +
/workspaces/{name or id}
+
+Attributes | Description
+---:| ---
+`name or id`**required** | The unique identifier **or** the name of the **Workspace** to patch + +#### Request Body + +Attributes | Description +---:| --- +`comment` | A string describing the **Workspace** + +The behavior of `PATCH` endpoints prevents the renaming of a **Workspace**. + +**Response** + +``` +HTTP 200 OK +``` + +```json +{ + "comment": "this is a sample comment in the patch request", + "config": { + "meta": null, + "portal": false, + "portal_access_request_email": null, + "portal_approved_email": null, + "portal_auth": null, + "portal_auth_conf": null, + "portal_auto_approve": null, + "portal_cors_origins": null, + "portal_developer_meta_fields": "[{\"label\":\"Full Name\",\"title\":\"full_name\",\"validator\":{\"required\":true,\"type\":\"string\"}}]", + "portal_emails_from": null, + "portal_emails_reply_to": null, + "portal_invite_email": null, + "portal_reset_email": null, + "portal_reset_success_email": null, + "portal_token_exp": null + }, + "created_at": 1557509909, + "id": "c543d2c8-d297-4c9c-adf5-cd64212868fd", + "meta": { + "color": null, + "thumbnail": null + }, + "name": "green-team" +} +``` + +### Add entities to a Workspace + +Workspaces are groups of entities. This endpoint allows one to add an entity, +identified by its unique identifier, to a **Workspace**. + +**Endpoint** + +
/workspaces/{name or id}/entities
+
+#### Request Body
+
+{{ page.workspace_entities_body }}
+
+**Response**
+
+```
+HTTP 200 Created
+```
+
+```json
+[
+ {
+ "connect_timeout": 60000,
+ "created_at": 1557510770,
+ "host": "httpbin.com",
+ "id": "8e15ca43-1d14-4f58-8f05-0327af74b5c5",
+ "name": "testservice",
+ "port": 80,
+ "protocol": "http",
+ "read_timeout": 60000,
+ "retries": 5,
+ "updated_at": 1557510770,
+ "write_timeout": 60000
+ }
+]
+```
+
+The response is the representation of the entity that was added to the
+workspaceâin this case, a Service.
+
+### List entities that are part of a Workspace
+
+**Endpoint**
+
+/workspaces/{name or id}/entities
+
+**Response**
+
+```
+HTTP 200 OK
+```
+
+```json
+{
+ "data": [
+ {
+ "entity_id": "8e15ca43-1d14-4f58-8f05-0327af74b5c5",
+ "entity_type": "services",
+ "unique_field_name": "name",
+ "unique_field_value": "testservice",
+ "workspace_id": "c543d2c8-d297-4c9c-adf5-cd64212868fd",
+ "workspace_name": "green-team"
+ },
+ {
+ "entity_id": "8e15ca43-1d14-4f58-8f05-0327af74b5c5",
+ "entity_type": "services",
+ "unique_field_name": "id",
+ "unique_field_value": "8e15ca43-1d14-4f58-8f05-0327af74b5c5",
+ "workspace_id": "c543d2c8-d297-4c9c-adf5-cd64212868fd",
+ "workspace_name": "green-team"
+ }
+ ],
+ "total": 2
+}
+```
+
+In this case, the **Workspace** references two Services.
+
+### Delete entities from a Workspace
+
+**Endpoint**
+
+/workspaces/{name or id}/entities
+
+#### Request Body
+
+{{ page.workspace_entities_body }}
+
+**Response**
+
+```
+HTTP 204 No Content
+```
+
+### Retrieve an entity from a Workspace
+
+This endpoint allows one to retrieve an entity from a workspaceâuseful, say,
+for checking if a given entity is part of a given **Workspace**.
+
+**Endpoint**
+
+/workspaces/{name or id}/entities/{name or id}
+
+**Response**
+
+```
+HTTP 200 OK
+```
+
+```json
+{
+ "entity_id": "8e15ca43-1d14-4f58-8f05-0327af74b5c5",
+ "entity_type": "services",
+ "workspace_id": "c543d2c8-d297-4c9c-adf5-cd64212868fd",
+ "workspace_name": "green-team"
+}
+```
+
+### Delete a particular entity from a Workspace
+
+**Endpoint**
+
+/workspaces/{name or id}/entities/{name or id}
+
+**Response**
+
+```
+HTTP 204 No Content
+```
+
+---
+
+[Admin API]: /enterprise/{{page.kong_version}}/admin-api/
diff --git a/app/enterprise/1.3-x/auth.md b/app/enterprise/1.3-x/auth.md
new file mode 100644
index 000000000000..f190620128e8
--- /dev/null
+++ b/app/enterprise/1.3-x/auth.md
@@ -0,0 +1,215 @@
+---
+title: Authentication Reference
+---
+
+## Introduction
+
+Traffic to your upstream services (APIs or microservices) is typically controlled by the application and
+configuration of various Kong [authentication plugins][plugins]. Since Kong's Service entity represents
+a 1-to-1 mapping of your own upstream services, the simplest scenario is to configure authentication
+plugins on the Services of your choosing.
+
+## Generic authentication
+
+The most common scenario is to require authentication and to not allow access for any unauthenticated request.
+To achieve this any of the authentication plugins can be used. The generic scheme/flow of those plugins
+works as follows:
+
+1. Apply an auth plugin to a Service, or globally (you cannot apply one on consumers)
+2. Create a `consumer` entity
+3. Provide the consumer with authentication credentials for the specific authentication method
+4. Now whenever a request comes in Kong will check the provided credentials (depends on the auth type) and
+it will either block the request if it cannot validate, or add consumer and credential details
+in the headers and forward the request
+
+The generic flow above does not always apply, for example when using external authentication like LDAP,
+then there is no consumer to be identified, and only the credentials will be added in the forwarded headers.
+
+The authentication method specific elements and examples can be found in each [plugin's documentation][plugins].
+
+## Consumers
+
+The easiest way to think about consumers is to map them one-on-one to users. Yet, to Kong this does not matter.
+The core principle for consumers is that you can attach plugins to them, and hence customize request behaviour.
+So you might have mobile apps, and define one consumer for each app, or version of it. Or have a consumer per
+platform, e.g. an android consumer, an iOS consumer, etc.
+
+It is an opaque concept to Kong and hence they are called "consumers" and not "users".
+
+## Anonymous Access
+
+Kong has the ability to configure a given Service to allow **both** authenticated **and** anonymous access.
+You might use this configuration to grant access to anonymous users with a low rate-limit, and grant access
+to authenticated users with a higher rate limit.
+
+To configure a Service like this, you first apply your selected authentication plugin, then create a new
+consumer to represent anonymous users, then configure your authentication plugin to allow anonymous
+access. Here is an example, which assumes you have already configured a Service named `example-service` and
+the corresponding route:
+
+1. ### Create an example Service and a Route
+
+ Issue the following cURL request to create `example-service` pointing to mockbin.org, which will echo
+ the request:
+
+ ```bash
+ $ curl -i -X POST \
+ --url http://localhost:8001/services/ \
+ --data 'name=example-service' \
+ --data 'url=http://mockbin.org/request'
+ ```
+
+ Add a route to the Service:
+
+ ```bash
+ $ curl -i -X POST \
+ --url http://localhost:8001/services/example-service/routes \
+ --data 'paths[]=/auth-sample'
+ ```
+
+ The url `http://localhost:8000/auth-sample` will now echo whatever is being requested.
+
+2. ### Configure the key-auth Plugin for your Service
+
+ Issue the following cURL request to add a plugin to a Service:
+
+ ```bash
+ $ curl -i -X POST \
+ --url http://localhost:8001/services/example-service/plugins/ \
+ --data 'name=key-auth'
+ ```
+
+ Be sure to note the created Plugin `id` - you'll need it in step 5.
+
+3. ### Verify that the key-auth plugin is properly configured
+
+ Issue the following cURL request to verify that the [key-auth][key-auth]
+ plugin was properly configured on the Service:
+
+ ```bash
+ $ curl -i -X GET \
+ --url http://localhost:8000/auth-sample
+ ```
+
+ Since you did not specify the required `apikey` header or parameter, and you have not yet
+ enabled anonymous access, the response should be `403 Forbidden`:
+
+ ```http
+ HTTP/1.1 403 Forbidden
+ ...
+
+ {
+ "message": "No API key found in headers or querystring"
+ }
+ ```
+
+4. ### Create an anonymous Consumer
+
+ Every request proxied by Kong must be associated with a Consumer. You'll now create a Consumer
+ named `anonymous_users` (that Kong will utilize when proxying anonymous access) by issuing the
+ following request:
+
+ ```bash
+ $ curl -i -X POST \
+ --url http://localhost:8001/consumers/ \
+ --data "username=anonymous_users"
+ ```
+
+ You should see a response similar to the one below:
+
+ ```http
+ HTTP/1.1 201 Created
+ Content-Type: application/json
+ Connection: keep-alive
+
+ {
+ "username": "anonymous_users",
+ "created_at": 1428555626000,
+ "id": "bbdf1c48-19dc-4ab7-cae0-ff4f59d87dc9"
+ }
+ ```
+
+ Be sure to note the Consumer `id` - you'll need it in the next step.
+
+5. ### Enable anonymous access
+
+ You'll now re-configure the key-auth plugin to permit anonymous access by issuing the following
+ request (**replace the sample uuids below by the `id` values from step 2 and 4**):
+
+ ```bash
+ $ curl -i -X PATCH \
+ --url http://localhost:8001/plugins/+ If this property is not set (empty) then the auth plugins will always perform authentication and return + a `40x` response if not validated. This results in a logical `AND` when multiple auth plugins are being + invoked. +- `config.anonymous` set to a valid consumer id
+ In this case the auth plugin will only perform authentication if it was not already authenticated. When + authentication fails, it will not return a `40x` response, but set the anonymous consumer as the consumer. This + results in a logical `OR` + 'anonymous access' when multiple auth plugins are being invoked. + +**NOTE 1**: Either all or none of the auth plugins must be configured for anonymous access. The behaviour is +undefined if they are mixed. + +**NOTE 2**: When using the `AND` method, the last plugin executed will be the one setting the credentials +passed to the upstream service. With the `OR` method, it will be the first plugin that successfully authenticates +the consumer, or the last plugin that will set its configured anonymous consumer. + +**NOTE 3**: When using the OAuth2 plugin in an `AND` fashion, then also the OAuth2 endpoints for requesting +tokens etc. will require authentication by the other configured auth plugins. + +
+ When multiple authentication plugins are enabled in an OR fashion on a given Service, and it is desired that
+ anonymous access be forbidden, then the request-termination plugin should be
+ configured on the anonymous consumer. Failure to do so will allow unauthorized requests.
+
+
+[plugins]: https://konghq.com/plugins/
+[key-auth]: /plugins/key-authentication
diff --git a/app/enterprise/1.3-x/brain-immunity/install-configure.md b/app/enterprise/1.3-x/brain-immunity/install-configure.md
new file mode 100644
index 000000000000..f1430613b524
--- /dev/null
+++ b/app/enterprise/1.3-x/brain-immunity/install-configure.md
@@ -0,0 +1,716 @@
+---
+title: Kong Brain & Kong Immunity Installation and Configuration Guide
+---
+
+
+### Introduction
+**Kong Brain** and **Kong Immunity** help automate the entire API and service development life cycle. By automating processes for configuration, traffic analysis and the creation of documentation, Kong Brain and Kong Immunity help organizations improve efficiency, governance, reliability and security. Kong Brain automates API and service documentation and Kong Immunity uses advanced machine learning to analyze traffic patterns to diagnose and improve security.
+
+### Overview
+
+#### Kong Collector Plugin
+
+Kong Collector Plugin (Collector) configuration includes:
+
+* Kong Collector Plugin is included with Kong Enterprise, and used by Kong Brain and (optional) Kong Immunity.
+* Configure the Collector, and Kong Brain is automatically enabled.
+* If you have Kong Immunity, configure the Collector and Kong Immunity is automatically enabled.
+
+#### Kong Brain
+
+Kong Brain (Brain) features include:
+
+* Kong Brain uses the real-time Kong Collector Plugin.
+* Once the Collector is configured, Kong Brain is automatically enabled.
+* Kong Brain ingests your documentation and data flows, analyze changes and take action.
+* Users can create workflows and approve changes directly in Kong Manager.
+* Visually map services using the real-time Kong Service Map.
+
+#### Kong Immunity
+
+Kong Immunity (Immunity) features include:
+
+* Kong Immunity is optional.
+* Once the Collector is configured, Kong Immunity is automatically enabled.
+* View Kong Immunity alerts in the Kong Service Map and take action with just a few clicks.
+* Instantly diagnose issues. Receive Slack alerts notifying users of anomalies that require attention.
+
+#### Kong Service Map
+
+* For information about the Kong Service Map, see **Using Kongâs Service Map**.
+
+
+### Configure the Kong Collector Plugin
+
+#### Prerequisites
+
+Prerequisites for installing the Collector include:
+
+* A working Kong Enterprise system using Kong Enterprise 0.35.3+ or later, with a minimum of one Kong node and a working data store (PostgreSQL or Cassandra).
+* Access to a platform for the Collector which has Docker installed. This system must be networked to âtalkâ to the Kong Enterprise system on which the Collector is installed.
+* Bintray access credentials (supplied by Kong) to access the downloads.
+
+#### Overview
+
+With the Collector, Kong Enterprise collects, coalesces and stores requests made through Kong. This plugin makes a copy of requests through Kong (not affecting the hot path) which are âTeedâ to Kong Brain and/or Kong Immunity platforms. See the diagram below for a visual of how Kong Collector Plugin works with Kong Enterprise.
+
+#### Configuration Order
+
+Configure the Collector in the following order, with configuration steps provided below:
+
+1. Deploy the Collector Plugin, which captures and sends traffic to the Collector for collection/processing.
+2. Deploy and start the Collector infrastructure on your Docker aware platform.
+3. Configure the components to talk to one another.
+4. Test their configuration.
+
+#### Deploy the Collector
+
+Deploy the Collector Plugin from the Kong Manager or the Admin API:
+
+```
+$ http --form POST http:///cache/{cache_key}
+
+**Response**
+
+If a value with that key is cached:
+
+```
+HTTP 200 OK
+...
+{
+ ...
+}
+```
+
+Else:
+
+```
+HTTP 404 Not Found
+```
+
+**Note**: retrieving the `cache_key` for each entity being cached by Kong is
+currently an undocumented process. Future versions of the Admin API will make
+this process easier.
+
+[Back to TOC](#table-of-contents)
+
+### Purge a cached value
+
+**Endpoint**
+
+/cache/{cache_key}
+
+**Response**
+
+```
+HTTP 204 No Content
+...
+```
+
+**Note**: retrieving the `cache_key` for each entity being cached by Kong is
+currently an undocumented process. Future versions of the Admin API will make
+this process easier.
+
+[Back to TOC](#table-of-contents)
+
+### Purge a node's cache
+
+**Endpoint**
+
+/cache
+
+**Response**
+
+```
+HTTP 204 No Content
+```
+
+**Note**: be wary of using this endpoint on a warm, production running node.
+If the node is receiving a lot of traffic, purging its cache at the same time
+will trigger many requests to your database, and could cause a
+[dog-pile effect](https://en.wikipedia.org/wiki/Cache_stampede).
+
+[Back to TOC](#table-of-contents)
+
+[db_update_frequency]: /enterprise/{{page.kong_version}}/property-reference/#db_update_frequency
+[db_update_propagation]: /enterprise/{{page.kong_version}}/property-reference/#db_update_propagation
+[db_cache_ttl]: /enterprise/{{page.kong_version}}/property-reference/#db_cache_ttl
diff --git a/app/enterprise/1.3-x/deployment/access-license.md b/app/enterprise/1.3-x/deployment/access-license.md
new file mode 100644
index 000000000000..d6eaf0fb766b
--- /dev/null
+++ b/app/enterprise/1.3-x/deployment/access-license.md
@@ -0,0 +1,38 @@
+---
+title: How to Access Your Kong Enterprise License
+toc: false
+---
+
+Starting with Kong EE 0.29, Kong requires a license file to start. This guide
+will walk you through how to access your license file.
+
+**Note:** The following guide only pertains to paid versions of Kong Enterprise. For free trial information, check the email received after signing up.
+
+Log into [https://bintray.com/login?forwardedFrom=%2Fkong%2F](https://bintray.com/login?forwardedFrom=%2Fkong%2F)
+If you are unaware of your login credentials, reach out to your CSE and they'll
+be able to assist you.
+
+You will notice that along with Kong Enterprise and Gelato, there is a new
+repository that has the same name as your company. Click on that repo.
+
+In the repo, click on the file called **license**.
+
+
+
+Click into the **Files** section
+
+
+
+Click any file you would like to download.
+
+Alternatively, you can run this command in your terminal
+
+```bash
+curl -L -u<$UserName>@kong<$API_KEY> "https://kong.bintray.com/<$repoName>/license.json" -o 
+
+## Installation Steps
+
+A guide to installing Kong Enterpriseâand its license fileâusing
+Docker.
+
+**Free trial users should skip directly to step 3**.
+
+1. Log in to bintray.com. Your Sales or Support
+contact will email the credential to you.
+
+2. In the upper right corner, click "Edit Profile' to retrieve your API
+key, which will be used in step 3. Alternatively, to retrieve it from
+Bintray, click here.
+
+3. For **users with existing contracts**, add the Kong Docker repository and
+pull the image:
+
+ ```
+ $ docker login -u
+
+
diff --git a/app/enterprise/1.3-x/deployment/installation/ubuntu.md b/app/enterprise/1.3-x/deployment/installation/ubuntu.md
new file mode 100644
index 000000000000..8f205f617217
--- /dev/null
+++ b/app/enterprise/1.3-x/deployment/installation/ubuntu.md
@@ -0,0 +1,197 @@
+---
+title: How to Install Kong Enterprise on Ubuntu
+---
+
+## Introduction
+
+This guide walks through downloading, installing, and starting Kong Enterprise
+using Ubuntu and PostgreSQL 9.5. The configuration shown in this guide is
+intended only as an example -- you will want to modify and take additional
+measures to secure your Kong Enterprise system before moving to a production
+environment.
+
+
+## Prerequisites
+
+To complete this guide you will need:
+
+- An Ubuntu system with root equivalent access.
+- The ability to SSH to the system.
+
+
+## Step 1. Download Kong Enterprise
+
+1. Download the .deb package
+
+ Log in to [Bintray](http://bintray.com) to download the latest Kong
+ Enterprise .deb for the desired version of Ubuntu. Your **Sales** or
+ **Support** contact will email this credential to you.
+
+ Copy the file to your home directory:
+
+ ```
+ $ scp kong-enterprise-edition-0.35.xxx.xxx.deb
+
+
+ Go to Guide→
+
+
+ Docker
+
+ Go to Guide→
+
+
+
+ Go to Guide→
+
+
+ CentOS
+
+ Go to Guide→
+
+
+
+ Go to Guide→
+
+
+
+
+Amazon Linux
+
+ Go to Guide→
+
+ Note: This action is irreversible, therefore it is highly recommended to have a backup of production data.
+
+
+Kong Enterprise 1.3-Îą includes a command to migrate all Kong entities to Kong Enterprise. The following steps will guide you through the migration process.
+
+First download Kong Enterprise 1.3-Îą, and configure it to point to the same datastore as your Kong 1.2 node. The migration command expects the datastore to be up to date on any pending migration:
+
+```shell
+$ kong migrations up [-c config]
+$ kong migrations finish [-c config]
+```
+
+Once all Kong Enterprise migrations are up to date, the migration command can be run as:
+
+```shell
+$ kong migrations migrate-community-to-enterprise [-c config] [-f] [-y]
+```
+
+Confirm now that all the entities are now available on your Kong Enterprise 0.35 node.
diff --git a/app/enterprise/1.3-x/developer-portal/administration/developer-permissions.md b/app/enterprise/1.3-x/developer-portal/administration/developer-permissions.md
new file mode 100644
index 000000000000..d3c309bafc5c
--- /dev/null
+++ b/app/enterprise/1.3-x/developer-portal/administration/developer-permissions.md
@@ -0,0 +1,56 @@
+---
+title: Developer Roles and Content Permissions
+---
+
+## Introduction
+
+Access to the Developer Portal can be fine-tuned with the use of Developer Roles and Content Permissions, managed through the Dev Portal Permissions page of Kong Manager. This page can be found by clicking on the **Permissions** link under **Dev Portal** in the Kong Manager side navigation.
+
+## Roles
+
+The Roles Tab contains a list of available developer roles as well as the ability to create and edit roles.
+
+Selecting "Create Role" will allow us to enter the unique role name, as well as a comment to provide context for the nature of the role. We can assign the role to existing developers from within the role creation page. Clicking "Create" will save the role and return us to the Roles List view. Here we can see our newly created role as well as any other previously defined roles.
+
+Clicking "View" will show us the Role Details page with a list of developers assigned.
+
+From the Role Details page, we can click the "Edit" button to make changes to the role. We can also access this page from the Roles List "Edit" button. Here we can change the name and comment of the role, assign or remove developers, or delete the role.
+
+Deleting a role will remove it from any developers assigned the role and remove the role restriction from any content files it is applied to.
+
+## Content
+
+The Content Tab shows the list of content files used by the Dev Portal. Here we can apply roles to our content files, restricting access to developers who posess certain roles. Selecting an individual content file displays a dropdown of availabled developer roles. Here we can choose which role has accese to the file. Unchecking all availabled roles will leave the file unauthenticated.
+
+An additional option is preset in the list: the `*` role. This predefined role behaves differently from other roles. When a content file has the `*` role attached to it, any developer may view the page as long as they are authenticated. Additionally, the `*` role may not be used in conjunction with other user defined roles and will deselect these roles when `*` is selected
+
+â ď¸**Important:** `dashboard.txt` and `settings.txt` content files are assigned the `*` role by default. All other content files have no roles by default. This means that until a role is added, the file is unauthenticated even if Dev Portal Authentication is enabled. Content Permissions are ignored when Dev Portal Authentication is disabled. For more information visit the Dev Portal Authentication section.
+
+## readable_by attribute
+
+When a role is applied to a content file via the Content Tab, a special attribute `readable_by` is added to the headmatter of the file.
+
+```
+---
+readable_by:
+ - role_name
+ - another_role_name
+---
+```
+
+ In the case of spec files, `readable_by` is applied under the key `x-headmatter` or `X-headmatter`.
+
+```
+x-headmatter:
+ readable_by:
+ - role_name
+ - another_role_name
+```
+
+The value of `readable_by` is an array of string role names that have access to view the content file. The exception is when the `*` role is applied to the file. In this case, the value of `readable_by` is no longer an array, but the single string character `*`.
+
+```
+readable_by: "*"
+```
+
+â ď¸**Important:** Please note that if you manually remove or edit the `readable_by` attribute, it will modify the permissions of the file. Attempting to save a content file with a `readable_by` array containing an nonexistent role name will result in an error. Additionally, if you make changes to permissions in the Content Tab or via the Portal Editor, be sure to sync any local files so that permissions are not overwritten next time you push changes.
diff --git a/app/enterprise/1.3-x/developer-portal/administration/index.md b/app/enterprise/1.3-x/developer-portal/administration/index.md
new file mode 100644
index 000000000000..87dc44d98542
--- /dev/null
+++ b/app/enterprise/1.3-x/developer-portal/administration/index.md
@@ -0,0 +1,20 @@
+---
+title: Dev Portal Administration
+---
+
+
+
diff --git a/app/enterprise/1.3-x/developer-portal/administration/managing-developers.md b/app/enterprise/1.3-x/developer-portal/administration/managing-developers.md
new file mode 100644
index 000000000000..1c8b02ec82f1
--- /dev/null
+++ b/app/enterprise/1.3-x/developer-portal/administration/managing-developers.md
@@ -0,0 +1,144 @@
+---
+title: Managing Developers
+---
+
+### Developer Status
+
+A status represents the state of a developer and the access they have to the Dev
+ Portal and APIs.
+
+* **Approved**
+ * A Developer who can access the Dev Portal. Approved Developers can create
+ credentials & access **all** APIs that allow those credentials.
+* **Requested**
+ * A Developer who has requested access but has not yet been Approved.
+* **Rejected**
+ * A Developer who has had their request denied by a Kong Admin.
+* **Revoked**
+ * A Developer who once had access to the Dev Portal but has since had access
+ Revoked.
+
+
+
+
+### Approving Developers
+
+Developers who have requested access to a Dev Portal will appear under the
+**Requested Access** tab. From this tab you can choose to *Accept* or *Reject*
+the developer from the actions in the table row. After selecting an action the
+corresponding tab will update.
+
+
+### Viewing Approved Developers
+
+To view all currently approved developers choose the **Approved** tab. From here you can choose to *Revoke* or *Delete* a particular developer. Additionally you can use this view to send an email to a developer with the **Email Developer** `mailto` link. See [Emailing Developers](#emailing-developers) for more info.
+
+
+### Viewing Revoked Developers
+
+To view all currently revoked developers choose the **Revoked** tab. From here you can choose to *Re-approve* or *Delete* a developer.
+
+
+### Viewing Rejected Developers
+
+To view all currently rejected developers choose the **Rejected** tab. Rejected developers completed the registration flow on your Dev Portal but were rejected from the **Request Access** tab. You may *Approve* or *Delete* a developer from this tab.
+
+
+### Emailing Developers
+
+#### Inviting Developers to Register
+
+To invite a single or set of developers...
+
+1. Click the **Invite Developers** button from the top right corner above the tabs
+2. Use the popup modal to enter email addresses separated by commas
+3. After all emails have been added click **Invite**. This will open a pre-filled message in your default email client with a link to the registration page for your Dev Portal
+
+Each developer is bcc'd by default for privacy. You may choose to edit the message or send as is.
+
+
+
+
+### Developer Management Property Reference
+
+
+#### portal_auto_approve
+
+**Default:** `off`
+
+**Description:**
+Dev Portal Auto Approve Access.
+
+When set to `on`, a developer will automatically be marked as `approved` after
+completing Dev Portal registration. Access can still be revoked through
+Kong Manager or API.
+
+When set to `off`, a Kong Admin will have to manually approve the Developer via
+the Kong Manager or API.
+
+
+#### portal_invite_email
+
+**Default:** `on`
+
+**Description:**
+When enabled, Admins will be able to invite Developers to a Dev Portal by using
+ the "Invite" button in the Kong Manager.
+
+
+#### portal_access_request_email
+
+**Default:** `on`
+
+**Description:**
+When enabled, Kong Admins specified by `smtp_admin_emails` will receive an email
+ when a Developer requests access to a Dev Portal.
+
+When disabled, Kong Admins will have to manually check the Kong Manager to view
+any requests.
+
+
+#### portal_approved_email
+
+**Default:** `on`
+
+**Description:**
+When enabled, Developers will receive an email when access to a Dev Portal has
+been approved.
+
+When disabled, Developers will receive no indication that they have been
+approved. It is suggested to only disable this feature if`portal_auto_approve`
+is enabled.
+
+
+#### portal_reset_email
+
+**Default:** `on`
+
+**Description:**
+When enabled, Developers will be able to use the "Reset Password" flow on a Dev
+Portal and will receive an email with password reset instructions.
+
+When disabled, Developers will *not* be able to reset their account passwords.
+Kong Admins will have to manually create new credentials for the Developer in
+the Kong Manager.
+
+#### portal_token_exp
+
+**Default:** `21600`
+
+**Description:**
+Duration in seconds for the expiration of the Dev Portal reset password token.
+Default `21600` is six hours.
+
+
+#### portal_reset_success_email
+
+**Default:** `on`
+
+**Description:**
+When enabled, Developers will receive an email after successfully resetting their
+ Dev Portal account password.
+
+When disabled, Developers will still be able to reset their account passwords,
+but will not receive a confirmation email.
diff --git a/app/enterprise/1.3-x/developer-portal/configuration/authentication/adding-registration-fields.md b/app/enterprise/1.3-x/developer-portal/configuration/authentication/adding-registration-fields.md
new file mode 100644
index 000000000000..8f3a4592ce0a
--- /dev/null
+++ b/app/enterprise/1.3-x/developer-portal/configuration/authentication/adding-registration-fields.md
@@ -0,0 +1,32 @@
+---
+title: Adding New Dev Portal Registration Fields
+toc: false
+---
+
+
+### Introduction
+
+By default, when authentication is enabled for a Dev Portal the only required
+fields are **full name**, **email**, and **password**. However, additional fields can be added
+to this form.
+
+
+### Adding Additional Registration Fields
+
+1. In Kong Manager, navigate to the desired Workspace's Dev Portal **Settings** page.
+
+2. Click the **Developer Meta Fields** tab on the **Settings Page**
+
+3. Click **+ Add Field** to add a new field object to the form.
+
+4. Give the new field a label, field name, and select the type of input
+
+5. Select the checkbox **Required** to require this field for registration
+
+6. Click the **Save Changes** button a the bottom of the form.
+
+
+Once saved, the new field will automatically be added to the registration form.
+
+> **WARNING** Adding new required fields to registration will block existing
+> developers from logging in. They will need to be removed and re-registered.
\ No newline at end of file
diff --git a/app/enterprise/1.3-x/developer-portal/configuration/authentication/basic-auth.md b/app/enterprise/1.3-x/developer-portal/configuration/authentication/basic-auth.md
new file mode 100644
index 000000000000..2149ea3ab7d0
--- /dev/null
+++ b/app/enterprise/1.3-x/developer-portal/configuration/authentication/basic-auth.md
@@ -0,0 +1,65 @@
+---
+title: How to Enable Basic Auth in the Dev Portal
+---
+
+### Introduction
+
+The Kong Developer Portal can be fully or partially authenticated using HTTP protocol's Basic Authentication scheme. Requests will be sent with the Authorization header that
+contains the word `Basic` followed by the base64-encoded `username:password` string.
+
+Basic Authentication for the Dev Portal can be enabled in three ways:
+
+- via the [Kong Manager](#enable-basic-auth-via-kong-manager)
+- via the [the command line](#enable-basic-auth-via-the-command-line)
+- via the [the Kong configuration file](#enable-basic-auth-via-the-kong-conf)
+
+>**Warning** Enabling authentication in the Dev Portal requires use of the
+> Sessions plugin. Developers will not be able to login if this is not set
+> properly. More information about [Sessions in the Dev Portal](/enterprise/{{page.kong_version}}/developer-portal/configuration/authentication/sessions)
+
+### Enable Portal Session Config
+
+In the the Kong configuration file set the `portal_session_conf` property:
+
+```
+portal_session_conf={ "cookie_name": "portal_session", "secret": "CHANGE_THIS", "storage": "kong" }
+```
+
+If using HTTP while testing, include `"cookie_secure": false` in the config:
+
+```
+portal_session_conf={ "cookie_name": "portal_session", "secret": "CHANGE_THIS", "storage": "kong", "cookie_secure": false }
+```
+
+### Enable Basic Auth via Kong Manager
+
+1. Navigate to the Dev Portal's **Settings** page
+2. Find **Authentication plugin** under the **Authentication** tab
+3. Select **Basic Authentication** from the drop down
+4. Click the **Save Changes** button at the bottom of the form
+
+>**Warning** When Dev Portal Authentication is enabled, content files will remain unauthenticated until a role is applied to them. The exception to this is `settings.txt` and `dashboard.txt` which begin with the `*` role. Please visit the Developer Roles and Content Permissions section for more info.
+
+### Enable Basic Auth via the Command Line
+
+To patch a Dev Portal's authentication property directly run:
+
+```
+curl -X PATCH http://localhost:8001/workspaces/
+
+
+
+ Managing Developers
+ Inviting, Approving, Rejecting, and Revoking Developers
+ + Learn More → +
+
+
+
+ Developer Roles and Content Permissions
+ Control access to your Dev Portal with Developer Roles and Content Permissions
+ + Learn More → +
+
+
+
+
+
+
+
diff --git a/app/enterprise/1.3-x/developer-portal/configuration/authentication/key-auth.md b/app/enterprise/1.3-x/developer-portal/configuration/authentication/key-auth.md
new file mode 100644
index 000000000000..d0c2d2a3f452
--- /dev/null
+++ b/app/enterprise/1.3-x/developer-portal/configuration/authentication/key-auth.md
@@ -0,0 +1,65 @@
+---
+title: How to Enable Key Auth in the Dev Portal
+---
+
+### Introduction
+
+The Kong Developer Portal can be fully or partially authenticated using API keys or **Key
+Authentication**. Users provide a unique key upon registering and use this key
+to log into the Dev Portal.
+
+Key Authentication for the Dev Portal can be enabled in three ways:
+
+- via the [Kong Manager](#enable-key-auth-via-kong-manager)
+- via the [the command line](#enable-key-auth-via-the-command-line)
+- via the [the Kong configuration file](#enable-key-auth-via-the-kong-conf)
+
+>**Warning** Enabling authentication in the Dev Portal requires use of the
+> Sessions plugin. Developers will not be able to login if this is not set
+> properly. More information about [Sessions in the Dev Portal](/enterprise/{{page.kong_version}}/developer-portal/configuration/authentication/sessions)
+
+### Enable Portal Session Config
+
+```
+portal_session_conf={ "cookie_name": "portal_session", "secret": "CHANGE_THIS", "storage": "kong" }
+```
+
+If using HTTP while testing, include `"cookie_secure": false` in the config:
+
+```
+portal_session_conf={ "cookie_name": "portal_session", "secret": "CHANGE_THIS", "storage": "kong", "cookie_secure": false }
+```
+
+### Enable Key Auth via Kong Manager
+
+1. Navigate to the Dev Portal's **Settings** page
+2. Find **Authentication plugin** under the **Authentication** tab
+3. Select **Key Authentication** from the drop down
+4. Click the **Save Changes** button at the bottom of the form
+
+>**Warning** When Dev Portal Authentication is enabled, content files will remain unauthenticated until a role is applied to them. The exception to this is `settings.txt` and `dashboard.txt` which begin with the `*` role. Please visit the Developer Roles and Content Permissions section for more info.
+
+### Enable Key Auth via the Command Line
+
+To patch a Dev Portal's authentication property directly run:
+
+```
+curl -X PATCH http://localhost:8001/workspaces/
+
+
+
+Authentication
+ + + + + + +
+
+
+
diff --git a/app/enterprise/1.3-x/developer-portal/configuration/smtp.md b/app/enterprise/1.3-x/developer-portal/configuration/smtp.md
new file mode 100644
index 000000000000..846e9c1fe871
--- /dev/null
+++ b/app/enterprise/1.3-x/developer-portal/configuration/smtp.md
@@ -0,0 +1,149 @@
+---
+title: Dev Portal SMTP Configuration
+---
+
+### Introduction
+
+The following property reference outlines each email and email variable used by the Dev Portal to send emails to Kong Admins and Developers.
+
+These settings can be modified in the `Kong Manager` under the Dev Portal `Settings / Email` tab. Or by running the following command:
+
+```
+curl http://localhost:8001/workspaces/