First, architecture

Here Insert Picture Description

Second, the term base

API: API refers to the instance Kong. You can configure your API as an administrator.
Plugin: He was referring Kong "plug-in", which is running the business logic in the proxy lifecycle. Can be configured globally by the administrator, it can also be configured separately for each API.
Client: Kong directed downstream in outbound proxy client requests, i.e., third-party clients.
Upstream Service: refers Kong is located behind your own API service, client requests are forwarded its final destination, the upstream server Nginx.

Third, the listening port

Kong listens for requests four ports, the default is:

8000: This port is used to monitor Kong HTTP requests from clients, and this request is forwarded to your upstream service. This is also the main port used in this tutorial.
8443: This port is listening Kong HTTP request port. The port has a similar behavior port 8000, but it only listens HTTPS requests and no forwarding behavior. This port can be disabled through a configuration file.
8001: KONG administrator for the port configuration.
8444: Administrator listening port for HTTPS requests.

In this article, we describe Kong routing functions, and the detailed description of the client on port 8000 requesting to how the proxy configuration according to upstream service request header, URI or HTTP.

IV Overview

On the whole, which listens for HTTP requests Kong configured proxy port (default 8000), and identifies the requesting upstream service which then run in the Plugin API arrangement (if not performed not), and upstream HTTP request to your own API service.
Kong is a transparent proxy, it forwards the request to your upstream service. When a client makes a request to the proxy port, Kong will be based on the configuration of the API KONG where to pass the request to determine which upstream services. You can add KONG where many attributes for each API, but there are three that must be configured, they are the hosts, uris and methods. If you can not determine the upstream service address KONG API request, it will return 404 "no API found with those values " error.

V. forwarding

How HTTP request to the API configuration properties host, uris, methods to match it? It should be noted that these three fields are optional, but at least a specified.

Matching rules and request the API:

Request must include all fields configured;
Request field value must match the value of at least one configured (although a plurality of parameter values can be arranged, a single request can only match one);

Let's look at a few examples, as an API configuration:

{
    "name": "my-api",
    "upstream_url": "http://my-api.com",
    "hosts": ["example.com", "service.com"],
    "uris": ["/foo", "/bar"],
    "methods": ["GET"]
}

Some matches with the API request may be:

GET /foo HTTP/1.1
Host: example.com
GET /bar HTTP/1.1
Host: service.com
GET /foo/hello/world HTTP/1.1
Host: example.com

Three or more requests are satisfied the conditions set in the API definitions.
However, following several requests the configuration does not match the condition:
the GET / the HTTP / 1.1
the Host: the example.com

POST /foo HTTP/1.1
Host: example.com

The GET / foo the HTTP / 1.1
the Host: the foo.com
three or more configuration requests meet only two criteria.

First request URI does not match;
The second method does not match the HTTP request;
Request does not match the third Host header.
Now that we understand how hosts, uris, methods work together. Let's see how one by one they are working alone.

hosts parameters

Host first transmission request based on the most direct way by Kong transmission request, which is one of the basic usage Host head.
Kong to make the process accessible through the Host API entity's easier and faster. hosts to accept a variety of parameters, when admin API request needs to be separated by a comma between each parameter.

$ curl -i -X POST http://localhost:8001/apis/ \
    -d 'name=my-api' \
    -d 'upstream_url=http://test-api.com' \
    -d 'hosts=test-api.com,demo.com,service.com'

The client can use the hosts = test-api.com , demo.com , any one service.com head Host access to my-api, but not the default value of the Host.

Use the wildcard * to configure hosts
in order to make agents more flexible, Kong wildcards are allowed to configure the hosts. Wildcards allow anyone to meet the conditions Host head-to-access API entities. When configuring the wildcard is only permitted an asterisk in the front or back of the Host (*), for example:
* .example.com: Match all access to the Host header example.com end.
example *:. Host match all head start access to the example.

preserve_host parameters

When enabled agent, Kong will default value upstream_url the API is configured as upstream service host host. preserve_host a boolean value, this behavior Kong is limited.
For example, when using the default values preserve_host be configured, the configuration is substantially the API:
{
"name": "My-API",
"upstream_url": " http://my-api.com ",
"the hosts": [ " service.com "],
}
at this time, the client sends a request message format is roughly:
the GET / the HTTP / 1.1
the Host: service.com
KONG extracts the value from the HOST upstream_url API in when the agent will be up similar travel service sends a request:
GET / HTTP / 1.1
Host: my-api.com
However, when the administrator when configuring the API, explicitly specify the preserver_host = true when:

{
“name”: “my-api”,
“upstream_url”: “http://my-api.com”,
“hosts”: [“service.com”],
“preserve_host”: true
}

