From b94bbf6f99ecbdbe3ed70b03014517b3691531fa Mon Sep 17 00:00:00 2001 From: Thijs Schreijer Date: Wed, 28 Jun 2017 11:21:38 +0200 Subject: [PATCH] docs(retries) document the retries setting --- app/docs/0.10.x/proxy.md | 30 ++++++++++++++++++++++++++++-- 1 file changed, 28 insertions(+), 2 deletions(-) diff --git a/app/docs/0.10.x/proxy.md b/app/docs/0.10.x/proxy.md index 159d309e8509..38523dcfd9ec 100644 --- a/app/docs/0.10.x/proxy.md +++ b/app/docs/0.10.x/proxy.md @@ -36,7 +36,8 @@ service depending on their headers, URI, and HTTP method. - [1. Load balancing][proxy-load-balancing] - [2. Plugins execution][proxy-plugins-execution] - [3. Proxying & upstream timeouts][proxy-proxying-upstream-timeouts] - - [4. Response][proxy-response] + - [4. Errors & retries][proxy-retries] + - [5. Response][proxy-response] - [Configuring a fallback API][proxy-configuring-a-fallback-api] - [Configuring SSL for an API][proxy-configuring-ssl-for-an-api] - [The `https_only` property][proxy-the-https-only-property] @@ -598,7 +599,31 @@ More information on this topic is covered in the [Back to TOC](#table-of-contents) -#### 4. Response +#### 4. Errors & retries + +Whenever an error occurs during while proxying, Kong will use the underlying +Nginx mechanism [retries][ngx-http-proxy-retries] to pass the request on to +the next upstream. + +There are two configurable elements here: + +1. The number of retries: this can be configured per API using the `retries` + property of the `API` object. See the [management API][API] for more + details on this. + +2. What exactly constitutes an error: here Kong uses the Nginx defaults, which + means an error or timeout occuring while establishing a connection with the + server, passing a request to it, or reading the response header. + +The second option is based on Nginx's [proxy_next_upstream][proxy_next_upstream] +directive. This option is not directly configurable through Kong, but can be +added using a custom Nginx configuration. See the +[configuration reference][configuration-reference] for more details. + + +[Back to TOC](#table-of-contents) + +#### 5. Response Kong receives the response from the upstream service and send it back to the downstream client in a streaming fashion. At this point Kong will execute @@ -819,4 +844,5 @@ topic we just covered. [API]: /docs/{{page.kong_version}}/admin-api [ngx-http-proxy-module]: http://nginx.org/en/docs/http/ngx_http_proxy_module.html +[ngx-http-proxy-retries]: http://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_next_upstream_tries [SNI]: https://en.wikipedia.org/wiki/Server_Name_Indication