Docs/ce 470 locality aware #19071
Merged
Docs/ce 470 locality aware #19071
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
trujillo-adam
added
type/docs
…sul into docs/CE-470-locality-aware Merginge remote into local
kisunji
reviewed
Oct 6, 2023
website/content/docs/connect/config-entries/service-defaults.mdx
Outdated
Show resolved
Hide resolved
kisunji
reviewed
Oct 6, 2023
website/content/docs/connect/config-entries/service-defaults.mdx
Outdated
Show resolved
Hide resolved
kisunji
reviewed
Oct 6, 2023
website/content/docs/connect/config-entries/service-defaults.mdx
Outdated
Show resolved
Hide resolved
kisunji
reviewed
Oct 6, 2023
website/content/docs/connect/manage-traffic/limit-request-rates.mdx
Outdated
Show resolved
Hide resolved
kisunji
reviewed
Oct 6, 2023
website/content/docs/connect/manage-traffic/limit-request-rates.mdx
Outdated
Show resolved
Hide resolved
kisunji
reviewed
Oct 6, 2023
website/content/docs/connect/manage-traffic/limit-request-rates.mdx
Outdated
Show resolved
Hide resolved
kisunji
reviewed
Oct 6, 2023
website/content/docs/connect/manage-traffic/limit-request-rates.mdx
Outdated
Show resolved
Hide resolved
kisunji
reviewed
Oct 6, 2023
website/content/docs/connect/manage-traffic/limit-request-rates.mdx
Outdated
Show resolved
Hide resolved
kisunji
reviewed
Oct 6, 2023
Co-authored-by: Chris S. Kim <[email protected]>
boruszak
approved these changes
Oct 6, 2023
There was a problem hiding this comment.
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/connect/config-entries/service-defaults.mdx
Outdated
Show resolved
Hide resolved
website/content/docs/connect/config-entries/service-defaults.mdx
Outdated
Show resolved
Hide resolved
website/content/docs/connect/config-entries/service-defaults.mdx
Outdated
Show resolved
Hide resolved
website/content/docs/connect/config-entries/service-defaults.mdx
Outdated
Show resolved
Hide resolved
website/content/docs/connect/manage-traffic/limit-request-rates.mdx
Outdated
Show resolved
Hide resolved
website/content/docs/connect/manage-traffic/limit-request-rates.mdx
Outdated
Show resolved
Hide resolved
website/content/docs/connect/manage-traffic/route-to-local-upstreams.mdx
Outdated
Show resolved
Hide resolved
website/content/docs/connect/manage-traffic/route-to-local-upstreams.mdx
Outdated
Show resolved
Hide resolved
website/content/docs/connect/manage-traffic/route-to-local-upstreams.mdx
Outdated
Show resolved
Hide resolved
kisunji
approved these changes
Oct 6, 2023
Co-authored-by: Jeff Boruszak <[email protected]> Co-authored-by: Chris S. Kim <[email protected]>
Comment on lines
+660
to
+663
| { | ||
| "title": "Service intentions", | ||
| "href": "/consul/docs/connect/config-entries/service-intentions" | ||
| } |
There was a problem hiding this comment.
I know this didn't change from before, but do you know why intentions under failover?
|
|
||
| ### `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. |
There was a problem hiding this comment.
I don't believe this "temporarily lowers the speed of the transactions". From my understanding, it proceeds as normal until the bucket is exhausted.
| 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. |
There was a problem hiding this comment.
We do something similar on the upcoming version of consul-ecs too.
| } | ||
| ``` | ||
|
|
||
| ## Specify the localities of your service instances |
There was a problem hiding this comment.
We only support running consul-dataplane on consul-k8s and consul-ecs. I think it might be safe to remove this section.
| ### 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. |
There was a problem hiding this comment.
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.
|
|
||
| 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. |
There was a problem hiding this comment.
What is this referring to?
zalimeni
reviewed
Oct 10, 2023
| 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. |
There was a problem hiding this comment.
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.
|
|
||
| 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. |
There was a problem hiding this comment.
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. |
| 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. |
There was a problem hiding this comment.
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.
|
|
||
| ## 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. |
There was a problem hiding this comment.
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. |
|
|
||
| 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: |
There was a problem hiding this comment.
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: |
| $ consul config write web-resolver.hcl | ||
| ``` | ||
|
|
||
| ## Start the proxies in your datacenter |
There was a problem hiding this comment.
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.
jmurret
pushed a commit
that referenced
this pull request
Oct 12, 2023
* 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 <[email protected]> * Apply suggestions from code review Co-authored-by: Jeff Boruszak <[email protected]> Co-authored-by: Chris S. Kim <[email protected]> * updated links and added redirects --------- Co-authored-by: Chris S. Kim <[email protected]> Co-authored-by: Jeff Boruszak <[email protected]>
4 tasks
4 tasks
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Description
This PR applies the following updates:
This PR also includes documentation updates for service-to-service rate limiting.
Links
Google doc draft
Jira tickets:
PR Checklist