Skip to content

Feat(Support): About the retries attribute of the service object #4957

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
Guaris wants to merge 10 commits into
base: main
Choose a base branch
from
+106 −0
Open

Feat(Support): About the retries attribute of the service object #4957

Show file tree
Hide file tree
Changes from 9 commits
Commits
Show all changes
10 commits
Select commit Hold shift + click to select a range
86fb497
Create About-retries-attribute-of-service-object.md
kong-kiransharma Apr 10, 2026
afdff9f
Update About-retries-attribute-of-service-object.md
kong-kiransharma Apr 13, 2026
23736c8
Update About-retries-attribute-of-service-object.md
kong-kiransharma Apr 13, 2026
8f31526
Update About-retries-attribute-of-service-object.md
kong-kiransharma Apr 13, 2026
d6840cf
Update About-retries-attribute-of-service-object.md
kong-kiransharma Apr 13, 2026
5dda810
Update About-retries-attribute-of-service-object.md
kong-kiransharma Apr 13, 2026
155080b
Update About-retries-attribute-of-service-object.md
kong-kiransharma Apr 13, 2026
620854d
Update About-retries-attribute-of-service-object.md
kong-kiransharma Apr 13, 2026
460cfe8
fix the file so it renders, and add comments.
Guaris Apr 13, 2026
2b05e64
Delete app/support.html
Guaris Apr 21, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
106 changes: 106 additions & 0 deletions app/_support/About-retries-attribute-of-service-object.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,106 @@
---
title: About the retries attribute of the service object
content_type: support
description: How Kong's retry behavior works for service objects, including how to observe retries in debug logs.
products:
- gateway
works_on:
- on-prem
- konnect
tldr:
q: How do I check the behavior of the retries attribute?
a: |
When an upstream is unreachable, Kong retries the connection up to the configured number of times. You can observe this in debug logs.
faqs:
- q: Does the service object only retry when an upstream object is set?
a: No, the service object can retry requests even if an upstream object has not been set.
- q: Does the service object retry on HTTP 4xx/5xx responses?
a: No, retries happen only for TCP connection errors. However, {{site.base_gateway}} can perform HTTP and TCP health checks using the upstream object. For more details, see the Health Checks and Circuit Breakers documentation.
---

## How to check the behavior of the retries attribute

1. Set `KONG_LOG_LEVEL=debug` and reload {{site.base_gateway}}.

In your container, set `KONG_LOG_LEVEL` to `debug`

```bash
echo "KONG_LOG_LEVEL=debug kong reload exit" | docker exec -i kong-ee /bin/sh
Copy link

Copilot AI Apr 21, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The docker exec command includes exit as an extra argument to kong reload and won’t actually run exit as a separate shell command; update the snippet to separate the commands properly (or use docker exec -e KONG_LOG_LEVEL=debug ... kong reload) so the instructions work as written.

Suggested change
echo "KONG_LOG_LEVEL=debug kong reload exit" | docker exec -i kong-ee /bin/sh
docker exec -e KONG_LOG_LEVEL=debug kong-ee kong reload

Copilot uses AI. Check for mistakes.
```

2. Run the httpbin container.

```bash
docker run -d --name httpbin --network=kong-ee-net -p 80:80 kong/httpbin
Copy link

Copilot AI Apr 21, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Publishing httpbin on host port 80 (-p 80:80) is unnecessary for this walkthrough (Kong reaches it via the Docker network) and can fail without elevated privileges; consider removing the port mapping or using a non-privileged host port.

Suggested change
docker run -d --name httpbin --network=kong-ee-net -p 80:80 kong/httpbin
docker run -d --name httpbin --network=kong-ee-net kong/httpbin

Copilot uses AI. Check for mistakes.
```

3. Create a service object linked to the httpbin container, setting retries.

```bash
curl -i -X POST http://localhost:8001/services \
--data name=example_service \
--data url='http://httpbin/anything' \
--data retries=5
```

4. Create a route object for the above service:

```bash
curl -i -X POST http://localhost:8001/services/example_service/routes \
--data 'paths[]=/mock' \
--data name=mocking
```

5. Access the route successfully, receiving a 200 response:

```bash
curl localhost:8000/mock -i

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 406
Connection: keep-alive
Server: gunicorn/19.9.0
Date: Thu, 08 Apr 2021 06:44:09 GMT
Access-Control-Allow-Origin: *
Access-Control-Allow-Credentials: true
X-Kong-Upstream-Latency: 13
X-Kong-Proxy-Latency: 4
Via: kong/2.3.3.0-enterprise-edition
...
```

6. Stop the httpbin container, then access the route again:

