Docs: locality-aware routing

microbus-io · Aug 15, 2024 · 362c629 · 362c629
1 parent 2817a0d
commit 362c629
Show file tree

Hide file tree

Showing 8 changed files with 30 additions and 14 deletions.
diff --git a/README.md b/README.md
@@ -51,7 +51,7 @@ Build your microservices on top of a `Connector` construct and use its simple AP
 * [Load balancing](./docs/blocks/lb.md)
 * [Time budget](./docs/blocks/time-budget.md)
 * [Ack or fail fast](./docs/blocks/ack-or-fail.md)
-* Locality-aware routing
+* [Locality-aware routing](./docs/blocks/locality-aware-routing.md)
 * Connectivity liveness check
 
 #### Precision Observability
@@ -139,6 +139,7 @@ Dig deeper into the technology of `Microbus` and its philosophy.
 * [Multiplexed connections](./docs/blocks/multiplexed.md) - Multiplexed connections are more efficient than HTTP/1.1
 * [Load balancing](./docs/blocks/lb.md) - Load balancing requests among all replicas of a microservice
 * [Internationalization](./docs/blocks/i18n.md) - Loading and localizing strings from `strings.yaml`
+* [Locality-aware routing](./docs/blocks/locality-aware-routing.md) - Optimizing service-to-service communication
 
 ### Design Choices
 

