Skip to content

Update USP docs to match change to default keepalive #2160

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

Merged
Morgan-P-04 merged 1 commit into from
Jul 22, 2026
+4 −7
Merged

Update USP docs to match change to default keepalive #2160

Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
11 changes: 4 additions & 7 deletions content/ngf/traffic-management/upstream-settings.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -344,14 +344,12 @@ upstream default_coffee_80 {
random two least_conn;
zone default_coffee_80 1m;
state /var/lib/nginx/state/default_coffee_80.conf;
keepAlive 16;
}

upstream default_tea_80 {
hash $upstream_addr consistent;
zone default_tea_80 1m;
state /var/lib/nginx/state/default_tea_80.conf;
keepAlive 16;
}
```

Expand Down Expand Up @@ -425,22 +423,18 @@ upstream default_coffee_80 {
zone default_coffee_80 1m;

server 10.244.0.14:8080;
keepAlive 16;
}

upstream default_tea_80 {
random two least_conn;
zone default_tea_80 1m;

server 10.244.0.15:8080;
keepAlive 16;
}
```

## Enable keepalive connections

By default, the `keepAlive` directive is enabled with a value of 16. You can override this value or disable `keepAlive` entirely by configuring an `UpstreamSettingsPolicy`. To disable keepalive, set the connections field to 0.

The following example creates an `UpstreamSettingsPolicy` that configures keepalive connections for the `coffee` Service with a value of 32:
Comment on lines -442 to 438

@bjee19 bjee19 Jul 22, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

@Morgan-P-04

Could we adjust this to look something like

By default, the keepAlive directive is enabled with a value of 32. You can override this value or disable keepAlive entirely by configuring an UpstreamSettingsPolicy. To disable keepalive, set the connections field to 0.

The following example creates an UpstreamSettingsPolicy that configures keepalive connections for the coffee Service with a value of 24:

To still tell the user what the default keepAlive is and to show how to set the value to something different?

@bjee19 bjee19 Jul 22, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Or the first line could be

By default, the keepAlive directive is omitted, causing NGINX to default to the keepalive value 32. You can override this value or disable keepAlive entirely by configuring an UpstreamSettingsPolicy. To disable keepalive, set the connections field to 0.

and we can remove the line further down

If keepAlive.connections is omitted, the NGINX default value for the keepalive directive is used. To disable keepalive, set keepAlive.connections to 0.


```yaml
Expand All @@ -461,6 +455,8 @@ EOF

This `UpstreamSettingsPolicy` targets the `coffee` service in the `targetRefs` field. It sets the number of keepalive connections to 32, which activates the cache for connections to the service's pods and sets the maximum number of idle connections to 32.

If `keepAlive.connections` is omitted, the NGINX default value for the `keepalive` directive is used. To disable keepalive, set `keepAlive.connections` to 0.

Verify that the `UpstreamSettingsPolicy` is Accepted:

```shell
Expand Down Expand Up @@ -506,7 +502,7 @@ upstream default_coffee_80 {
}
```

To disable `keepAlive` directive lets create an `UpstreamSettingsPolicy` targeting the `tea` service with value 0:
To disable the `keepalive` directive, lets create an `UpstreamSettingsPolicy` targeting the `tea` service with value 0:

```yaml
kubectl apply -f - <<EOF
Expand Down Expand Up @@ -562,6 +558,7 @@ upstream default_tea_80 {
zone default_tea_80 1m;

server 10.244.0.15:8080;
keepalive 0;
}
```

Expand Down
Loading