And assuming that the client sends the same request:
GET / HTTP / 1.1
Host: service.com
KONG HOST will retain the value of a client sent when the agent will request the upstream service to send the following:
GET / HTTP / 1.1
Host: service.com

uris parameters

Kong forwards the request to the upstream services in another way, the value is the URI specified by configuration properties uris request. uris can configure a plurality of values, when making the request by the client, the prefix must be selected as a value in uris request.
For example, if you configure the API to:

{
“name”: “my-api”,
“upstream_url”: “http://my-api.com”,
“uris”: ["/service", “/hello/world”]
}

The following are several ways can request access to this API:

GET /service HTTP/1.1
Host: my-api.com

GET /service/resource?param=value HTTP/1.1
Host: my-api.com

GET /hello/world/resource HTTP/1.1
Host: anything.com

When the above ways making the request, the attribute value KONG detected uris their prefix API are matched, these requests are available.
When uris attribute configured, when making the request, will take the longest first KONG uris URI matching filter values,
if not match, then the length of time before taking uris values to match,
and so on, until the match is successful or access denied.
Such as the example above, when sending the request, KONG will take the first /hello/worldmatch with the request uri, if unsuccessful, will continue to take /serviceto continue to match work.

strip_uri parameters

When configuring uris API, and if you want to hide the true upstream service uri, and in another a URI to the client, it can be achieved by a simple configuration strip_uri property API. E.g:

{
“name”: “my-api”,
“upstream_url”: “http://my-api.com”,
“uris”: ["/service"],
“strip_uri”: true
}

Enable strip_uri attribute to indicate when the agent Kong the API, the request URI should not contain upstream URI prefix match.
API for the above configuration, when the client sends a request:
the GET /-Service / path / to / Resource the HTTP / 1.1
the Host:
real uri Kong agent for the upstream service (in this case does not contain content uris uri configured):
GET / path / to / Resource HTTP / 1.1
Host: my-api.com

methods parameters

Starting Kong 0.10 version, can be specified by configuring the client requests the API methods attribute. By default, regardless of the HTTP request methods, Kong will be the agent of its request to the API. However, when the configuration attribute methods, only the HTTP request proxied Kong embodiment will be matched.
Attribute values can configure methods:

{
“name”: “api-1”,
“upstream_url”: “http://my-api.com”,
“methods”: [“GET”, “HEAD”]
}

https_only parameters

If you only want to provide API via HTTPS, can be achieved by enabling its https_only attributes:

$ curl -i -X POST http://localhost:8001/apis \
    -d "name=ssl-only-api" \
    -d "upstream_url=http://example.com" \
    -d "hosts=my-api.com" \
    -d "https_only=true"

After such configuration, KONG agent will reject non-HTTPS requests. If at this time using an HTTP request to access the API, KONG prompts the user need to upgrade the client to HTTPS:

$ curl -i http://localhost:8000 \
-H "Host: my-api.com"

报错：
HTTP/1.1 426
Content-Type: application/json; charset=utf-8
Transfer-Encoding: chunked
Connection: Upgrade
Upgrade: TLS/1.2, HTTP/1.1
Server: kong/x.x.x

{“message”:“Please use HTTPS protocol”}

http_if_terminated参数

When the API request is locked in HTTPS, if you want to add X-Forwarded-Proto in the request header information, as long as the property is configured http_if_terminated API you can:

$ curl -i -X PATCH http://localhost:8001/apis/ssl-only-api \
    -d "http_if_terminated=true"

And we use the X-Forwarded-Proto (assuming it from a trusted client) request:

$ curl -i http://localhost:8000 \
    -H "Host: my-api.com" \
    -H "X-Forwarded-Proto: https"

Kong agent of this request now, because it assumes that your architecture components have been previously achieved SSL.

6, the Acting priority

An API can hosts, uris attributes and methods defined by the configuration matching rules. For Kong, only when all the fields match, it will be forwarded. However, KONG API allows two or more have the same configuration. At this point, it is related to the priority issues of the request.
Matching priority principles: Kong will first rule matching the most API match (when evaluating a request, Kong will first try to match the APIs with the most rules.).
For example there are arranged two API follows:

{
“name”: “api-1”,
“upstream_url”: “http://my-api.com”,
“hosts”: [“example.com”]
},

{
“name”: “api-2”,
“upstream_url”: “http://my-api-2.com”,
“hosts”: [“example.com”],
“methods”: [“POST”]
}

api-2 more than a configuration methods api-1, it will be the first to request KONG match api-2. With this configuration, we can avoid the api 2-request, forwarded to the wrong api-1.

This request will be forwarded to. 1-API:
the GET / the HTTP / 1.1
the Host: the example.com

And this request will be forwarded to-2 API:
the POST / the HTTP / 1.1
the Host: the example.com