diff --git a/connector/connector.go b/connector/connector.go
@@ -279,8 +279,9 @@ func (c *Connector) SetPlane(plane string) error {
 
 // SetLocality sets the geographic locality of the microservice which is used to optimize routing.
 // Localities are hierarchical with the more specific identifiers first, separated by dots.
-// It can be set to correlate to AWS regions such as az1.dc2.west.us, or arbitrarily to rome.italy.europe for example.
+// It can be set to correlate to AWS regions such as "1.b.west.us", or arbitrarily to "rome.italy.europe" for example.
 // Localities are case-insensitive. Each segment of the hostname may contain letters, numbers, hyphens or underscores only.
+// The special values "AWS" or "GCP" can be set to determine the locality automatically from the cloud provider's meta-data servers.
 func (c *Connector) SetLocality(locality string) error {
  if c.IsStarted() {
  return c.captureInitErr(errors.New("already started"))

diff --git a/docs/blocks/layers.md b/docs/blocks/layers.md
@@ -106,7 +106,7 @@ A microservices transparently makes itself [discoverable](./docs/blocks/discover
 
 [Load balancing](../blocks/lb.md) is handled transparently by the messaging bus. Multiple microservices that subscribe to the same queue are delivered messages randomly. An external load balancer is not required.
 
-With __locality-aware routing__ unicast requests are routed to the replica of the destination whose locality is nearest to the caller's locality. Locality is typically configured by means of an [environment variable](../tech/envars.md).
+With [locality-aware routing](../blocks/locality-aware-routing.md) unicast requests are routed to the replica of the downstream microservice whose locality is nearest to the upstream's locality.
 
 A microservice is __alive__ when it is connected to the messaging bus and can send and receive messages. The bus validates the connection using regular pings. Explicit liveness checks are unnecessary. 
 

diff --git a/docs/blocks/locality-aware-routing-1.drawio.svg b/docs/blocks/locality-aware-routing-1.drawio.svg
diff --git a/docs/blocks/locality-aware-routing.md b/docs/blocks/locality-aware-routing.md
@@ -0,0 +1,18 @@
+# Locality-Aware Routing
+
+A geographic locality, when provided, is used by `Microbus` to optimize routing of [unicast](../blocks/unicast.md) communications. A microservice making a unicast request will prioritize microservices that most resemble its own locality. For example, if the upstream microservice is located in `1.b.west.us` and replicas of the downstream microservice are located in both `2.b.west.us` and `1.a.east.us`, the request will be directed to the former because they share the longer common suffix `b.west.us`.
+
+Locality-aware routing works when both upstream and downstream microservices designate a locality, by means of the `MICROBUS_LOCALITY` environment variable or the `SetLocality` method of the `Connector`. The locality is a hierarchical pattern similar to that of a standard hostname, with the most specific location first.
+
+The special value `AWS` can be used when deployed on AWS to determine the availability zone automatically by making a request to the meta-data service at `http://169.254.169.254/latest/meta-data/placement/availability-zone`. The availability zone will then be used as the basis for the locality of the microservice. For example, availability zone `us-east-1b` is transformed to locality `b.1.east.us`.
+
+Similarly, the special value `GCP` can be used when deployed on GCP to determine the availability zone from `http://metadata.google.internal/computeMetadata/v1/instance/zone`. For example, availability zone `us-east1-b` is transformed to locality `b.1.east.us`
+
+Caution: When designating either `AWS` or `GCP`, the microservice will fail to start if the availability zone cannot be determined.
+
+Using the availability zone as the basis of the locality, for example `1.b.west.us`, keeps traffic in the same availability zone, in the same data center, or in the same region, whichever is nearest. This is often the best strategy but it ultimately depends on the geographic distribution of the microservices.
+
+<img src="locality-aware-routing-1.drawio.svg">
+<p></p>
+
+Using the machine identifier in the locality, for example `a6506f32.1.b.west.us`or even just `a6506f32`, is a more aggressive strategy that keeps traffic within the same machine when possible. This strategy reduces service-to-service latency but can lead to an imbalanced load distribution.
diff --git a/docs/general/mission-statement.md b/docs/general/mission-statement.md
@@ -118,7 +118,7 @@ Benchmarks indicate `Microbus` is capable of processing upward of 94,500 req/sec
 
 ### Reliability
 
-Reliable communication is an imperative quality of any distributed system. In `Microbus`, microservices communicate with each other over a messaging bus. Each microservice connects to the bus over a [persistent multiplexed connection](../blocks/multiplexed.md) that is monitored constantly and kept alive with automatic reconnects if required. Locality-aware routing, [ack of fail fast](../blocks/ack-or-fail.md) and [graceful shutdowns](../blocks/graceful-shutdown.md) further enhance the reliability of communications.
+Reliable communication is an imperative quality of any distributed system. In `Microbus`, microservices communicate with each other over a messaging bus. Each microservice connects to the bus over a [persistent multiplexed connection](../blocks/multiplexed.md) that is monitored constantly and kept alive with automatic reconnects if required. [Locality-aware routing](../blocks/locality-aware-routing.md), [ack of fail fast](../blocks/ack-or-fail.md) and [graceful shutdowns](../blocks/graceful-shutdown.md) further enhance the reliability of communications.
 
 It is also imperative that a distributed system remains online at all times. `Microbus` achieves that by capturing all errors and panics so that malfunctioning microservices do not crash.
 

diff --git a/docs/tech/envars.md b/docs/tech/envars.md
@@ -33,15 +33,7 @@ This is an advanced feature and in most cases there is no need to customize the
 
 ## Locality
 
-A geographic locality, when provided, is used by `Microbus` to optimize routing of unicast communications. A microservice making a unicast request will prioritize microservices that most resemble its own locality. For example, if the upstream microservice is located in `az1.dc2.west.us` and the downstream microservice is located in both `az2.dc2.west.us` and `az1.dc1.east.us`, the request will be directed to the former because they share the longer common suffix `dc2.west.us`.
-
-Locality-aware routing works when both upstream and downstream microservices designate a locality, typically by means of the `MICROBUS_LOCALITY` environment variable. The pattern is similar to that of a standard hostname, with the most specific location first.
-
-The special value `AWS` can be used when deployed on AWS to determine the availability zone automatically by making a request to the meta-data service at `http://169.254.169.254/latest/meta-data/placement/availability-zone`. The availability zone will then be used as the basis for the locality of the microservice. For example, availability zone `us-east-1b` is transformed to locality `b.1.east.us`.
-
-Similarly, the special value `GCP` can be used when deployed on GCP to determine the availability zone from `http://metadata.google.internal/computeMetadata/v1/instance/zone`. For example, availability zone `us-east1-b` is transformed to locality `b.1.east.us`
-
-Caution: the microservice will fail to start if the availability zone cannot be determined.
+The `MICROBUS_LOCALITY` environment variable sets the locality of the microservice, which is used as the basis for [locality-aware routing](../blocks/locality-aware-routing.md).
 
 ## Logging
 

diff --git a/docs/tech/path-arguments.md b/docs/tech/path-arguments.md
@@ -2,7 +2,7 @@
 
 Path arguments are request arguments that are extracted from a URL's path rather than its query string.
 
-[Warning!](#warning) Path arguments interfere with multicast as well as locality-aware routing. 
+[Warning!](#warning) Path arguments interfere with [multicast](../blocks/multicast.md) as well as [locality-aware routing](../blocks/locality-aware-routing.md).
 
 ## Fixed Path