From a6ddf25a4cb0c3cf73f4602189031f8d30460663 Mon Sep 17 00:00:00 2001 From: Kemi-Elizabeth <97071326+Kemi-Elizabeth@users.noreply.github.com> Date: Thu, 23 Oct 2025 11:35:35 +0100 Subject: [PATCH 1/4] feat: added sticky routing section added sticky section to docs --- sites/platform/src/define-routes/_index.md | 22 +++++++++++++++++++ sites/upsun/src/define-routes/_index.md | 25 +++++++++++++++++++++- 2 files changed, 46 insertions(+), 1 deletion(-) diff --git a/sites/platform/src/define-routes/_index.md b/sites/platform/src/define-routes/_index.md index 47c5667167..5e660848ab 100644 --- a/sites/platform/src/define-routes/_index.md +++ b/sites/platform/src/define-routes/_index.md @@ -69,6 +69,27 @@ Redirects from `http` to `https` are generally included by default and don't nee The specifics of configuring the Router container for multiple applications is explored in detail in the [Multiple apps](/create-apps/multi-app/routes.md) documentation. +### Sticky routing + +Sticky routing is a method that keeps a client’s requests directed to the same application container, helping maintain connection consistency. You can enable sticky routing in your [route configuration](#route-configuration-reference) to help the router send repeat requests from the same client to the same application container. + +At {{% vendor/name %}}, this behavior is implemented using hashing based on the client’s IP address, so that repeated requests from the same IP are routed to the same container. + +```yaml {configFile="routes"} +routes: + "https://{default}/": + type: upstream + upstream: app:http + sticky: true +``` +This enables sticky routing at the router level. + +{{< note theme="note" title="Note">}} + +Because the routing uses IP hashing, scaling your environment up or down can change the hash distribution, causing requests to be routed to different containers. For production workloads that require persistent sessions, use an external session store (for example, [Redis](/add-services/redis.md)), or design your app to be stateless. + +{{< /note >}} + ## Trailing slashes All defined routes have at least a slash in the path. @@ -400,6 +421,7 @@ You can configure each route separately with the following properties: | ------------ | --------- | ----------------------- | ----------- | | `type` | `string` | Yes | One of the following options: | | `upstream` | `string` | If `type` is `upstream` | The `name` of the app to be served (as defined in your [app configuration](/create-apps/_index.md)) followed by `:http`. Example: `app:http` | +| `sticky` | `boolean` | No | Enables [sticky routing](#sticky-routing) for the route. When `true`, the router attempts to send repeat requests from the same client to the same upstream container, based on a hash of the client’s IP address. | | `to` | `string` | If `type` is `redirect` | The absolute URL or other route to which the given route should be redirected with an HTTP 301 status code. | | `ssi` | `boolean` | No | Whether [server side includes](/define-routes/ssi.md) are enabled. | | `redirects` | Object | No | Defines redirects for partial routes. For definition and options, see the [redirect rules](/define-routes/redirects.md). | diff --git a/sites/upsun/src/define-routes/_index.md b/sites/upsun/src/define-routes/_index.md index 984758eeba..754da8a88c 100644 --- a/sites/upsun/src/define-routes/_index.md +++ b/sites/upsun/src/define-routes/_index.md @@ -68,6 +68,27 @@ Redirects from `http` to `https` are generally included by default and don't nee The specifics of configuring the Router container for multiple applications is explored in detail in the [Multiple apps](/create-apps/multi-app/routes.md) documentation. +### Sticky routing + +Sticky routing is a method that keeps a client’s requests directed to the same application container, helping maintain connection consistency. You can enable sticky routing in your [route configuration](#route-configuration-reference) to help the router send repeat requests from the same client to the same application container. + +At {{% vendor/name %}}, this behavior is implemented using hashing based on the client’s IP address, so that repeated requests from the same IP are routed to the same container. + +```yaml {configFile="routes"} +routes: + "https://{default}/": + type: upstream + upstream: app:http + sticky: true +``` +This enables sticky routing at the router level. + +{{< note theme="note" title="Note">}} + +Because the routing uses IP hashing, scaling your environment up or down can change the hash distribution, causing requests to be routed to different containers. For production workloads that require persistent sessions, use an external session store (for example, [Redis](/add-services/redis.md)), or design your app to be stateless. + +{{< /note >}} + ## Trailing slashes All defined routes have at least a slash in the path. @@ -358,9 +379,10 @@ Non-default ports (other than `80` and `443`) aren't supported and can't be incl You can configure each route separately with the following properties: | Name | Type | Required | Description | -| ------------ | --------- | ----------------------- | ----------- | +| ------------- | --------- | ----------------------- | ----------- | | `type` | `string` | Yes | One of the following options: | | `upstream` | `string` | If `type` is `upstream` | The `name` of the app to be served (as defined in your [app configuration](/create-apps/_index.md)) followed by `:http`. Example: `app:http` | +| `sticky` | `boolean` | No | Enables [sticky routing](#sticky-routing) for the route. When `true`, the router attempts to send repeat requests from the same client to the same upstream container, based on a hash of the client’s IP address. | | `to` | `string` | If `type` is `redirect` | The absolute URL or other route to which the given route should be redirected with an HTTP 301 status code. | | `ssi` | `boolean` | No | Whether [server side includes](/define-routes/ssi.md) are enabled. | | `redirects` | Object | No | Defines redirects for partial routes. For definition and options, see the [redirect rules](/define-routes/redirects.md). | @@ -370,6 +392,7 @@ You can configure each route separately with the following properties: | `tls` | Object | No | TLS configuration. See [HTTPS](/define-routes/https.md#optional-configure-tls-connections). | | `attributes` | Object | No | Any key-value pairs you want to make available to your app. See [route attributes](#route-attributes). | + ## CLI access The [{{% vendor/name %}} CLI](../administration/cli/_index.md) can show you the routes you have configured for an environment. From 34f1dca081c2f18cb6fb9228cb450d147801372a Mon Sep 17 00:00:00 2001 From: Kemi-Elizabeth <97071326+Kemi-Elizabeth@users.noreply.github.com> Date: Thu, 23 Oct 2025 11:39:06 +0100 Subject: [PATCH 2/4] feat: adjusted paragraph added sticky routing paragraph --- sites/platform/src/define-routes/_index.md | 4 ++-- sites/upsun/src/define-routes/_index.md | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/sites/platform/src/define-routes/_index.md b/sites/platform/src/define-routes/_index.md index 5e660848ab..6e294ca695 100644 --- a/sites/platform/src/define-routes/_index.md +++ b/sites/platform/src/define-routes/_index.md @@ -71,9 +71,9 @@ The specifics of configuring the Router container for multiple applications is e ### Sticky routing -Sticky routing is a method that keeps a client’s requests directed to the same application container, helping maintain connection consistency. You can enable sticky routing in your [route configuration](#route-configuration-reference) to help the router send repeat requests from the same client to the same application container. +Sticky routing is a method that directs a client’s requests to the same application container, helping maintain request consistency. You can enable it in your [route configuration](#route-configuration-reference) to have the router attempt to send repeated requests from the same client to the same backend. -At {{% vendor/name %}}, this behavior is implemented using hashing based on the client’s IP address, so that repeated requests from the same IP are routed to the same container. +At {{% vendor/name %}}, sticky routing is implemented using a hash of the client’s IP address. This ensures requests from the same IP are generally routed to the same container. ```yaml {configFile="routes"} routes: diff --git a/sites/upsun/src/define-routes/_index.md b/sites/upsun/src/define-routes/_index.md index 754da8a88c..2acc775938 100644 --- a/sites/upsun/src/define-routes/_index.md +++ b/sites/upsun/src/define-routes/_index.md @@ -70,9 +70,9 @@ The specifics of configuring the Router container for multiple applications is e ### Sticky routing -Sticky routing is a method that keeps a client’s requests directed to the same application container, helping maintain connection consistency. You can enable sticky routing in your [route configuration](#route-configuration-reference) to help the router send repeat requests from the same client to the same application container. +Sticky routing is a method that directs a client’s requests to the same application container, helping maintain request consistency. You can enable it in your [route configuration](#route-configuration-reference) to have the router attempt to send repeated requests from the same client to the same backend. -At {{% vendor/name %}}, this behavior is implemented using hashing based on the client’s IP address, so that repeated requests from the same IP are routed to the same container. +At {{% vendor/name %}}, sticky routing is implemented using a hash of the client’s IP address. This ensures requests from the same IP are generally routed to the same container. ```yaml {configFile="routes"} routes: From b3171eef876aa8cd93304a23034c9c1330182d19 Mon Sep 17 00:00:00 2001 From: Kemi Elizabeth <97071326+Kemi-Elizabeth@users.noreply.github.com> Date: Tue, 28 Oct 2025 12:30:14 +0000 Subject: [PATCH 3/4] Apply suggestion from @Kemi-Elizabeth --- sites/platform/src/define-routes/_index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sites/platform/src/define-routes/_index.md b/sites/platform/src/define-routes/_index.md index 6e294ca695..62372f8b40 100644 --- a/sites/platform/src/define-routes/_index.md +++ b/sites/platform/src/define-routes/_index.md @@ -71,7 +71,7 @@ The specifics of configuring the Router container for multiple applications is e ### Sticky routing -Sticky routing is a method that directs a client’s requests to the same application container, helping maintain request consistency. You can enable it in your [route configuration](#route-configuration-reference) to have the router attempt to send repeated requests from the same client to the same backend. +Sticky routing ensures that all requests from a specific client are consistently routed to the same instance of your application. This can be critical for stateful applications that rely on local session data, preventing user context from being lost in a horizontally scaled environment. You can enable it in your [route configuration](#route-configuration-reference) to have the router attempt to send repeated requests from the same client to the same instance. At {{% vendor/name %}}, sticky routing is implemented using a hash of the client’s IP address. This ensures requests from the same IP are generally routed to the same container. From cd331efdbc4e6ee69901a3d283f944cbfee96ba9 Mon Sep 17 00:00:00 2001 From: Kemi Elizabeth <97071326+Kemi-Elizabeth@users.noreply.github.com> Date: Tue, 28 Oct 2025 12:30:39 +0000 Subject: [PATCH 4/4] Apply suggestion from @Kemi-Elizabeth --- sites/upsun/src/define-routes/_index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sites/upsun/src/define-routes/_index.md b/sites/upsun/src/define-routes/_index.md index 2acc775938..5827d73aec 100644 --- a/sites/upsun/src/define-routes/_index.md +++ b/sites/upsun/src/define-routes/_index.md @@ -70,7 +70,7 @@ The specifics of configuring the Router container for multiple applications is e ### Sticky routing -Sticky routing is a method that directs a client’s requests to the same application container, helping maintain request consistency. You can enable it in your [route configuration](#route-configuration-reference) to have the router attempt to send repeated requests from the same client to the same backend. +Sticky routing ensures that all requests from a specific client are consistently routed to the same instance of your application. This can be critical for stateful applications that rely on local session data, preventing user context from being lost in a horizontally scaled environment. You can enable it in your [route configuration](#route-configuration-reference) to have the router attempt to send repeated requests from the same client to the same instance. At {{% vendor/name %}}, sticky routing is implemented using a hash of the client’s IP address. This ensures requests from the same IP are generally routed to the same container.