```bash
docker stop httpbin
curl localhost:8000/mock -i

HTTP/1.1 502 Bad Gateway
Server: openresty
Date: Thu, 08 Apr 2021 06:48:30 GMT
Content-Type: application/json; charset=utf-8
Connection: keep-alive
Content-Length: 75
X-Kong-Upstream-Latency: 3071
X-Kong-Proxy-Latency: 30607
Via: kong/2.3.3.0-enterprise-edition

{
"message":"An invalid response was received from the upstream server"
}
```

You can check the {{site.base_gateway}} logs to observe retry attempts, as shown below:

```bash
docker logs -f kong-ent
Copy link

Copilot AI Apr 21, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The container name is inconsistent (docker exec ... kong-ee earlier vs docker logs -f kong-ent here); use a single container name (or a placeholder like KONG_CONTAINER_ID) throughout the steps to avoid confusion.

Suggested change
docker logs -f kong-ent
docker logs -f kong-ee

Copilot uses AI. Check for mistakes.

DATE [debug] ... balancer(): setting address (try 1): xxx.xxx.xxx.xxx:xxx
...
...
DATE [error] ... connect() failed (110: Operation timed out) while connecting to upstream, client: xxx.xxx.xxx.xxx, server: kong, request: "GET /xxx HTTP/1.1", upstream: "xxx", host: "xxx"
DATE [debug] ... balancer(): setting address (try 2): xxx.xxx.xxx.xxx:xxx
...
...
```
49 changes: 49 additions & 0 deletions app/support.html
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,49 @@
---
title: Support Articles
layout: default
edit_and_issue_links: false
description: Browse troubleshooting guides and knowledge base articles for Kong products and services.
---
<div class="flex flex-col gap-12 w-full">
<div class="flex justify-between gap-[60px]">
<div class="flex flex-col gap-6 py-24 self-center">
<div class="flex flex-col gap-2">
<h1 class="font-extrabold text-[40px] leading-[60px]">Support Articles</h1>
<span class="leading-7">Browse troubleshooting guides and knowledge base articles for Kong products and services.</span>
Copy link

Copilot AI Apr 21, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This page should follow the established hub-page pattern (for example, app/how-to.html) by adding a page.output_format == 'markdown' branch (to avoid emitting raw HTML/SVG in LLM/Markdown output) and including the LLM dropdown next to the H1 in the HTML branch.

