Docs/ce 470 locality aware #19071

trujillo-adam · 2023-10-05T05:12:50Z

Description

This PR applies the following updates:

new params on configuration references pages for enabling locality-aware routing
Adds a usage page for routing to local upstreams
Updates related overview page,
Updates the navigation around traffic management

This PR also includes documentation updates for service-to-service rate limiting.

Links

Google doc draft

Jira tickets:

PR Checklist

external facing docs updated
appropriate backport labels added
not a security concern

…sul into docs/CE-470-locality-aware Merginge remote into local

website/content/docs/connect/config-entries/service-defaults.mdx

website/content/docs/connect/manage-traffic/limit-request-rates.mdx

kisunji

Added some minor comments and fixes. Thank you for this work!

Co-authored-by: Chris S. Kim <ckim@hashicorp.com>

boruszak

Great work here - I think most of my comments are simple style guide alignments and corrections that you can accept suggestions for.

Big callout - You changed the l7-traffic path to manage-traffic but there aren't any redirects in this PR. Create a folder-level redirect before merging this PR.

Approving on behalf of consul-docs so that you're not blocked. Let me know if you need anything else!

website/content/docs/agent/config/config-files.mdx

website/content/docs/connect/config-entries/service-defaults.mdx

website/content/docs/connect/manage-traffic/limit-request-rates.mdx

website/content/docs/connect/manage-traffic/route-to-local-upstreams.mdx

kisunji

Still a few floating comments from me but pre-approving from eng side for rate limiting

Co-authored-by: Jeff Boruszak <104028618+boruszak@users.noreply.github.com> Co-authored-by: Chris S. Kim <ckim@hashicorp.com>

erichaberkorn · 2023-10-06T19:41:37Z

website/data/docs-nav-data.json

+                  {
+                    "title": "Service intentions",
+                    "href": "/consul/docs/connect/config-entries/service-intentions"
+                  }


I know this didn't change from before, but do you know why intentions under failover?

erichaberkorn · 2023-10-06T19:48:55Z

website/content/docs/connect/config-entries/service-defaults.mdx

