Skip to content
|
You are browsing the Kong Gateway documentation archive. This documentation is no longer actively maintained.
See the latest Kong Gateway documentation.
Kong Gateway OSS [ARCHIVE]
2.3.x

PermalinkAdmin API for DB-less Mode

Kong comes with an internal RESTful Admin API for administration purposes. In DB-less mode, this Admin API can be used to load a new declarative configuration, and for inspecting the current configuration. In DB-less mode, the Admin API for each 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.

  • 8001 is the default port on which the Admin API listens.
  • 8444 is the default port for HTTPS traffic to the Admin API.

This API provides full control over Kong, so care should be taken when setting up Kong environments to avoid undue public exposure of this API. See this document for a discussion of methods to secure the Admin API.

PermalinkSupported Content Types

The Admin API accepts 3 content types on every endpoint:

  • 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"
    }
}
  • 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
  • multipart/form-data

Similar to URL-encoded, this content type uses dotted keys to reference nested objects. Here is an example of sending a Lua file to the pre-function Kong plugin:

curl -i -X POST http://localhost:8001/services/plugin-testing/plugins \
     -F "name=pre-function" \
     -F "config.functions=@custom-auth.lua"

PermalinkInformation Routes

PermalinkRetrieve Node Information

Retrieve generic details about a node.

/

PermalinkResponse

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 different node_id each time it is restarted.
  • available_on_server: Names of plugins that are installed on the node.
  • enabled_in_cluster: Names of plugins that are enabled/configured. That is, the plugins configurations currently in the datastore shared by all Kong nodes.

PermalinkList Available Endpoints

List all available endpoints provided by the Admin API.

/endpoints

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.

/schemas/{entity}/validate

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.

/schemas/{entity name}

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.

/schemas/plugins/{plugin name}

PermalinkResponse

HTTP 200 OK

{
    "fields": {
        "hide_credentials": {
            "default": false,
            "type": "boolean"
        },
        "key_names": {
            "default": "function",
            "required": true,
            "type": "array"
        }
    }
}

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.

/status

PermalinkResponse

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 by collectgarbage("count"), for every active worker, i.e. a worker that received a proxy call in the last 10 seconds.
    • pid: worker’s process identification number.
    • lua_shared_dicts: An array of information about dictionaries that are shared with all workers in a Kong node, where each array node contains how much memory is dedicated for the specific shared dictionary (capacity) and how much of said memory is in use (allocated_slabs). These shared dictionaries have least recent used (LRU) eviction capabilities, so a full dictionary, where allocated_slabs == capacity, will work properly. However for some dictionaries, e.g. cache HIT/MISS shared dictionaries, increasing their size can be beneficial for the overall performance of a Kong node.
    • The memory usage unit and precision can be changed using the querystring arguments unit and scale:
      • unit: one of b/B, k/K, m/M, g/G, which will return results in bytes, kibibytes, mebibytes, or gibibytes, respectively. When “bytes” are requested, the memory values in the response will have a number type instead of string. Defaults to m.
      • scale: the number of digits to the right of the decimal points when values are given in human-readable memory strings (unit other than “bytes”). Defaults to 2. You can get the shared dictionaries memory usage in kibibytes with 4 digits of precision by doing: GET /status?unit=k&scale=4
  • server: Metrics about the nginx HTTP/S server.
    • total_requests: The total number of client requests.
    • connections_active: The current number of active client connections including Waiting connections.
    • connections_accepted: The total number of accepted client connections.
    • connections_handled: The total number of handled connections. Generally, the parameter value is the same as accepts unless some resource limits have been reached.
    • connections_reading: The current number of connections where Kong is reading the request header.
    • connections_writing: The current number of connections where nginx is writing the response back to the client.
    • connections_waiting: The current number of idle client connections waiting for a request.
  • database: Metrics about the database.
    • reachable: A boolean value reflecting the state of the database connection. Please note that this flag does not reflect the health of the database itself.

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, please read the declarative configuration documentation.

