*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. + +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. + `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 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"] + }], + + +--- + +
+ This page refers to the Admin API for running Kong configured with a
+ database (Postgres or Cassandra). For using the Admin API for Kong
+ in DB-less mode, please refer to the
+ Admin API for DB-less Mode
+ page.
+
+
+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,
+and the status of the database connection.
+
+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
+{
+ "server": {
+ "total_requests": 3,
+ "connections_active": 1,
+ "connections_accepted": 1,
+ "connections_handled": 1,
+ "connections_reading": 0,
+ "connections_writing": 1,
+ "connections_waiting": 0
+ },
+ "database": {
+ "reachable": true
+ }
+}
+```
+
+* `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
+```
+
+#### Response
+
+``` 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/private key pair for an SSL
+certificate. These objects are used by Kong to handle SSL/TLS termination for
+encrypted requests. Certificates are optionally associated with SNI objects to
+tie a cert/key pair to one or more hostnames.
+
+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 +``` + + +--- + +## 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 + } + ] +} +``` + + +--- + +[clustering]: /{{page.kong_version}}/clustering +[cli]: /{{page.kong_version}}/cli +[active]: /{{page.kong_version}}/health-checks-circuit-breakers/#active-health-checks +[healthchecks]: /{{page.kong_version}}/health-checks-circuit-breakers +[secure-admin-api]: /{{page.kong_version}}/secure-admin-api +[proxy-reference]: /{{page.kong_version}}/proxy +[db-less-admin-api]: /{{page.kong_version}}/db-less-admin-api diff --git a/app/1.2.x/1.1.x/auth.md b/app/1.2.x/1.1.x/auth.md new file mode 100644 index 000000000000..f190620128e8 --- /dev/null +++ b/app/1.2.x/1.1.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/1.2.x/1.1.x/cli.md b/app/1.2.x/1.1.x/cli.md
new file mode 100644
index 000000000000..3246e3004c76
--- /dev/null
+++ b/app/1.2.x/1.1.x/cli.md
@@ -0,0 +1,307 @@
+---
+title: CLI Reference
+---
+
+## Introduction
+
+The provided CLI (*Command Line Interface*) allows you to start, stop, and
+manage your Kong instances. The CLI manages your local node (as in, on the
+current machine).
+
+If you haven't yet, we recommend you read the [configuration reference][configuration-reference].
+
+## Global flags
+
+All commands take a set of special, optional flags as arguments:
+
+* `--help`: print the command's help message
+* `--v`: enable verbose mode
+* `--vv`: enable debug mode (noisy)
+
+[Back to TOC](#table-of-contents)
+
+## Available commands
+
+
+### kong check
+
+```
+Usage: kong check /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]: /{{page.kong_version}}/configuration/#db_update_frequency
+[db_update_propagation]: /{{page.kong_version}}/configuration/#db_update_propagation
+[db_cache_ttl]: /{{page.kong_version}}/configuration/#db_cache_ttl
diff --git a/app/1.2.x/1.1.x/configuration.md b/app/1.2.x/1.1.x/configuration.md
new file mode 100644
index 000000000000..2d59b3ef2b43
--- /dev/null
+++ b/app/1.2.x/1.1.x/configuration.md
@@ -0,0 +1,1264 @@
+---
+title: Configuration Reference
+---
+
+## Configuration loading
+
+Kong comes with a default configuration file that can be found at
+`/etc/kong/kong.conf.default` if you installed Kong via one of the official
+packages. To start configuring Kong, you can copy this file:
+
+```bash
+$ cp /etc/kong/kong.conf.default /etc/kong/kong.conf
+```
+
+Kong will operate with default settings should all the values in your
+configuration be commented out. Upon starting, Kong looks for several
+default locations that might contain a configuration file:
+
+```
+/etc/kong/kong.conf
+/etc/kong.conf
+```
+
+You can override this behavior by specifying a custom path for your
+configuration file using the `-c / --conf` argument in the CLI:
+
+```bash
+$ kong start --conf /path/to/kong.conf
+```
+
+The configuration format is straightforward: simply uncomment any property
+(comments are defined by the `#` character) and modify it to your needs.
+Boolean values can be specified as `on`/`off` or `true`/`false` for convenience.
+
+## Verifying your configuration
+
+You can verify the integrity of your settings with the `check` command:
+
+```bash
+$ kong check *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. + `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": {"minute":20, "hour":500}, + "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": {"minute":20, "hour":500}, + "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": {"minute":20, "hour":500}, + "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. + +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. + `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 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"] + }], + + +--- + +
+ This page refers to the Admin API for running Kong configured without a
+ database, managing in-memory entities via declarative config.
+ For using the Admin API for Kong with a database, please refer to the
+ Admin API for Database Mode page.
+
+
+Kong comes with an **internal** RESTful Admin API for administration purposes.
+In [DB-less mode][db-less], this Admin API can be used to load a new declarative
+configuration, and for inspecting the current configuration. In DB-less mode,
+the Admin API for each node functions independently, reflecting the memory state
+of that particular Kong node. This is the case because there is no database
+coordination between Kong 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 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**
+- **application/json**
+
+---
+
+## 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,
+and the status of the database connection.
+
+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
+{
+ "server": {
+ "total_requests": 3,
+ "connections_active": 1,
+ "connections_accepted": 1,
+ "connections_handled": 1,
+ "connections_reading": 0,
+ "connections_writing": 1,
+ "connections_waiting": 0
+ },
+ "database": {
+ "reachable": true
+ }
+}
+```
+
+* `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.
+
+
+---
+
+## Declarative Configuration
+
+Loading the declarative configuration of entities into Kong
+can be done in two ways: at start-up, through the `declarative_config`
+property, or at run-time, through the Admin API using the `/config`
+endpoint.
+
+To get started using declarative configuration, you need a file
+(in YAML or JSON format) containing entity definitions. You can
+generate a sample declarative configuration with the command:
+
+```
+kong config init
+```
+
+It generates a file named `kong.yml` in the current directory,
+containing the appropriate structure and examples.
+
+
+### Reload Declarative Configuration
+
+This endpoint allows resetting a DB-less Kong with a new
+declarative configuration data file. All previous contents
+are erased from memory, and the entities specified in the
+given file take their place.
+
+To learn more about the file format, please read the
+[declarative configuration][db-less] documentation.
+
+
+/config
+
+Attributes | Description
+---:| ---
+`config`**required** | The config data (in YAML or JSON format) to be loaded. + + +*Response* + +``` +HTTP 200 OK +``` + +``` json +{ + { "services": [], + "routes": [] + } +} +``` + +The response contains a list of all the entities that were parsed from the +input file. + + +--- + +## 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 }}
+```
+
+### 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 }} +``` + + +--- + +## 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 }} +``` + +### 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 }} +``` + + +--- + +## 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 }} +``` + +### 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 }} +``` + + +--- + +## 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. + + +### 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 }} +``` + + +--- + +### 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/private key pair for an SSL
+certificate. These objects are used by Kong to handle SSL/TLS termination for
+encrypted requests. Certificates are optionally associated with SNI objects to
+tie a cert/key pair to one or more hostnames.
+
+Certificates can be both [tagged and filtered by tags](#tags).
+
+
+```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 }} +``` + + +--- + +## 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 }} +``` + +### 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 }} +``` + + +--- + +## 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 }} +``` + +### 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 }} +``` + + +--- + +### 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 }} +``` + +### 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" +} +``` + + +--- + +### 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 + } + ] +} +``` + + +--- + +[clustering]: /{{page.kong_version}}/clustering +[cli]: /{{page.kong_version}}/cli +[active]: /{{page.kong_version}}/health-checks-circuit-breakers/#active-health-checks +[healthchecks]: /{{page.kong_version}}/health-checks-circuit-breakers +[secure-admin-api]: /{{page.kong_version}}/secure-admin-api +[proxy-reference]: /{{page.kong_version}}/proxy +[db-less]: /{{page.kong_version}}/db-less-and-declarative-config +[admin-api]: /{{page.kong_version}}/admin-api diff --git a/app/1.2.x/1.1.x/db-less-and-declarative-config.md b/app/1.2.x/1.1.x/db-less-and-declarative-config.md new file mode 100644 index 000000000000..09d8ddad4f44 --- /dev/null +++ b/app/1.2.x/1.1.x/db-less-and-declarative-config.md @@ -0,0 +1,321 @@ +--- +title: DB-less and Declarative Configuration +--- + + +## Introduction + +Traditionally, Kong has always required a database, which could be either +Postgres or Cassandra, to store its configured entities such as Routes, +Services and Plugins. Kong uses its configuration file, `kong.conf`, to +specify the use of Postgres and Cassandra and its various settings. + +Kong 1.1 added the capability to run Kong without a database, using only +in-memory storage for entities: we call this **DB-less mode**. When running +Kong DB-less, the configuration of entities is done in a second configuration +file, in YAML or JSON, using **declarative configuration**. + +The combination of DB-less mode and declarative configuration has a number +of benefits: + +* Reduced number of dependencies: no need to manage a database installation + if the entire setup for your use-cases fits in memory +* it is a good fit for automation in CI/CD scenarios: configuration for + entities can be kept in a single source of truth managed via a Git + repository +* It enables more deployment options for Kong: for example, DB-less Kong + is a natural fit for a lightweight sidecar in a Service Mesh scenario + +## What Is Declarative Configuration + +If you are already familiar with the concept of declarative configuration you +may skip this section. + +The key idea in declarative configuration is, as its name shows, the notion +that it is *declarative*, as opposed to an *imperative* style of +configuration. "Imperative" means that a configuration is given as a series of +orders: "do this, then to that". "Declative" means that the configuration is +given all at once: "I declare this to be the state of the world". + +The Kong Admin API is an example of an imperative configuration tool: the +final state of the configuration is obtain through a sequence of API calls: +one call to create a Service, another call to create a Route, another call to +add a Plugin, and so on. + +Performing the configuration incrementally like this has the undesirable +side-effect that *intermediate states* happen. In the above example, there is +a window of time in between creating a Route and adding the Plugin in which +the Route did not have the Plugin applied. + +A declarative configuration file, on the other hand, will contain the settings +for all desired entities in a single file, and once that file is loaded into +Kong, it replaces the entire configuration. When incremental changes are +desired, they are made to the declarative configuration file, which is then +reloaded in its entirety. At all times, the configuration described in the +file loaded into Kong is the configured state of the system. + +## Setting Up Kong in DB-less mode + +To use Kong in DB-less mode, set the `database` directive of `kong.conf` +to `off`. As usual, you can do this by editing `kong.conf` and setting +`database=off` or via environment variables. You can then start Kong +as usual: + +``` +$ export KONG_DATABASE=off +$ kong start -c kong.conf +``` + +Once Kong starts, access the `/` endpoint of the Admin API to verify that it +is running without a database. It will return the entire Kong configuration; +verify that `database` is set to `off`: + +``` +$ http :8001/ + +HTTP/1.1 200 OK +Access-Control-Allow-Origin: * +Connection: keep-alive +Content-Length: 6342 +Content-Type: application/json; charset=utf-8 +Date: Wed, 27 Mar 2019 15:24:58 GMT +Server: kong/1.1.0 +{ + "configuration:" { + ... + "database": "off", + ... + }, + ... + "version": "1.1.0" +} +``` + +Kong is running, but no declarative configuration was loaded yet. This +means that the configuration of this node is empty. There are no Routes, +Services or entities of any kind: + +``` +$ http :8001/routes + +HTTP/1.1 200 OK +Access-Control-Allow-Origin: * +Connection: keep-alive +Content-Length: 23 +Content-Type: application/json; charset=utf-8 +Date: Wed, 27 Mar 2019 15:30:02 GMT +Server: kong/1.1.0 + +{ + "data": [], + "next": null +} +``` + +## Creating a Declarative Configuration File + +To load entities into DB-less Kong, we need a declarative configuration +file. The following command will create a skeleton file to get you +started: + +``` +$ kong config -c kong.conf init +``` + +This command creates a `kong.yml` file in the current directory, +containing examples of the syntax for declaring entities and their +relationships. All examples in the generated file are commented-out +by default. You can experiment by uncommenting the examples +(removing the `#` markers) and modifying their values. + +## The Declarative Configuration Format + +The Kong declarative configuration format consists of lists of +entities and their attributes. This is a small, yet, complete +example, which illustrates a number of features: + +```yaml +_format_version: "1.1" + +services: +- name: my-service + url: https://example.com + plugins: + - name: key-auth + routes: + - name: my-route + paths: + - / + +consumers: +- username: my-user + keyauth_credentials: + - key: my-key +``` + +The only mandatory piece of metadata is `_format_version: "1.1"`, which +specifies the version number of the declarative configuration syntax format. +This also matches the minimum version of Kong required to parse the file. + +At the top level, you can specify any Kong entity, be it a core entity such as +`services` and `consumers` as in the above example, or custom entities created +by Plugins, such as `keyauth_credentials`. (This makes the declarative +configuration format inherently extensible, and it is the reason why `kong +config` commands that process declarative configuration require `kong.conf` to +be available, so that the `plugins` directive is taken into account.) + +When entities have a relationship, such as a Route which points to a Service, +this relationship can be specified via nesting. + +Only one-to-one relationships can be specified by nesting: a Plugin that is +applied to a Service can have its relationship depicted via nesting, as in the +example above. Relationships involving more than two entities, such as a +Plugin that is applied to both a Service and a Consumer must be done via a +top-level entry, where the entities can be identified by their primary keys +or identifying names (the same identifiers that can be used to refer to them +in the Admin API). This is an example of a plugin applied to a Service and +a Consumer: + +```yml +plugins: +- name: syslog + consumer: my-user + service: my-service +``` + +## Checking The Declarative Configuration File + +Once you are done editing the file, it is possible to check the syntax +for any errors before attempting to load it into Kong: + +``` +$ kong config -c kong.conf parse kong.yml + +parse successful +``` + +## Loading The Declarative Configuration File + +There are two ways to load a declarative configuration into Kong: via +`kong.conf` and via the Admin API. + +To load a declarative configuration at Kong start-up, use the +`declarative_config` directive in `kong.conf` (or, as usual to all `kong.conf` +entries, the equivalent `KONG_DECLARATIVE_CONFIG` environment variable). + +``` +$ export KONG_DATABASE=off +$ export KONG_DECLARATIVE_CONFIG=kong.yml +$ kong start -c kong.conf +``` + +Alternatively, you can load a declarative configuration into a running +Kong node via its Admin API, using the `/config` endpoint. The +following example loads `kong.yml` using HTTPie: + +``` +$ http :8001/config config=@kong.yml +``` + +The `/config` endpoint replaces the entire set of entities in memory +with the ones specified in the given file. + +## Using Kong in DB-less Mode + +There are a number of things to be aware of when using Kong in DB-less +mode. + +#### Memory Cache Requirements + +The entire configuration of entities must fit inside the Kong +cache. Make sure that the in-memory cache is configured appropriately: +see the `mem_cache_size` directive in `kong.conf`. + +#### No Central Database Coordination + +Since there is no central database, multiple Kong nodes have no +central coordination point and no cluster propagation of data: +nodes are completely independent of each other. + +This means that the declarative configuration should be loaded into each node +independently. Using the `/config` endpoint does not affect other Kong +nodes, since they have no knowledge of each other. + +#### Read-Only Admin API + +Since the only way to configure entities is via declarative configuration, +the endpoints for CRUD operations on entities are effectively read-only +in the Admin API when running Kong in DB-less mode. `GET` operations +for inspecting entities work as usual, but attempts to `POST`, `PATCH` +`PUT` or `DELETE` in endpoints such as `/services` or `/plugins` will return +`HTTP 405 Not Allowed`. + +This restriction is limited to what would be otherwise database operations. In +particular, using `POST` to set the health state of Targets is still enabled, +since this is a node-specific in-memory operation. + +#### Plugin Compatibility + +Not all Kong plugins are compatible with DB-less mode, since some of them +by design require a central database coordination and/or dynamic creation of +entities. + +##### Fully Compatible + +The following plugins only read from the database (most of them just to read +their initial config) so they are fully compatible with DB-less: + +* `aws-lambda` +* `azure-functions` +* `bot-detection` +* `correlation-id` +* `cors` +* `datadog` +* `file-log` +* `http-log` +* `tcp-log` +* `udp-log` +* `syslog` +* `ip-restriction` +* `prometheus` +* `zipkin` +* `request-transformer` +* `response-transformer` +* `request-termination` +* `kubernetes-sidecar-injector` + +##### Partial Compatibility + +Authentication plugins can be used insofar as the set of credentials +used is static and specified as part of the declarative configuration. +Admin API endpoints to dynamically create, update or delete credentials +are not available in DB-less mode. Plugins that fall into this +category are: + +* `acl` +* `basic-auth` +* `hmac-auth` +* `jwt` +* `key-auth` + +Rate limiting plugins bundled with Kong offer different policies for +storing and coordinating counters: a `local` policy which stores counters +the Nodes's memory, applying limits in a per-node fashion; a `redis` +policy which uses Redis as an external key-value store for coordinating +counters across nodes; and a `cluster` policy which uses the Kong database +as a central coordination point for cluster-wide limits. In DB-less mode +the `local` and `redis` policies are available, and `cluster` cannot be +used. Plugins that fall into this category are: + +* `rate-limiting` +* `response-ratelimiting` + +The `pre-function` and `post-function` plugins for serverless can be used +in DB-less mode, with the caveat that if any configured functions attempt to +write to the database, the writes will fail. + +##### Not Compatible + +* `oauth2` - For its regular work, the plugin needs to both generate and delete + tokens, and commit those changes to the database, which is not compatible with + DB-less. diff --git a/app/1.2.x/1.1.x/getting-started/adding-consumers.md b/app/1.2.x/1.1.x/getting-started/adding-consumers.md new file mode 100644 index 000000000000..4b3488cbe3b6 --- /dev/null +++ b/app/1.2.x/1.1.x/getting-started/adding-consumers.md @@ -0,0 +1,97 @@ +--- +title: Adding Consumers +--- + +
+ Before you start:
+
+
+In the last section, we learned how to add plugins to Kong, in this section
+we're going to learn how to add consumers to your Kong instances. Consumers are
+associated to individuals using your Service, and can be used for tracking, access
+management, and more.
+
+**Note:** This section assumes you have [enabled][enabling-plugins] the
+[key-auth][key-auth] plugin. If you haven't, you can either [enable the
+plugin][enabling-plugins] or skip steps two and three.
+
+## 1. Create a Consumer through the RESTful API
+
+Lets create a user named `Jason` by issuing the following request:
+
+```bash
+$ curl -i -X POST \
+ --url http://localhost:8001/consumers/ \
+ --data "username=Jason"
+```
+
+You should see a response similar to the one below:
+
+```http
+HTTP/1.1 201 Created
+Content-Type: application/json
+Connection: keep-alive
+
+{
+ "username": "Jason",
+ "created_at": 1428555626000,
+ "id": "bbdf1c48-19dc-4ab7-cae0-ff4f59d87dc9"
+}
+```
+
+Congratulations! You've just added your first consumer to Kong.
+
+**Note:** Kong also accepts a `custom_id` parameter when [creating
+consumers][API-consumers] to associate a consumer with your existing user
+database.
+
+## 2. Provision key credentials for your Consumer
+
+Now, we can create a key for our recently created consumer `Jason` by
+issuing the following request:
+
+```bash
+$ curl -i -X POST \
+ --url http://localhost:8001/consumers/Jason/key-auth/ \
+ --data 'key=ENTER_KEY_HERE'
+```
+
+## 3. Verify that your Consumer credentials are valid
+
+We can now issue the following request to verify that the credentials of
+our `Jason` Consumer is valid:
+
+```bash
+$ curl -i -X GET \
+ --url http://localhost:8000 \
+ --header "Host: example.com" \
+ --header "apikey: ENTER_KEY_HERE"
+```
+
+## Next Steps
+
+Now that we've covered the basics of adding Services, Routes, Consumers and enabling
+Plugins, feel free to read more on Kong in one of the following documents:
+
+- [Configuration file Reference][configuration]
+- [CLI Reference][CLI]
+- [Proxy Reference][proxy]
+- [Admin API Reference][API]
+- [Clustering Reference][cluster]
+
+Questions? Issues? Contact us on one of the [Community Channels](/community)
+for help!
+
+[key-auth]: /plugins/key-authentication
+[API-consumers]: /{{page.kong_version}}/admin-api#create-consumer
+[enabling-plugins]: /{{page.kong_version}}/getting-started/enabling-plugins
+[configuration]: /{{page.kong_version}}/configuration
+[CLI]: /{{page.kong_version}}/cli
+[proxy]: /{{page.kong_version}}/proxy
+[API]: /{{page.kong_version}}/admin-api
+[cluster]: /{{page.kong_version}}/clustering
diff --git a/app/1.2.x/1.1.x/getting-started/configuring-a-service.md b/app/1.2.x/1.1.x/getting-started/configuring-a-service.md
new file mode 100644
index 000000000000..6c1f819c0068
--- /dev/null
+++ b/app/1.2.x/1.1.x/getting-started/configuring-a-service.md
@@ -0,0 +1,137 @@
+---
+title: Configuring a Service
+---
+
+-
+
- Make sure you've installed Kong — It should only take a minute! +
- Make sure you've started Kong. +
- Also, make sure you've configured your Service in Kong. +
+ Before you start:
+
+
+In this section, you'll be adding an API to Kong. In order to do this, you'll
+first need to add a _Service_; that is the name Kong uses to refer to the upstream APIs and microservices
+it manages.
+
+For the purpose of this guide, we'll create a Service pointing to the [Mockbin API][mockbin]. Mockbin is
+an "echo" type public website which returns the requests it gets back to the requester, as responses. This
+makes it helpful for learning how Kong proxies your API requests.
+
+Before you can start making requests against the Service, you will need to add a _Route_ to it.
+Routes specify how (and _if_) requests are sent to their Services after they reach Kong. A single
+Service can have many Routes.
+
+After configuring the Service and the Route, you'll be able to make requests through Kong using them.
+
+Kong exposes a [RESTful Admin API][API] on port `:8001`. Kong's configuration, including adding Services and
+Routes, is made via requests on that API.
+
+## 1. Add your Service using the Admin API
+
+Issue the following cURL request to add your first Service (pointing to the [Mockbin API][mockbin])
+to Kong:
+
+```bash
+$ curl -i -X POST \
+ --url http://localhost:8001/services/ \
+ --data 'name=example-service' \
+ --data 'url=http://mockbin.org'
+```
+
+You should receive a response similar to:
+
+```http
+HTTP/1.1 201 Created
+Content-Type: application/json
+Connection: keep-alive
+
+{
+ "host":"mockbin.org",
+ "created_at":1519130509,
+ "connect_timeout":60000,
+ "id":"92956672-f5ea-4e9a-b096-667bf55bc40c",
+ "protocol":"http",
+ "name":"example-service",
+ "read_timeout":60000,
+ "port":80,
+ "path":null,
+ "updated_at":1519130509,
+ "retries":5,
+ "write_timeout":60000
+}
+```
+
+
+## 2. Add a Route for the Service
+
+```bash
+$ curl -i -X POST \
+ --url http://localhost:8001/services/example-service/routes \
+ --data 'hosts[]=example.com'
+```
+
+The answer should be similar to:
+
+```http
+HTTP/1.1 201 Created
+Content-Type: application/json
+Connection: keep-alive
+
+{
+ "created_at":1519131139,
+ "strip_path":true,
+ "hosts":[
+ "example.com"
+ ],
+ "preserve_host":false,
+ "regex_priority":0,
+ "updated_at":1519131139,
+ "paths":null,
+ "service":{
+ "id":"79d7ee6e-9fc7-4b95-aa3b-61d2e17e7516"
+ },
+ "methods":null,
+ "protocols":[
+ "http",
+ "https"
+ ],
+ "id":"f9ce2ed7-c06e-4e16-bd5d-3a82daef3f9d"
+}
+```
+
+Kong is now aware of your Service and ready to proxy requests.
+
+## 3. Forward your requests through Kong
+
+Issue the following cURL request to verify that Kong is properly forwarding
+requests to your Service. Note that [by default][proxy-port] Kong handles proxy
+requests on port `:8000`:
+
+```bash
+$ curl -i -X GET \
+ --url http://localhost:8000/ \
+ --header 'Host: example.com'
+```
+
+A successful response means Kong is now forwarding requests made to
+`http://localhost:8000` to the `url` we configured in step #1,
+and is forwarding the response back to us. Kong knows to do this through
+the header defined in the above cURL request:
+
+-
+
- Make sure you've installed Kong — It should only take a minute! +
- Make sure you've started Kong. +
-
+
- Host: <given host> +
+ +## Next Steps + +Now that you've added your Service to Kong, let's learn how to enable plugins. + +Go to [Enabling Plugins ›][enabling-plugins] + +[API]: /{{page.kong_version}}/admin-api +[enabling-plugins]: /{{page.kong_version}}/getting-started/enabling-plugins +[proxy-port]: /{{page.kong_version}}/configuration/#nginx-section +[mockbin]: https://mockbin.com/ diff --git a/app/1.2.x/1.1.x/getting-started/enabling-plugins.md b/app/1.2.x/1.1.x/getting-started/enabling-plugins.md new file mode 100644 index 000000000000..36210428c350 --- /dev/null +++ b/app/1.2.x/1.1.x/getting-started/enabling-plugins.md @@ -0,0 +1,74 @@ +--- +title: Enabling Plugins +--- + +
+ Before you start:
+
+
+In this section, you'll learn how to configure Kong plugins. One of the core
+principles of Kong is its extensibility through [plugins][plugins]. Plugins
+allow you to easily add new features to your Service or make it easier to
+manage.
+
+In the steps below you will configure the [key-auth][key-auth] plugin to add
+authentication to your Service. Prior to the addition of this plugin, **all**
+requests to your Service would be proxied upstream. Once you add and configure this
+plugin, **only** requests with the correct key(s) will be proxied - all
+other requests will be rejected by Kong, thus protecting your upstream service
+from unauthorized use.
+
+
+## 1. Configure the key-auth plugin
+
+To configure the key-auth plugin for the Service you configured in Kong,
+issue the following cURL request:
+
+```bash
+$ curl -i -X POST \
+ --url http://localhost:8001/services/example-service/plugins/ \
+ --data 'name=key-auth'
+```
+
+**Note:** This plugin also accepts a `config.key_names` parameter, which
+defaults to `['apikey']`. It is a list of headers and parameters names (both
+are supported) that are supposed to contain the apikey during a request.
+
+## 2. Verify that the 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/ \
+ --header 'Host: example.com'
+```
+
+Since you did not specify the required `apikey` header or parameter, the
+response should be `401 Unauthorized`:
+
+```http
+HTTP/1.1 401 Unauthorized
+...
+
+{
+ "message": "No API key found in request"
+}
+```
+
+## Next Steps
+
+Now that you've configured the **key-auth** plugin lets learn how to add
+consumers to your Service so we can continue proxying requests through Kong.
+
+Go to [Adding Consumers ›][adding-consumers]
+
+[key-auth]: /plugins/key-authentication
+[plugins]: /plugins
+[adding-consumers]: /{{page.kong_version}}/getting-started/adding-consumers
diff --git a/app/1.2.x/1.1.x/getting-started/introduction.md b/app/1.2.x/1.1.x/getting-started/introduction.md
new file mode 100644
index 000000000000..4a333b9d9414
--- /dev/null
+++ b/app/1.2.x/1.1.x/getting-started/introduction.md
@@ -0,0 +1,31 @@
+---
+title: Welcome to Kong
+---
+
+-
+
- Make sure you've installed Kong - It should only take a minute! +
- Make sure you've started Kong. +
- Also, make sure you've configured your Service in Kong. +
+ Before you start: Make sure you've installed Kong — It should only take a minute!
+
+
+Before going further into Kong, make sure you understand its [purpose and philosophy](/about). Once you are confident with the concept of API Gateways, this guide is going to take you through a quick introduction on how to use Kong and perform basic operations such as:
+
+- [Running your own Kong instance][quickstart]
+- [Adding and consuming Services][configuring-a-service]
+- [Installing plugins on Kong][enabling-plugins]
+
+## What is Kong, technically?
+
+You’ve probably heard that Kong is built on Nginx, leveraging its stability and efficiency. But how is this possible exactly?
+
+To be more precise, Kong is a Lua application running in Nginx and made possible by the [lua-nginx-module](https://github.com/openresty/lua-nginx-module). Instead of compiling Nginx with this module, Kong is distributed along with [OpenResty](https://openresty.org/), which already includes lua-nginx-module. OpenResty is *not* a fork of Nginx, but a bundle of modules extending its capabilities.
+
+This sets the foundations for a pluggable architecture, where Lua scripts (referred to as *”plugins”*) can be enabled and executed at runtime. Because of this, we like to think of Kong as **a paragon of microservice architecture**: at its core, it implements database abstraction, routing and plugin management. Plugins can live in separate code bases and be injected anywhere into the request lifecycle, all in a few lines of code.
+
+## Next Steps
+
+Now, lets get familiar with learning how to "start" and "stop" Kong.
+
+Go to [5-minute quickstart with Kong ›][quickstart]
+
+[quickstart]: /{{page.kong_version}}/getting-started/quickstart
+[configuring-a-service]: /{{page.kong_version}}/getting-started/configuring-a-service
+[enabling-plugins]: /{{page.kong_version}}/getting-started/enabling-plugins
diff --git a/app/1.2.x/1.1.x/getting-started/quickstart.md b/app/1.2.x/1.1.x/getting-started/quickstart.md
new file mode 100644
index 000000000000..2112771250fc
--- /dev/null
+++ b/app/1.2.x/1.1.x/getting-started/quickstart.md
@@ -0,0 +1,80 @@
+---
+title: 5-minute Quickstart
+---
+
+
+ Before you start: Make sure you've
+ installed Kong — It should only take a minute!
+
+
+In this section, you'll learn how to manage your Kong instance. First, we'll
+have you start Kong in order to give you access to the RESTful Admin
+interface, through which you manage your Services, Routes, Consumers, and more. Data sent
+through the Admin API is stored in Kong's [datastore][datastore-section] (Kong
+supports PostgreSQL and Cassandra).
+
+## 1. Start Kong
+
+Issue the following command to prepare your datastore by running the Kong
+migrations:
+
+```bash
+$ kong migrations bootstrap [-c /path/to/kong.conf]
+```
+
+You should see a message that tells you Kong has successfully migrated your
+database. If not, you probably incorrectly configured your database
+connection settings in your configuration file.
+
+Now let's [start][CLI] Kong:
+
+```bash
+$ kong start [-c /path/to/kong.conf]
+```
+
+**Note:** the CLI accepts a configuration option (`-c /path/to/kong.conf`)
+allowing you to point to [your own configuration][configuration-loading].
+
+## 2. Verify that Kong has started successfully
+
+If everything went well, you should see a message (`Kong started`)
+informing you that Kong is running.
+
+By default Kong listens on the following ports:
+
+- `:8000` on which Kong listens for incoming HTTP traffic from your
+ clients, and forwards it to your upstream services.
+- `:8443` on which Kong listens for incoming HTTPS traffic. This port has a
+ similar behavior as the `:8000` port, except that it expects HTTPS
+ traffic only. This port can be disabled via the configuration file.
+- `:8001` on which the [Admin API][API] used to configure Kong listens.
+- `:8444` on which the Admin API listens for HTTPS traffic.
+
+## 3. Stop Kong
+
+As needed you can stop the Kong process by issuing the following
+[command][CLI]:
+
+```bash
+$ kong stop
+```
+
+## 4. Reload Kong
+
+Issue the following command to [reload][CLI] Kong without downtime:
+
+```bash
+$ kong reload
+```
+
+## Next Steps
+
+Now that you have Kong running you can interact with the Admin API.
+
+To begin, go to [Configuring a Service ›][configuring-a-service]
+
+[configuration-loading]: /{{page.kong_version}}/configuration/#configuration-loading
+[CLI]: /{{page.kong_version}}/cli
+[API]: /{{page.kong_version}}/admin-api
+[datastore-section]: /{{page.kong_version}}/configuration/#datastore-section
+[configuring-a-service]: /{{page.kong_version}}/getting-started/configuring-a-service
diff --git a/app/1.2.x/1.1.x/health-checks-circuit-breakers.md b/app/1.2.x/1.1.x/health-checks-circuit-breakers.md
new file mode 100644
index 000000000000..18a6f0784aaf
--- /dev/null
+++ b/app/1.2.x/1.1.x/health-checks-circuit-breakers.md
@@ -0,0 +1,321 @@
+---
+title: Health Checks and Circuit Breakers Reference
+---
+
+## Introduction
+
+You can make an API proxied by Kong use a [ring-balancer][ringbalancer], configured
+by adding an [upstream][upstream] entity that contains one or more [target][ringtarget]
+entities, each target pointing to a different IP address (or hostname) and
+port. The ring-balancer will balance load among the various targets, and based
+on the [upstream][upstream] configuration, will perform health checks on the targets,
+making them as healthy or unhealthy whether they are responsive or not. The
+ring-balancer will then only route traffic to healthy targets.
+
+Kong supports two kinds of health checks, which can be used separately or in
+conjunction:
+
+* **active checks**, where a specific HTTP or HTTPS endpoint in the target is
+periodically requested and the health of the target is determined based on its
+response;
+
+* **passive checks** (also known as **circuit breakers**), where Kong analyzes
+the ongoing traffic being proxied and determines the health of targets based
+on their behavior responding requests.
+
+## Healthy and unhealthy targets
+
+The objective of the health checks functionality is to dynamically mark
+targets as healthy or unhealthy, **for a given Kong node**. There is
+no cluster-wide synchronization of health information: each Kong node
+determines the health of its targets separately. This is desirable since at a
+given point one Kong node may be able to connect to a target successfully
+while another node is failing to reach it: the first node will consider
+it healthy, while the second will mark it as unhealthy and start routing
+traffic to other targets of the upstream.
+
+Either an active probe (on active health checks) or a proxied request
+(on passive health checks) produces data which is used to determine
+whether a target is healthy or unhealthy. A request may produce a TCP
+error, timeout, or produce an HTTP status code. Based on this
+information, the health checker updates a series of internal counters:
+
+* If the returned status code is one configured as "healthy", it will
+increment the "Successes" counter for the target and clear all its other
+counters;
+* If it fails to connect, it will increment the "TCP failures" counter
+for the target and clear the "Successes" counter;
+* If it times out, it will increment the "timeouts" counter
+for the target and clear the "Successes" counter;
+* If the returned status code is one configured as "unhealthy", it will
+increment the "HTTP failures" counter for the target and clear the "Successes" counter.
+
+If any of the "TCP failures", "HTTP failures" or "timeouts" counters reaches
+their configured threshold, the target will be marked as unhealthy.
+
+If the "Successes" counter reaches its configured threshold, the target will be
+marked as healthy.
+
+The list of which HTTP status codes are "healthy" or "unhealthy", and the
+individual thresholds for each of these counters are configurable on a
+per-upstream basis. Below, we have an example of a configuration for an
+Upstream entity, showcasing the default values of the various fields
+available for configuring health checks. A description of each
+field is included in the [Admin API][addupstream] reference documentation.
+
+```json
+{
+ "name": "service.v1.xyz",
+ "healthchecks": {
+ "active": {
+ "concurrency": 10,
+ "healthy": {
+ "http_statuses": [ 200, 302 ],
+ "interval": 0,
+ "successes": 0
+ },
+ "http_path": "/",
+ "timeout": 1,
+ "unhealthy": {
+ "http_failures": 0,
+ "http_statuses": [ 429, 404, 500, 501,
+ 502, 503, 504, 505 ],
+ "interval": 0,
+ "tcp_failures": 0,
+ "timeouts": 0
+ }
+ },
+ "passive": {
+ "healthy": {
+ "http_statuses": [ 200, 201, 202, 203,
+ 204, 205, 206, 207,
+ 208, 226, 300, 301,
+ 302, 303, 304, 305,
+ 306, 307, 308 ],
+ "successes": 0
+ },
+ "unhealthy": {
+ "http_failures": 0,
+ "http_statuses": [ 429, 500, 503 ],
+ "tcp_failures": 0,
+ "timeouts": 0
+ }
+ }
+ },
+ "slots": 10
+}
+```
+
+If all targets of an upstream are unhealthy, Kong will respond to requests
+to the upstream with `503 Service Unavailable`.
+
+Note:
+
+1. health checks operate only on [*active* targets][targetobject] and do not
+ modify the *active* status of a target in the Kong database.
+2. unhealthy targets will not be removed from the loadbalancer, and hence will
+ not have any impact on the balancer layout when using the hashing algorithm
+ (they will just be skipped).
+3. The [DNS caveats][dnscaveats] and [balancer caveats][balancercaveats]
+ also apply to health checks. If using hostnames for the targets, then make
+ sure the DNS server always returns the full set of IP addresses for a name,
+ and does not limit the response. *Failing to do so might lead to health
+ checks not being executed.*
+
+## Types of health checks
+
+### Active health checks
+
+Active health checks, as the name implies, actively probe targets for
+their health. When active health checks are enabled in an upstream entity,
+Kong will periodically issue HTTP or HTTPS requests to a configured path at each target
+of the upstream. This allows Kong to automatically enable and disable targets
+in the balancer based on the [probe results](#healthy-and-unhealthy-targets).
+
+The periodicity of active health checks can be configured separately for
+when a target is healthy or unhealthy. If the `interval` value for either
+is set to zero, the checking is disabled at the corresponding scenario.
+When both are zero, active health checks are disabled altogether.
+
+
+Note: Active health checks currently only support HTTP/HTTPS targets. They
+do not apply to Upstreams assigned to Services with the protocol attribute set to "tcp" or "tls".
+
+
+[Back to TOC](#table-of-contents)
+
+### Passive health checks (circuit breakers)
+
+Passive health checks, also known as circuit breakers, are
+checks performed based on the requests being proxied by Kong (HTTP/HTTPS/TCP),
+with no additional traffic being generated. When a target becomes
+unresponsive, the passive health checker will detect that and mark
+the target as unhealthy. The ring-balancer will start skipping this
+target, so no more traffic will be routed to it.
+
+Once the problem with a target is solved and it is ready to receive
+traffic again, the Kong administrator can manually inform the
+health checker that the target should be enabled again, via an
+Admin API endpoint:
+
+```bash
+$ curl -i -X POST http://localhost:8001/upstreams/my_upstream/targets/10.1.2.3:1234/healthy
+HTTP/1.1 204 No Content
+```
+
+This command will broadcast a cluster-wide message so that the "healthy"
+status is propagated to the whole [Kong cluster][clustering]. This will cause Kong nodes to
+reset the health counters of the health checkers running in all workers of the
+Kong node, allowing the ring-balancer to route traffic to the target again.
+
+Passive health checks have the advantage of not producing extra
+traffic, but they are unable to automatically mark a target as
+healthy again: the "circuit is broken", and the target needs to
+be re-enabled again by the system administrator.
+
+
+[Back to TOC](#table-of-contents)
+
+## Summary of pros and cons
+
+* Active health checks can automatically re-enable a target in the
+ring balancer as soon as it is healthy again. Passive health checks cannot.
+* Passive health checks do not produce additional traffic to the
+target. Active health checks do.
+* An active health checker demands a known URL with a reliable status response
+in the target to be configured as a probe endpoint (which may be as
+simple as `"/"`). Passive health checks do not demand such configuration.
+* By providing a custom probe endpoint for an active health checker,
+an application may determine its own health metrics and produce a status
+code to be consumed by Kong. Even though a target continues to serve
+traffic which looks healthy to the passive health checker,
+it would be able to respond to the active probe with a failure
+status, essentially requesting to be relieved from taking new traffic.
+
+It is possible to combine the two modes. For example, one can enable
+passive health checks to monitor the target health based solely on its
+traffic, and only use active health checks while the target is unhealthy,
+in order to re-enable it automatically.
+
+## Enabling and disabling health checks
+
+### Enabling active health checks
+
+To enable active health checks, you need to specify the configuration items
+under `healthchecks.active` in the [Upstream object][upstreamobjects] configuration. You
+need to specify the necessary information so that Kong can perform periodic
+probing on the target, and how to interpret the resulting information.
+
+You can use the `healthchecks.active.type` field to specify whether to perform
+HTTP or HTTPS probes (setting it to `"http"` or `"https"`), or by simply
+testing if the connection to a given host and port is successful
+(setting it to `"tcp"`).
+
+For configuring the probe, you need to specify:
+
+* `healthchecks.active.http_path` - The path that should be used when
+issuing the HTTP GET request to the target. The default value is `"/"`.
+* `healthchecks.active.timeout` - The connection timeout limit for the
+HTTP GET request of the probe. The default value is 1 second.
+* `healthchecks.active.concurrency` - Number of targets to check concurrently
+in active health checks.
+
+You also need to specify positive values for intervals, for running
+probes:
+
+* `healthchecks.active.healthy.interval` - 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.
+* `healthchecks.active.unhealthy.interval` - 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.
+
+This allows you to tune the behavior of the active health checks, whether you
+want probes for healthy and unhealthy targets to run at the same interval, or
+one to be more frequent than the other.
+
+If you are using HTTPS healthchecks, you can also specify the following
+fields:
+
+* `healthchecks.active.https_verify_certificate` - Whether to check the
+validity of the SSL certificate of the remote host when performing active
+health checks using HTTPS.
+* `healthchecks.active.https_sni` - 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.
+
+Note that failed TLS verifications will increment the "TCP failures" counter;
+the "HTTP failures" refer only to HTTP status codes, whether probes are done
+through HTTP or HTTPS.
+
+Finally, you need to configure how Kong should interpret the probe, by setting
+the various thresholds on the [health
+counters](#healthy-and-unhealthy-targets), which, once reached will trigger a
+status change. The counter threshold fields are:
+
+* `healthchecks.active.healthy.successes` - Number of successes in active
+probes (as defined by `healthchecks.active.healthy.http_statuses`) to consider
+a target healthy.
+* `healthchecks.active.unhealthy.tcp_failures` - Number of TCP failures
+or TLS verification failures in active probes to consider a target unhealthy.
+* `healthchecks.active.unhealthy.timeouts` - Number of timeouts in active
+probes to consider a target unhealthy.
+* `healthchecks.active.unhealthy.http_failures` - Number of HTTP failures in
+active probes (as defined by `healthchecks.active.unhealthy.http_statuses`) to
+consider a target unhealthy.
+
+### Enabling passive health checks
+
+Passive health checks do not feature a probe, as they work by interpreting
+the ongoing traffic that flows from a target. This means that to enable
+passive checks you only need to configure its counter thresholds:
+
+* `healthchecks.passive.healthy.successes` - 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. This needs to
+be positive when passive checks are enabled so that healthy traffic resets the
+unhealthy counters.
+* `healthchecks.passive.unhealthy.tcp_failures` - Number of TCP failures in
+proxied traffic to consider a target unhealthy, as observed by passive health
+checks.
+* `healthchecks.passive.unhealthy.timeouts` - Number of timeouts in proxied
+traffic to consider a target unhealthy, as observed by passive health checks.
+* `healthchecks.passive.unhealthy.http_failures` - 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.
+
+### Disabling health checks
+
+In all counter thresholds and intervals specified in the `healthchecks`
+configuration, setting a value to zero means that the functionality the field
+represents is disabled. Setting a probe interval to zero disables a probe.
+Likewise, you can disable certain types of checks by setting their counter
+thresholds to zero. For example, to not consider timeouts when performing
+healthchecks, you can set both `timeouts` fields (for active and passive
+checks) to zero. This gives you a fine-grained control of the behavior of the
+health checker.
+
+In summary, to completely disable active health checks for an upstream, you
+need to set both `healthchecks.active.healthy.interval` and
+`healthchecks.active.unhealthy.interval` to `0`.
+
+To completely disable passive health checks, you need to set all counter
+thresholds under `healthchecks.passive` for its various counters to zero.
+
+All counter thresholds and intervals in `healthchecks` are zero by default,
+meaning that health checks are completely disabled by default in newly created
+upstreams.
+
+[Back to TOC](#table-of-contents)
+
+[ringbalancer]: /{{page.kong_version}}/loadbalancing#ring-balancer
+[ringtarget]: /{{page.kong_version}}/loadbalancing#target
+[upstream]: /{{page.kong_version}}/loadbalancing#upstream
+[targetobject]: /{{page.kong_version}}/admin-api#target-object
+[addupstream]: /{{page.kong_version}}/admin-api#add-upstream
+[clustering]: /{{page.kong_version}}/clustering
+[upstreamobjects]: /{{page.kong_version}}/admin-api#upstream-objects
+[balancercaveats]: /{{page.kong_version}}/loadbalancing#balancing-caveats
+[dnscaveats]: /{{page.kong_version}}/loadbalancing#dns-caveats
diff --git a/app/1.2.x/1.1.x/index.md b/app/1.2.x/1.1.x/index.md
new file mode 100644
index 000000000000..3ef4630e281a
--- /dev/null
+++ b/app/1.2.x/1.1.x/index.md
@@ -0,0 +1,91 @@
+---
+title: Documentation for Kong
+---
+
+
+
diff --git a/app/1.2.x/1.1.x/loadbalancing.md b/app/1.2.x/1.1.x/loadbalancing.md
new file mode 100644
index 000000000000..bee0dac7f2c1
--- /dev/null
+++ b/app/1.2.x/1.1.x/loadbalancing.md
@@ -0,0 +1,374 @@
+---
+title: Loadbalancing reference
+---
+
+## Introduction
+
+Kong provides multiple ways of load balancing requests to multiple backend
+services: a straightforward DNS-based method, and a more dynamic ring-balancer
+that also allows for service registry without needing a DNS server.
+
+## DNS-based loadbalancing
+
+When using DNS-based load balancing, the registration of the backend services
+is done outside of Kong, and Kong only receives updates from the DNS server.
+
+Every Service that has been defined with a `host` containing a hostname
+(instead of an IP address) will automatically use DNS-based load balancing
+if the name resolves to multiple IP addresses, provided the hostname does not
+resolve to an `upstream` name or a name in your DNS hostsfile.
+
+The DNS record `ttl` setting (time to live) determines how often the information
+is refreshed. When using a `ttl` of 0, every request will be resolved using its
+own DNS query. Obviously this will have a performance penalty, but the latency of
+updates/changes will be very low.
+
+[Back to TOC](#table-of-contents)
+
+### A records
+
+An A record contains one or more IP addresses. Hence, when a hostname
+resolves to an A record, each backend service must have its own IP address.
+
+Because there is no `weight` information, all entries will be treated as equally
+weighted in the load balancer, and the balancer will do a straight forward
+round-robin.
+
+[Back to TOC](#table-of-contents)
+
+### SRV records
+
+An SRV record contains weight and port information for all of its IP addresses.
+A backend service can be identified by a unique combination of IP address
+and port number. Hence, a single IP address can host multiple instances of the
+same service on different ports.
+
+Because the `weight` information is available, each entry will get its own
+weight in the load balancer and it will perform a weighted round-robin.
+
+Similarly, any given port information will be overridden by the port information from
+the DNS server. If a Service has attributes `host=myhost.com` and `port=123`,
+and `myhost.com` resolves to an SRV record with `127.0.0.1:456`, then the request
+will be proxied to `http://127.0.0.1:456/somepath`, as port `123` will be
+overridden by `456`.
+
+[Back to TOC](#table-of-contents)
+
+### DNS priorities
+
+The DNS resolver will start resolving the following record types in order:
+
+ 1. The last successful type previously resolved
+ 2. SRV record
+ 3. A record
+ 4. CNAME record
+
+This order is configurable through the [`dns_order` configuration property][dns-order-config].
+
+[Back to TOC](#table-of-contents)
+
+### DNS caveats
+
+- Whenever the DNS record is refreshed a list is generated to handle the
+weighting properly. Try to keep the weights as multiples of each other to keep
+the algorithm performant, e.g., 2 weights of 17 and 31 would result in a structure
+with 527 entries, whereas weights 16 and 32 (or their smallest relative
+counterparts 1 and 2) would result in a structure with merely 3 entries,
+especially with a very small (or even 0) `ttl` value.
+
+- Some nameservers do not return all entries (due to UDP packet size) in those
+cases (for example Consul returns a maximum of 3) a given Kong node will only
+use the few upstream service instances provided by the nameserver. In this
+scenario, it is possible that the pool of upstream instances will be loaded
+inconsistently, because the Kong node is effectively unaware of some of the
+instances, due to the limited information provided by the nameserver.
+To mitigate this use a different nameserver, use IP
+addresses instead of names, or make sure you use enough Kong nodes to still
+have all upstream services being used.
+
+- When the nameserver returns a `3 name error`, then that is a valid response
+for Kong. If this is unexpected, first validate the correct name is being
+queried for, and second check your nameserver configuration.
+
+- The initial pick of an IP address from a DNS record (A or SRV) is not
+randomized. So when using records with a `ttl` of 0, the nameserver is
+expected to randomize the record entries.
+
+[Back to TOC](#table-of-contents)
+
+## Ring-balancer
+
+When using the ring-balancer, the adding and removing of backend services will
+be handled by Kong, and no DNS updates will be necessary. Kong will act as the
+service registry. Nodes can be added/deleted with a single HTTP request and
+will instantly start/stop receiving traffic.
+
+Configuring the ring-balancer is done through the `upstream` and `target`
+entities.
+
+ - `target`: an IP address or hostname with a port number where a backend
+ service resides, eg. "192.168.100.12:80". Each target gets an additional
+ `weight` to indicate the relative load it gets. IP addresses can be
+ in both IPv4 and IPv6 format.
+ - `upstream`: a 'virtual hostname' which can be used in a Route `host`
+ field, e.g., an upstream named `weather.v2.service` would get all requests
+ from a Service with `host=weather.v2.service`.
+
+[Back to TOC](#table-of-contents)
+
+### Upstream
+
+Each upstream gets its own ring-balancer. Each `upstream` can have many
+`target` entries attached to it, and requests proxied to the 'virtual hostname'
+will be load balanced over the targets. A ring-balancer has a pre-defined
+number of slots, and based on the target weights the slots get assigned to the
+targets of the upstream.
+
+Adding and removing targets can be done with a simple HTTP request on the
+Admin API. This operation is relatively cheap. Changing the upstream
+itself is more expensive as the balancer will need to be rebuilt when the
+number of slots change for example.
+
+The only occurrence where the balancer will be rebuilt automatically is when
+the target history is cleaned; other than that, it will only rebuild upon changes.
+
+Within the balancer there are the positions (from 1 to `slots`),
+which are __randomly distributed__ on the ring.
+The randomness is required to make invoking the ring-balancer cheap at
+runtime. A simple round-robin over the wheel (the positions) will do to
+provide a well distributed weighted round-robin over the `targets`, whilst
+also having cheap operations when inserting/deleting targets.
+
+The number of slots to use per target should (at least) be around 100 to make
+sure the slots are properly distributed. Eg. for an expected maximum of 8
+targets, the `upstream` should be defined with at least `slots=800`, even if
+the initial setup only features 2 targets.
+
+The tradeoff here is that the higher the number of slots, the better the random
+distribution, but the more expensive the changes are (add/removing targets)
+
+Detailed information on adding and manipulating
+upstreams is available in the `upstream` section of the
+[Admin API reference][upstream-object-reference].
+
+[Back to TOC](#table-of-contents)
+
+### Target
+
+Because the `upstream` maintains a history of changes, targets can only be
+added, not modified nor deleted. To change a target, just add a new entry for
+the target, and change the `weight` value. The last entry is the one that will
+be used. As such setting `weight=0` will disable a target, effectively
+deleting it from the balancer. Detailed information on adding and manipulating
+targets is available in the `target` section of the
+[Admin API reference][target-object-reference].
+
+The targets will be automatically cleaned when there are 10x more inactive
+entries than active ones. Cleaning will involve rebuilding the balancer, and
+hence is more expensive than just adding a target entry.
+
+A `target` can also have a hostname instead of an IP address. In that case
+the name will be resolved and all entries found will individually be added to
+the ring balancer, e.g., adding `api.host.com:123` with `weight=100`. The
+name 'api.host.com' resolves to an A record with 2 IP addresses. Then both
+ip addresses will be added as target, each getting `weight=100` and port 123.
+__NOTE__: the weight is used for the individual entries, not for the whole!
+
+Would it resolve to an SRV record, then also the `port` and `weight` fields
+from the DNS record would be picked up, and would overrule the given port `123`
+and `weight=100`.
+
+The balancer will honor the DNS record's `ttl` setting and requery and update
+the balancer when it expires.
+
+__Exception__: When a DNS record has `ttl=0`, the hostname will be added
+as a single target, with the specified weight. Upon every proxied request
+to this target it will query the nameserver again.
+
+[Back to TOC](#table-of-contents)
+
+### Balancing algorithms
+
+By default a ring-balancer will use a weighted-round-robin scheme. The alternative
+would be to use the hash-based algorithm. The input for the hash can be either
+`none`, `consumer`, `ip`, `header`, or `cookie`. When set to `none` the
+weighted-round-robin scheme will be used, and hashing will be disabled.
+
+There are two options, a primary and a fallback in case the primary fails
+(e.g., if the primary is set to `consumer`, but no consumer is authenticated)
+
+The different hashing options:
+
+- `none`: Do not use hashing, but use weighted-round-robin instead (default).
+
+- `consumer`: Use the consumer id as the hash input. This option will fallback
+ on the credential id if no consumer id is available (in case of external auth
+ like ldap).
+
+- `ip`: The remote (originating) IP address will be used as input. Review the
+ configuration settings for [determining the real IP][real-ip-config] when
+ using this.
+
+- `header`: Use a specified header (in either `hash_on_header` or `hash_fallback_header`
+ field) as input for the hash.
+
+- `cookie`: Use a specified cookie name (in the `hash_on_cookie` field) with a
+ specified path (in the `hash_on_cookie_path` field, default `"/"`) as input for
+ the hash. If the cookie is not present in the request, it will be set by the
+ response. Hence, the `hash_fallback` setting is invalid if `cookie` is the primary
+ hashing mechanism.
+
+The hashing algorithm is based on 'consistent-hashing' (or the 'ketama principle')
+which makes sure that when the balancer gets modified by changing the targets
+(adding, removing, failing, or changing weights) only the minimum number of
+hashing losses occur. This will maximize upstream cache hits.
+
+For more information on the exact settings see the `upstream` section of the
+[Admin API reference][upstream-object-reference].
+
+[Back to TOC](#table-of-contents)
+
+### Balancing caveats
+
+The ring-balancer is designed to work both with a single node as well as in a cluster.
+For the weighted-round-robin algorithm there isn't much difference, but when using
+the hash based algorithm it is important that all nodes build the exact same
+ring-balancer to make sure they all work identical. To do this the balancer
+must be build in a deterministic way.
+
+- Do not use hostnames in the balancer as the
+balancers might/will slowly diverge because the DNS ttl has only second precision
+and renewal is determined by when a name is actually requested. On top of this is
+the issue with some nameservers not returning all entries, which exacerbates
+this problem. So when using the hashing approach in a Kong cluster, add `target`
+entities only by their IP address, and never by name.
+
+- When picking your hash input make sure the input has enough variance to get
+to a well distributed hash. Hashes will be calculated using the CRC-32 digest.
+So for example, if your system has thousands of users, but only a few consumers, defined
+per platform (eg. 3 consumers: Web, iOS and Android) then picking the `consumer`
+hash input will not suffice, using the remote IP address by setting the hash to
+`ip` would provide more variance in the input and hence a better distribution
+in the hash output. However, if many clients will be behind the same NAT gateway (e.g. in
+call center), `cookie` will provide a better distribution than `ip`.
+
+[Back to TOC](#table-of-contents)
+
+# Blue-Green Deployments
+
+Using the ring-balancer a [blue-green deployment][blue-green-canary] can be easily orchestrated for
+a Service. Switching target infrastructure only requires a `PATCH` request on a
+Service, to change its `host` value.
+
+Set up the "Blue" environment, running version 1 of the address service:
+
+```bash
+# create an upstream
+$ curl -X POST http://kong:8001/upstreams \
+ --data "name=address.v1.service"
+
+# add two targets to the upstream
+$ curl -X POST http://kong:8001/upstreams/address.v1.service/targets \
+ --data "target=192.168.34.15:80"
+ --data "weight=100"
+$ curl -X POST http://kong:8001/upstreams/address.v1.service/targets \
+ --data "target=192.168.34.16:80"
+ --data "weight=50"
+
+# create a Service targeting the Blue upstream
+$ curl -X POST http://kong:8001/services/ \
+ --data "name=address-service" \
+ --data "host=address.v1.service" \
+ --data "path=/address"
+
+# finally, add a Route as an entry-point into the Service
+$ curl -X POST http://kong:8001/services/address-service/routes/ \
+ --data "hosts[]=address.mydomain.com"
+```
+
+Requests with host header set to `address.mydomain.com` will now be proxied
+by Kong to the two defined targets; 2/3 of the requests will go to
+`http://192.168.34.15:80/address` (`weight=100`), and 1/3 will go to
+`http://192.168.34.16:80/address` (`weight=50`).
+
+Before deploying version 2 of the address service, set up the "Green"
+environment:
+
+```bash
+# create a new Green upstream for address service v2
+$ curl -X POST http://kong:8001/upstreams \
+ --data "name=address.v2.service"
+
+# add targets to the upstream
+$ curl -X POST http://kong:8001/upstreams/address.v2.service/targets \
+ --data "target=192.168.34.17:80"
+ --data "weight=100"
+$ curl -X POST http://kong:8001/upstreams/address.v2.service/targets \
+ --data "target=192.168.34.18:80"
+ --data "weight=100"
+```
+
+To activate the Blue/Green switch, we now only need to update the Service:
+
+```bash
+# Switch the Service from Blue to Green upstream, v1 -> v2
+$ curl -X PATCH http://kong:8001/services/address-service \
+ --data "host=address.v2.service"
+```
+
+Incoming requests with host header set to `address.mydomain.com` will now be
+proxied by Kong to the new targets; 1/2 of the requests will go to
+`http://192.168.34.17:80/address` (`weight=100`), and the other 1/2 will go to
+`http://192.168.34.18:80/address` (`weight=100`).
+
+As always, the changes through the Kong Admin API are dynamic and will take
+effect immediately. No reload or restart is required, and no in progress
+requests will be dropped.
+
+[Back to TOC](#table-of-contents)
+
+# Canary Releases
+
+Using the ring-balancer, target weights can be adjusted granularly, allowing
+for a smooth, controlled [canary release][blue-green-canary].
+
+Using a very simple 2 target example:
+
+```bash
+# first target at 1000
+$ curl -X POST http://kong:8001/upstreams/address.v2.service/targets \
+ --data "target=192.168.34.17:80"
+ --data "weight=1000"
+
+# second target at 0
+$ curl -X POST http://kong:8001/upstreams/address.v2.service/targets \
+ --data "target=192.168.34.18:80"
+ --data "weight=0"
+```
+
+By repeating the requests, but altering the weights each time, traffic will
+slowly be routed towards the other target. For example, set it at 10%:
+
+```bash
+# first target at 900
+$ curl -X POST http://kong:8001/upstreams/address.v2.service/targets \
+ --data "target=192.168.34.17:80"
+ --data "weight=900"
+
+# second target at 100
+$ curl -X POST http://kong:8001/upstreams/address.v2.service/targets \
+ --data "target=192.168.34.18:80"
+ --data "weight=100"
+```
+
+The changes through the Kong Admin API are dynamic and will take
+effect immediately. No reload or restart is required, and no in progress
+requests will be dropped.
+
+[Back to TOC](#table-of-contents)
+
+[upstream-object-reference]: /{{page.kong_version}}/admin-api#upstream-object
+[target-object-reference]: /{{page.kong_version}}/admin-api#target-object
+[dns-order-config]: /{{page.kong_version}}/configuration/#dns_order
+[real-ip-config]: /{{page.kong_version}}/configuration/#real_ip_header
+[blue-green-canary]: http://blog.christianposta.com/deploy/blue-green-deployments-a-b-testing-and-canary-releases/
diff --git a/app/1.2.x/1.1.x/logging.md b/app/1.2.x/1.1.x/logging.md
new file mode 100644
index 000000000000..33008a60099c
--- /dev/null
+++ b/app/1.2.x/1.1.x/logging.md
@@ -0,0 +1,151 @@
+---
+title: Logging Reference
+toc: false
+---
+
+## Removing Certain Elements From Your Kong Logs
+
+With new regulations surrounding protecting private data like GDPR, there is a chance you may need to change your logging habits. If you use Kong as your API Gateway, this can be done in a single location to take effect on all of your APIs. This guide will walk you through one approach to accomplishing this, but there are always different approaches for different needs. Please note, these changes will effect the output of the NGINX access logs. This will not have any effect on Kong's logging plugins.
+
+For this example, let’s say you want to remove any instances of an email address from your kong logs. The emails addresses may come through in different ways, for example something like `/apiname/v2/verify/alice@example.com` or `/v3/verify?alice@example.com`. In order to keep these from being added to the logs, we will need to use a custom NGINX template.
+
+## Log Levels
+
+Log levels are set in [Kong's configuration](/{{page.kong_version}}/configuration/#log_level). Following are the log levels in increasing order of their severity, `debug`, `info`,
+`notice`, `warn`, `error` and `crit`.
+
+- *`debug`:* It provides debug information about the plugin's runloop and each individual plugin or other components. Only to be used during debugging since it is too chatty.
+- *`info`/`notice`:* Kong does not make a big difference between both these levels. Provides information about normal behavior most of which can be ignored.
+- *`warn`:* To log any abnormal behavior that doesn't result in dropped transactions but requires further investigation, `warn` level should be used.
+- *`error`:* Used for logging errors that result in a request being dropped (for example getting an HTTP 500 error). The rate of such logs need to be monitored.
+- *`crit`:* This level is used when Kong is working under critical conditions and not working properly thereby affecting several clients. Nginx also provides `alert` and `emerg` levels but currently Kong doesn't make use of these levels making `crit` the highest severity log level.
+
+By default `notice` is the log level that used and also recommended. However if the logs turn out to be too chatty they can be bumped up to a higher level like `warn`.
+
+## Removing Certain Elements From Your Kong Logs
+
+With new regulations surrounding protecting private data like GDPR, there is a chance you may need to change your logging habits. If you use Kong as your API Gateway, this can be done in a single location to take effect on all of your Services. This guide will walk you through one approach to accomplishing this, but there are always different approaches for different needs. Please note, these changes will effect the output of the NGINX access logs. This will not have any effect on Kong's logging plugins.
+
+For this example, let’s say you want to remove any instances of an email address from your kong logs. The emails addresses may come through in different ways, for example something like `/servicename/v2/verify/alice@example.com` or `/v3/verify?alice@example.com`. In order to keep these from being added to the logs, we will need to use a custom NGINX template.
+
+To start using a custom NGINX template, first get a copy of our template. This can be found [https://docs.konghq.com/latest/configuration/#custom-nginx-templates-embedding-kong](https://docs.konghq.com/latest/configuration/#custom-nginx-templates-embedding-kong) or copied from below
+
+```
+# ---------------------
+# custom_nginx.template
+# ---------------------
+
+worker_processes ${{NGINX_WORKER_PROCESSES}}; # can be set by kong.conf
+daemon ${{NGINX_DAEMON}}; # can be set by kong.conf
+
+pid pids/nginx.pid; # this setting is mandatory
+error_log logs/error.log ${{LOG_LEVEL}}; # can be set by kong.conf
+
+events {
+ use epoll; # custom setting
+ multi_accept on;
+}
+
+http {
+ # include default Kong Nginx config
+ include 'nginx-kong.conf';
+
+ # custom server
+ server {
+ listen 8888;
+ server_name custom_server;
+
+ location / {
+ ... # etc
+ }
+ }
+}
+```
+
+In order to control what is placed in the logs, we will be using the NGINX map module in our template. For more detailed information abut using the map directive, please see [this guide](http://nginx.org/en/docs/http/ngx_http_map_module.html). This will create a new variable whose value depends on values of one or more of the source variables specified in the first parameter. The format is:
+
+```
+
+map $paramater_to_look_at $variable_name {
+ pattern_to_look_for 0;
+ second_pattern_to_look_for 0;
+
+ default 1;
+}
+```
+
+For this example, we will be mapping a new variable called `keeplog` which is dependent on certain values appearing in the `$request_uri`. We will be placing our map directive right at the start of the http block, this must be before `include 'nginx-kong.conf';`. So, for our example, we will add something along the lines of:
+
+```
+map $request_uri $keeplog {
+ ~.+\@.+\..+ 0;
+ ~/servicename/v2/verify 0;
+ ~/v3/verify 0;
+
+ default 1;
+}
+```
+
+You’ll probably notice that each of those lines start with a tilde. This is what tells NGINX to use RegEx when evaluating the line. We have three things to look for in this example:
+- The first line uses regex to look for any email address in the x@y.z format
+- The second line looks for any part of the URI which is /servicename/v2/verify
+- The third line looks at any part of the URI which contains /v3/verify
+
+Because all of those have a value of something other than 0, if a request has one of those elements, it will not be added to the log.
+
+Now, we need to set the log format for what we will keep in the logs. We will use the `log_format` module and assign our new logs a name of show_everything. The contents of the log can be customized for you needs, but for this example, I will simply change everything back to the Kong standards. To see the full list of options you can use, please refer to [this guide](https://nginx.org/en/docs/http/ngx_http_core_module.html#variables).
+
+```
+log_format show_everything '$remote_addr - $remote_user [$time_local] '
+ '$request_uri $status $body_bytes_sent '
+ '"$http_referer" "$http_user_agent"';
+```
+
+Now, our custom NGINX template is all ready to be used. If you have been following along, your file should now be look like this:
+
+```
+# ---------------------
+# custom_nginx.template
+# ---------------------
+
+worker_processes ${{NGINX_WORKER_PROCESSES}}; # can be set by kong.conf
+daemon ${{NGINX_DAEMON}}; # can be set by kong.conf
+
+pid pids/nginx.pid; # this setting is mandatory
+error_log stderr ${{LOG_LEVEL}}; # can be set by kong.conf
+
+
+
+events {
+ use epoll; # custom setting
+ multi_accept on;
+}
+
+http {
+
+
+ map $request_uri $keeplog {
+ ~.+\@.+\..+ 0;
+ ~/v1/invitation/ 0;
+ ~/reset/v1/customer/password/token 0;
+ ~/v2/verify 0;
+
+ default 1;
+ }
+ log_format show_everything '$remote_addr - $remote_user [$time_local] '
+ '$request_uri $status $body_bytes_sent '
+ '"$http_referer" "$http_user_agent"';
+
+ include 'nginx-kong.conf';
+}
+```
+
+The last thing we need to do is tell Kong to use the newly created log, `show_everything`. To do this, we will be altering the Kong variable `prpxy_access_log`. Either by opening and editing `etc/kong/kong.conf` or by using an environmental variable `KONG_PROXY_ACCESS_LOG=` you will want to mend the default location to show
+
+```
+proxy_access_log=logs/access.log show_everything if=$keeplog
+```
+
+The final step in the process to make all the changes take effect is to restart kong. you can use the `kong restart` command to do so.
+
+Now, any requests made with an email address in it will no longer be logged. Of course, we can use this logic to remove anything we want from the logs on a conditional manner.
diff --git a/app/1.2.x/1.1.x/network.md b/app/1.2.x/1.1.x/network.md
new file mode 100644
index 000000000000..0875cfe153d2
--- /dev/null
+++ b/app/1.2.x/1.1.x/network.md
@@ -0,0 +1,70 @@
+---
+title: Network & Firewall
+---
+
+## Introduction
+
+In this section you will find a summary about the recommended network and firewall settings for Kong.
+
+## Ports
+
+Kong uses multiple connections for different purposes.
+
+* proxy
+* admin api
+
+### Proxy
+
+The proxy ports is where Kong receives its incoming traffic. There are two ports with the following defaults:
+
+* `8000` for proxying HTTP traffic, and
+* `8443` for proxying HTTPS traffic
+
+See [proxy_listen] for more details on HTTP/HTTPS proxy listen options. For production environment it is common
+to change HTTP and HTTPS listen ports to `80` and `443`.
+
+Kong can also proxy TCP/TLS streams. The stream proxying is disabled by default. See [stream_listen] for
+additional details on stream proxy listen options, and how to enable it (if you plan to proxy anything other than
+HTTP/HTTPS traffic).
+
+In general the proxy ports are the **only ports** that should be made available to your clients.
+
+### Admin API
+
+This is the port where Kong exposes its management API. Hence in production this port should be firewalled to protect
+it from unauthorized access.
+
+* `8001` provides Kong's **Admin API** that you can use to operate Kong with HTTP. See [admin_listen].
+* `8444` provides the same Kong **Admin API** but using HTTPS. See [admin_listen] and the `ssl` suffix.
+
+## Firewall
+
+Below are the recommended firewall settings:
+
+* The upstream Services behind Kong will be available via the [proxy_listen] interface/port values.
+ Configure these values according to the access level you wish to grant to the upstream Services.
+* If you are binding the Admin API to a public-facing interface (via [admin_listen]), then **protect** it to only
+ allow trusted clients to access the Admin API. See also [Securing the Admin API][secure_admin_api].
+* Your proxy will need have rules added for any HTTP/HTTPS and TCP/TLS stream listeners that you configure.
+ For example, if you want Kong to manage traffic on port `4242`, your firewall will need to allow traffic
+ on said port.
+
+#### Transparent Proxying
+
+It is worth mentioning that the `transparent` listen option may be applied to [proxy_listen]
+and [stream_listen] configuration. With packet filtering such as `iptables` (Linux) or `pf` (macOS/BSDs)
+or with hardware routers/switches, you can specify pre-routing or redirection rules for TCP packets that
+allow you to mangle the original destination address and port. For example a HTTP request with a destination
+address of `10.0.0.1`, and a destination port of `80` can be redirected to `127.0.0.1` at port `8000`.
+To make this work, you need (with Linux) to add the `transparent` listen option to Kong proxy,
+`proxy_listen=8000 transparent`. This allows Kong to see the original destination for the request
+(`10.0.0.1:80`) even when Kong didn't actually listen to it directly. With this information,
+Kong can route the request correctly. The `transparent` listen option should only be used with Linux.
+macOS/BSDs allow transparent proxying without `transparent` listen option. With Linux you may also need
+to start Kong as a `root` user or set the needed capabilities for the executable.
+
+
+[proxy_listen]: /{{page.kong_version}}/configuration/#proxy_listen
+[stream_listen]: /{{page.kong_version}}/configuration/#stream_listen
+[admin_listen]: /{{page.kong_version}}/configuration/#admin_listen
+[secure_admin_api]: /{{page.kong_version}}/secure-admin-api
diff --git a/app/1.2.x/1.1.x/pdk/index.md b/app/1.2.x/1.1.x/pdk/index.md
new file mode 100644
index 000000000000..2f951970b6c4
--- /dev/null
+++ b/app/1.2.x/1.1.x/pdk/index.md
@@ -0,0 +1,176 @@
+---
+title: PDK
+pdk: true
+toc: true
+---
+
+## Plugin Development Kit
+
+The Plugin Development Kit (or "PDK") is set of Lua functions and variables
+ that can be used by plugins to implement their own logic. The PDK is a
+ [Semantically Versioned](https://semver.org/) component, originally
+ released in Kong 0.14.0. The PDK will be guaranteed to be forward-compatible
+ from its 1.0.0 release and on.
+
+ As of this release, the PDK has not yet reached 1.0.0, but plugin authors
+ can already depend on it for a safe and reliable way of interacting with the
+ request, response, or the core components.
+
+ The Plugin Development Kit is accessible from the `kong` global variable,
+ and various functionalities are namespaced under this table, such as
+ `kong.request`, `kong.log`, etc...
+
+
+
+
+### kong.version
+
+A human-readable string containing the version number of the currently
+ running node.
+
+**Usage**
+
+``` lua
+print(kong.version) -- "0.14.0"
+```
+
+[Back to TOC](#table-of-contents)
+
+
+### kong.version_num
+
+An integral number representing the version number of the currently running
+ node, useful for comparison and feature-existence checks.
+
+**Usage**
+
+``` lua
+if kong.version_num < 13000 then -- 000.130.00 -> 0.13.0
+ -- no support for Routes & Services
+end
+```
+
+[Back to TOC](#table-of-contents)
+
+
+### kong.pdk_major_version
+
+A number representing the major version of the current PDK (e.g.
+ `1`). Useful for feature-existence checks or backwards-compatible behavior
+ as users of the PDK.
+
+
+**Usage**
+
+``` lua
+if kong.pdk_version_num < 2 then
+ -- PDK is below version 2
+end
+```
+
+[Back to TOC](#table-of-contents)
+
+
+### kong.pdk_version
+
+A human-readable string containing the version number of the current PDK.
+
+**Usage**
+
+``` lua
+print(kong.pdk_version) -- "1.0.0"
+```
+
+[Back to TOC](#table-of-contents)
+
+
+### kong.configuration
+
+A read-only table containing the configuration of the current Kong node,
+ based on the configuration file and environment variables.
+
+ See [kong.conf.default](https://github.com/Kong/kong/blob/master/kong.conf.default)
+ for details.
+
+ Comma-separated lists in that file get promoted to arrays of strings in this
+ table.
+
+
+**Usage**
+
+``` lua
+print(kong.configuration.prefix) -- "/usr/local/kong"
+-- this table is read-only; the following throws an error:
+kong.configuration.prefix = "foo"
+```
+
+[Back to TOC](#table-of-contents)
+
+
+
+
+### kong.db
+
+Instance of Kong's DAO (the `kong.db` module). Contains accessor objects
+ to various entities.
+
+ A more thorough documentation of this DAO and new schema definitions is to
+ be made available in the future.
+
+
+**Usage**
+
+``` lua
+kong.db.services:insert()
+kong.db.routes:select()
+```
+
+[Back to TOC](#table-of-contents)
+
+
+### kong.dns
+
+Instance of Kong's DNS resolver, a client object from the
+ [lua-resty-dns-client](https://github.com/kong/lua-resty-dns-client) module.
+
+ **Note:** usage of this module is currently reserved to the core or to
+ advanced users.
+
+
+[Back to TOC](#table-of-contents)
+
+
+### kong.worker_events
+
+Instance of Kong's IPC module for inter-workers communication from the
+ [lua-resty-worker-events](https://github.com/Kong/lua-resty-worker-events)
+ module.
+
+ **Note:** usage of this module is currently reserved to the core or to
+ advanced users.
+
+
+[Back to TOC](#table-of-contents)
+
+
+### kong.cluster_events
+
+Instance of Kong's cluster events module for inter-nodes communication.
+
+ **Note:** usage of this module is currently reserved to the core or to
+ advanced users.
+
+
+[Back to TOC](#table-of-contents)
+
+
+### kong.cache
+
+Instance of Kong's database caching object, from the `kong.cache` module.
+
+ **Note:** usage of this module is currently reserved to the core or to
+ advanced users.
+
+
+[Back to TOC](#table-of-contents)
+
diff --git a/app/1.2.x/1.1.x/pdk/kong.client.md b/app/1.2.x/1.1.x/pdk/kong.client.md
new file mode 100644
index 000000000000..2528544fad15
--- /dev/null
+++ b/app/1.2.x/1.1.x/pdk/kong.client.md
@@ -0,0 +1,286 @@
+---
+title: kong.client
+pdk: true
+toc: true
+---
+
+## kong.client
+
+Client information module
+ A set of functions to retrieve information about the client connecting to
+ Kong in the context of a given request.
+
+ See also:
+ [nginx.org/en/docs/http/ngx_http_realip_module.html](http://nginx.org/en/docs/http/ngx_http_realip_module.html)
+
+
+
+### kong.client.get_ip()
+
+Returns the remote address of the client making the request. This will
+ **always** return the address of the client directly connecting to Kong.
+ That is, in cases when a load balancer is in front of Kong, this function
+ will return the load balancer's address, and **not** that of the
+ downstream client.
+
+
+**Phases**
+
+* certificate, rewrite, access, header_filter, body_filter, log
+
+**Returns**
+
+* `string` ip The remote address of the client making the request
+
+
+**Usage**
+
+``` lua
+-- Given a client with IP 127.0.0.1 making connection through
+-- a load balancer with IP 10.0.0.1 to Kong answering the request for
+-- https://example.com:1234/v1/movies
+kong.client.get_ip() -- "10.0.0.1"
+```
+
+[Back to TOC](#table-of-contents)
+
+
+### kong.client.get_forwarded_ip()
+
+Returns the remote address of the client making the request. Unlike
+ `kong.client.get_ip`, this function will consider forwarded addresses in
+ cases when a load balancer is in front of Kong. Whether this function
+ returns a forwarded address or not depends on several Kong configuration
+ parameters:
+
+ * [trusted\_ips](https://getkong.org/docs/latest/configuration/#trusted_ips)
+ * [real\_ip\_header](https://getkong.org/docs/latest/configuration/#real_ip_header)
+ * [real\_ip\_recursive](https://getkong.org/docs/latest/configuration/#real_ip_recursive)
+
+
+**Phases**
+
+* certificate, rewrite, access, header_filter, body_filter, log
+
+**Returns**
+
+* `string` ip The remote address of the client making the request,
+ considering forwarded addresses
+
+
+
+**Usage**
+
+``` lua
+-- Given a client with IP 127.0.0.1 making connection through
+-- a load balancer with IP 10.0.0.1 to Kong answering the request for
+-- https://username:password@example.com:1234/v1/movies
+
+kong.request.get_forwarded_ip() -- "127.0.0.1"
+
+-- Note: assuming that 10.0.0.1 is one of the trusted IPs, and that
+-- the load balancer adds the right headers matching with the configuration
+-- of `real_ip_header`, e.g. `proxy_protocol`.
+```
+
+[Back to TOC](#table-of-contents)
+
+
+### kong.client.get_port()
+
+Returns the remote port of the client making the request. This will
+ **always** return the port of the client directly connecting to Kong. That
+ is, in cases when a load balancer is in front of Kong, this function will
+ return load balancer's port, and **not** that of the downstream client.
+
+**Phases**
+
+* certificate, rewrite, access, header_filter, body_filter, log
+
+**Returns**
+
+* `number` The remote client port
+
+
+**Usage**
+
+``` lua
+-- [client]:40000 <-> 80:[balancer]:30000 <-> 80:[kong]:20000 <-> 80:[service]
+kong.client.get_port() -- 30000
+```
+
+[Back to TOC](#table-of-contents)
+
+
+### kong.client.get_forwarded_port()
+
+Returns the remote port of the client making the request. Unlike
+ `kong.client.get_port`, this function will consider forwarded ports in cases
+ when a load balancer is in front of Kong. Whether this function returns a
+ forwarded port or not depends on several Kong configuration parameters:
+
+ * [trusted\_ips](https://getkong.org/docs/latest/configuration/#trusted_ips)
+ * [real\_ip\_header](https://getkong.org/docs/latest/configuration/#real_ip_header)
+ * [real\_ip\_recursive](https://getkong.org/docs/latest/configuration/#real_ip_recursive)
+
+**Phases**
+
+* certificate, rewrite, access, header_filter, body_filter, log
+
+**Returns**
+
+* `number` The remote client port, considering forwarded ports
+
+
+**Usage**
+
+``` lua
+-- [client]:40000 <-> 80:[balancer]:30000 <-> 80:[kong]:20000 <-> 80:[service]
+kong.client.get_forwarded_port() -- 40000
+
+-- Note: assuming that [balancer] is one of the trusted IPs, and that
+-- the load balancer adds the right headers matching with the configuration
+-- of `real_ip_header`, e.g. `proxy_protocol`.
+```
+
+[Back to TOC](#table-of-contents)
+
+
+### kong.client.get_credential()
+
+Returns the credentials of the currently authenticated consumer.
+ If not set yet, it returns `nil`.
+
+**Phases**
+
+* access, header_filter, body_filter, log
+
+**Returns**
+
+* the authenticated credential
+
+
+**Usage**
+
+``` lua
+local credential = kong.client.get_credential()
+if credential then
+ consumer_id = credential.consumer_id
+else
+ -- request not authenticated yet
+end
+```
+
+[Back to TOC](#table-of-contents)
+
+
+### kong.client.get_consumer()
+
+Returns the `consumer` entity of the currently authenticated consumer.
+ If not set yet, it returns `nil`.
+
+**Phases**
+
+* access, header_filter, body_filter, log
+
+**Returns**
+
+* `table` the authenticated consumer entity
+
+
+**Usage**
+
+``` lua
+local consumer = kong.client.get_consumer()
+if consumer then
+ consumer_id = consumer.id
+else
+ -- request not authenticated yet, or a credential
+ -- without a consumer (external auth)
+end
+```
+
+[Back to TOC](#table-of-contents)
+
+
+### kong.client.authenticate(consumer, credential)
+
+Sets the authenticated consumer and/or credential for the current request.
+ While both `consumer` and `credential` can be `nil`, it is required
+ that at least one of them exists. Otherwise this function will throw an
+ error.
+
+**Phases**
+
+* access
+
+**Parameters**
+
+* **consumer** (table|nil): The consumer to set. Note: if no
+ value is provided, then any existing value will be cleared!
+* **credential** (table|nil): The credential to set. Note: if
+ no value is provided, then any existing value will be cleared!
+
+**Usage**
+
+``` lua
+-- assuming `credential` and `consumer` have been set by some authentication code
+kong.client.authenticate(consumer, credentials)
+```
+
+[Back to TOC](#table-of-contents)
+
+
+### kong.client.get_subsystem()
+
+Returns the Nginx subsystem used by the client. It can be
+ "http" or "stream"
+
+
+**Phases**
+
+* access, header_filter, body_filter, log
+
+**Returns**
+
+* `string` a string with either `"http"` or `"stream"`
+
+
+**Usage**
+
+``` lua
+kong.client.get_subsystem() -- "http"
+```
+
+[Back to TOC](#table-of-contents)
+
+
+### _CLIENT.get_protocol(allow_terminated)
+
+Returns the protocol matched by the current route (`"http"`, `"https"`, `"tcp"` or
+ `"tls"`), or `nil`, if no route has been matched, which can happen when dealing with
+ erroneous requests.
+
+**Phases**
+
+* access, header_filter, body_filter, log
+
+**Parameters**
+
+* **allow_terminated** ([opt]): boolean. If set, the `X-Forwarded-Proto` header will be checked when checking for https
+
+**Returns**
+
+1. `string|nil` `"http"`, `"https"`, `"tcp"`, `"tls"` or `nil` in case of failure
+
+1. `nil|err` an error message when a failure happens. `nil` otherwise
+
+
+**Usage**
+
+``` lua
+kong.client.get_protocol() -- "http"
+```
+
+[Back to TOC](#table-of-contents)
+
diff --git a/app/1.2.x/1.1.x/pdk/kong.ctx.md b/app/1.2.x/1.1.x/pdk/kong.ctx.md
new file mode 100644
index 000000000000..c44dc7e8a776
--- /dev/null
+++ b/app/1.2.x/1.1.x/pdk/kong.ctx.md
@@ -0,0 +1,106 @@
+---
+title: kong.ctx
+pdk: true
+toc: true
+---
+
+## kong.ctx
+
+Current request context data
+
+
+
+### kong.ctx.shared
+
+A table that has the lifetime of the current request and is shared between
+ all plugins. It can be used to share data between several plugins in a given
+ request.
+
+ Since only relevant in the context of a request, this table cannot be
+ accessed from the top-level chunk of Lua modules. Instead, it can only be
+ accessed in request phases, which are represented by the `rewrite`,
+ `access`, `header_filter`, `body_filter`, and `log` phases of the plugin
+ interfaces. Accessing this table in those functions (and their callees) is
+ fine.
+
+ Values inserted in this table by a plugin will be visible by all other
+ plugins. One must use caution when interacting with its values, as a naming
+ conflict could result in the overwrite of data.
+
+
+**Phases**
+
+* rewrite, access, header_filter, body_filter, log
+
+**Usage**
+
+``` lua
+-- Two plugins A and B, and if plugin A has a higher priority than B's
+-- (it executes before B):
+
+-- plugin A handler.lua
+function plugin_a_handler:access(conf)
+ kong.ctx.shared.foo = "hello world"
+
+ kong.ctx.shared.tab = {
+ bar = "baz"
+ }
+end
+
+-- plugin B handler.lua
+function plugin_b_handler:access(conf)
+ kong.log(kong.ctx.shared.foo) -- "hello world"
+ kong.log(kong.ctx.shared.tab.bar) -- "baz"
+end
+```
+
+[Back to TOC](#table-of-contents)
+
+
+### kong.ctx.plugin
+
+A table that has the lifetime of the current request - Unlike
+ `kong.ctx.shared`, this table is **not** shared between plugins. Instead,
+ it is only visible for the current plugin _instance_. That is, if several
+ instances of the rate-limiting plugin are configured (e.g. on different
+ Services), each instance has its own table, for every request.
+
+ Because of its namespaced nature, this table is safer for a plugin to use
+ than `kong.ctx.shared` since it avoids potential naming conflicts, which
+ could lead to several plugins unknowingly overwrite each other's data.
+
+ Since only relevant in the context of a request, this table cannot be
+ accessed from the top-level chunk of Lua modules. Instead, it can only be
+ accessed in request phases, which are represented by the `rewrite`,
+ `access`, `header_filter`, `body_filter`, and `log` phases of the plugin
+ interfaces. Accessing this table in those functions (and their callees) is
+ fine.
+
+ Values inserted in this table by a plugin will be visible in successful
+ phases of this plugin's instance only. For example, if a plugin wants to
+ save some value for post-processing during the `log` phase:
+
+
+**Phases**
+
+* rewrite, access, header_filter, body_filter, log
+
+**Usage**
+
+``` lua
+-- plugin handler.lua
+
+function plugin_handler:access(conf)
+ kong.ctx.plugin.val_1 = "hello"
+ kong.ctx.plugin.val_2 = "world"
+end
+
+function plugin_handler:log(conf)
+ local value = kong.ctx.plugin.val_1 .. " " .. kong.ctx.plugin.val_2
+
+ kong.log(value) -- "hello world"
+end
+```
+
+[Back to TOC](#table-of-contents)
+
diff --git a/app/1.2.x/1.1.x/pdk/kong.ip.md b/app/1.2.x/1.1.x/pdk/kong.ip.md
new file mode 100644
index 000000000000..86c74d21942e
--- /dev/null
+++ b/app/1.2.x/1.1.x/pdk/kong.ip.md
@@ -0,0 +1,51 @@
+---
+title: kong.ip
+pdk: true
+toc: true
+---
+
+## kong.ip
+
+Trusted IPs module
+
+ This module can be used to determine whether or not a given IP address is
+ in the range of trusted IP addresses defined by the `trusted_ips` configuration
+ property.
+
+ Trusted IP addresses are those that are known to send correct replacement
+ addresses for clients (as per the chosen header field, e.g. X-Forwarded-*).
+
+ See [docs.konghq.com/latest/configuration/#trusted_ips](https://docs.konghq.com/latest/configuration/#trusted_ips)
+
+
+
+
+### kong.ip.is_trusted(address)
+
+Depending on the `trusted_ips` configuration property,
+ this function will return whether a given ip is trusted or not Both ipv4 and ipv6 are supported.
+
+
+**Phases**
+
+* init_worker, certificate, rewrite, access, header_filter, body_filter, log
+
+**Parameters**
+
+* **address** (string): A string representing an IP address
+
+**Returns**
+
+* `boolean` `true` if the IP is trusted, `false` otherwise
+
+
+**Usage**
+
+``` lua
+if kong.ip.is_trusted("1.1.1.1") then
+ kong.log("The IP is trusted")
+end
+```
+
+[Back to TOC](#table-of-contents)
+
diff --git a/app/1.2.x/1.1.x/pdk/kong.log.md b/app/1.2.x/1.1.x/pdk/kong.log.md
new file mode 100644
index 000000000000..1914b5d02f3c
--- /dev/null
+++ b/app/1.2.x/1.1.x/pdk/kong.log.md
@@ -0,0 +1,261 @@
+---
+title: kong.log
+pdk: true
+toc: true
+---
+
+## kong.log
+
+This namespace contains an instance of a "logging facility", which is a
+ table containing all of the methods described below.
+
+ This instance is namespaced per plugin, and Kong will make sure that before
+ executing a plugin, it will swap this instance with a logging facility
+ dedicated to the plugin. This allows the logs to be prefixed with the
+ plugin's name for debugging purposes.
+
+
+
+
+### kong.log(...)
+
+Write a log line to the location specified by the current Nginx
+ configuration block's `error_log` directive, with the `notice` level (similar
+ to `print()`).
+
+ The Nginx `error_log` directive is set via the `log_level`, `proxy_error_log`
+ and `admin_error_log` Kong configuration properties.
+
+ Arguments given to this function will be concatenated similarly to
+ `ngx.log()`, and the log line will report the Lua file and line number from
+ which it was invoked. Unlike `ngx.log()`, this function will prefix error
+ messages with `[kong]` instead of `[lua]`.
+
+ Arguments given to this function can be of any type, but table arguments
+ will be converted to strings via `tostring` (thus potentially calling a
+ table's `__tostring` metamethod if set). This behavior differs from
+ `ngx.log()` (which only accepts table arguments if they define the
+ `__tostring` metamethod) with the intent to simplify its usage and be more
+ forgiving and intuitive.
+
+ Produced log lines have the following format when logging is invoked from
+ within the core:
+
+ ``` plain
+ [kong] %file_src:%line_src %message
+ ```
+
+ In comparison, log lines produced by plugins have the following format:
+
+ ``` plain
+ [kong] %file_src:%line_src [%namespace] %message
+ ```
+
+ Where:
+
+ * `%namespace`: is the configured namespace (the plugin name in this case).
+ * `%file_src`: is the file name from where the log was called from.
+ * `%line_src`: is the line number from where the log was called from.
+ * `%message`: is the message, made of concatenated arguments given by the caller.
+
+ For example, the following call:
+
+ ``` lua
+ kong.log("hello ", "world")
+ ```
+
+ would, within the core, produce a log line similar to:
+
+ ``` plain
+ 2017/07/09 19:36:25 [notice] 25932#0: *1 [kong] some_file.lua:54 hello world, client: 127.0.0.1, server: localhost, request: "GET /log HTTP/1.1", host: "localhost"
+ ```
+
+ If invoked from within a plugin (e.g. `key-auth`) it would include the
+ namespace prefix, like so:
+
+ ``` plain
+ 2017/07/09 19:36:25 [notice] 25932#0: *1 [kong] some_file.lua:54 [key-auth] hello world, client: 127.0.0.1, server: localhost, request: "GET /log HTTP/1.1", host: "localhost"
+ ```
+
+
+**Phases**
+
+* init_worker, certificate, rewrite, access, header_filter, body_filter, log
+
+**Parameters**
+
+* **...** : all params will be concatenated and stringified before being sent to the log
+
+**Returns**
+
+* Nothing; throws an error on invalid inputs.
+
+
+**Usage**
+
+``` lua
+kong.log("hello ", "world") -- alias to kong.log.notice()
+```
+
+[Back to TOC](#table-of-contents)
+
+
+### kong.log.LEVEL(...)
+
+Similar to `kong.log()`, but the produced log will have the severity given by
+ `
+
+
+
+ 
Installation
+ You can install Kong on most Linux distributions and macOS. We even provide the source so you can compile yourself.
+ Install Kong → +
+
+
+
+ 
5-minute Quickstart
+ Learn how to start Kong, add a Service, enable plugins, and add consumers in under thirty seconds.
+ Start using Kong → +
+
+
+
+ 
DB-less & Declarative Configuration
+ Learn how to leverage the declarative configuration format for using Kong without a database, using in-memory storage only.
+ Read the tutorial → +
+
+
+
+ Streams & Service Mesh
+ Want to use Kong over TCP traffic? Want to start using Service Mesh? Check our tutorial to learn how to do it.
+ Read the tutorial → +
+
+
+
+ Kubernetes & Service Mesh
+ We have a quick demo repository showing how to run Kong Service Mesh on Kubernetes.
+ Visit the repo → +
+
+
+
+ Upgrade guide
+ Already using Kong, and wanting to upgrade? Here's the step-by-step guide.
+ Read the upgrade guide → +
+
+
+
+ Configuration file
+ Want to further optimize your Kong cluster, database, or configure NGINX? Dive into the configuration.
+ Start configuring Kong → +
+
+
+
+ CLI reference
+ Want a better understanding of the CLI tool and its options? Browse the detailed command reference.
+ Use the CLI → +
+
+
+
+ Admin API reference
+ Ready to learn the underlying interface? Browse the Admin API reference to learn how to start making requests.
+ Explore the interface → +
+
+
+
+ Proxy reference
+ Learn every way to configure Kong to proxy your Services, serve them over SSL or use WebSockets.
+ Read the Proxy Reference → +
+
+
+
+ Load balancing reference
+ Learn how to setup Kong to load balance traffic through replicas of your upstream services.
+ Read the Load balancing Reference → +
+
+
+
+ Health checks & circuit breakers
+ Let Kong monitor the availability of your services and adjust its load balancing accordingly.
+ Learn about health checks and circuit breakers → +
+
+
+
+ 
Clustering
+ If you are starting more than one node, you must use clustering to make sure all the nodes belong to the same Kong cluster.
+ Read the clustering reference → +
+
+
+
+
+Write your own plugins
+ Looking for something Kong does not do for you? Easy: write it as a plugin. Learn how to write your own plugins for Kong.
+ Read the plugin development guide → +
+ Note: This chapter assumes that you have a relative
+ knowledge of Lapis.
+
+
+## Introduction
+
+Kong can be configured using a REST interface referred to as the [Admin API].
+Plugins can extend it by adding their own endpoints to accommodate custom
+entities or other personalized management needs. A typical example of this is
+the creation, retrieval, and deletion (commonly referred to as "CRUD
+operations") of API keys.
+
+The Admin API is a [Lapis](http://leafo.net/lapis/) application, and Kong's
+level of abstraction makes it easy for you to add endpoints.
+
+## Module
+
+```
+kong.plugins.| Name | Type | Description |
|---|---|---|
name |
+ string (required) |
+ It will be used to determine the DAO name (kong.db.[name]). |
+
primary_key |
+ table (required) |
+
+ Field names forming the entity's primary key.
+ Schemas support composite keys, even if most Kong core entities currently use an UUID named
+ id. If you are using Cassandra and need a composite key, it should have the same
+ fields as the partition key.
+ |
+
endpoint_key |
+ string (optional) |
+
+ The name of the field used as an alternative identifier on the Admin API.
+ On the example above, key is the endpoint_key. This means that a credential with
+ id = 123 and key = "foo" could be referenced as both
+ /keyauth_credentials/123 and /keyauth_credentials/foo.
+ |
+
cache_key |
+ table (optional) |
+
+ Contains the name of the fields used for generating the cache_key, a string which must
+ unequivocally identify the entity inside Kong's cache. A unique field, like key in your example,
+ is usually good candidate. In other cases a combination of several fields is preferable.
+ |
+
fields |
+ table |
+ + Each field definition is a table with a single key, which is the field's name. The table value is + a subtable containing the field's attributes, some of which will be explained below. + | +
| Attribute name | type | Description |
|---|---|---|
type |
+ string |
+
+ Schemas support the following scalar types: "string", "integer", "number" and
+ "boolean". Compound types like "array", "record", or "set" are
+ also supported.+ + In additon to these values, the type attribute can also take the special "foreign" value,
+ which denotes a foreign relationship.+ + Each field will need to be backed by database fields of appropriately similar types, created via migrations. + + type is the only required attribute for all field definitions.
+ |
+
default |
+ any (matching with type attribute) |
+ + Specifies the value the field will have when attempting to insert it, if no value was provided. + Default values are always set via Lua, never by the underlying database. It is thus not recommended to set + any default values on fields in migrations. + | +
required |
+ boolean |
+
+ When set to true on a field, an error will be thrown when attempting to insert an entity lacking a value
+ for said field (unless the field in question has a default value).
+ |
+
unique |
+ boolean |
+
+ When set to This attribute must be backed up by declaring fields as |
+
auto |
+ boolean |
+
+ When attempting to insert an entity without providing a value for this a field where auto is set to true,
+ +
|
+
reference |
+ string |
+ Required for fields of type foreign. The given string must be the name of an existing schema,
+ to which the foreign key will "point to". This means that if a schema B has a foreign key pointing to schema A,
+ then A needs to be loaded before B.
+ |
+
on_delete |
+ string |
+
+ Optional and exclusive for fields of type foreign. It dictates what must happen
+ with entities linked by a foreign key when the entity being referenced is deleted. It can have three possible
+ values:+ +
+ In Cassandra this is handled with pure Lua code, but in PostgreSQL it will be necessary to declare the references + as ON DELETE CASCADE/NULL/RESTRICT in a migration.
+ |
+
+ Note: This chapter assumes that you are familiar with
+ Lua.
+
+
+## Introduction
+
+A Kong plugin allows you to inject custom logic (in Lua) at several
+entry-points in the life-cycle of a request/response or a tcp stream
+connection as it is proxied by Kong. To do so, one must implement one
+or several of the methods of the `base_plugin.lua` interface. Those
+methods are to be implemented in a module namespaced under:
+`kong.plugins.
+ Note: Kong uses the
+ rxi/classic module to simulate
+ classes in Lua and ease the inheritance pattern.
+
+
+```lua
+-- Extending the Base Plugin handler is optional, as there is no real
+-- concept of interface in Lua, but the Base Plugin handler's methods
+-- can be called from your child implementation and will print logs
+-- in your `error.log` file (where all logs are printed).
+local BasePlugin = require "kong.plugins.base_plugin"
+
+
+local CustomHandler = BasePlugin:extend()
+
+
+CustomHandler.VERSION = "1.0.0"
+CustomHandler.PRIORITY = 10
+
+
+-- Your plugin handler's constructor. If you are extending the
+-- Base Plugin handler, it's only role is to instantiate itself
+-- with a name. The name is your plugin name as it will be printed in the logs.
+function CustomHandler:new()
+ CustomHandler.super.new(self, "my-custom-plugin")
+end
+
+function CustomHandler:init_worker()
+ -- Eventually, execute the parent implementation
+ -- (will log that your plugin is entering this context)
+ CustomHandler.super.init_worker(self)
+
+ -- Implement any custom logic here
+end
+
+
+function CustomHandler:preread(config)
+ -- Eventually, execute the parent implementation
+ -- (will log that your plugin is entering this context)
+ CustomHandler.super.preread(self)
+
+ -- Implement any custom logic here
+end
+
+
+function CustomHandler:certificate(config)
+ -- Eventually, execute the parent implementation
+ -- (will log that your plugin is entering this context)
+ CustomHandler.super.certificate(self)
+
+ -- Implement any custom logic here
+end
+
+function CustomHandler:rewrite(config)
+ -- Eventually, execute the parent implementation
+ -- (will log that your plugin is entering this context)
+ CustomHandler.super.rewrite(self)
+
+ -- Implement any custom logic here
+end
+
+function CustomHandler:access(config)
+ -- Eventually, execute the parent implementation
+ -- (will log that your plugin is entering this context)
+ CustomHandler.super.access(self)
+
+ -- Implement any custom logic here
+end
+
+function CustomHandler:header_filter(config)
+ -- Eventually, execute the parent implementation
+ -- (will log that your plugin is entering this context)
+ CustomHandler.super.header_filter(self)
+
+ -- Implement any custom logic here
+end
+
+function CustomHandler:body_filter(config)
+ -- Eventually, execute the parent implementation
+ -- (will log that your plugin is entering this context)
+ CustomHandler.super.body_filter(self)
+
+ -- Implement any custom logic here
+end
+
+function CustomHandler:log(config)
+ -- Eventually, execute the parent implementation
+ -- (will log that your plugin is entering this context)
+ CustomHandler.super.log(self)
+
+ -- Implement any custom logic here
+end
+
+-- This module needs to return the created table, so that Kong
+-- can execute those functions.
+return CustomHandler
+```
+
+Of course, the logic of your plugin itself can be abstracted away in another
+module, and called from your `handler` module. Many existing plugins have
+already chosen this pattern when their logic is verbose, but it is purely
+optional:
+
+```lua
+local BasePlugin = require "kong.plugins.base_plugin"
+
+-- The actual logic is implemented in those modules
+local access = require "kong.plugins.my-custom-plugin.access"
+local body_filter = require "kong.plugins.my-custom-plugin.body_filter"
+
+
+local CustomHandler = BasePlugin:extend()
+
+
+CustomHandler.VERSION = "1.0.0"
+CustomHandler.PRIORITY = 10
+
+
+function CustomHandler:new()
+ CustomHandler.super.new(self, "my-custom-plugin")
+end
+
+function CustomHandler:access(config)
+ CustomHandler.super.access(self)
+
+ -- Execute any function from the module loaded in `access`,
+ -- for example, `execute()` and passing it the plugin's configuration.
+ access.execute(config)
+end
+
+function CustomHandler:body_filter(config)
+ CustomHandler.super.body_filter(self)
+
+ -- Execute any function from the module loaded in `body_filter`,
+ -- for example, `execute()` and passing it the plugin's configuration.
+ body_filter.execute(config)
+end
+
+
+return CustomHandler
+```
+
+See [the source code of the Key-Auth plugin](https://github.com/Kong/kong/blob/master/kong/plugins/key-auth/handler.lua)
+for an example of a real-life handler code.
+
+---
+
+## Plugin Development Kit
+
+Logic implemented in those phases will most likely have to interact with the
+request/response objects or core components (e.g. access the cache, and
+database). Kong provides a [Plugin Development Kit][pdk] (or "PDK") for such
+purposes: a set of Lua functions and variables that can be used by plugins to
+execute various gateway operations in a way that is guaranteed to be
+forward-compatible with future releases of Kong.
+
+When you are trying to implement some logic that needs to interact with Kong
+(e.g. retrieving request headers, producing a response from a plugin, logging
+some error or debug information), you should consult the [Plugin Development
+Kit Reference][pdk].
+
+---
+
+## Plugins execution order
+
+Some plugins might depend on the execution of others to perform some
+operations. For example, plugins relying on the identity of the consumer have
+to run **after** authentication plugins. Considering this, Kong defines
+**priorities** between plugins execution to ensure that order is respected.
+
+Your plugin's priority can be configured via a property accepting a number in
+the returned handler table:
+
+```lua
+CustomHandler.PRIORITY = 10
+```
+
+The higher the priority, the sooner your plugin's phases will be executed in
+regard to other plugins' phases (such as `:access()`, `:log()`, etc.).
+
+The current order of execution for the bundled plugins is:
+
+Plugin | Priority
+----------------------------|----------
+pre-function | `+inf`
+zipkin | 100000
+ip-restriction | 3000
+bot-detection | 2500
+cors | 2000
+kubernetes-sidecar-injector | 1006
+jwt | 1005
+oauth2 | 1004
+key-auth | 1003
+ldap-auth | 1002
+basic-auth | 1001
+hmac-auth | 1000
+request-size-limiting | 951
+acl | 950
+rate-limiting | 901
+response-ratelimiting | 900
+request-transformer | 801
+response-transformer | 800
+aws-lambda | 750
+azure-functions | 749
+prometheus | 13
+http-log | 12
+statsd | 11
+datadog | 10
+file-log | 9
+udp-log | 8
+tcp-log | 7
+loggly | 6
+syslog | 4
+request-termination | 2
+correlation-id | 1
+post-function | -1000
+
+---
+
+Next: [Plugin configuration ›]({{page.book.next}})
+
+[lua-nginx-module]: https://github.com/openresty/lua-nginx-module
+[pdk]: /{{page.kong_version}}/pdk
diff --git a/app/1.2.x/1.1.x/plugin-development/distribution.md b/app/1.2.x/1.1.x/plugin-development/distribution.md
new file mode 100644
index 000000000000..3b1d6bf66a9c
--- /dev/null
+++ b/app/1.2.x/1.1.x/plugin-development/distribution.md
@@ -0,0 +1,306 @@
+---
+title: Plugin Development - (un)Installing your plugin
+book: plugin_dev
+chapter: 10
+---
+
+## Introduction
+
+Custom plugins for Kong consist of Lua source files that need to be in the file
+system of each of your Kong nodes. This guide will provide you with
+step-by-step instructions that will make a Kong node aware of your custom
+plugin(s).
+
+These steps should be applied to each node in your Kong cluster, to ensure the
+custom plugin(s) are available on each one of them.
+
+## Packaging sources
+
+You can either use a regular packing strategy (e.g. `tar`), or use the LuaRocks
+package manager to do it for you. We recommend LuaRocks as it is installed
+along with Kong when using one of the official distribution packages.
+
+When using LuaRocks, you must create a `rockspec` file, which specifies the
+package contents. For an example see the [Kong plugin
+template][plugin-template], for more info about the format see the LuaRocks
+[documentation on rockspecs][rockspec].
+
+Pack your rock using the following command (from the plugin repo):
+
+ # install it locally (based on the `.rockspec` in the current directory)
+ $ luarocks make
+
+ # pack the installed rock
+ $ luarocks pack
+ Note: This chapter assumes that you are familiar with
+ Lua.
+
+
+## Introduction
+
+Consider your plugin as a set of [Lua
+modules](http://www.lua.org/manual/5.1/manual.html#6.3). Each file described in
+this chapter is to be considered as a separate module. Kong will detect and
+load your plugin's modules if their names follow this convention:
+
+```
+kong.plugins.
+
+
+## Terminology
+
+- `client`: Refers to the *downstream* client making requests to Kong's
+ proxy port.
+- `upstream service`: Refers to your own API/service sitting behind Kong, to
+ which client requests are forwarded.
+- `Service`: 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.
+- `Route`: This refers to the Kong Routes entity. Routes are entrypoints into
+ Kong, and defining rules for a request to be matched, and routed to a given
+ Service.
+- `Plugin`: This refers to Kong "plugins", which are pieces of business logic
+ that run in the proxying lifecycle. Plugins can be configured through the
+ Admin API - either globally (all incoming traffic) or on specific Routes
+ and Services.
+
+[Back to TOC](#table-of-contents)
+
+## Overview
+
+From a high-level perspective, Kong listens for HTTP traffic on its configured
+proxy port(s) (`8000` and `8443` by default). Kong will evaluate any incoming
+HTTP request against the Routes you have configured and try to find a matching
+one. If a given request matches the rules of a specific Route, Kong will
+process proxying the request. Because each Route is linked to a Service, Kong
+will run the plugins you have configured on your Route and its associated
+Service, and then proxy the request upstream.
+
+You can manage Routes via Kong's Admin API. The `hosts`, `paths`, and `methods`
+attributes of Routes define rules for matching incoming HTTP requests.
+
+If Kong receives a request that it cannot match against any of the configured
+Routes (or if no Routes are configured), it will respond with:
+
+```http
+HTTP/1.1 404 Not Found
+Content-Type: application/json
+Server: kong/Note: Starting with 1.0.0, the API entity has been removed. +This document will cover proxying with the new Routes and +Services entities.
+See an older version of this document if you are using 0.12 or +below.
+
+ Enterprise-Only This feature is only available with an
+ Enterprise Subscription.
+
+
+Enterprise users can configure role-based access control to secure access to the
+Admin API. RBAC allows for fine-grained control over resource access based on
+a model of user roles and permissions. Users are assigned to one or more roles,
+which each in turn possess one or more permissions granting or denying access
+to a particular resource. In this way, fine-grained control over specific Admin
+API resources can be enforced, while scaling to allow complex, case-specific
+uses.
+
+If you are not a Kong Enterprise customer, you can inquire about our
+Enterprise offering by [contacting us](/enterprise).
+
+[Back to TOC](#table-of-contents)
+
+
+[acl]: /plugins/acl
+[basic-auth]: /plugins/basic-authentication/
+[custom-configuration]: /{{page.kong_version}}/configuration/#custom-nginx-configuration
+[ip-restriction]: /plugins/ip-restriction
+[key-auth]: /plugins/key-authentication
diff --git a/app/1.2.x/1.1.x/streams-and-service-mesh.md b/app/1.2.x/1.1.x/streams-and-service-mesh.md
new file mode 100644
index 000000000000..0b44db64f8b5
--- /dev/null
+++ b/app/1.2.x/1.1.x/streams-and-service-mesh.md
@@ -0,0 +1,643 @@
+---
+title: Streams and Service Mesh
+---
+
+
+## Introduction
+
+Kong `0.15.0` / `1.0.0` added the capability to proxy and route raw `tcp` and `tls`
+streams and deploy Kong using a service-mesh sidecar pattern with mutual
+`tls` between Kong nodes. This tutorial walks you trough a basic setup of
+a simplified Service Mesh deployment using simple tooling: two servers,
+talking with each other via two Kong nodes, in a single host. It introduces
+new concepts, configuration settings and tools along the way. In a production
+environment, almost all of this should be automated. It is still nice to
+know how things work on a lower level. If you are interested in running
+Service Mesh with Kubernetes, please head over to our
+[Kubernetes and Service Mesh example repo](https://github.com/Kong/kong-mesh-dist-kubernetes).
+
+Kong supports gradual deployment of a sidecar pattern. It can work both as
+a traditional gateway and as a service mesh node at the same time. In Kong
+the service mesh is built dynamically, and it only exists when there are
+active connections between the Kong nodes. In short it means that Kong nodes
+do not have to know about other Kong nodes, and services do not have to
+know about Kong.
+
+
+## Prerequisites
+
+You need **Kong 1.1.0 or later** to run through different deployment scenarios
+in this tutorial. It is recommended to use Linux distribution to run
+the demos, e.g. a recent version of Ubuntu. You will also need some additional
+tools to be installed on your system:
+
+- `ncat` (usually comes with `nmap`)
+- `iptables` (**Linux**) or `pfctl` (**macOS** / **BSD**)
+- `curl`
+
+Your host machine needs to bind `lo0` (or similar) network adapter to these
+localhost IPs:
+
+- `127.0.0.1` (**Host C** running **Kong Control Plane**)
+- `127.0.0.2` (**Host A** running **Service A**)
+- `127.0.0.3` (**Host A** running **Kong A**)
+- `127.0.0.4` (**Host B** running **Kong B**)
+- `127.0.0.5` (**Host B** running **Service B**)
+
+We are running everything in a single host on this tutorial, but you are allowed
+to use two separate nodes to run the demos. In such case, please note that there
+will be differences in IP addresses in related commands and configurations.
+For the sake of simplicity we also configure everything using just IP addresses
+instead of using DNS.
+
+For some of the configuration changes, you may also need **root** privileges on
+a target host.
+
+
+## Terms and Definitions
+
+
+**Kong Control Plane** is started on network address `127.0.0.1`. It listens on Kong
+Admin API on ports `8001` (`http`), and `8444` (`https`), and it won't proxy any traffic.
+
+**Service A** represents an imaginary business entity (microservice, app) making the network
+connections to **Service B**. On this tutorial **Service A** is modelled by
+direct invocations of `ncat` and `curl`. **Service A**'s network address is `127.0.0.2`.
+
+**Service B** represent a business entity which accepts network connections from **Service A**.
+On this tutorial it is implemented via several `ncat` processes, kept open. Its network address
+is `127.0.0.5`, and it listens on ports `18000`(`http`), `18443`(`https`), `19000`(`tcp`), and
+`19443`(`tls`).
+
+**Kong A** is the sidecar proxy in-front of **Service A**. It listens on network address
+`127.0.0.3` on proxy ports `8000` (`http`), `8443` (`https`), `9000` (`tcp`), and `9443` (`tls`).
+It does not listen or provide Kong Admin API.
+
+**Kong B** is the sidecar proxy in-front of **Service B**. It listens on network address
+`127.0.0.4` on proxy ports `8000` (`http`), `8443` (`https`), `9000` (`tcp`), and `9443` (`tls`).
+It does not listen or provide Kong Admin API.
+
+The examples presented here are run directly from a `terminal`, such as `bash` shell.
+Please follow each step as it gradually builds the understanding and introduces new
+concepts along the way.
+
+
+## Step 1: Start Service B
+
+As we said before, **Service B** can be modelled as several `ncat` processes. We need
+several in order to model all possible Service Mesh combinations.
+
+
+Start **Service B** listening on TCP traffic:
+
+```
+$ ncat --listen \
+ --keep-open \
+ --verbose \
+ --sh-exec "echo 'Hello from Service B (TCP)'" \
+ 127.0.0.5 19000
+```
+
+You should see output similar to one below:
+
+```
+Ncat: Version 7.70 ( https://nmap.org/ncat )
+Ncat: Listening on 127.0.0.5:19000
+```
+
+Leave the command running.
+
+
+Open a new console and start **Service B** listening on TLS traffic:
+
+```
+$ ncat --listen \
+ --keep-open \
+ --verbose \
+ --ssl \
+ --sh-exec "echo 'Hello from Service B (TLS)'" \
+ 127.0.0.5 19443
+```
+
+You should see output similar to one below:
+
+```
+Ncat: Version 7.70 ( https://nmap.org/ncat )
+Ncat: Listening on 127.0.0.5:19443
+```
+
+Leave it running.
+
+
+Open a new console and start **Service B** listening on HTTP traffic:
+
+```
+ncat --listen \
+ --keep-open \
+ --verbose \
+ --sh-exec "echo 'HTTP/1.1 200 OK\r\n\r\nHello from Service (HTTP)'" \
+ 127.0.0.5 18000
+```
+
+You should see output similar to one below:
+
+```
+Ncat: Version 7.70 ( https://nmap.org/ncat )
+Ncat: Listening on 127.0.0.5:18000
+```
+
+Again, leave that running.
+
+
+Open a fourth console and start **Service B** listening on HTTPS traffic:
+
+```
+ncat --listen \
+ --keep-open \
+ --verbose \
+ --ssl \
+ --sh-exec "echo 'HTTP/1.1 200 OK\r\n\r\nHello from Service B (HTTPS)'" \
+ 127.0.0.5 18443
+```
+
+You should see output similar to one below:
+
+```
+Ncat: Version 7.70 ( https://nmap.org/ncat )
+Ncat: Listening on 127.0.0.5:18443
+```
+
+Leave this command running as well.
+
+At this point you should have four `ncat` processes in 4 consoles,
+representing the **Service B** listening with different protocols.
+
+
+## Step 2: Ensure that Service A can connect Service B
+
+Our **Service A** is just direct invocations of `ncat` and `curl`.
+
+
+Connect with **Service B** using TCP:
+
+```
+ncat --source 127.0.0.2 --recv-only 127.0.0.5 19000
+```
+
+You should see output similar to one below:
+
+```
+Hello from Service B (TCP)
+```
+
+
+Connect with **Service B** using TLS:
+
+```
+ncat --source 127.0.0.2 --recv-only --ssl 127.0.0.5 19443
+```
+
+You should see output similar to one below:
+
+```
+Hello from Service B (TLS)
+```
+
+
+Connect with **Service B** using HTTP:
+
+```
+curl --interface 127.0.0.2 http://127.0.0.5:18000
+```
+
+You should see output similar to one below:
+
+```
+Hello from Service B (HTTP)
+```
+
+
+Connect with **Service B** using HTTPS:
+
+```
+curl --interface 127.0.0.2 --insecure https://127.0.0.5:18443
+```
+
+You should see output similar to one below:
+
+```
+Hello from Service B (HTTPS)
+```
+
+At this point you have **Service B** running at `127.0.0.5` and our
+**Service A** at `127.0.0.2` can directly and successfully connect
+to it.
+
+
+## Step 3: Start Kong Control Plane
+
+Start a Kong node that only listens to its Kong Admin API:
+
+```
+$ KONG_PREFIX=kong-c \
+ KONG_LOG_LEVEL=debug \
+ KONG_STREAM_LISTEN="off" \
+ KONG_PROXY_LISTEN="off" \
+ KONG_ADMIN_LISTEN="127.0.0.1:8001, 127.0.0.1:8444 ssl" \
+ kong start
+```
+
+You should see this message:
+
+```
+Kong started
+```
+
+
+## Step 4: Start Kong A
+
+**Kong A**, will be a Kong instance acting as sidecar for **Service A**.
+
+Start it like this:
+
+```
+$ KONG_PREFIX=kong-a \
+ KONG_LOG_LEVEL=debug \
+ KONG_STREAM_LISTEN="127.0.0.3:9000 transparent, 127.0.0.3:9443 transparent" \
+ KONG_PROXY_LISTEN="127.0.0.3:8000 transparent, 127.0.0.3:8443 ssl transparent" \
+ KONG_ADMIN_LISTEN="off" \
+ KONG_NGINX_PROXY_PROXY_BIND="127.0.0.3" \
+ KONG_NGINX_SPROXY_PROXY_BIND="127.0.0.3" \
+ kong start
+```
+
+On `macOS` / `BSD` use this instead:
+
+```
+$ KONG_PREFIX=kong-a \
+ KONG_LOG_LEVEL=debug \
+ KONG_STREAM_LISTEN="127.0.0.3:9000, 127.0.0.3:9443" \
+ KONG_PROXY_LISTEN="127.0.0.3:8000, 127.0.0.3:8443 ssl" \
+ KONG_ADMIN_LISTEN="off" \
+ KONG_NGINX_PROXY_PROXY_BIND="127.0.0.3" \
+ KONG_NGINX_SPROXY_PROXY_BIND="127.0.0.3" \
+ kong start
+```
+
+You should see this message:
+
+```
+Kong started
+```
+
+
+### About the `transparent` option
+
+The `transparent` listen option makes it possible for Kong to answer requests
+mangled with `iptables` `PREROUTING` rules, and to read the original destination
+address and the port that client tried to connect before `iptables` rules
+did `transparently` proxy it to its sidecar proxy.
+
+**Note:** `transparent` is only supported on `Linux`, and specifying
+it may require you to start Kong as a `root` user. If you are **not** running
+`Linux` (e.g. `macOS` or `BSD`), the transparent proxying is supported by default.
+
+
+## Step 5: Start Kong B
+
+**Kong B** will be the sidecar Kong instance for **Service B**.
+
+```
+$ KONG_PREFIX=kong-b \
+ KONG_LOG_LEVEL=debug \
+ KONG_STREAM_LISTEN="127.0.0.4:9000 transparent, 127.0.0.4:9443 transparent" \
+ KONG_PROXY_LISTEN="127.0.0.4:8000 transparent, 127.0.0.4:8443 transparent ssl" \
+ KONG_ADMIN_LISTEN="off" \
+ KONG_NGINX_PROXY_PROXY_BIND="127.0.0.4" \
+ KONG_NGINX_SPROXY_PROXY_BIND="127.0.0.4" \
+ kong start
+```
+
+On `macOS` / `BSD` use this instead:
+
+```
+$ KONG_PREFIX=kong-b \
+ KONG_LOG_LEVEL=debug \
+ KONG_STREAM_LISTEN="127.0.0.4:9000, 127.0.0.4:9443" \
+ KONG_PROXY_LISTEN="127.0.0.4:8000, 127.0.0.4:8443 ssl" \
+ KONG_ADMIN_LISTEN="off" \
+ KONG_NGINX_PROXY_PROXY_BIND="127.0.0.4" \
+ KONG_NGINX_SPROXY_PROXY_BIND="127.0.0.4" \
+ kong start
+```
+
+You should see this message if the Kong node starts successfully:
+
+```
+Kong started
+```
+
+**Note**: In the real world, you should use `nginx worker user` to make the exceptions
+to `iptables` rules (see step 7), but for this simplified demo, we use the `proxy_bind`
+for the exceptions on rules.
+
+
+## Step 6: Create Kong Services and Routes
+
+Create Kong Service for **Service B**'s TCP Traffic:
+
+```
+$ curl -X PUT \
+ -d url=tcp://127.0.0.5:19000 \
+ http://127.0.0.1:8001/services/service-b-tcp
+```
+
+Create one Kong Route for that Kong Service:
+
+```
+$ curl -X POST \
+ -d name=service-b-tcp \
+ -d protocols=tcp \
+ -d destinations[1].ip=127.0.0.5 \
+ -d destinations[1].port=19000 \
+ http://127.0.0.1:8001/services/service-b-tcp/routes
+```
+
+Create a Kong Service for **Service B**'s TLS Traffic:
+
+```
+$ curl -X PUT \
+ -d url=tls://127.0.0.5:19443 \
+ http://127.0.0.1:8001/services/service-b-tls
+```
+
+And one Route for it:
+
+```
+$ curl -X POST \
+ -d name=service-b-tls \
+ -d protocols=tls \
+ -d destinations[1].ip=127.0.0.5 \
+ -d destinations[1].port=19443 \
+ http://127.0.0.1:8001/services/service-b-tls/routes
+```
+
+Create a Kong Service for **Service B**'s HTTP Traffic:
+
+```
+$ curl -X PUT \
+ -d url=http://127.0.0.5:18000 \
+ http://127.0.0.1:8001/services/service-b-http
+```
+
+Create a Kong Route for this Kong Service as well:
+
+```
+$ curl -X POST \
+ -d name=service-b-http \
+ -d protocols=http \
+ -d hosts=127.0.0.5 \
+ http://127.0.0.1:8001/services/service-b-http/routes
+```
+
+Finally, create a Kong Service for **Service B**'s HTTPS Traffic:
+
+```
+$ curl -X PUT \
+ -d url=https://127.0.0.5:18443/ \
+ http://127.0.0.1:8001/services/service-b-https
+```
+
+And a Kong Route to go with it:
+
+```
+$ curl -X POST \
+ -d name=service-b-https \
+ -d protocols=https \
+ -d hosts=127.0.0.5 \
+ http://127.0.0.1:8001/services/service-b-https/routes
+```
+
+
+## Step 7: Configure Transparent Proxying Rules
+
+Following `iptables` commands add transparent proxying rules for **Service A**.
+They make **Service A** to connect **Kong A** instead of connecting to to **Service B**
+directly as we saw on Step 2.
+
+Configure `iptables` on **Service A**:
+
+```
+$ sudo iptables --insert PREROUTING \
+ --table mangle \
+ --protocol tcp \
+ --dport 19000 \
+ --source 127.0.0.2 \
+ --jump TPROXY \
+ --on-port=9000 \
+ --on-ip=127.0.0.3
+
+$ sudo iptables --insert PREROUTING \
+ --table mangle \
+ --protocol tcp \
+ --dport 19443 \
+ --source 127.0.0.2 \
+ --jump TPROXY \
+ --on-port=9443 \
+ --on-ip=127.0.0.3
+
+$ sudo iptables --insert PREROUTING \
+ --table mangle \
+ --protocol tcp \
+ --dport 18000 \
+ --source 127.0.0.2 \
+ --jump TPROXY \
+ --on-port=8000 \
+ --on-ip=127.0.0.3
+
+$ sudo iptables --insert PREROUTING \
+ --table mangle \
+ --protocol tcp \
+ --dport 18443 \
+ --source 127.0.0.2 \
+ --jump TPROXY \
+ --on-port=8443 \
+ --on-ip=127.0.0.3
+```
+
+And then configure more rules for intercepting traffic destined for **Service B**, and send
+it to **Kong B** instead:
+
+```
+$ sudo iptables --append PREROUTING \
+ --table mangle \
+ --protocol tcp \
+ "!" --source 127.0.0.4 \
+ --dport 19000 \
+ --destination 127.0.0.5 \
+ --jump TPROXY \
+ --on-port=9000 \
+ --on-ip=127.0.0.4
+
+$ sudo iptables --append PREROUTING \
+ --table mangle \
+ --protocol tcp \
+ "!" --source 127.0.0.4 \
+ --dport 19443 \
+ --destination 127.0.0.5 \
+ --jump TPROXY \
+ --on-port=9443 \
+ --on-ip=127.0.0.4
+
+$ sudo iptables --append PREROUTING \
+ --table mangle \
+ --protocol tcp \
+ "!" --source 127.0.0.4 \
+ --dport 18000 \
+ --destination 127.0.0.5 \
+ --jump TPROXY \
+ --on-port=8000 \
+ --on-ip=127.0.0.4
+
+$ sudo iptables --append PREROUTING \
+ --table mangle \
+ --protocol tcp \
+ "!" --source 127.0.0.4 \
+ --dport 18443 \
+ --destination 127.0.0.5 \
+ --jump TPROXY \
+ --on-port=8443 \
+ --on-ip=127.0.0.4
+```
+
+
+The equivalent `TPROXY` rules with `macOS` or `BSDs` is a bit tricky, so we leave that
+to the reader. If we find a simple way to define them, we'll update this article.
+
+
+## Step 8: Start tailing Kong Logs
+
+We do this so that you can view that the requests on next step do pass both **Kong A**
+and **Kong B**. Run this command for **Kong A**:
+
+```
+$ tail -F kong-a/logs/error.log
+```
+
+Leave it running, and in another console, run this command for **Kong B**:
+
+```
+$ tail -F kong-b/logs/error.log
+```
+
+
+## Step 9: Connect Service A to Service B using Two Sidecars
+
+Connect from **Service A** to **Service B** using TCP:
+
+```
+ncat --source 127.0.0.2 127.0.0.5 19000
+```
+
+**Note:** at the moment you need to write around twenty bytes to
+the stream with the client to actually receive the response from
+the server (we are working on it).
+
+You should see output similar to one below:
+
+```
+Hello from Service B (TCP)
+```
+
+Connect using TLS:
+
+```
+ncat --source 127.0.0.2 --recv-only --ssl 127.0.0.5 19443
+```
+
+You should see output similar to one below:
+
+```
+Hello from Service B (TLS)
+```
+
+Connect using HTTP:
+
+```
+curl --interface 127.0.0.2 http://127.0.0.5:18000
+```
+
+You should see output similar to one below:
+
+```
+Hello from Service B (HTTP)
+```
+
+Connect using HTTPS:
+
+```
+curl --interface 127.0.0.2 --insecure https://127.0.0.5:18443
+```
+
+You should see output similar to one below:
+
+```
+Hello from Service B (HTTPS)
+```
+
+As you can see, step 9 looks exactly the same as step 2. We did not need to
+make any changes to **Service A** or **Service B**, but we introduced a sidecar proxy
+to each of them while successfully demonstrating that Kong is capable to proxy
+both raw `tcp` and `tls` streams and `http` and `https` traffic.
+
+
+### About Service Mesh
+
+In Kong we call it Service Mesh only when the connection between the two sidecars,
+**Kong A** and **Kong B**, is mutually TLS authenticated. That is not obviously the
+case in this document with the `tcp` and `http` demos. But what makes things interesting
+is that Kong can automatically update unprotected `tcp` and `http` connections to `tls`
+protected connections so that **Kong A** will always talk to **Kong B** using either `tls`
+or `https`. And on the other side, **Kong B**, Kong can also downgrade the `tls` and `https`
+connections to unprotected `tcp` or `http` before making that final proxy connection
+to the local **Service B**. You can adjust these settings by modifying the Service
+entities (or adjusting the `KONG_ORIGINS` setting on **Kong B** which we didn't cover
+on this tutorial).
+
+## Step 10: Stop Kong Nodes and Cleanup
+
+Cleanup the `iptables` rules:
+
+```
+sudo iptables --table mangle --flush PREROUTING
+```
+
+Stop **Kong B**:
+
+```
+KONG_PREFIX=kong-b kong stop
+```
+
+Stop **Kong A**:
+
+```
+KONG_PREFIX=kong-a kong stop
+```
+
+Stop Kong Control Plane:
+
+```
+KONG_PREFIX=kong-c kong stop
+```
+
+Stop Tailing Kong Logs:
+
+```
+pkill tail
+```
+
+Stop Ncat Servers:
+
+```
+pkill ncat
+```
diff --git a/app/1.2.x/1.1.x/upgrading.md b/app/1.2.x/1.1.x/upgrading.md
new file mode 100644
index 000000000000..a019d846f832
--- /dev/null
+++ b/app/1.2.x/1.1.x/upgrading.md
@@ -0,0 +1,307 @@
+---
+title: Upgrade guide
+---
+
+
+ Note: What follows is the upgrade guide for 1.0.x.
+ If you are trying to upgrade to an earlier version of Kong, please read
+ UPGRADE.md file in the Kong repo
+
+
+This guide will inform you about breaking changes you should be aware of
+when upgrading, as well as take you through the correct sequence of steps
+in order to obtain a **no-downtime** migration in different upgrade
+scenarios.
+
+## Upgrade to `1.0.0`
+
+This is a major release of Kong, and includes a number of new features
+as well as breaking changes.
+
+This version introduces **a new schema format for plugins**, **changes in
+Admin API endpoints**, **database migrations**, **Nginx configuration
+changes**, and **removed configuration properties**.
+
+In this release, the **API entity is removed**, along with its related
+Admin API endpoints.
+
+This section will highlight breaking changes that you need to be aware of
+before upgrading and will describe the recommended upgrade path. We recommend
+that you consult the full [1.0.0
+Changelog](https://github.com/Kong/kong/blob/master/CHANGELOG.md) for a
+complete list of changes and new features.
+
+## 1. Breaking Changes
+
+### Dependencies
+
+- The required OpenResty version is 1.13.6.2, but for a full feature set,
+ including stream routing and service mesh abilities with mutual TLS, you need
+ Kong's [openresty-patches](https://github.com/kong/openresty-patches).
+- The minimum required OpenSSL version is 1.1.1. If you are building by hand,
+ make sure all dependencies, including LuaRocks modules, are compiled using
+ the same OpenSSL version. If you are installing Kong from one of our
+ distribution packages, you are not affected by this change.
+
+### Configuration
+
+- The `custom_plugins` directive is removed (deprecated since 0.14.0).
+ Use `plugins` instead, which you can use not only to enable
+ custom plugins, but also to disable bundled plugins.
+- The default value for `cassandra_lb_policy` changed from `RoundRobin`
+ to `RequestRoundRobin`.
+- Kong generates a new template file for stream routing,
+ `nginx-kong-stream.conf`, included in the `stream` block
+ of its top-level Nginx configuration file. If you use
+ a custom Nginx configuration and wish to use stream
+ routing, you can generate this file using `kong prepare`.
+- The Nginx configuration file has changed, which means that you need to update
+ it if you are using a custom template. The changes are detailed in the following diff:
+
+``` diff
+diff --git a/kong/templates/nginx_kong.lua b/kong/templates/nginx_kong.lua
+index d4e416bc..8f268ffd 100644
+--- a/kong/templates/nginx_kong.lua
++++ b/kong/templates/nginx_kong.lua
+@@ -66,7 +66,9 @@ upstream kong_upstream {
+ balancer_by_lua_block {
+ Kong.balancer()
+ }
++> if upstream_keepalive > 0 then
+ keepalive ${{UPSTREAM_KEEPALIVE}};
++> end
+ }
+
+ server {
+@@ -85,7 +87,7 @@ server {
+ > if proxy_ssl_enabled then
+ ssl_certificate ${{SSL_CERT}};
+ ssl_certificate_key ${{SSL_CERT_KEY}};
+- ssl_protocols TLSv1.1 TLSv1.2;
++ ssl_protocols TLSv1.1 TLSv1.2 TLSv1.3;
+ ssl_certificate_by_lua_block {
+ Kong.ssl_certificate()
+ }
+@@ -200,7 +202,7 @@ server {
+ > if admin_ssl_enabled then
+ ssl_certificate ${{ADMIN_SSL_CERT}};
+ ssl_certificate_key ${{ADMIN_SSL_CERT_KEY}};
+- ssl_protocols TLSv1.1 TLSv1.2;
++ ssl_protocols TLSv1.1 TLSv1.2 TLSv1.3;
+
+ ssl_session_cache shared:SSL:10m;
+ ssl_session_timeout 10m;
+```
+
+### Core
+
+- The **API** entity and related concepts such as the
+ `/apis` endpoint, are removed. These were deprecated since
+ 0.13.0. Instead, use **Routes** to configure your
+ endpoints and **Services** to configure your upstream
+ services.
+- The old DAO implementation (`kong.dao`) is removed,
+ which includes the old schema validation library. This
+ has implications to plugin developers, listed below.
+ - The last remaining entities that were converted to
+ the new DAO implementation were Plugins, Upstreams
+ and Targets. This has implications to the Admin API,
+ listed below.
+
+### Plugins
+
+Kong 1.0.0 marks the introduction of version 1.0.0 of
+the Plugin Development Kit (PDK). No major changes are
+made to the PDK compared to release 0.14, but some older
+non-PDK functionality which was possibly used by custom
+plugins is now removed.
+
+- Plugins now use the new schema format introduced by the
+ new DAO implementation, for both plugin schemas
+ (in `schema.lua`) and custom DAO entities (`daos.lua`).
+ To ease the transition of plugins, the plugin loader
+ in 1.0 includes a *best-effort* schema auto-translator
+ for `schema.lua`, which should be sufficient for many
+ plugins (in 1.0.0rc1, our bundled plugins used the
+ auto-translator; they now use the new format).
+ - If your plugin using the old format in `schema.lua`
+ fails to load, check the error logs for messages
+ produced by the auto-translator. If a field cannot
+ be auto-translated, you can make a gradual conversion
+ of the schema file by adding a `new_type` entry to
+ the field table translation of the format. See,
+ for example, the [key-auth schema in 1.0.0rc1](https://github.com/Kong/kong/blob/1.0.0rc1/kong/plugins/key-auth/schema.lua#L39-L54).
+ The `new_type` annotation is ignored by Kong 0.x.
+ - If your custom plugin uses custom DAO objects (i.e.
+ if it includes a `daos.lua` file), it needs to be
+ converted to the new format. Their code also needs
+ to be adjusted accordingly, replacing uses of
+ `singletons.dao` or `kong.dao` by `kong.db` (note
+ that this module exposes a different API from the
+ old DAO implementation).
+- Some Kong modules that had their functionality replaced
+ by the PDK in 0.14.0 are now removed:
+ - `kong.tools.ip`: use `kong.ip` from the PDK instead.
+ - `kong.tools.public`: replaced by various functionalities
+ of the PDK.
+ - `kong.tools.responses`: use `kong.response.exit` from the PDK instead. You
+ might want to use `kong.log.err` to log internal server errors as well.
+- The `kong.api.crud_helpers` module was removed.
+ Use `kong.api.endpoints` instead if you need to customize
+ the auto-generated endpoints.
+
+### Admin API
+
+- With the removal of the API entity, the `/apis` endpoint
+ is removed; accordingly, other endpoints that accepted
+ `api_id` no longer do so. Use Routes and Services instead.
+- All entity endpoints now use the new Admin API implementaion.
+ This means their requests and responses now use the same
+ syntax, which was already in use in endpoints such as
+ `/routes` and `/services`.
+ - All endpoints now use the same syntax for
+ referencing other entities as `/routes`
+ (for example, `"service":{"id":"..."}` instead of
+ `"service_id":"..."`), both in requests and responses.
+ - This change affects `/plugins` as well as
+ plugin-specific endpoints.
+ - Array-typed values are not specified as a
+ comma-separated list anymore. It must be specified as a
+ JSON array or using the various formats supported by
+ the url-formencoded array notation of the new Admin API
+ implementation (`a[1]=x&a[2]=y`, `a[]=x&a[]=y`,
+ `a=x&a=y`).
+ - This change affects attributes of the `/upstreams` endpoint.
+ - Error responses for the updated endpoints use
+ the new standardized format.
+ - As a result of being moved to the new Admin API implementation,
+ all endpoints supporting `PUT` do so with proper semantics.
+ - See the [Admin API
+ reference](https://docs.konghq.com/1.0.x/admin-api)
+ for more details.
+
+## 2. Deprecation Notices
+
+There are no deprecation notices in this release.
+
+## 3. Suggested Upgrade Path
+
+### Preliminary Checks
+
+If your cluster is running a version lower than 0.14, you need to
+upgrade to 0.14.1 first instead. Upgrading from a pre-0.14 cluster
+straight to Kong 1.0 is **not** supported.
+
+If you still use the deprecated API entity to configure your endpoints and
+upstream services (via `/apis`) instead of using Routes for endpoints (via
+`/routes`) and Services for upstream services (via `/services`), now is the
+time to do so. Kong 1.0 will refuse to run migrations if you have any entity
+configured using `/apis` in your datastore. Create equivalent Routes and
+Services and delete your APIs. (Note that Kong does not do this automatically
+because the naive option of creating a Route and Service pair for each API
+would miss the point of the improvements brought by Routes and Services;
+the ideal mapping of Routes and Services depends on your microservice
+architecture.)
+
+If you use additional plugins other than the ones bundled with Kong,
+make sure they are compatible with Kong 1.0 prior to upgrading.
+See the section above on Plugins for information on plugin compatibility.
+
+### Migration Steps from 0.14
+
+Kong 1.0 introduces a new, improved migrations framework.
+It supports a no-downtime, Blue/Green migration model for upgrading
+from 0.14.x. The full migration is now split into two steps,
+which are performed via commands `kong migrations up` and
+`kong migrations finish`.
+
+For a no-downtime migration from a 0.14 cluster to a 1.0 cluster,
+we recommend the following sequence of steps:
+
+1. Download 1.0, and configure it to point to the same datastore
+ as your 0.14 cluster. Run `kong migrations up`.
+2. Both 0.14 and 1.0 nodes can now run simultaneously on the same
+ datastore. Start provisioning 1.0 nodes, but do not use their
+ Admin API yet. Prefer making Admin API requests to your 0.14 nodes
+ instead.
+3. Gradually divert traffic away from your 0.14 nodes, and into
+ your 1.0 cluster. Monitor your traffic to make sure everything
+ is going smoothly.
+4. When your traffic is fully migrated to the 1.0 cluster,
+ decommission your 0.14 nodes.
+5. From your 1.0 cluster, run: `kong migrations finish`.
+ From this point on, it will not be possible to start 0.14
+ nodes pointing to the same datastore anymore. Only run
+ this command when you are confident that your migration
+ was successful. From now on, you can safely make Admin API
+ requests to your 1.0 nodes.
+
+At any step of the way, you may run `kong migrations list` to get
+a report of the state of migrations. It will list whether there
+are missing migrations, if there are pending migrations (which have
+already started in the `kong migrations up` step and later need to
+finish in the `kong migrations finish` step) or if there
+are new migrations available. The status code of the process will
+also change accordingly:
+
+* `0` - migrations are up-to-date
+* `1` - failed inspecting the state of migrations (e.g. database is down)
+* `3` - database needs bootstrapping:
+ you should run `kong migrations bootstrap` to install on
+ a fresh datastore.
+* `4` - there are pending migrations: once your old cluster is
+ decomissioned you should run `kong migrations finish` (step 5 above).
+* `5` - there are new migrations: you should start a migration
+ sequence (beginning from step 1 above).
+
+### Migration Steps from 1.0 Release Candidates
+
+The process is the same as for upgrading for 0.14 listed above, but on step 1
+you should run `kong migrations up --force` instead.
+
+## Upgrade Path for Patch Releases
+
+There are no migrations in upgrades between current or
+future patch releases of the same minor release of Kong
+(e.g. 1.0.0 to 1.0.1, 1.0.1 to 1.0.4, etc.). Therefore, the
+upgrade process is simpler.
+
+Assuming that Kong is already running on your system, acquire the latest
+version from any of the available [installation
+methods](https://getkong.org/install/) and proceed to install it, overriding
+your previous installation.
+
+If you are planning to make modifications to your configuration, this is a
+good time to do so.
+
+Then, run migration to upgrade your database schema:
+
+```shell
+$ kong migrations up [-c configuration_file]
+```
+
+If the command is successful, and no migration ran
+(no output), then you only have to
+[reload](https://getkong.org/docs/latest/cli/#reload) Kong:
+
+```shell
+$ kong reload [-c configuration_file]
+```
+
+**Reminder**: `kong reload` leverages the Nginx `reload` signal that seamlessly
+starts new workers, which take over from old workers before those old workers
+are terminated. In this way, Kong will serve new requests via the new
+configuration, without dropping existing in-flight connections.
+
+## Installing 1.0 on a Fresh Datastore
+
+For installing on a fresh datastore, Kong 1.0 introduces the `kong migrations
+bootstrap` command. The following commands can be run to prepare a new 1.0
+cluster from a fresh datastore:
+
+```
+$ kong migrations bootstrap [-c config]
+$ kong start [-c config]
+```
+
+