+
+### `RateLimits{}.InstanceLevel{}.RequestsPerScond`
+
+Specifies the average number of requests per second allowed to the service. Consul allows requests to the service when the average number of requests per second exceeds this value, but it temporarily lowers the speed of the transactions. You may also specify the [`RequestsMaxBurst`](#ratelimits-instancelevel-requestsmaxburst) parameter. The number of requests per second to the service can exceed the limit specified in the `RequestsPerSecond` parameter, but not the `RequestsMaxBurst` parameter. 


I don't believe this "temporarily lowers the speed of the transactions". From my understanding, it proceeds as normal until the bucket is exhausted.

erichaberkorn · 2023-10-06T19:54:49Z

website/content/docs/connect/manage-traffic/route-to-local-upstreams.mdx

+1. Enable service mesh proxies to route traffic locally within the partition.
+1. Start service mesh proxies.
+
+For Kubernetes-orchestrated networks, Consul automatically populates geographic information about service instances using the `topology.kubernetes.io/region` and `topology.kubernetes.io/zone` annotations from the Kubernetes nodes. As a result, you do not need to specify the regions and zones unless you are implementing a custom Kuberenetes deployment.


We do something similar on the upcoming version of consul-ecs too.

erichaberkorn · 2023-10-06T19:57:09Z

website/content/docs/connect/manage-traffic/route-to-local-upstreams.mdx

+}
+```
+
+## Specify the localities of your service instances


We only support running consul-dataplane on consul-k8s and consul-ecs. I think it might be safe to remove this section.

erichaberkorn · 2023-10-06T19:59:20Z

website/content/docs/connect/manage-traffic/route-to-local-upstreams.mdx

+### Configure routing behavior for individual service
+
+1. Create a service resolver configuration entry and specify the following fields:
+   - `Name`: Specify the name of the service that the routing behavior defined in the configuration entry applies to.


I believe this does the opposite. This is the name of the service that is opting into locality aware routing. This causes downstream services to use locality aware routing when calling this service.

erichaberkorn · 2023-10-06T20:08:33Z

website/content/docs/connect/manage-traffic/route-to-local-upstreams.mdx

+
+For details about operating an Envoy proxy in Consul, refer to the [Envoy proxy reference](/consul/docs/connect/proxies/envoy). 
+
+Use the `/agent/service/register` API endpoint to register sidecars independently from their application services. You must include the `locality` configuration in the payload. Refer to [Register Service](/consul/api-docs/agent/service#register-service) in the API documentation for additional information.


What is this referring to?

zalimeni · 2023-10-10T15:46:31Z

website/content/docs/connect/manage-traffic/route-to-local-upstreams.mdx

+By default, Consul balances traffic to all healthy upstream instances in the cluster, even if the instances are in different network zones. You can specify the cloud service provider (CSP) locale for Consul server agents and services registered to the service mesh, which enables several benefits:
+
+- Consul prioritizes the nearest upstream when routing traffic through the mesh. 
+- When a service instance in the same partition becomes unhealthy, Consul prioritizes failing over to upstream services that are in the same region as the downstream service. Refer to [Failover](/consul/docs/connect/traffic-management/failover) for additional information about failover strategies in Consul.


Suggested change

- When a service instance in the same partition becomes unhealthy, Consul prioritizes failing over to upstream services that are in the same region as the downstream service. Refer to [Failover](/consul/docs/connect/traffic-management/failover) for additional information about failover strategies in Consul.

- When upstream service instances become unhealthy, Consul prioritizes failing over to instances that are in the same region as the downstream service. Refer to [Failover](/consul/docs/connect/traffic-management/failover) for additional information about failover strategies in Consul.

I think it might be clearer to refer to these in plural since currently, we don't support partial failover, and in general, any future change to support that would be in terms of a ratio, not individual instances.

zalimeni · 2023-10-10T15:51:55Z

website/content/docs/connect/manage-traffic/route-to-local-upstreams.mdx

+
+1. Specify the region and zone for your Consul client agents. 
+1. It is not required, but you can specify the region and zone for your services. Skip this step to allow services to inherit the region and zone configured for the Consul client that the services are registered with. 
+1. Enable service mesh proxies to route traffic locally within the partition.


Suggested change

1. Enable service mesh proxies to route traffic locally within the partition.

1. Configure service mesh proxies to route traffic locally within the partition based on locality configuration.

zalimeni · 2023-10-10T15:52:48Z

website/content/docs/connect/manage-traffic/route-to-local-upstreams.mdx

+1. Enable service mesh proxies to route traffic locally within the partition.
+1. Start service mesh proxies.
+
+For Kubernetes-orchestrated networks, Consul automatically populates geographic information about service instances using the `topology.kubernetes.io/region` and `topology.kubernetes.io/zone` annotations from the Kubernetes nodes. As a result, you do not need to specify the regions and zones unless you are implementing a custom Kuberenetes deployment.


Suggested change

For Kubernetes-orchestrated networks, Consul automatically populates geographic information about service instances using the `topology.kubernetes.io/region` and `topology.kubernetes.io/zone` annotations from the Kubernetes nodes. As a result, you do not need to specify the regions and zones unless you are implementing a custom Kuberenetes deployment.

For Kubernetes-orchestrated networks, Consul automatically populates geographic information about service instances using the `topology.kubernetes.io/region` and `topology.kubernetes.io/zone` annotations from the Kubernetes nodes. As a result, you do not need to specify the regions and zones unless you are implementing a custom Kubernetes deployment.

In addition to Eric's comment, small typo here.

zalimeni · 2023-10-10T17:47:13Z

website/content/docs/connect/manage-traffic/route-to-local-upstreams.mdx

+
+## Start the proxies in your datacenter
+
+Envoy requires a bootstrap configuration file before it can start. Use the [`consul connect envoy` command](/consul/commands/connect/envoy) to create the Envoy bootstrap configuration and start the sidecar proxy service. Specify the ID of the sidecar proxy you want to start with the `-sidecar-for` option.  


Suggested change

Envoy requires a bootstrap configuration file before it can start. Use the [`consul connect envoy` command](/consul/commands/connect/envoy) to create the Envoy bootstrap configuration and start the sidecar proxy service. Specify the ID of the sidecar proxy you want to start with the `-sidecar-for` option.

Envoy requires a bootstrap configuration file before it can start. Use the [`consul connect envoy` command](/consul/commands/connect/envoy) to create the Envoy bootstrap configuration and start the sidecar proxy service. Specify the ID of service you want to start a proxy for using the `-sidecar-for` option.

zalimeni · 2023-10-10T17:48:07Z

website/content/docs/connect/manage-traffic/route-to-local-upstreams.mdx

+
+Envoy requires a bootstrap configuration file before it can start. Use the [`consul connect envoy` command](/consul/commands/connect/envoy) to create the Envoy bootstrap configuration and start the sidecar proxy service. Specify the ID of the sidecar proxy you want to start with the `-sidecar-for` option.  
+
+The following example command starts an Envoy proxy for the `web` proxy service:


Suggested change

The following example command starts an Envoy proxy for the `web` proxy service:

The following example command starts an Envoy proxy for the `web` service:

zalimeni · 2023-10-10T22:46:46Z

website/content/docs/connect/manage-traffic/route-to-local-upstreams.mdx

+   $ consul config write web-resolver.hcl
+   ```
+
+## Start the proxies in your datacenter