Copilot uses AI. Check for mistakes.
</div>
</div>
<div class="hidden lg:flex pt-9 pr-9 ">
<svg class="hidden dark:inline" xmlns="http://www.w3.org/2000/svg" width="300" height="219" viewBox="0 0 300 219" fill="none">
<path d="M136.16 178.382L136.837 178.705V177.955V43.6364V43.3651L136.603 43.228C127.247 37.7515 117.32 33.644 106.824 30.9058C96.3309 28.1684 85.7226 26.7995 75 26.7995C66.7873 26.7995 58.6316 27.598 50.5335 29.1948C42.4336 30.792 34.6182 33.1879 27.0879 36.3826L26.7995 36.5049V36.8182V171.818V172.481L27.4262 172.266C35.3585 169.546 43.232 167.507 51.047 166.148C58.8604 164.789 66.8446 164.11 75 164.11C85.6463 164.11 96.0075 165.299 106.085 167.676C116.163 170.055 126.188 173.622 136.16 178.382ZM163.163 177.955V178.705L163.84 178.382C173.812 173.622 183.837 170.055 193.915 167.676C203.993 165.299 214.354 164.11 225 164.11C233.155 164.11 241.14 164.789 248.953 166.148C256.768 167.507 264.642 169.546 272.574 172.266L273.2 172.481V171.818V36.8182V36.5049L272.912 36.3826C265.382 33.1879 257.566 30.792 249.467 29.1948C241.368 27.598 233.213 26.7995 225 26.7995C214.277 26.7995 203.669 28.1684 193.176 30.9058C182.68 33.644 172.753 37.7515 163.397 43.228L163.163 43.3651V43.6364V177.955ZM7.69581 16.7944L7.7075 16.7891L7.71888 16.7832C18.1394 11.3464 29.0121 7.26918 40.3377 4.55103C51.6648 1.83254 63.2186 0.473186 75 0.473186C88.1405 0.473186 100.997 2.17232 113.57 5.57043C126.141 8.96817 138.205 14.065 149.76 20.8624L150 21.0035L150.24 20.8624C161.795 14.065 173.859 8.96817 186.43 5.57043C199.003 2.17232 211.86 0.473186 225 0.473186C236.781 0.473186 248.335 1.83254 259.662 4.55103C270.988 7.26918 281.861 11.3464 292.281 16.7832L292.293 16.7891L292.304 16.7944C294.717 17.8912 296.513 19.5274 297.71 21.7053C298.923 23.9109 299.527 26.2191 299.527 28.6364V192.955C299.527 198.018 297.395 201.843 293.104 204.483C288.821 207.119 284.398 207.234 279.767 204.809C271.327 200.247 262.488 196.712 253.249 194.202C244.004 191.691 234.587 190.436 225 190.436C211.307 190.436 198.069 192.832 185.288 197.625C172.628 202.373 160.865 209.025 150 217.579C139.135 209.025 127.372 202.373 114.712 197.625C101.931 192.832 88.6929 190.436 75 190.436C65.4127 190.436 55.996 191.691 46.751 194.202C37.5123 196.712 28.6726 200.247 20.2324 204.809C15.602 207.234 11.1786 207.119 6.89572 204.483C2.60462 201.843 0.473186 198.018 0.473186 192.955V28.6364C0.473186 26.2192 1.07654 23.9109 2.28961 21.7053C3.48745 19.5274 5.28288 17.8912 7.69581 16.7944ZM258.618 52.8698V73.6378C253.346 71.701 248.021 70.2385 242.642 69.2505C237.044 68.2222 231.163 67.7086 225 67.7086C216.324 67.7086 207.987 68.7932 199.99 70.9638C192.254 73.0634 184.839 75.9657 177.746 79.6705V57.5864C185.125 54.4777 192.669 52.1415 200.378 50.5774C208.186 48.9932 216.393 48.2005 225 48.2005C230.885 48.2005 236.655 48.6531 242.312 49.5582C247.856 50.4452 253.291 51.5492 258.618 52.8698ZM258.618 127.87V148.638C253.346 146.701 248.021 145.238 242.642 144.251C237.044 143.222 231.163 142.709 225 142.709C216.326 142.709 207.991 143.736 199.996 145.792C192.258 147.782 184.841 150.734 177.746 154.649V132.586C185.125 129.478 192.669 127.141 200.378 125.577C208.186 123.993 216.393 123.2 225 123.2C230.885 123.2 236.655 123.653 242.312 124.558C247.856 125.445 253.291 126.549 258.618 127.87ZM258.618 90.3698V111.138C253.346 109.201 248.021 107.738 242.642 106.751C237.044 105.722 231.163 105.209 225 105.209C216.324 105.209 207.987 106.293 199.99 108.464C192.254 110.563 184.839 113.466 177.746 117.17V95.0864C185.125 91.9777 192.669 89.6415 200.378 88.0774C208.186 86.4932 216.393 85.7005 225 85.7005C230.885 85.7005 236.655 86.1531 242.312 87.0582C247.856 87.9452 253.291 89.0491 258.618 90.3698Z" fill="url(#paint0_linear_8307_30944)" stroke="url(#paint1_linear_8307_30944)" stroke-width="0.946372"/>
<defs>
<linearGradient id="paint0_linear_8307_30944" x1="159.08" y1="-21.9018" x2="159.08" y2="218.084" gradientUnits="userSpaceOnUse">
<stop offset="0.015" stop-color="#0C3867"/>
<stop offset="0.25" stop-color="#04284F"/>
<stop offset="1" stop-color="#021428"/>
</linearGradient>
<linearGradient id="paint1_linear_8307_30944" x1="173.756" y1="2.54411" x2="173.756" y2="226.12" gradientUnits="userSpaceOnUse">
<stop stop-color="#428CDC" stop-opacity="0.5"/>
<stop offset="1" stop-color="#428CDC" stop-opacity="0"/>
</linearGradient>
</defs>
</svg>