/config
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.

PermalinkTags

Tags are strings associated to entities in Kong. Each tag must be composed of one or more alphanumeric characters, _, -, . or ~.

Most core entities can be tagged via their tags attribute, upon creation or edition.

Tags can be used to filter core entities as well, via the ?tags querystring parameter.

For example: if you normally get a list of all the Services by doing:

GET /services

You can get the list of all the Services tagged example by doing:

GET /services?tags=example

Similarly, if you want to filter Services so that you only get the ones tagged example and admin, you can do that like so:

GET /services?tags=example,admin

Finally, if you wanted to filter the Services tagged example or admin, you could use:

GET /services?tags=example/admin

Some notes:

  • A maximum of 5 tags can be queried simultaneously in a single request with , or /
  • Mixing operators is not supported: if you try to mix , with / in the same querystring, you will receive an error.
  • You may need to quote and/or escape some characters when using them from the command line.
  • Filtering by tags is not supported in foreign key relationship endpoints. For example, the tags parameter will be ignored in a request such as GET /services/foo/routes?tags=a,b
  • offset parameters are not guaranteed to work if the tags parameter is altered or removed

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.

/tags

PermalinkResponse

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.

/tags/{tags}

PermalinkResponse

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 entities, as the name implies, are abstractions of each of your own upstream services. Examples of Services would be a data transformation microservice, a billing API, etc.

The main attribute of a Service is its URL (where Kong should proxy traffic to), which can be set as a single string or by specifying its protocol, host, port and path individually.

Services are associated to Routes (a Service can have many Routes associated with it). Routes are entry-points in Kong and define rules to match client requests. Once a Route is matched, Kong proxies the request to its associated Service. See the Proxy Reference 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"]
}

PermalinkList Services

PermalinkList All Services
/services
PermalinkList Services Associated to a Specific Certificate
/certificates/{certificate name or id}/services
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.

PermalinkResponse

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
/services/{service name or id}
Attributes Description
service name or id
required		 The unique identifier or the name of the Service to retrieve.
PermalinkRetrieve Service Associated to a Specific Certificate
/certificates/{certificate id}/services/{service name or id}
Attributes Description
certificate id
required		 The unique identifier of the Certificate to retrieve.
service name or id
required		 The unique identifier or the name of the Service to retrieve.
PermalinkRetrieve Service Associated to a Specific Route
/routes/{route name or id}/service
Attributes Description
route name or id
required		 The unique identifier or the name of the Route associated to the Service to be retrieved.
PermalinkRetrieve Service Associated to a Specific Plugin
/plugins/{plugin id}/service
Attributes Description
plugin id
required		 The unique identifier of the Plugin associated to the Service to be retrieved.

PermalinkResponse

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"]
}

PermalinkRoute Object

Route entities define rules to match client requests. Each Route is associated with a Service, and a Service may have multiple Routes associated to it. Every request matching a given Route will be proxied to its associated Service.

The combination of Routes and Services (and the separation of concerns between them) offers a powerful routing mechanism with which it is possible to define fine-grained entry-points in Kong leading to different upstream services of your infrastructure.

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 of methods, hosts, headers or paths;
  • For https, at least one of methods, hosts, headers, paths or snis;
  • For tcp, at least one of sources or destinations;
  • For tls, at least one of sources, destinations or snis;
  • For grpc, at least one of hosts, headers or paths;
  • For grpcs, at least one of hosts, headers, paths or snis.

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.

In the following table, s is the Service and r is the Route.

s.path r.path r.strip_path r.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"}
}

PermalinkList Routes

PermalinkList All Routes
/routes
PermalinkList Routes Associated to a Specific Service
/services/{service name or id}/routes
Attributes Description
service name or id
required		 The unique identifier or the name attribute of the Service whose Routes are to be retrieved. When using this endpoint, only Routes associated to the specified Service will be listed.