Given the advice to set client locality above (or defer to K8s/ECS), similar to @erichaberkorn 's comment above, I'm not certain we really need this section, since how to start and manage proxies is already documented in other pages, and assumed for a mesh deployment.

* updated nav; renamed L7 traffic folder * Added locality-aware routing to traffic mgmt overview * Added route to local upstreams topic * Updated agent configuration reference * Added locality param to services conf ref * Added locality param to conf entries * mentioned traffic management in proxies overview * added locality-aware to failover overview * added docs for service rate limiting * updated service defaults conf entry * Apply suggestions from code review Co-authored-by: Chris S. Kim <ckim@hashicorp.com> * Apply suggestions from code review Co-authored-by: Jeff Boruszak <104028618+boruszak@users.noreply.github.com> Co-authored-by: Chris S. Kim <ckim@hashicorp.com> * updated links and added redirects --------- Co-authored-by: Chris S. Kim <ckim@hashicorp.com> Co-authored-by: Jeff Boruszak <104028618+boruszak@users.noreply.github.com>

trujillo-adam added 8 commits October 4, 2023 19:48

updated nav; renamed L7 traffic folder

79f2105

Added locality-aware routing to traffic mgmt overview

e209e82

Added route to local upstreams topic

e860219

Updated agent configuration reference

8ad81f9

Added locality param to services conf ref

6a98edc

Added locality param to conf entries

13e12ce

mentioned traffic management in proxies overview

56f60ae

added locality-aware to failover overview

db46295

trujillo-adam added type/docs Documentation needs to be created/updated/clarified pr/no-changelog PR does not need a corresponding .changelog entry pr/no-metrics-test pr/no-backport labels Oct 5, 2023

Merge branch 'main' into docs/CE-470-locality-aware

58c8cc3

vercel bot deployed to Preview – consul October 5, 2023 14:43 View deployment

Merge branch 'main' into docs/CE-470-locality-aware

60c99f3

trujillo-adam marked this pull request as ready for review October 5, 2023 21:16

trujillo-adam requested a review from a team as a code owner October 5, 2023 21:16

trujillo-adam marked this pull request as draft October 5, 2023 21:18