<svg class="inline dark:hidden" xmlns="http://www.w3.org/2000/svg" width="300" height="219" viewBox="0 0 300 219" fill="none">
<path d="M136.148 178.406L136.864 178.747V177.955V43.6364V43.3497L136.616 43.2049C127.258 37.7272 117.33 33.6187 106.831 30.8798C96.3355 28.1419 85.7249 26.7727 75 26.7727C66.7855 26.7727 58.6282 27.5714 50.5283 29.1685C42.4266 30.766 34.6095 33.1625 27.0775 36.3579L26.7727 36.4872V36.8182V171.818V172.518L27.4349 172.291C35.3659 169.572 43.2381 167.533 51.0516 166.174C58.8634 164.816 66.8461 164.136 75 164.136C85.6442 164.136 96.0034 165.325 106.078 167.703C116.155 170.08 126.178 173.647 136.148 178.406ZM163.136 177.955V178.747L163.852 178.406C173.822 173.647 183.845 170.08 193.922 167.703C203.997 165.325 214.356 164.136 225 164.136C233.154 164.136 241.137 164.816 248.948 166.174C256.762 167.533 264.634 169.572 272.565 172.291L273.227 172.518V171.818V36.8182V36.4872L272.923 36.3579C265.391 33.1625 257.573 30.766 249.472 29.1685C241.372 27.5714 233.214 26.7727 225 26.7727C214.275 26.7727 203.665 28.1419 193.169 30.8798C182.67 33.6187 172.742 37.7272 163.384 43.2049L163.136 43.3497V43.6364V177.955ZM7.7069 16.8188L7.71925 16.8132L7.73128 16.8069C18.1499 11.3711 29.0205 7.29473 40.344 4.5771C51.6689 1.85911 63.2207 0.5 75 0.5C88.1382 0.5 100.992 2.19882 113.563 5.59632C126.132 8.99341 138.193 14.0893 149.746 20.8855L150 21.0346L150.254 20.8855C161.807 14.0893 173.868 8.99341 186.437 5.59632C199.008 2.19882 211.862 0.5 225 0.5C236.779 0.5 248.331 1.85911 259.656 4.5771C270.98 7.29473 281.85 11.3711 292.269 16.8069L292.281 16.8132L292.293 16.8188C294.701 17.9134 296.492 19.5457 297.687 21.7182C298.898 23.92 299.5 26.2238 299.5 28.6364V192.955C299.5 198.009 297.373 201.825 293.09 204.461C288.816 207.091 284.403 207.206 279.78 204.786C271.339 200.223 262.497 196.686 253.256 194.177C244.009 191.665 234.59 190.409 225 190.409C211.304 190.409 198.063 192.806 185.279 197.6C172.623 202.346 160.863 208.995 150 217.545C139.137 208.995 127.377 202.346 114.721 197.6C101.937 192.806 88.6961 190.409 75 190.409C65.4103 190.409 55.9912 191.665 46.7439 194.177C37.5033 196.686 28.6616 200.223 20.2197 204.786C15.5974 207.206 11.1841 207.091 6.90978 204.461C2.62665 201.825 0.5 198.009 0.5 192.955V28.6364C0.5 26.2238 1.10213 23.92 2.31311 21.7182C3.50799 19.5457 5.2989 17.9134 7.7069 16.8188ZM258.591 52.8908V73.5994C253.33 71.6687 248.015 70.2101 242.647 69.2241C237.047 68.1955 231.164 67.6818 225 67.6818C216.322 67.6818 207.982 68.7667 199.983 70.9379C192.26 73.0342 184.856 75.9303 177.773 79.6262V57.6042C185.145 54.4996 192.682 52.1662 200.384 50.6036C208.189 49.0199 216.394 48.2273 225 48.2273C230.883 48.2273 236.652 48.6798 242.307 49.5846C247.844 50.4705 253.272 51.5725 258.591 52.8908ZM258.591 127.891V148.599C253.33 146.669 248.015 145.21 242.647 144.224C237.047 143.195 231.164 142.682 225 142.682C216.324 142.682 207.986 143.709 199.989 145.766C192.263 147.752 184.857 150.699 177.773 154.604V132.604C185.145 129.5 192.682 127.166 200.384 125.604C208.189 124.02 216.394 123.227 225 123.227C230.883 123.227 236.652 123.68 242.307 124.585C247.844 125.47 253.272 126.573 258.591 127.891ZM258.591 90.3908V111.099C253.33 109.169 248.015 107.71 242.647 106.724C237.047 105.695 231.164 105.182 225 105.182C216.322 105.182 207.982 106.267 199.983 108.438C192.26 110.534 184.856 113.43 177.773 117.126V95.1042C185.145 91.9996 192.682 89.6662 200.384 88.1036C208.189 86.5199 216.394 85.7273 225 85.7273C230.883 85.7273 236.652 86.1798 242.307 87.0846C247.844 87.9705 253.272 89.0725 258.591 90.3908Z" fill="url(#paint0_linear_8307_31135)" stroke="url(#paint1_linear_8307_31135)"/>
<defs>
<linearGradient id="paint0_linear_8307_31135" x1="150" y1="0.000174278" x2="150" y2="218.182" gradientUnits="userSpaceOnUse">
<stop offset="0.015" stop-color="#D3E8FF"/>
<stop offset="0.3" stop-color="#EEF6FF"/>
<stop offset="1" stop-color="#F7FBFF"/>
</linearGradient>
<linearGradient id="paint1_linear_8307_31135" x1="152.736" y1="-11.7141" x2="152.736" y2="230.5" gradientUnits="userSpaceOnUse">
<stop stop-color="#428CDC" stop-opacity="0.5"/>
<stop offset="1" stop-color="#428CDC" stop-opacity="0"/>
</linearGradient>
</defs>
</svg>
</div>
</div>

<div id="search-index-app" data-content-type="support"></div>
</div>
Loading