PermalinkResponse

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
/routes/{route name or id}
Attributes Description
route name or id
required		 The unique identifier or the name of the Route to retrieve.
PermalinkRetrieve Route Associated to a Specific Service
/services/{service name or id}/routes/{route name or id}
Attributes Description
service name or id
required		 The unique identifier or the name of the Service to retrieve.
route name or id
required		 The unique identifier or the name of the Route to retrieve.
PermalinkRetrieve Route Associated to a Specific Plugin
/plugins/{plugin id}/route
Attributes Description
plugin id
required		 The unique identifier of the Plugin associated to the Route to be retrieved.

PermalinkResponse

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

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"]
}

PermalinkList Consumers

PermalinkList All Consumers
/consumers

PermalinkResponse

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
/consumers/{consumer username or id}
Attributes Description
consumer username or id
required		 The unique identifier or the username of the Consumer to retrieve.
PermalinkRetrieve Consumer Associated to a Specific Plugin
/plugins/{plugin id}/consumer
Attributes Description
plugin id
required		 The unique identifier of the Plugin associated to the Consumer to be retrieved.

PermalinkResponse

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"]
}

PermalinkPlugin Object

A Plugin entity represents a plugin configuration that will be executed during the HTTP request/response lifecycle. It is how you can add functionalities to Services that run behind Kong, like Authentication or Rate Limiting for example. You can find more information about how to install and what values each plugin takes by visiting the Kong Hub.

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": {"minute":20, "hour":500},
    "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:

  1. Plugins configured on a combination of: a Route, a Service, and a Consumer. (Consumer means the request must be authenticated).
  2. Plugins configured on a combination of a Route and a Consumer. (Consumer means the request must be authenticated).
  3. Plugins configured on a combination of a Service and a Consumer. (Consumer means the request must be authenticated).
  4. Plugins configured on a combination of a Route and a Service.
  5. Plugins configured on a Consumer. (Consumer means the request must be authenticated).
  6. Plugins configured on a Route.
  7. Plugins configured on a Service.
  8. Plugins configured to run globally.

Example: if the rate-limiting plugin is applied twice (with different configurations): for a Service (Plugin config A), and for a Consumer (Plugin config B), then requests authenticating this Consumer will run Plugin config B and ignore A. However, requests that do not authenticate this Consumer will fallback to running Plugin config A. Note that if config B is disabled (its enabled flag is set to false), config A will apply to requests that would have otherwise matched config B.

PermalinkList Plugins

PermalinkList All Plugins
/plugins
PermalinkList Plugins Associated to a Specific Route
/routes/{route name or id}/plugins
Attributes Description
route name or id
required		 The unique identifier or the name attribute 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
/services/{service name or id}/plugins
Attributes Description
service name or id
required		 The unique identifier or the name attribute 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
/consumers/{consumer name or id}/plugins
Attributes Description
consumer name or id
required		 The unique identifier or the name attribute of the Consumer whose Plugins are to be retrieved. When using this endpoint, only Plugins associated to the specified Consumer will be listed.

PermalinkResponse

HTTP 200 OK