vercel bot deployed to Preview – consul October 5, 2023 21:19 View deployment

trujillo-adam added 2 commits October 5, 2023 14:42

added docs for service rate limiting

c2aedfa

Merge branch 'docs/CE-470-locality-aware' of github.com:hashicorp/con…

295da17

…sul into docs/CE-470-locality-aware Merginge remote into local

vercel bot deployed to Preview – consul October 5, 2023 21:49 View deployment

updated service defaults conf entry

b2b858a

vercel bot deployed to Preview – consul October 5, 2023 22:48 View deployment

Merge branch 'main' into docs/CE-470-locality-aware

3fac825

trujillo-adam marked this pull request as ready for review October 5, 2023 22:50

kisunji reviewed Oct 6, 2023

View reviewed changes

website/content/docs/connect/config-entries/service-defaults.mdx Outdated Show resolved Hide resolved

kisunji reviewed Oct 6, 2023

View reviewed changes

website/content/docs/connect/config-entries/service-defaults.mdx Outdated Show resolved Hide resolved

kisunji reviewed Oct 6, 2023

View reviewed changes

website/content/docs/connect/config-entries/service-defaults.mdx Outdated Show resolved Hide resolved

kisunji reviewed Oct 6, 2023

View reviewed changes

website/content/docs/connect/manage-traffic/limit-request-rates.mdx Outdated Show resolved Hide resolved

kisunji reviewed Oct 6, 2023

View reviewed changes

website/content/docs/connect/manage-traffic/limit-request-rates.mdx Outdated Show resolved Hide resolved

kisunji reviewed Oct 6, 2023

View reviewed changes

website/content/docs/connect/manage-traffic/limit-request-rates.mdx Outdated Show resolved Hide resolved

kisunji reviewed Oct 6, 2023

View reviewed changes

website/content/docs/connect/manage-traffic/limit-request-rates.mdx Outdated Show resolved Hide resolved

kisunji reviewed Oct 6, 2023

View reviewed changes

website/content/docs/connect/manage-traffic/limit-request-rates.mdx Outdated Show resolved Hide resolved

kisunji reviewed Oct 6, 2023

View reviewed changes

Apply suggestions from code review

da2e373

Co-authored-by: Chris S. Kim <ckim@hashicorp.com>

vercel bot deployed to Preview – consul October 6, 2023 15:38 View deployment

Merge branch 'main' into docs/CE-470-locality-aware

bb10b19

trujillo-adam requested a review from kisunji October 6, 2023 17:58

Merge branch 'main' into docs/CE-470-locality-aware

db89103

boruszak approved these changes Oct 6, 2023

View reviewed changes

kisunji approved these changes Oct 6, 2023

View reviewed changes

Apply suggestions from code review

3db1687

Co-authored-by: Jeff Boruszak <104028618+boruszak@users.noreply.github.com> Co-authored-by: Chris S. Kim <ckim@hashicorp.com>

vercel bot deployed to Preview – consul October 6, 2023 19:18 View deployment

trujillo-adam and others added 2 commits October 6, 2023 12:32

updated links and added redirects

3ce76eb

Merge branch 'main' into docs/CE-470-locality-aware

97c1619

vercel bot deployed to Preview – consul October 6, 2023 19:41 View deployment

trujillo-adam merged commit a9747dc into main Oct 6, 2023
48 checks passed

trujillo-adam deleted the docs/CE-470-locality-aware branch October 6, 2023 19:48

erichaberkorn reviewed Oct 6, 2023

View reviewed changes

zalimeni reviewed Oct 10, 2023

View reviewed changes

zalimeni mentioned this pull request Nov 6, 2023

[NET-5916] Update locality-aware routing docs #19529

Merged

4 tasks

hc-github-team-consul-core mentioned this pull request Nov 6, 2023

Backport of [NET-5916] Update locality-aware routing docs into release/1.17.x #19532