So, if a api configure the hosts, methods, uris, then this API will be the first match with the request, his priority will be the three highest.

Seven, agent behavior

Kong foregoing detailed account of the requesting agent to an upstream proxy rules and services. Below we will explain in detail in Kong will forward the request to some of the things this time upstream services actually occurred.

Load Balancing

Kong1.10 version from the start, Kong inherited achieve a load balancing feature, you can forward the request to be distributed to multiple upstream service instance. Prior Kong 0.10, under normal circumstances, Kong agent will forward the request to the specified upstream_url, if you want to achieve load balancing services, the need for additional tools. You can balance the load by referring to the relevant information, find more information about adding to the API load balancing.

Plug-in extension

The user can customize the plugins by extension, the plug-in application and the request / response cycle life. Plug-ins can perform various operations on the behavior of agents in your production environment. Through the plug-in configuration, you can plug should be applied globally or for individual API applications. If given a certain API or application of a plug-in or more plug-ins, the proxy requests to the upstream before the service will be performed first match API, matching the plug after the successful implementation of defined when the plug-in implementation of the latter If conditions are met, the request will be the final agency to go upstream service. This contains the concept of plug-access period, with particular reference to the development of plug-in configuration-related information.

Agent or request timeout

When all of the proxy logic KONG, including API authentication plug-ins and the like, are dealt with, until the upstream service request broker. These are achieved by Nginx proxy module. Starting KONG 0.10, the configuration may be defined by the following three properties API connection time:
　　upstream_connect_timeout: establish a defined timeout connection with an upstream service, in milliseconds, the default value 60000.
　　upstream_send_timeout: Define two consecutive upstream transmission service write operation timeout, in milliseconds, the default value 60000.
upstream_read_timeout: definition of two consecutive transmission timeout upstream service read operations, in milliseconds, the default value 60000.
using 1.1 HTTP /, Kong added by default following request headers:

HOST: <upstream and services host>
Connection: keep-alive: allow reuse upstream connection
X-REAL-IP:<$proxy_add_x_forwarded_for>: 参见 nginx_http_proxy_module.
X-Forwarded-Proto: <protocol >: protocol is the protocol used by the client the name of
the other request headers are added by the default configuration.
When using WebSocket, there can be exceptions occur. If occurs, Kong header allows the request to upgrade protocol:
Connection: Upgrade
Upgrade: a WebSocket

Response

Kong in response to receiving the upstream and services, and in a manner which flow downstream back to the client. At this time, Kong added to a subsequent execution of the specific widget API, and these plug-ins inherited header_filter clause. When all inherited header_filter plug after the implementation of the following measures header information is returned to the client:
l Via: kong / xxx KONG version information, xxx is his version.
 Kong-Proxy-Latency :, Kong where latency represents receiving a request from the client and sends the request to the upstream service consumed time value (in milliseconds).
 Kong-Upstream-Latency :, wherein latency represents a waiting time Kong upstream of the first byte of a service response consumed (milliseconds).
When the headers sent to the client, Kong will be performed on this API registered, inherited body_filter plug-ins. After body_filter upstream return data successfully processed, and then sent to the client.

Configuring fallback API

By default, when sending a request to Kong, if the request fails, Kong will return HTTP 404, "API not found" and other information. To prevent this from happening, we can implement a custom configure fallback API "abnormal \ error" message.
Below is an example:

{
“name”: “root-fallback”,
“upstream_url”: “http://www.error.page”,
“uris”: ["/"]
}

Observation in this configuration, "uris", will find here Configuration "/" can be adapted to all requests, in accordance with the matching rules uris, each request URI first longest match, in descending order. So when all the uri does not match, the request is automatically forwarded to the configured here has to go to the service, thus implemented a custom "abnormal \ error" message.

Use Host API test head

curl -i -k https://localhost/test -H 'host=my-api.com'

Acting WebSocket

As the underlying Kong achieved Nginx, so he also supports WebSocket. If you want to between the client and recommend a WebSocket connection Kong, then you must first establish a WebSocket handshake. This is done by HTTP Upgrade mechanism. This can be operated by the client Kong, for example:
the GET / the HTTP / 1.1
Connection: Upgrade
the Host: my-websocket-api.com
Upgrade: a WebSocket
In this case, two Kong will Connection Upgrade request header and forwards to the upstream service go with.

# Eight, summary
through this guide, we hope you understand the underlying knowledge relating to the Agent Kong, matches from uris API, and how to use the WebSocket protocol, configure SSL for API. If you want to learn more knowledge, please refer Nginx load-balancing content.

Eight other tutorials

Installation Kong Dashboard (II)

Kong admin configuration (c)

Kong Common Problems and Solutions (iv)

Kong basics (a)

Article Directory