{
"data": [{
    "id": "02621eee-8309-4bf6-b36b-a82017a5393e",
    "name": "rate-limiting",
    "created_at": 1422386534,
    "route": null,
    "service": null,
    "consumer": null,
    "config": {"minute":20, "hour":500},
    "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": {"minute":20, "hour":500},
    "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
/plugins/{plugin id}
Attributes Description
plugin id
required		 The unique identifier of the Plugin to retrieve.
PermalinkRetrieve Plugin Associated to a Specific Route
/routes/{route name or id}/plugins/{plugin id}
Attributes Description
route name or id
required		 The unique identifier or the name of the Route to retrieve.
plugin id
required		 The unique identifier of the Plugin to retrieve.
PermalinkRetrieve Plugin Associated to a Specific Service
/services/{service name or id}/plugins/{plugin id}
Attributes Description
service name or id
required		 The unique identifier or the name of the Service to retrieve.
plugin id
required		 The unique identifier of the Plugin to retrieve.
PermalinkRetrieve Plugin Associated to a Specific Consumer
/consumers/{consumer username or id}/plugins/{plugin id}
Attributes Description
consumer username or id
required		 The unique identifier or the username of the Consumer to retrieve.
plugin id
required		 The unique identifier of the Plugin to retrieve.

PermalinkResponse

HTTP 200 OK

{
    "id": "ce44eef5-41ed-47f6-baab-f725cecf98c7",
    "name": "rate-limiting",
    "created_at": 1422386534,
    "route": null,
    "service": null,
    "consumer": null,
    "config": {"minute":20, "hour":500},
    "protocols": ["http", "https"],
    "enabled": true,
    "tags": ["user-level", "low-priority"]
}

PermalinkRetrieve Enabled Plugins

Retrieve a list of all installed plugins on the Kong node.

/plugins/enabled

PermalinkResponse

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"
    ]
}

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-----...",
    "cert_alt": "-----BEGIN CERTIFICATE-----...",
    "key_alt": "-----BEGIN EC PRIVATE KEY-----...",
    "tags": ["user-level", "low-priority"]
}

PermalinkList Certificates

PermalinkList All Certificates
/certificates

PermalinkResponse

HTTP 200 OK

{
"data": [{
    "id": "d044b7d4-3dc2-4bbc-8e9f-6b7a69416df6",
    "created_at": 1422386534,
    "cert": "-----BEGIN CERTIFICATE-----...",
    "key": "-----BEGIN RSA PRIVATE KEY-----...",
    "cert_alt": "-----BEGIN CERTIFICATE-----...",
    "key_alt": "-----BEGIN EC PRIVATE KEY-----...",
    "tags": ["user-level", "low-priority"]
}, {
    "id": "a9b2107f-a214-47b3-add4-46b942187924",
    "created_at": 1422386534,
    "cert": "-----BEGIN CERTIFICATE-----...",
    "key": "-----BEGIN RSA PRIVATE KEY-----...",
    "cert_alt": "-----BEGIN CERTIFICATE-----...",
    "key_alt": "-----BEGIN EC PRIVATE KEY-----...",
    "tags": ["admin", "high-priority", "critical"]
}],

    "next": "http://localhost:8001/certificates?offset=6378122c-a0a1-438d-a5c6-efabae9fb969"
}

PermalinkRetrieve Certificate

PermalinkRetrieve Certificate
/certificates/{certificate id}
Attributes Description
certificate id
required		 The unique identifier of the Certificate to retrieve.
PermalinkRetrieve Certificate Associated to a Specific Upstream
/upstreams/{upstream name or id}/client_certificate
Attributes Description
upstream name or id
required		 The unique identifier or the name of the Upstream associated to the Certificate to be retrieved.

PermalinkResponse

HTTP 200 OK

{
    "id": "7fca84d6-7d37-4a74-a7b0-93e576089a41",
    "created_at": 1422386534,
    "cert": "-----BEGIN CERTIFICATE-----...",
    "key": "-----BEGIN RSA PRIVATE KEY-----...",
    "cert_alt": "-----BEGIN CERTIFICATE-----...",
    "key_alt": "-----BEGIN EC PRIVATE KEY-----...",
    "tags": ["user-level", "low-priority"]
}

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-----...",
    "cert_digest": "c641e28d77e93544f2fa87b2cf3f3d51...",
    "tags": ["user-level", "low-priority"]
}

PermalinkList CA Certificates

PermalinkList All CA Certificates
/ca_certificates

PermalinkResponse

HTTP 200 OK