Merged

4 tasks

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Docs/ce 470 locality aware #19071

Docs/ce 470 locality aware #19071

trujillo-adam commented Oct 5, 2023 •

edited by jira bot

Loading

kisunji left a comment

boruszak left a comment

kisunji left a comment

erichaberkorn Oct 6, 2023

erichaberkorn Oct 6, 2023

erichaberkorn Oct 6, 2023

erichaberkorn Oct 6, 2023

erichaberkorn Oct 6, 2023

erichaberkorn Oct 6, 2023

zalimeni Oct 10, 2023

zalimeni Oct 10, 2023

zalimeni Oct 10, 2023

zalimeni Oct 10, 2023

zalimeni Oct 10, 2023

zalimeni Oct 10, 2023


		### `RateLimits{}.InstanceLevel{}.RequestsPerScond`

		Specifies the average number of requests per second allowed to the service. Consul allows requests to the service when the average number of requests per second exceeds this value, but it temporarily lowers the speed of the transactions. You may also specify the [`RequestsMaxBurst`](#ratelimits-instancelevel-requestsmaxburst) parameter. The number of requests per second to the service can exceed the limit specified in the `RequestsPerSecond` parameter, but not the `RequestsMaxBurst` parameter.


		For details about operating an Envoy proxy in Consul, refer to the [Envoy proxy reference](/consul/docs/connect/proxies/envoy).

		Use the `/agent/service/register` API endpoint to register sidecars independently from their application services. You must include the `locality` configuration in the payload. Refer to [Register Service](/consul/api-docs/agent/service#register-service) in the API documentation for additional information.

	- When a service instance in the same partition becomes unhealthy, Consul prioritizes failing over to upstream services that are in the same region as the downstream service. Refer to [Failover](/consul/docs/connect/traffic-management/failover) for additional information about failover strategies in Consul.
	- When upstream service instances become unhealthy, Consul prioritizes failing over to instances that are in the same region as the downstream service. Refer to [Failover](/consul/docs/connect/traffic-management/failover) for additional information about failover strategies in Consul.

	1. Enable service mesh proxies to route traffic locally within the partition.
	1. Configure service mesh proxies to route traffic locally within the partition based on locality configuration.

	For Kubernetes-orchestrated networks, Consul automatically populates geographic information about service instances using the `topology.kubernetes.io/region` and `topology.kubernetes.io/zone` annotations from the Kubernetes nodes. As a result, you do not need to specify the regions and zones unless you are implementing a custom Kuberenetes deployment.
	For Kubernetes-orchestrated networks, Consul automatically populates geographic information about service instances using the `topology.kubernetes.io/region` and `topology.kubernetes.io/zone` annotations from the Kubernetes nodes. As a result, you do not need to specify the regions and zones unless you are implementing a custom Kubernetes deployment.


		## Start the proxies in your datacenter

		Envoy requires a bootstrap configuration file before it can start. Use the [`consul connect envoy` command](/consul/commands/connect/envoy) to create the Envoy bootstrap configuration and start the sidecar proxy service. Specify the ID of the sidecar proxy you want to start with the `-sidecar-for` option.


		Envoy requires a bootstrap configuration file before it can start. Use the [`consul connect envoy` command](/consul/commands/connect/envoy) to create the Envoy bootstrap configuration and start the sidecar proxy service. Specify the ID of the sidecar proxy you want to start with the `-sidecar-for` option.

		The following example command starts an Envoy proxy for the `web` proxy service:

Docs/ce 470 locality aware #19071

Docs/ce 470 locality aware #19071

Conversation

trujillo-adam commented Oct 5, 2023 • edited by jira bot Loading

Description

Links

PR Checklist

kisunji left a comment

Choose a reason for hiding this comment

boruszak left a comment

Choose a reason for hiding this comment

kisunji left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

trujillo-adam commented Oct 5, 2023 •

edited by jira bot

Loading