PermalinkAdmin API
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 for a discussion of methods to secure the Admin API.
PermalinkDB-less mode
In DB-less mode, the 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 Kong 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.
In DB-less mode, you configure Kong Gateway declaratively. Therefore, the Admin API is mostly read-only. The only tasks it can perform are all related to handling the declarative config, including:
- Validating configurations against schemas
- Validating plugin configurations against schemas
- Reloading the declarative configuration
- Setting a target’s health status in the load balancer
PermalinkDeclarative 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.
PermalinkReload 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, see the declarative configuration documentation.
Attributes | Description |
---|---|
config required |
The config data (in YAML or JSON format) to be loaded. |
PermalinkRequest Querystring Parameters
Attributes | Description |
---|---|
check_hash optional |
If set to 1, Kong will compare the hash of the input config data against that of the previous one. If the configuration is identical, it will not reload it and will return HTTP 304. |
PermalinkResponse
HTTP 200 OK
{
{
"services": [],
"routes": []
}
}
The response contains a list of all the entities that were parsed from the input file.
PermalinkSupported 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
- 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:
{
"config": {
"limit": 10,
"period": "seconds"
}
}
PermalinkInformation Routes
PermalinkRetrieve Node Information
Retrieve generic details about a node.
Response
HTTP 200 OK
{
"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 differentnode_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.
PermalinkList Available Endpoints
List all available endpoints provided by the Admin API.
PermalinkResponse
HTTP 200 OK
{
"data": [
"/",
"/acls",
"/acls/{acls}",
"/acls/{acls}/consumer",
"/basic-auths",
"/basic-auths/{basicauth_credentials}",
"/basic-auths/{basicauth_credentials}/consumer",
"/ca_certificates",
"/ca_certificates/{ca_certificates}",
"/cache",
"/cache/{key}",
"..."
]
}
PermalinkValidate A Configuration against A Schema
Check validity of a configuration against its entity schema. This allows you to test your input before submitting a request to the entity endpoints of the Admin API.
Note that this only performs the schema validation checks, checking that the input configuration is well-formed. A requests to the entity endpoint using the given configuration may still fail due to other reasons, such as invalid foreign key relationships or uniqueness check failures against the contents of the data store.
PermalinkResponse
HTTP 200 OK
{
"message": "schema validation successful"
}
PermalinkRetrieve Entity Schema
Retrieve the schema of an entity. This is useful to understand what fields an entity accepts, and can be used for building third-party integrations to the Kong.
PermalinkResponse
HTTP 200 OK
{
"fields": [
{
"id": {
"auto": true,
"type": "string",
"uuid": true
}
},
{
"created_at": {
"auto": true,
"timestamp": true,
"type": "integer"
}
},
...
]
}
PermalinkRetrieve 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.
PermalinkResponse
HTTP 200 OK
{
"fields": {
"hide_credentials": {
"default": false,
"type": "boolean"
},
"key_names": {
"default": "function",
"required": true,
"type": "array"
}
}
}
PermalinkValidate A Plugin Configuration against The Schema
Check validity of a plugin configuration against the plugins entity schema. This allows you to test your input before submitting a request to the entity endpoints of the Admin API.
Note that this only performs the schema validation checks, checking that the input configuration is well-formed. A requests to the entity endpoint using the given configuration may still fail due to other reasons, such as invalid foreign key relationships or uniqueness check failures against the contents of the data store.
PermalinkResponse
HTTP 200 OK
{
"message": "schema validation successful"
}
PermalinkHealth Routes
PermalinkRetrieve Node Status
Retrieve usage information about a node, with some basic information about the connections being processed by the underlying nginx process, the status of the database connection, and node’s memory usage.
If you want to monitor the Kong process, since Kong is built on top of nginx, every existing nginx monitoring tool or agent can be used.
Response
HTTP 200 OK
{
"database": {
"reachable": true
},
"memory": {
"workers_lua_vms": [{
"http_allocated_gc": "0.02 MiB",
"pid": 18477
}, {
"http_allocated_gc": "0.02 MiB",
"pid": 18478
}],
"lua_shared_dicts": {
"kong": {
"allocated_slabs": "0.04 MiB",
"capacity": "5.00 MiB"
},
"kong_db_cache": {
"allocated_slabs": "0.80 MiB",
"capacity": "128.00 MiB"
},
}
},
"server": {
"total_requests": 3,
"connections_active": 1,
"connections_accepted": 1,
"connections_handled": 1,
"connections_reading": 0,
"connections_writing": 1,
"connections_waiting": 0
}
}
memory
: Metrics about the memory usage.workers_lua_vms
: An array with all workers of the Kong node, where each entry contains:http_allocated_gc
: HTTP submodule’s Lua virtual machine’s memory usage information, as reported bycollectgarbage("count")
, for every active worker, i.e. a worker that received a proxy call in the last 10 seconds.pid
: worker’s process identification number.lua_shared_dicts
: An array of information about dictionaries that are shared with all workers in a Kong node, where each array node contains how much memory is dedicated for the specific shared dictionary (capacity
) and how much of said memory is in use (allocated_slabs
). These shared dictionaries have least recent used (LRU) eviction capabilities, so a full dictionary, whereallocated_slabs == capacity
, will work properly. However for some dictionaries, e.g. cache HIT/MISS shared dictionaries, increasing their size can be beneficial for the overall performance of a Kong node.- The memory usage unit and precision can be changed using the querystring
arguments
unit
andscale
:unit
: one ofb/B
,k/K
,m/M
,g/G
, which will return results in bytes, kibibytes, mebibytes, or gibibytes, respectively. When “bytes” are requested, the memory values in the response will have a number type instead of string. Defaults tom
.scale
: the number of digits to the right of the decimal points when values are given in human-readable memory strings (unit other than “bytes”). Defaults to2
. You can get the shared dictionaries memory usage in kibibytes with 4 digits of precision by doing:GET /status?unit=k&scale=4
server
: Metrics about the nginx HTTP/S server.total_requests
: The total number of client requests.connections_active
: The current number of active client connections including Waiting connections.connections_accepted
: The total number of accepted client connections.connections_handled
: The total number of handled connections. Generally, the parameter value is the same as accepts unless some resource limits have been reached.connections_reading
: The current number of connections where Kong is reading the request header.connections_writing
: The current number of connections where nginx is writing the response back to the client.connections_waiting
: The current number of idle client connections waiting for a request.
database
: Metrics about the database.reachable
: A boolean value reflecting the state of the database connection. Please note that this flag does not reflect the health of the database itself.
PermalinkTags
Tags are strings associated to entities in Kong.
Tags can contain almost all UTF-8 characters, with the following exceptions:
,
and/
are reserved for filtering tags with “and” and “or”, so they are not allowed in tags.- Non-printable ASCII (for example, the space character) is not allowed.
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, thetags
parameter will be ignored in a request such asGET /services/foo/routes?tags=a,b
offset
parameters are not guaranteed to work if thetags
parameter is altered or removed
PermalinkList 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.
Response
HTTP 200 OK
{
{
"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",
}
}
PermalinkList 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.
Response
HTTP 200 OK
{
{
"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",
}
}
PermalinkService Object
Service objects, 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 for a detailed explanation of how Kong proxies traffic.
Services can be both tagged and filtered by tags.
{
"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"],
"client_certificate": {"id":"4e3ad2e4-0bc4-4638-8e34-c84a417ba39b"},
"tls_verify": true,
"tls_verify_depth": null,
"ca_certificates": ["4e3ad2e4-0bc4-4638-8e34-c84a417ba39b", "51e77dc2-8f3e-4afa-9d0e-0e3bbbcfd515"]
}
PermalinkAdd Service
PermalinkCreate Service
PermalinkCreate Service Associated to a Specific Certificate
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 Service. |
Request Body
Attributes | Description |
---|---|
name optional |
The Service name. |
retries optional |
The number of retries to execute upon failure to proxy. Defaults to 5 . |
protocol |
The protocol used to communicate with the upstream. Accepted values are: "grpc" , "grpcs" , "http" , "https" , "tcp" , "tls" , "udp" . Default: "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. |
client_certificate optional |
Certificate to be used as client certificate while TLS handshaking to the upstream server. With form-encoded, the notation is client_certificate.id=<client_certificate_id> . With JSON, use "client_certificate":{"id":"<client_certificate_id>"} . |
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). |
tls_verify optional |
Whether to enable verification of upstream server TLS certificate. If set to null , then the Nginx default is respected. |
tls_verify_depth optional |
Maximum depth of chain while verifying Upstream server’s TLS certificate. If set to null , then the Nginx default is respected. Default: null . |
ca_certificates optional |
Array of CA Certificate object UUIDs that are used to build the trust store while verifying upstream server’s TLS certificate. If set to null when Nginx default is respected. If default CA list in Nginx are not specified and TLS verification is enabled, then handshake with upstream server will always fail (because no CA are trusted). With form-encoded, the notation is ca_certificates[]=4e3ad2e4-0bc4-4638-8e34-c84a417ba39b&ca_certificates[]=51e77dc2-8f3e-4afa-9d0e-0e3bbbcfd515 . With JSON, use an Array. |
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). |
Response
HTTP 201 Created
{
"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"],
"client_certificate": {"id":"4e3ad2e4-0bc4-4638-8e34-c84a417ba39b"},
"tls_verify": true,
"tls_verify_depth": null,
"ca_certificates": ["4e3ad2e4-0bc4-4638-8e34-c84a417ba39b", "51e77dc2-8f3e-4afa-9d0e-0e3bbbcfd515"]
}
PermalinkList Services
PermalinkList All Services
PermalinkList Services Associated to a Specific Certificate
Attributes | Description |
---|---|
certificate name or id required |
The unique identifier or the name attribute of the Certificate whose Services are to be retrieved. When using this endpoint, only Services associated to the specified Certificate will be listed. |
Response
HTTP 200 OK
{
"data": [{
"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": "/some_api",
"connect_timeout": 60000,
"write_timeout": 60000,
"read_timeout": 60000,
"tags": ["user-level", "low-priority"],
"client_certificate": {"id":"51e77dc2-8f3e-4afa-9d0e-0e3bbbcfd515"},
"tls_verify": true,
"tls_verify_depth": null,
"ca_certificates": ["4e3ad2e4-0bc4-4638-8e34-c84a417ba39b", "51e77dc2-8f3e-4afa-9d0e-0e3bbbcfd515"]
}, {
"id": "fc73f2af-890d-4f9b-8363-af8945001f7f",
"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"],
"client_certificate": {"id":"4506673d-c825-444c-a25b-602e3c2ec16e"},
"tls_verify": true,
"tls_verify_depth": null,
"ca_certificates": ["4e3ad2e4-0bc4-4638-8e34-c84a417ba39b", "51e77dc2-8f3e-4afa-9d0e-0e3bbbcfd515"]
}],
"next": "http://localhost:8001/services?offset=6378122c-a0a1-438d-a5c6-efabae9fb969"
}
PermalinkRetrieve Service
PermalinkRetrieve Service
Attributes | Description |
---|---|
name or id required |
The unique identifier or the name of the Service to retrieve. |
PermalinkRetrieve Service Associated to a Specific Route
Attributes | Description |
---|---|
route name or id required |
The unique identifier or the name of the Route associated to the Service to be retrieved. |
PermalinkRetrieve Service Associated to a Specific Plugin
Attributes | Description |
---|---|
plugin id required |
The unique identifier of the Plugin associated to the Service to be retrieved. |
Response
HTTP 200 OK
{
"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"],
"client_certificate": {"id":"4e3ad2e4-0bc4-4638-8e34-c84a417ba39b"},
"tls_verify": true,
"tls_verify_depth": null,
"ca_certificates": ["4e3ad2e4-0bc4-4638-8e34-c84a417ba39b", "51e77dc2-8f3e-4afa-9d0e-0e3bbbcfd515"]
}
PermalinkUpdate Service
PermalinkUpdate Service
Attributes | Description |
---|---|
name or id required |
The unique identifier or the name of the Service to update. |
PermalinkUpdate Service Associated to a Specific Route
Attributes | Description |
---|---|
route name or id required |
The unique identifier or the name of the Route associated to the Service to be updated. |
PermalinkUpdate Service Associated to a Specific Plugin
Attributes | Description |
---|---|
plugin id required |
The unique identifier of the Plugin associated to the Service to be updated. |
Request Body
Attributes | Description |
---|---|
name optional |
The Service name. |
retries optional |
The number of retries to execute upon failure to proxy. Defaults to 5 . |
protocol |
The protocol used to communicate with the upstream. Accepted values are: "grpc" , "grpcs" , "http" , "https" , "tcp" , "tls" , "udp" . Default: "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. |
client_certificate optional |
Certificate to be used as client certificate while TLS handshaking to the upstream server. With form-encoded, the notation is client_certificate.id=<client_certificate_id> . With JSON, use "client_certificate":{"id":"<client_certificate_id>"} . |
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). |
tls_verify optional |
Whether to enable verification of upstream server TLS certificate. If set to null , then the Nginx default is respected. |
tls_verify_depth optional |
Maximum depth of chain while verifying Upstream server’s TLS certificate. If set to null , then the Nginx default is respected. Default: null . |
ca_certificates optional |
Array of CA Certificate object UUIDs that are used to build the trust store while verifying upstream server’s TLS certificate. If set to null when Nginx default is respected. If default CA list in Nginx are not specified and TLS verification is enabled, then handshake with upstream server will always fail (because no CA are trusted). With form-encoded, the notation is ca_certificates[]=4e3ad2e4-0bc4-4638-8e34-c84a417ba39b&ca_certificates[]=51e77dc2-8f3e-4afa-9d0e-0e3bbbcfd515 . With JSON, use an Array. |
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). |
Response
HTTP 200 OK
{
"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"],
"client_certificate": {"id":"4e3ad2e4-0bc4-4638-8e34-c84a417ba39b"},
"tls_verify": true,
"tls_verify_depth": null,
"ca_certificates": ["4e3ad2e4-0bc4-4638-8e34-c84a417ba39b", "51e77dc2-8f3e-4afa-9d0e-0e3bbbcfd515"]
}
PermalinkUpdate or Create Service
PermalinkCreate or Update Service
Attributes | Description |
---|---|
name or id required |
The unique identifier or the name of the Service to create or update. |
PermalinkCreate or Update Service Associated to a Specific Route
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. |
PermalinkCreate or Update Service Associated to a Specific Plugin
Attributes | Description |
---|---|
plugin id required |
The unique identifier of the Plugin associated to the Service to be created or updated. |
Request Body
Attributes | Description |
---|---|
name optional |
The Service name. |
retries optional |
The number of retries to execute upon failure to proxy. Defaults to 5 . |
protocol |
The protocol used to communicate with the upstream. Accepted values are: "grpc" , "grpcs" , "http" , "https" , "tcp" , "tls" , "udp" . Default: "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. |
client_certificate optional |
Certificate to be used as client certificate while TLS handshaking to the upstream server. With form-encoded, the notation is client_certificate.id=<client_certificate_id> . With JSON, use "client_certificate":{"id":"<client_certificate_id>"} . |
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). |
tls_verify optional |
Whether to enable verification of upstream server TLS certificate. If set to null , then the Nginx default is respected. |
tls_verify_depth optional |
Maximum depth of chain while verifying Upstream server’s TLS certificate. If set to null , then the Nginx default is respected. Default: null . |
ca_certificates optional |
Array of CA Certificate object UUIDs that are used to build the trust store while verifying upstream server’s TLS certificate. If set to null when Nginx default is respected. If default CA list in Nginx are not specified and TLS verification is enabled, then handshake with upstream server will always fail (because no CA are trusted). With form-encoded, the notation is ca_certificates[]=4e3ad2e4-0bc4-4638-8e34-c84a417ba39b&ca_certificates[]=51e77dc2-8f3e-4afa-9d0e-0e3bbbcfd515 . With JSON, use an Array. |
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). |
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.
PermalinkDelete Service
PermalinkDelete Service
Attributes | Description |
---|---|
name or id required |
The unique identifier or the name of the Service to delete. |
Response
HTTP 204 No Content
PermalinkRoute Object
Route objects 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.
You need at least one matching rule that applies to the protocol being matched
by the Route. Depending on the protocols configured to be matched by the Route
(as defined with the protocols
field), this means that at least one of the
following attributes must be set:
- For
http
, at least one ofmethods
,hosts
,headers
orpaths
; - For
https
, at least one ofmethods
,hosts
,headers
,paths
orsnis
; - For
tcp
, at least one ofsources
ordestinations
; - For
tls
, at least one ofsources
,destinations
orsnis
; - For
grpc
, at least one ofhosts
,headers
orpaths
; - For
grpcs
, at least one ofhosts
,headers
,paths
orsnis
.
Routes can be both tagged and filtered by tags.
PermalinkPath handling algorithms
"v0"
is the behavior used in Kong 0.x and 2.x. It treats service.path
, route.path
and request path as
segments of a url. It will always join them via slashes. Given a service path /s
, route path /r
and request path /re
, the concatenated path will be /s/re
. If the resulting path is a single slash,
no further transformation is done to it. If it’s longer, then the trailing slash is removed.
"v1"
is the behavior used in Kong 1.x. It treats service.path
as a prefix, and ignores the initial
slashes of the request and route paths. Given service path /s
, route path /r
and request path /re
,
the concatenated path will be /sre
.
Both versions of the algorithm detect “double slashes” when combining paths, replacing them by single slashes.
service.path |
route.path |
route.strip_path |
route.path_handling |
request path | proxied path |
---|---|---|---|---|---|
/s |
/fv0 |
false |
v0 |
/fv0req |
/s/fv0req |
/s |
/fv1 |
false |
v1 |
/fv1req |
/sfv1req |
/s |
/tv0 |
true |
v0 |
/tv0req |
/s/req |
/s |
/tv1 |
true |
v1 |
/tv1req |
/sreq |
/s |
/fv0/ |
false |
v0 |
/fv0/req |
/s/fv0/req |
/s |
/fv1/ |
false |
v1 |
/fv1/req |
/sfv1/req |
/s |
/tv0/ |
true |
v0 |
/tv0/req |
/s/req |
/s |
/tv1/ |
true |
v1 |
/tv1/req | /sreq` |
Routes can be both tagged and filtered by tags.
{
"id": "d35165e2-d03e-461a-bdeb-dad0a112abfe",
"created_at": 1422386534,
"updated_at": 1422386534,
"name": "my-route",
"protocols": ["http", "https"],
"methods": ["GET", "POST"],
"hosts": ["example.com", "foo.test"],
"paths": ["/foo", "/bar"],
"headers": {"x-another-header":["bla"], "x-my-header":["foo", "bar"]},
"https_redirect_status_code": 426,
"regex_priority": 0,
"strip_path": true,
"path_handling": "v0",
"preserve_host": false,
"request_buffering": true,
"response_buffering": true,
"tags": ["user-level", "low-priority"],
"service": {"id":"af8330d3-dbdc-48bd-b1be-55b98608834b"}
}
PermalinkAdd Route
PermalinkCreate Route
PermalinkCreate Route Associated to a Specific Service
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
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. |
hosts semi-optional |
A list of domain names that match this Route. 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. With form-encoded, the notation is paths[]=/foo&paths[]=/bar . With JSON, use an Array. |
headers semi-optional |
One or more lists of values indexed by header name that will cause this Route to match if present in the request. The Host header cannot be used with this attribute: hosts should be specified using the hosts attribute. |
https_redirect_status_code |
The status code Kong responds with when all properties of a Route match except the protocol i.e. if the protocol of the request is HTTP instead of HTTPS . Location header is injected by Kong if the field is set to 301, 302, 307 or 308. Defaults to 426 . |
regex_priority optional |
A number used to choose which route resolves a given request when several routes match it using regexes simultaneously. When two routes match the path and have the same regex_priority , the older one (lowest created_at ) is used. Note that the priority for non-regex routes is different (longer non-regex routes are matched before shorter ones). Defaults to 0 . |
strip_path optional |
When matching a Route via one of the paths , strip the matching prefix from the upstream request URL. Defaults to true . |
path_handling optional |
Controls how the Service path, Route path and requested path are combined when sending a request to the upstream. See above for a detailed description of each behavior. Accepted values are: "v0" , "v1" . Defaults to "v0" . |
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 . |
request_buffering |
Whether to enable request body buffering or not. With HTTP 1.1, it may make sense to turn this off on services that receive data with chunked transfer encoding. Default: true . |
response_buffering |
Whether to enable response body buffering or not. With HTTP 1.1, it may make sense to turn this off on services that send data with chunked transfer encoding. Default: true . |
snis semi-optional |
A list of SNIs that match this Route when using stream routing. |
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”. |
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”. |
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=<service id> or service.name=<service name> . With JSON, use “"service":{"id":"<service id>"} or "service":{"name":"<service name>"} . |
Response
HTTP 201 Created
{
"id": "d35165e2-d03e-461a-bdeb-dad0a112abfe",
"created_at": 1422386534,
"updated_at": 1422386534,
"name": "my-route",
"protocols": ["http", "https"],
"methods": ["GET", "POST"],
"hosts": ["example.com", "foo.test"],
"paths": ["/foo", "/bar"],
"headers": {"x-another-header":["bla"], "x-my-header":["foo", "bar"]},
"https_redirect_status_code": 426,
"regex_priority": 0,
"strip_path": true,
"path_handling": "v0",
"preserve_host": false,
"request_buffering": true,
"response_buffering": true,
"tags": ["user-level", "low-priority"],
"service": {"id":"af8330d3-dbdc-48bd-b1be-55b98608834b"}
}
PermalinkList Routes
PermalinkList All Routes
PermalinkList Routes Associated to a Specific Service
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
{
"data": [{
"id": "a9daa3ba-8186-4a0d-96e8-00d80ce7240b",
"created_at": 1422386534,
"updated_at": 1422386534,
"name": "my-route",
"protocols": ["http", "https"],
"methods": ["GET", "POST"],
"hosts": ["example.com", "foo.test"],
"paths": ["/foo", "/bar"],
"headers": {"x-another-header":["bla"], "x-my-header":["foo", "bar"]},
"https_redirect_status_code": 426,
"regex_priority": 0,
"strip_path": true,
"path_handling": "v0",
"preserve_host": false,
"request_buffering": true,
"response_buffering": true,
"tags": ["user-level", "low-priority"],
"service": {"id":"127dfc88-ed57-45bf-b77a-a9d3a152ad31"}
}, {
"id": "9aa116fd-ef4a-4efa-89bf-a0b17c4be982",
"created_at": 1422386534,
"updated_at": 1422386534,
"name": "my-route",
"protocols": ["tcp", "tls"],
"https_redirect_status_code": 426,
"regex_priority": 0,
"strip_path": true,
"path_handling": "v0",
"preserve_host": false,
"request_buffering": true,
"response_buffering": true,
"snis": ["foo.test", "example.com"],
"sources": [{"ip":"10.1.0.0/16", "port":1234}, {"ip":"10.2.2.2"}, {"port":9123}],
"destinations": [{"ip":"10.1.0.0/16", "port":1234}, {"ip":"10.2.2.2"}, {"port":9123}],
"tags": ["admin", "high-priority", "critical"],
"service": {"id":"ba641b07-e74a-430a-ab46-94b61e5ea66b"}
}],
"next": "http://localhost:8001/routes?offset=6378122c-a0a1-438d-a5c6-efabae9fb969"
}
PermalinkRetrieve Route
PermalinkRetrieve Route
Attributes | Description |
---|---|
name or id required |
The unique identifier or the name of the Route to retrieve. |
PermalinkRetrieve Route Associated to a Specific Plugin
Attributes | Description |
---|---|
plugin id required |
The unique identifier of the Plugin associated to the Route to be retrieved. |
Response
HTTP 200 OK
{
"id": "d35165e2-d03e-461a-bdeb-dad0a112abfe",
"created_at": 1422386534,
"updated_at": 1422386534,
"name": "my-route",
"protocols": ["http", "https"],
"methods": ["GET", "POST"],
"hosts": ["example.com", "foo.test"],
"paths": ["/foo", "/bar"],
"headers": {"x-another-header":["bla"], "x-my-header":["foo", "bar"]},
"https_redirect_status_code": 426,
"regex_priority": 0,
"strip_path": true,
"path_handling": "v0",
"preserve_host": false,
"request_buffering": true,
"response_buffering": true,
"tags": ["user-level", "low-priority"],
"service": {"id":"af8330d3-dbdc-48bd-b1be-55b98608834b"}
}
PermalinkUpdate Route
PermalinkUpdate Route
Attributes | Description |
---|---|
name or id required |
The unique identifier or the name of the Route to update. |
PermalinkUpdate Route Associated to a Specific Plugin
Attributes | Description |
---|---|
plugin id required |
The unique identifier of the Plugin associated to the Route to be updated. |
Request 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. |
hosts semi-optional |
A list of domain names that match this Route. 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. With form-encoded, the notation is paths[]=/foo&paths[]=/bar . With JSON, use an Array. |
headers semi-optional |
One or more lists of values indexed by header name that will cause this Route to match if present in the request. The Host header cannot be used with this attribute: hosts should be specified using the hosts attribute. |
https_redirect_status_code |
The status code Kong responds with when all properties of a Route match except the protocol i.e. if the protocol of the request is HTTP instead of HTTPS . Location header is injected by Kong if the field is set to 301, 302, 307 or 308. Defaults to 426 . |
regex_priority optional |
A number used to choose which route resolves a given request when several routes match it using regexes simultaneously. When two routes match the path and have the same regex_priority , the older one (lowest created_at ) is used. Note that the priority for non-regex routes is different (longer non-regex routes are matched before shorter ones). Defaults to 0 . |
strip_path optional |
When matching a Route via one of the paths , strip the matching prefix from the upstream request URL. Defaults to true . |
path_handling optional |
Controls how the Service path, Route path and requested path are combined when sending a request to the upstream. See above for a detailed description of each behavior. Accepted values are: "v0" , "v1" . Defaults to "v0" . |
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 . |
request_buffering |
Whether to enable request body buffering or not. With HTTP 1.1, it may make sense to turn this off on services that receive data with chunked transfer encoding. Default: true . |
response_buffering |
Whether to enable response body buffering or not. With HTTP 1.1, it may make sense to turn this off on services that send data with chunked transfer encoding. Default: true . |
snis semi-optional |
A list of SNIs that match this Route when using stream routing. |
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”. |
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”. |
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=<service id> or service.name=<service name> . With JSON, use “"service":{"id":"<service id>"} or "service":{"name":"<service name>"} . |
Response
HTTP 200 OK
{
"id": "d35165e2-d03e-461a-bdeb-dad0a112abfe",
"created_at": 1422386534,
"updated_at": 1422386534,
"name": "my-route",
"protocols": ["http", "https"],
"methods": ["GET", "POST"],
"hosts": ["example.com", "foo.test"],
"paths": ["/foo", "/bar"],
"headers": {"x-another-header":["bla"], "x-my-header":["foo", "bar"]},
"https_redirect_status_code": 426,
"regex_priority": 0,
"strip_path": true,
"path_handling": "v0",
"preserve_host": false,
"request_buffering": true,
"response_buffering": true,
"tags": ["user-level", "low-priority"],
"service": {"id":"af8330d3-dbdc-48bd-b1be-55b98608834b"}
}
PermalinkUpdate or Create Route
PermalinkCreate or Update Route
Attributes | Description |
---|---|
name or id required |
The unique identifier or the name of the Route to create or update. |
PermalinkCreate or Update Route Associated to a Specific Plugin
Attributes | Description |
---|---|
plugin id required |
The unique identifier of the Plugin associated to the Route to be created or updated. |
Request 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. |
hosts semi-optional |
A list of domain names that match this Route. 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. With form-encoded, the notation is paths[]=/foo&paths[]=/bar . With JSON, use an Array. |
headers semi-optional |
One or more lists of values indexed by header name that will cause this Route to match if present in the request. The Host header cannot be used with this attribute: hosts should be specified using the hosts attribute. |
https_redirect_status_code |
The status code Kong responds with when all properties of a Route match except the protocol i.e. if the protocol of the request is HTTP instead of HTTPS . Location header is injected by Kong if the field is set to 301, 302, 307 or 308. Defaults to 426 . |
regex_priority optional |
A number used to choose which route resolves a given request when several routes match it using regexes simultaneously. When two routes match the path and have the same regex_priority , the older one (lowest created_at ) is used. Note that the priority for non-regex routes is different (longer non-regex routes are matched before shorter ones). Defaults to 0 . |
strip_path optional |
When matching a Route via one of the paths , strip the matching prefix from the upstream request URL. Defaults to true . |
path_handling optional |
Controls how the Service path, Route path and requested path are combined when sending a request to the upstream. See above for a detailed description of each behavior. Accepted values are: "v0" , "v1" . Defaults to "v0" . |
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 . |
request_buffering |
Whether to enable request body buffering or not. With HTTP 1.1, it may make sense to turn this off on services that receive data with chunked transfer encoding. Default: true . |
response_buffering |
Whether to enable response body buffering or not. With HTTP 1.1, it may make sense to turn this off on services that send data with chunked transfer encoding. Default: true . |
snis semi-optional |
A list of SNIs that match this Route when using stream routing. |
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”. |
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”. |
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=<service id> or service.name=<service name> . With JSON, use “"service":{"id":"<service id>"} or "service":{"name":"<service name>"} . |
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.
PermalinkDelete Route
PermalinkDelete Route
Attributes | Description |
---|---|
name or id required |
The unique identifier or the name of the Route to delete. |
Response
HTTP 204 No Content
PermalinkConsumer 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.
{
"id": "ec1a1f6f-2aa4-4e58-93ff-b56368f19b27",
"created_at": 1422386534,
"username": "my-username",
"custom_id": "my-custom-id",
"tags": ["user-level", "low-priority"]
}
PermalinkAdd Consumer
PermalinkCreate Consumer
Request Body
Attributes | Description |
---|---|
username 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. |
Response
HTTP 201 Created
{
"id": "ec1a1f6f-2aa4-4e58-93ff-b56368f19b27",
"created_at": 1422386534,
"username": "my-username",
"custom_id": "my-custom-id",
"tags": ["user-level", "low-priority"]
}
PermalinkList Consumers
PermalinkList All Consumers
Response
HTTP 200 OK
{
"data": [{
"id": "a4407883-c166-43fd-80ca-3ca035b0cdb7",
"created_at": 1422386534,
"username": "my-username",
"custom_id": "my-custom-id",
"tags": ["user-level", "low-priority"]
}, {
"id": "01c23299-839c-49a5-a6d5-8864c09184af",
"created_at": 1422386534,
"username": "my-username",
"custom_id": "my-custom-id",
"tags": ["admin", "high-priority", "critical"]
}],
"next": "http://localhost:8001/consumers?offset=6378122c-a0a1-438d-a5c6-efabae9fb969"
}
PermalinkRetrieve Consumer
PermalinkRetrieve Consumer
Attributes | Description |
---|---|
username or id required |
The unique identifier or the username of the Consumer to retrieve. |
PermalinkRetrieve Consumer Associated to a Specific Plugin
Attributes | Description |
---|---|
plugin id required |
The unique identifier of the Plugin associated to the Consumer to be retrieved. |
Response
HTTP 200 OK
{
"id": "ec1a1f6f-2aa4-4e58-93ff-b56368f19b27",
"created_at": 1422386534,
"username": "my-username",
"custom_id": "my-custom-id",
"tags": ["user-level", "low-priority"]
}
PermalinkUpdate Consumer
PermalinkUpdate Consumer
Attributes | Description |
---|---|
username or id required |
The unique identifier or the username of the Consumer to update. |
PermalinkUpdate Consumer Associated to a Specific Plugin
Attributes | Description |
---|---|
plugin id required |
The unique identifier of the Plugin associated to the Consumer to be updated. |
Request Body
Attributes | Description |
---|---|
username 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. |
Response
HTTP 200 OK
{
"id": "ec1a1f6f-2aa4-4e58-93ff-b56368f19b27",
"created_at": 1422386534,
"username": "my-username",
"custom_id": "my-custom-id",
"tags": ["user-level", "low-priority"]
}
PermalinkUpdate Or Create Consumer
PermalinkCreate Or Update Consumer
Attributes | Description |
---|---|
username or id required |
The unique identifier or the username of the Consumer to create or update. |
PermalinkCreate Or Update Consumer Associated to a Specific Plugin
Attributes | Description |
---|---|
plugin id required |
The unique identifier of the Plugin associated to the Consumer to be created or updated. |
Request Body
Attributes | Description |
---|---|
username 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. |
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.
PermalinkDelete Consumer
PermalinkDelete Consumer
Attributes | Description |
---|---|
username or id required |
The unique identifier or the username of the Consumer to delete. |
Response
HTTP 204 No Content
PermalinkPlugin Object
A Plugin object 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.
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.
{
"id": "ce44eef5-41ed-47f6-baab-f725cecf98c7",
"name": "rate-limiting",
"created_at": 1422386534,
"route": null,
"service": null,
"consumer": null,
"config": {"hour":500, "minute":20},
"protocols": ["http", "https"],
"enabled": true,
"tags": ["user-level", "low-priority"]
}
See the Precedence section below for more details.
PermalinkPrecedence
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:
- Plugins configured on a combination of: a Route, a Service, and a Consumer. (Consumer means the request must be authenticated).
- Plugins configured on a combination of a Route and a Consumer. (Consumer means the request must be authenticated).
- Plugins configured on a combination of a Service and a Consumer. (Consumer means the request must be authenticated).
- Plugins configured on a combination of a Route and a Service.
- Plugins configured on a Consumer. (Consumer means the request must be authenticated).
- Plugins configured on a Route.
- Plugins configured on a Service.
- 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.
PermalinkAdd Plugin
PermalinkCreate Plugin
PermalinkCreate Plugin Associated to a Specific Route
Attributes | Description |
---|---|
route id required |
The unique identifier of the Route that should be associated to the newly-created Plugin. |
PermalinkCreate Plugin Associated to a Specific Service
Attributes | Description |
---|---|
service id required |
The unique identifier of the Service that should be associated to the newly-created Plugin. |
PermalinkCreate Plugin Associated to a Specific Consumer
Attributes | Description |
---|---|
consumer id required |
The unique identifier of the Consumer that should be associated to the newly-created Plugin. |
Request 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=<route_id> . With JSON, use "route":{"id":"<route_id>"} . |
service 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=<service_id> . With JSON, use "service":{"id":"<service_id>"} . |
consumer 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=<consumer_id> . With JSON, use "consumer":{"id":"<consumer_id>"} . |
config optional |
The configuration properties for the Plugin which can be found on the plugins documentation page in the Kong Hub. |
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 ["grpc", "grpcs", "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. |
Response
HTTP 201 Created
{
"id": "ce44eef5-41ed-47f6-baab-f725cecf98c7",
"name": "rate-limiting",
"created_at": 1422386534,
"route": null,
"service": null,
"consumer": null,
"config": {"hour":500, "minute":20},
"protocols": ["http", "https"],
"enabled": true,
"tags": ["user-level", "low-priority"]
}
PermalinkList Plugins
PermalinkList All Plugins
PermalinkList Plugins Associated to a Specific Route
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. |
PermalinkList Plugins Associated to a Specific Service
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. |
PermalinkList Plugins Associated to a Specific Consumer
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
{
"data": [{
"id": "02621eee-8309-4bf6-b36b-a82017a5393e",
"name": "rate-limiting",
"created_at": 1422386534,
"route": null,
"service": null,
"consumer": null,
"config": {"hour":500, "minute":20},
"protocols": ["http", "https"],
"enabled": true,
"tags": ["user-level", "low-priority"]
}, {
"id": "66c7b5c4-4aaf-4119-af1e-ee3ad75d0af4",
"name": "rate-limiting",
"created_at": 1422386534,
"route": null,
"service": null,
"consumer": null,
"config": {"hour":500, "minute":20},
"protocols": ["tcp", "tls"],
"enabled": true,
"tags": ["admin", "high-priority", "critical"]
}],
"next": "http://localhost:8001/plugins?offset=6378122c-a0a1-438d-a5c6-efabae9fb969"
}
PermalinkRetrieve Plugin
PermalinkRetrieve Plugin
Attributes | Description |
---|---|
plugin id required |
The unique identifier of the Plugin to retrieve. |
Response
HTTP 200 OK
{
"id": "ce44eef5-41ed-47f6-baab-f725cecf98c7",
"name": "rate-limiting",
"created_at": 1422386534,
"route": null,
"service": null,
"consumer": null,
"config": {"hour":500, "minute":20},
"protocols": ["http", "https"],
"enabled": true,
"tags": ["user-level", "low-priority"]
}
PermalinkUpdate Plugin
PermalinkUpdate Plugin
Attributes | Description |
---|---|
plugin id required |
The unique identifier of the Plugin to update. |
Request 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=<route_id> . With JSON, use "route":{"id":"<route_id>"} . |
service 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=<service_id> . With JSON, use "service":{"id":"<service_id>"} . |
consumer 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=<consumer_id> . With JSON, use "consumer":{"id":"<consumer_id>"} . |
config optional |
The configuration properties for the Plugin which can be found on the plugins documentation page in the Kong Hub. |
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 ["grpc", "grpcs", "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. |
Response
HTTP 200 OK
{
"id": "ce44eef5-41ed-47f6-baab-f725cecf98c7",
"name": "rate-limiting",
"created_at": 1422386534,
"route": null,
"service": null,
"consumer": null,
"config": {"hour":500, "minute":20},
"protocols": ["http", "https"],
"enabled": true,
"tags": ["user-level", "low-priority"]
}
PermalinkUpdate or Create Plugin
PermalinkCreate or Update Plugin
Attributes | Description |
---|---|
plugin id required |
The unique identifier of the Plugin to create or update. |
Request 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=<route_id> . With JSON, use "route":{"id":"<route_id>"} . |
service 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=<service_id> . With JSON, use "service":{"id":"<service_id>"} . |
consumer 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=<consumer_id> . With JSON, use "consumer":{"id":"<consumer_id>"} . |
config optional |
The configuration properties for the Plugin which can be found on the plugins documentation page in the Kong Hub. |
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 ["grpc", "grpcs", "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. |
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.
PermalinkDelete Plugin
PermalinkDelete Plugin
Attributes | Description |
---|---|
plugin id required |
The unique identifier of the Plugin to delete. |
Response
HTTP 204 No Content
PermalinkRetrieve Enabled Plugins
Retrieve a list of all installed plugins on the Kong node.
Response
HTTP 200 OK
{
"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"
]
}
PermalinkRetrieve 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.
Response
HTTP 200 OK
{
"fields": {
"hide_credentials": {
"default": false,
"type": "boolean"
},
"key_names": {
"default": "function",
"required": true,
"type": "array"
}
}
}
PermalinkCertificate Object
A certificate object represents a public certificate, and can be optionally paired with the corresponding private key. These objects are used by Kong to handle SSL/TLS termination for encrypted requests, or for use as a trusted CA store when validating peer certificate of client/service. Certificates are optionally associated with SNI objects to tie a cert/key pair to one or more hostnames.
If intermediate certificates are required in addition to the main certificate, they should be concatenated together into one string according to the following order: main certificate on the top, followed by any intermediates.
Certificates can be both tagged and filtered by tags.
{
"id": "7fca84d6-7d37-4a74-a7b0-93e576089a41",
"created_at": 1422386534,
"cert": "-----BEGIN CERTIFICATE-----...",
"key": "-----BEGIN RSA PRIVATE KEY-----...",
"tags": ["user-level", "low-priority"]
}
PermalinkAdd Certificate
PermalinkCreate Certificate
Request Body
Attributes | Description |
---|---|
cert |
PEM-encoded public certificate chain of the SSL key pair. |
key |
PEM-encoded private key of the SSL key pair. |
tags optional |
An optional set of strings associated with the Certificate, for grouping and filtering. |
snis shorthand-attribute |
An array of zero or more hostnames to associate with this certificate as SNIs. This is a sugar parameter that will, under the hood, create an SNI object and associate it with this certificate for your convenience. To set this attribute this certificate must have a valid private key associated with it. |
passphrase optional |
To load an encrypted private key into Kong, specify the passphrase using this attribute. Kong will decrypt the private key and store it in its database. To encrypt the private key and other sensitive information in Kong’s database, consider using DB encryption. |
Response
HTTP 201 Created
{
"id": "7fca84d6-7d37-4a74-a7b0-93e576089a41",
"created_at": 1422386534,
"cert": "-----BEGIN CERTIFICATE-----...",
"key": "-----BEGIN RSA PRIVATE KEY-----...",
"tags": ["user-level", "low-priority"]
}
PermalinkList Certificates
PermalinkList All Certificates
Response
HTTP 200 OK
{
"data": [{
"id": "d044b7d4-3dc2-4bbc-8e9f-6b7a69416df6",
"created_at": 1422386534,
"cert": "-----BEGIN CERTIFICATE-----...",
"key": "-----BEGIN RSA PRIVATE KEY-----...",
"tags": ["user-level", "low-priority"]
}, {
"id": "a9b2107f-a214-47b3-add4-46b942187924",
"created_at": 1422386534,
"cert": "-----BEGIN CERTIFICATE-----...",
"key": "-----BEGIN RSA PRIVATE KEY-----...",
"tags": ["admin", "high-priority", "critical"]
}],
"next": "http://localhost:8001/certificates?offset=6378122c-a0a1-438d-a5c6-efabae9fb969"
}
PermalinkRetrieve Certificate
PermalinkRetrieve Certificate
Attributes | Description |
---|---|
certificate id required |
The unique identifier of the Certificate to retrieve. |
Response
HTTP 200 OK
{
"id": "7fca84d6-7d37-4a74-a7b0-93e576089a41",
"created_at": 1422386534,
"cert": "-----BEGIN CERTIFICATE-----...",
"key": "-----BEGIN RSA PRIVATE KEY-----...",
"tags": ["user-level", "low-priority"]
}
PermalinkUpdate Certificate
PermalinkUpdate Certificate
Attributes | Description |
---|---|
certificate id required |
The unique identifier of the Certificate to update. |
Request Body
Attributes | Description |
---|---|
cert |
PEM-encoded public certificate chain of the SSL key pair. |
key |
PEM-encoded private key of the SSL key pair. |
tags optional |
An optional set of strings associated with the Certificate, for grouping and filtering. |
snis shorthand-attribute |
An array of zero or more hostnames to associate with this certificate as SNIs. This is a sugar parameter that will, under the hood, create an SNI object and associate it with this certificate for your convenience. To set this attribute this certificate must have a valid private key associated with it. |
passphrase optional |
To load an encrypted private key into Kong, specify the passphrase using this attribute. Kong will decrypt the private key and store it in its database. To encrypt the private key and other sensitive information in Kong’s database, consider using DB encryption. |
Response
HTTP 200 OK
{
"id": "7fca84d6-7d37-4a74-a7b0-93e576089a41",
"created_at": 1422386534,
"cert": "-----BEGIN CERTIFICATE-----...",
"key": "-----BEGIN RSA PRIVATE KEY-----...",
"tags": ["user-level", "low-priority"]
}
PermalinkUpdate or Create Certificate
PermalinkCreate or Update Certificate
Attributes | Description |
---|---|
certificate id required |
The unique identifier of the Certificate to create or update. |
Request Body
Attributes | Description |
---|---|
cert |
PEM-encoded public certificate chain of the SSL key pair. |
key |
PEM-encoded private key of the SSL key pair. |
tags optional |
An optional set of strings associated with the Certificate, for grouping and filtering. |
snis shorthand-attribute |
An array of zero or more hostnames to associate with this certificate as SNIs. This is a sugar parameter that will, under the hood, create an SNI object and associate it with this certificate for your convenience. To set this attribute this certificate must have a valid private key associated with it. |
passphrase optional |
To load an encrypted private key into Kong, specify the passphrase using this attribute. Kong will decrypt the private key and store it in its database. To encrypt the private key and other sensitive information in Kong’s database, consider using DB encryption. |
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.
PermalinkDelete Certificate
PermalinkDelete Certificate
Attributes | Description |
---|---|
certificate id required |
The unique identifier of the Certificate to delete. |
Response
HTTP 204 No Content
PermalinkCA Certificate Object
A CA certificate object represents a trusted CA. These objects are used by Kong to verify the validity of a client or server certificate.
CA Certificates can be both tagged and filtered by tags.
{
"id": "04fbeacf-a9f1-4a5d-ae4a-b0407445db3f",
"created_at": 1422386534,
"cert": "-----BEGIN CERTIFICATE-----...",
"tags": ["user-level", "low-priority"]
}
PermalinkAdd CA Certificate
PermalinkCreate CA Certificate
Request Body
Attributes | Description |
---|---|
cert |
PEM-encoded public certificate of the CA. |
tags optional |
An optional set of strings associated with the Certificate, for grouping and filtering. |
Response
HTTP 201 Created
{
"id": "04fbeacf-a9f1-4a5d-ae4a-b0407445db3f",
"created_at": 1422386534,
"cert": "-----BEGIN CERTIFICATE-----...",
"tags": ["user-level", "low-priority"]
}
PermalinkList CA Certificates
PermalinkList All CA Certificates
Response
HTTP 200 OK
{
"data": [{
"id": "43429efd-b3a5-4048-94cb-5cc4029909bb",
"created_at": 1422386534,
"cert": "-----BEGIN CERTIFICATE-----...",
"tags": ["user-level", "low-priority"]
}, {
"id": "d26761d5-83a4-4f24-ac6c-cff276f2b79c",
"created_at": 1422386534,
"cert": "-----BEGIN CERTIFICATE-----...",
"tags": ["admin", "high-priority", "critical"]
}],
"next": "http://localhost:8001/ca_certificates?offset=6378122c-a0a1-438d-a5c6-efabae9fb969"
}
PermalinkRetrieve CA Certificate
PermalinkRetrieve CA Certificate
Attributes | Description |
---|---|
ca_certificate id required |
The unique identifier of the CA Certificate to retrieve. |
Response
HTTP 200 OK
{
"id": "04fbeacf-a9f1-4a5d-ae4a-b0407445db3f",
"created_at": 1422386534,
"cert": "-----BEGIN CERTIFICATE-----...",
"tags": ["user-level", "low-priority"]
}
PermalinkUpdate CA Certificate
PermalinkUpdate CA Certificate
Attributes | Description |
---|---|
ca_certificate id required |
The unique identifier of the CA Certificate to update. |
Request Body
Attributes | Description |
---|---|
cert |
PEM-encoded public certificate of the CA. |
tags optional |
An optional set of strings associated with the Certificate, for grouping and filtering. |
Response
HTTP 200 OK
{
"id": "04fbeacf-a9f1-4a5d-ae4a-b0407445db3f",
"created_at": 1422386534,
"cert": "-----BEGIN CERTIFICATE-----...",
"tags": ["user-level", "low-priority"]
}
PermalinkUpdate or Create CA Certificate
PermalinkCreate or Update CA Certificate
Attributes | Description |
---|---|
ca_certificate id required |
The unique identifier of the CA Certificate to create or update. |
Request Body
Attributes | Description |
---|---|
cert |
PEM-encoded public certificate of the CA. |
tags optional |
An optional set of strings associated with the Certificate, for grouping and filtering. |
Inserts (or replaces) the CA Certificate under the requested resource with the
definition specified in the body. The CA Certificate will be identified via the name
or id
attribute.
When the name or id
attribute has the structure of a UUID, the CA Certificate being
inserted/replaced will be identified by its id
. Otherwise it will be
identified by its name
.
When creating a new CA 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.
PermalinkDelete CA Certificate
PermalinkDelete CA Certificate
Attributes | Description |
---|---|
ca_certificate id required |
The unique identifier of the CA Certificate to delete. |
Response
HTTP 204 No Content
PermalinkSNI 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.
{
"id": "91020192-062d-416f-a275-9addeeaffaf2",
"name": "my-sni",
"created_at": 1422386534,
"tags": ["user-level", "low-priority"],
"certificate": {"id":"a2e013e8-7623-4494-a347-6d29108ff68b"}
}
PermalinkAdd SNI
PermalinkCreate SNI
PermalinkCreate SNI Associated to a Specific Certificate
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
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. The Certificate must have a valid private key associated with it to be used by the SNI object. With form-encoded, the notation is certificate.id=<certificate_id> . With JSON, use "certificate":{"id":"<certificate_id>"} . |
Response
HTTP 201 Created
{
"id": "91020192-062d-416f-a275-9addeeaffaf2",
"name": "my-sni",
"created_at": 1422386534,
"tags": ["user-level", "low-priority"],
"certificate": {"id":"a2e013e8-7623-4494-a347-6d29108ff68b"}
}
PermalinkList SNIs
PermalinkList All SNIs
PermalinkList SNIs Associated to a Specific Certificate
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
{
"data": [{
"id": "147f5ef0-1ed6-4711-b77f-489262f8bff7",
"name": "my-sni",
"created_at": 1422386534,
"tags": ["user-level", "low-priority"],
"certificate": {"id":"a3ad71a8-6685-4b03-a101-980a953544f6"}
}, {
"id": "b87eb55d-69a1-41d2-8653-8d706eecefc0",
"name": "my-sni",
"created_at": 1422386534,
"tags": ["admin", "high-priority", "critical"],
"certificate": {"id":"4e8d95d4-40f2-4818-adcb-30e00c349618"}
}],
"next": "http://localhost:8001/snis?offset=6378122c-a0a1-438d-a5c6-efabae9fb969"
}
PermalinkRetrieve SNI
PermalinkRetrieve SNI
Attributes | Description |
---|---|
name or id required |
The unique identifier or the name of the SNI to retrieve. |
Response
HTTP 200 OK
{
"id": "91020192-062d-416f-a275-9addeeaffaf2",
"name": "my-sni",
"created_at": 1422386534,
"tags": ["user-level", "low-priority"],
"certificate": {"id":"a2e013e8-7623-4494-a347-6d29108ff68b"}
}
PermalinkUpdate SNI
PermalinkUpdate SNI
Attributes | Description |
---|---|
name or id required |
The unique identifier or the name of the SNI to update. |
Request 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. The Certificate must have a valid private key associated with it to be used by the SNI object. With form-encoded, the notation is certificate.id=<certificate_id> . With JSON, use "certificate":{"id":"<certificate_id>"} . |
Response
HTTP 200 OK
{
"id": "91020192-062d-416f-a275-9addeeaffaf2",
"name": "my-sni",
"created_at": 1422386534,
"tags": ["user-level", "low-priority"],
"certificate": {"id":"a2e013e8-7623-4494-a347-6d29108ff68b"}
}
PermalinkUpdate or Create SNI
PermalinkCreate or Update SNI
Attributes | Description |
---|---|
name or id required |
The unique identifier or the name of the SNI to create or update. |
Request 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. The Certificate must have a valid private key associated with it to be used by the SNI object. With form-encoded, the notation is certificate.id=<certificate_id> . With JSON, use "certificate":{"id":"<certificate_id>"} . |
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.
PermalinkDelete SNI
PermalinkDelete SNI
Attributes | Description |
---|---|
name or id required |
The unique identifier or the name of the SNI to delete. |
Response
HTTP 204 No Content
PermalinkUpstream 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, 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.
{
"id": "58c8ccbb-eafb-4566-991f-2ed4f678fa70",
"created_at": 1422386534,
"name": "my-upstream",
"algorithm": "round-robin",
"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"]
}
PermalinkAdd Upstream
PermalinkCreate Upstream
Request Body
Attributes | Description |
---|---|
name |
This is a hostname, which must be equal to the host of a Service. |
algorithm optional |
Which load balancing algorithm to use. One of: round-robin , consistent-hashing , or least-connections . Defaults to "round-robin" . |
hash_on 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. |
Response
HTTP 201 Created
{
"id": "58c8ccbb-eafb-4566-991f-2ed4f678fa70",
"created_at": 1422386534,
"name": "my-upstream",
"algorithm": "round-robin",
"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"]
}
PermalinkList Upstreams
PermalinkList All Upstreams
Response
HTTP 200 OK
{
"data": [{
"id": "ea29aaa3-3b2d-488c-b90c-56df8e0dd8c6",
"created_at": 1422386534,
"name": "my-upstream",
"algorithm": "round-robin",
"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": "4fe14415-73d5-4f00-9fbc-c72a0fccfcb2",
"created_at": 1422386534,
"name": "my-upstream",
"algorithm": "round-robin",
"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"]
}],
"next": "http://localhost:8001/upstreams?offset=6378122c-a0a1-438d-a5c6-efabae9fb969"
}
PermalinkRetrieve Upstream
Attributes | Description |
---|---|
name or id required |
The unique identifier or the name of the Upstream to retrieve. |
Response
HTTP 200 OK
{
"id": "58c8ccbb-eafb-4566-991f-2ed4f678fa70",
"created_at": 1422386534,
"name": "my-upstream",
"algorithm": "round-robin",
"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"]
}
PermalinkUpdate Upstream
Attributes | Description |
---|---|
name or id required |
The unique identifier or the name of the Upstream to update. |
Request Body
Attributes | Description |
---|---|
name |
This is a hostname, which must be equal to the host of a Service. |
algorithm optional |
Which load balancing algorithm to use. One of: round-robin , consistent-hashing , or least-connections . Defaults to "round-robin" . |
hash_on 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. |
Response
HTTP 200 OK
{
"id": "58c8ccbb-eafb-4566-991f-2ed4f678fa70",
"created_at": 1422386534,
"name": "my-upstream",
"algorithm": "round-robin",
"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"]
}
PermalinkUpdate or Create Upstream
Attributes | Description |
---|---|
name or id required |
The unique identifier or the name of the Upstream to create or update. |
PermalinkRequest Body
Attributes | Description |
---|---|
name |
This is a hostname, which must be equal to the host of a Service. |
algorithm optional |
Which load balancing algorithm to use. One of: round-robin , consistent-hashing , or least-connections . Defaults to "round-robin" . |
hash_on 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. |
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.
PermalinkResponse
HTTP 201 Created or HTTP 200 OK
See POST and PATCH responses.
PermalinkDelete Upstream
Attributes | Description |
---|---|
name or id required |
The unique identifier or the name of the Upstream to delete. |
Response
HTTP 204 No Content
PermalinkShow 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 balancer due to DNS issues,
its status displays as
DNS_ERROR
. - When health checks 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,
its status is displayed as
HEALTHY
. This means that this Target is currently included in this Upstream’s load balancer execution. - When a Target has been disabled by either active or passive health checks
(circuit breakers) or manually,
its status is displayed as
UNHEALTHY
. The load balancer is not directing any traffic to this Target via this Upstream.
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
{
"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
}
]
}
PermalinkTarget 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.
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.
{
"id": "a3395f66-2af6-4c79-bea2-1b6933764f80",
"created_at": 1422386534,
"upstream": {"id":"885a0392-ef1b-4de3-aacf-af3f1697ce2c"},
"target": "example.com:8000",
"weight": 100,
"tags": ["user-level", "low-priority"]
}
PermalinkAdd Target
PermalinkCreate Target Associated to a Specific Upstream
Attributes | Description |
---|---|
upstream_id required |
The unique identifier of the Upstream that should be associated to the newly-created Target. |
Request 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. |
Response
HTTP 201 Created
{
"id": "a3395f66-2af6-4c79-bea2-1b6933764f80",
"created_at": 1422386534,
"upstream": {"id":"885a0392-ef1b-4de3-aacf-af3f1697ce2c"},
"target": "example.com:8000",
"weight": 100,
"tags": ["user-level", "low-priority"]
}
PermalinkList Targets
PermalinkList Targets Associated to a Specific Upstream
Attributes | Description |
---|---|
upstream_id required |
The unique identifier 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
{
"data": [{
"id": "f5a9c0ca-bdbb-490f-8928-2ca95836239a",
"created_at": 1422386534,
"upstream": {"id":"173a6cee-90d1-40a7-89cf-0329eca780a6"},
"target": "example.com:8000",
"weight": 100,
"tags": ["user-level", "low-priority"]
}, {
"id": "bdab0e47-4e37-4f0b-8fd0-87d95cc4addc",
"created_at": 1422386534,
"upstream": {"id":"f00c6da4-3679-4b44-b9fb-36a19bd3ae83"},
"target": "example.com:8000",
"weight": 100,
"tags": ["admin", "high-priority", "critical"]
}],
"next": "http://localhost:8001/targets?offset=6378122c-a0a1-438d-a5c6-efabae9fb969"
}
PermalinkDelete 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.
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
PermalinkSet Target Address As Healthy
Set the current health status of an individual address resolved by a target in the load balancer to “healthy” in the entire Kong cluster.
This endpoint can be used to manually re-enable an address resolved by a target that was previously disabled by the upstream’s health checker. Upstreams only forward requests to healthy nodes, so this call tells Kong to start using this address 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.
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. |
address required |
The host/port combination element of the address to set as healthy. |
Response
HTTP 204 No Content
PermalinkSet Target Address as Unhealthy
Set the current health status of an individual address resolved by a target in the load balancer to “unhealthy” in the entire Kong cluster.
This endpoint can be used to manually disable an address and have it stop responding to requests. Upstreams only forward requests to healthy nodes, so this call tells Kong to start skipping this address.
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 continue to execute for unhealthy addresses. Note that if active health checks are enabled and the probe detects that the address is actually healthy, it will automatically re-enable it again. To permanently remove a target from the balancer, you should delete a target instead.
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
PermalinkSet Target as Healthy
Set the current health status of a target in the load balancer to “healthy” in the entire Kong cluster. This sets the “healthy” status to all addresses resolved by this target.
This endpoint can be used to manually re-enable a target that was previously disabled by the upstream’s health checker. 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.
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
PermalinkSet Target as Unhealthy
Set the current health status of a target in the load balancer to “unhealthy” in the entire Kong cluster. This sets the “unhealthy” status to all addresses resolved by this target.
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.
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 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 balancer, you should delete a target instead.
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
PermalinkList 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.
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
{
"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
}
]
}