{
"data": [{
    "id": "43429efd-b3a5-4048-94cb-5cc4029909bb",
    "created_at": 1422386534,
    "cert": "-----BEGIN CERTIFICATE-----...",
    "cert_digest": "c641e28d77e93544f2fa87b2cf3f3d51...",
    "tags": ["user-level", "low-priority"]
}, {
    "id": "d26761d5-83a4-4f24-ac6c-cff276f2b79c",
    "created_at": 1422386534,
    "cert": "-----BEGIN CERTIFICATE-----...",
    "cert_digest": "c641e28d77e93544f2fa87b2cf3f3d51...",
    "tags": ["admin", "high-priority", "critical"]
}],

    "next": "http://localhost:8001/ca_certificates?offset=6378122c-a0a1-438d-a5c6-efabae9fb969"
}

PermalinkRetrieve CA Certificate

PermalinkRetrieve CA Certificate
/ca_certificates/{ca_certificate id}
Attributes Description
ca_certificate id
required		 The unique identifier of the CA Certificate to retrieve.

PermalinkResponse

HTTP 200 OK

{
    "id": "04fbeacf-a9f1-4a5d-ae4a-b0407445db3f",
    "created_at": 1422386534,
    "cert": "-----BEGIN CERTIFICATE-----...",
    "cert_digest": "c641e28d77e93544f2fa87b2cf3f3d51...",
    "tags": ["user-level", "low-priority"]
}

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

PermalinkList SNIs

PermalinkList All SNIs
/snis
PermalinkList SNIs Associated to a Specific Certificate
/certificates/{certificate name or id}/snis
Attributes Description
certificate name or id
required		 The unique identifier or the name attribute of the Certificate whose SNIs are to be retrieved. When using this endpoint, only SNIs associated to the specified Certificate will be listed.

PermalinkResponse

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
/snis/{sni name or id}
Attributes Description
sni name or id
required		 The unique identifier or the name of the SNI to retrieve.
PermalinkRetrieve SNI Associated to a Specific Certificate
/certificates/{certificate id}/snis/{sni name or id}
Attributes Description
certificate id
required		 The unique identifier of the Certificate to retrieve.
sni name or id
required		 The unique identifier or the name of the SNI to retrieve.

PermalinkResponse

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

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]
            }
        },
        "threshold": 0
    },
    "tags": ["user-level", "low-priority"],
    "host_header": "example.com",
    "client_certificate": {"id":"ea29aaa3-3b2d-488c-b90c-56df8e0dd8c6"}
}

PermalinkList Upstreams

PermalinkList All Upstreams
/upstreams
PermalinkList Upstreams Associated to a Specific Certificate
/certificates/{certificate name or id}/upstreams
Attributes Description
certificate name or id
required		 The unique identifier or the name attribute of the Certificate whose Upstreams are to be retrieved. When using this endpoint, only Upstreams associated to the specified Certificate will be listed.

PermalinkResponse

HTTP 200 OK

{
"data": [{
    "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]
            }
        },
        "threshold": 0
    },
    "tags": ["user-level", "low-priority"],
    "host_header": "example.com",
    "client_certificate": {"id":"a3395f66-2af6-4c79-bea2-1b6933764f80"}
}, {
    "id": "885a0392-ef1b-4de3-aacf-af3f1697ce2c",
    "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]
            }
        },
        "threshold": 0
    },
    "tags": ["admin", "high-priority", "critical"],
    "host_header": "example.com",
    "client_certificate": {"id":"f5a9c0ca-bdbb-490f-8928-2ca95836239a"}
}],

    "next": "http://localhost:8001/upstreams?offset=6378122c-a0a1-438d-a5c6-efabae9fb969"
}

PermalinkRetrieve Upstream

PermalinkRetrieve Upstream
/upstreams/{upstream name or id}
Attributes Description
upstream name or id
required		 The unique identifier or the name of the Upstream to retrieve.
PermalinkRetrieve Upstream Associated to a Specific Certificate
/certificates/{certificate id}/upstreams/{upstream name or id}
Attributes Description
certificate id
required		 The unique identifier of the Certificate to retrieve.
upstream name or id
required		 The unique identifier or the name of the Upstream to retrieve.
PermalinkRetrieve Upstream Associated to a Specific Target
/targets/{target host:port or id}/upstream
Attributes Description
target host:port or id
required		 The unique identifier or the host:port of the Target associated to the Upstream to be retrieved.

PermalinkResponse

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]
            }
        },
        "threshold": 0
    },
    "tags": ["user-level", "low-priority"],
    "host_header": "example.com",
    "client_certificate": {"id":"ea29aaa3-3b2d-488c-b90c-56df8e0dd8c6"}
}

PermalinkShow Upstream Health for Node

Displays the health status for all Targets of a given Upstream, or for the whole 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.

When the request query parameter balancer_health is set to 1, the data field of the response refers to the Upstream itself, and its health attribute is defined by the state of all of Upstream’s Targets, according to the field healthchecks.threshold.

/upstreams/{name or id}/health/
Attributes Description
name or id
required		 The unique identifier or the name of the Upstream for which to display Target health.

PermalinkRequest Querystring Parameters

Attributes Description
balancer_health
optional		 If set to 1, Kong will return the health status of the Upstream itself. See the healthchecks.threshold property.

PermalinkResponse

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
        }
    ]
}

If balancer_health=1:

HTTP 200 OK

{
    "data": {
        "health": "HEALTHY",
        "id": "07131005-ba30-4204-a29f-0927d53257b4"
    },
    "next": null,
    "node_id": "cbb297c0-14a9-46bc-ad91-1d0ef9b42df9"
}

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, modified, or deleted. Changes take effect on the fly.

Because the upstream maintains a history of target changes, the targets cannot be deleted or modified. To disable a target, post a new one with weight=0; alternatively, use the DELETE convenience method to accomplish the same.

The current target object definition is the one with the latest created_at.

Targets can be both tagged and filtered by tags.

{
    "id": "173a6cee-90d1-40a7-89cf-0329eca780a6",
    "created_at": 1422386534,
    "upstream": {"id":"bdab0e47-4e37-4f0b-8fd0-87d95cc4addc"},
    "target": "example.com:8000",
    "weight": 100,
    "tags": ["user-level", "low-priority"]
}

PermalinkList Targets

PermalinkList Targets Associated to a Specific Upstream
/upstreams/{upstream host:port or id}/targets
Attributes Description
upstream host:port or id
required		 The unique identifier or the host:port attribute of the Upstream whose Targets are to be retrieved. When using this endpoint, only Targets associated to the specified Upstream will be listed.

PermalinkResponse

HTTP 200 OK

{
"data": [{
    "id": "f00c6da4-3679-4b44-b9fb-36a19bd3ae83",
    "created_at": 1422386534,
    "upstream": {"id":"0c61e164-6171-4837-8836-8f5298726d53"},
    "target": "example.com:8000",
    "weight": 100,
    "tags": ["user-level", "low-priority"]
}, {
    "id": "5027BBC1-508C-41F8-87F2-AB1801E9D5C3",
    "created_at": 1422386534,
    "upstream": {"id":"68FDB05B-7B08-47E9-9727-AF7F897CFF1A"},
    "target": "example.com:8000",
    "weight": 100,
    "tags": ["admin", "high-priority", "critical"]
}],

    "next": "http://localhost:8001/targets?offset=6378122c-a0a1-438d-a5c6-efabae9fb969"
}

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.

/upstreams/{upstream name or id}/targets/{target or id}/healthy
Attributes Description
upstream name or id
required		 The unique identifier or the name of the upstream.
target or id
required		 The host/port combination element of the target to set as healthy, or the id of an existing target entry.

PermalinkResponse

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.

/upstreams/{upstream name or id}/targets/{target or id}/unhealthy
Attributes Description
upstream name or id
required		 The unique identifier or the name of the upstream.
target or id
required		 The host/port combination element of the target to set as unhealthy, or the id of an existing target entry.

PermalinkResponse

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.

/upstreams/{name or id}/targets/all/
Attributes Description
name or id
required		 The unique identifier or the name of the upstream for which to list the targets.

PermalinkResponse

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
        }
    ]
}