Update MR docs to recommend 250ms max-offset

_includes/v21.1/faq/clock-synchronization-effects.md

@@ -12,6 +12,7 @@ When setting up clock synchronization:
 - For nodes running in AWS, we recommend [Amazon Time Sync Service](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/set-time.html#configure-amazon-time-service). For nodes running in GCP, we recommend [Google's internal NTP service](https://cloud.google.com/compute/docs/instances/managing-instances#configure_ntp_for_your_instances). For nodes running elsewhere, we recommend [Google Public NTP](https://developers.google.com/time/). Note that the Google and Amazon time services can be mixed with each other, but they cannot be mixed with other time services (unless you have verified leap second behavior). Either all of your nodes should use the Google and Amazon services, or none of them should.
 - If you do not want to use the Google or Amazon time sources, you can use [`chrony`](https://chrony.tuxfamily.org/index.html) and enable client-side leap smearing, unless the time source you're using already does server-side smearing. In most cases, we recommend the Google Public NTP time source because it handles smearing the leap second. If you use a different NTP time source that doesn't smear the leap second, you must configure client-side smearing manually and do so in the same way on each machine.
 - Do not run more than one clock sync service on VMs where `cockroach` is running.
+- {% include v21.1/misc/multiregion-max-offset.md %}
 
 ### Tutorials
 

_includes/v21.1/misc/multiregion-max-offset.md

@@ -0,0 +1 @@
+For new clusters using the [multi-region SQL abstractions](multiregion-overview.html), we recommend lowering the [`--max-offset`](cockroach-start.html#flags-max-offset) setting to `250ms`.  This is especially helpful for lowering the write latency of [global tables](multiregion-overview.html#global-tables). Note that this will require restarting all of the nodes in your cluster at the same time; it cannot be done with a rolling restart.

_includes/v21.2/faq/clock-synchronization-effects.md

@@ -12,6 +12,7 @@ When setting up clock synchronization:
 - For nodes running in AWS, we recommend [Amazon Time Sync Service](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/set-time.html#configure-amazon-time-service). For nodes running in GCP, we recommend [Google's internal NTP service](https://cloud.google.com/compute/docs/instances/managing-instances#configure_ntp_for_your_instances). For nodes running elsewhere, we recommend [Google Public NTP](https://developers.google.com/time/). Note that the Google and Amazon time services can be mixed with each other, but they cannot be mixed with other time services (unless you have verified leap second behavior). Either all of your nodes should use the Google and Amazon services, or none of them should.
 - If you do not want to use the Google or Amazon time sources, you can use [`chrony`](https://chrony.tuxfamily.org/index.html) and enable client-side leap smearing, unless the time source you're using already does server-side smearing. In most cases, we recommend the Google Public NTP time source because it handles smearing the leap second. If you use a different NTP time source that doesn't smear the leap second, you must configure client-side smearing manually and do so in the same way on each machine.
 - Do not run more than one clock sync service on VMs where `cockroach` is running.
+- {% include v21.2/misc/multiregion-max-offset.md %}
 
 ### Tutorials
 

_includes/v21.2/misc/multiregion-max-offset.md

@@ -0,0 +1 @@
+For new clusters using the [multi-region SQL abstractions](multiregion-overview.html), we recommend lowering the [`--max-offset`](cockroach-start.html#flags-max-offset) setting to `250ms`.  This is especially helpful for lowering the write latency of [global tables](multiregion-overview.html#global-tables). Note that this will require restarting all of the nodes in your cluster at the same time; it cannot be done with a rolling restart.

v21.1/choosing-a-multi-region-configuration.md

@@ -49,6 +49,10 @@ The table below offers another view of how the configuration options described a
 Different databases and tables within the same cluster can each use different combinations of the settings above.
 {{site.data.alerts.end}}
 
+{{site.data.alerts.callout_success}}
+{% include {{page.version.version}}/misc/multiregion-max-offset.md %}
+{{site.data.alerts.end}}
+
 ## See also
 
 - [Multi-region overview](multiregion-overview.html)

v21.1/global-tables.md

@@ -12,8 +12,10 @@ In a [multi-region deployment](multiregion-overview.html), the [`GLOBAL` table l
 
 In general, this pattern is suited well for reference tables that are rarely updated.
 
-{{site.data.alerts.callout_info}}
 Tables with the `GLOBAL` locality can survive zone or region failures, depending on the database-level [survival goal](multiregion-overview.html#survival-goals) setting.
+
+{{site.data.alerts.callout_success}}
+{% include {{page.version.version}}/misc/multiregion-max-offset.md %}
 {{site.data.alerts.end}}
 
 {{site.data.alerts.callout_info}}

v21.1/multiregion-overview.md

@@ -28,6 +28,10 @@ The steps above describe the simplest case, where you accept all of the default
 
 For more information about CockroachDB's multi-region capabilities and the customization options that are available, see below.
 
+{{site.data.alerts.callout_success}}
+{% include {{page.version.version}}/misc/multiregion-max-offset.md %}
+{{site.data.alerts.end}}
+
 {% include enterprise-feature.md %}
 
 ## Cluster Regions

v21.1/regional-tables.md

@@ -9,8 +9,10 @@ In a [multi-region deployment](multiregion-overview.html), the [Regional Table L
 - Read and write latency must be low.
 - Rows in the table, and all latency-sensitive queries, can be tied to specific regions.
 
-{{site.data.alerts.callout_info}}
 Tables with the Regional Table Locality Pattern can survive zone or region failures, depending on the database-level [survival goal](multiregion-overview.html#survival-goals) setting.
+
+{{site.data.alerts.callout_success}}
+{% include {{page.version.version}}/misc/multiregion-max-offset.md %}
 {{site.data.alerts.end}}
 
 {{site.data.alerts.callout_info}}

v21.1/when-to-use-regional-vs-global-tables.md

@@ -19,10 +19,12 @@ Use [`REGIONAL` tables](multiregion-overview.html#regional-by-row-tables) if:
 Use [`GLOBAL` tables](multiregion-overview.html#global-tables) if:
 
 - Your application has a "read-mostly" table of reference data that is rarely updated, and that needs to be available to all regions.
-- You can accept that writes to the table will incur higher latencies from any given region, since writes use a novel non-blocking transaction protocol that uses a timestamp "in the future" (documentation forthcoming).
+- You can accept that writes to the table will incur higher latencies from any given region, since writes use a novel [non-blocking transaction protocol](architecture/transaction-layer.html#non-blocking-transactions) that uses a timestamp "in the future". Note that the observed write latency is dependent on the [`--max-offset`](cockroach-start.html#flags-max-offset) setting.
 
-{{site.data.alerts.callout_success}}
 For more information about how to choose an overall multi-region configuration, see [Choosing a multi-region configuration](choosing-a-multi-region-configuration.html).
+
+{{site.data.alerts.callout_success}}
+{% include {{page.version.version}}/misc/multiregion-max-offset.md %}
 {{site.data.alerts.end}}
 
 {% include enterprise-feature.md %}

v21.2/choosing-a-multi-region-configuration.md

@@ -49,6 +49,10 @@ The table below offers another view of how the configuration options described a
 Different databases and tables within the same cluster can each use different combinations of the settings above.
 {{site.data.alerts.end}}
 
+{{site.data.alerts.callout_success}}
+{% include {{page.version.version}}/misc/multiregion-max-offset.md %}
+{{site.data.alerts.end}}
+
 ## See also
 
 - [Multi-region overview](multiregion-overview.html)

v21.2/global-tables.md

@@ -12,8 +12,10 @@ In a [multi-region deployment](multiregion-overview.html), the [`GLOBAL` table l
 
 In general, this pattern is suited well for reference tables that are rarely updated.
 
-{{site.data.alerts.callout_info}}
 Tables with the `GLOBAL` locality can survive zone or region failures, depending on the database-level [survival goal](multiregion-overview.html#survival-goals) setting.
+
+{{site.data.alerts.callout_success}}
+{% include {{page.version.version}}/misc/multiregion-max-offset.md %}
 {{site.data.alerts.end}}
 
 {{site.data.alerts.callout_info}}

v21.2/multiregion-overview.md

@@ -28,6 +28,10 @@ The steps above describe the simplest case, where you accept all of the default
 
 For more information about CockroachDB's multi-region capabilities and the customization options that are available, see below.
 
+{{site.data.alerts.callout_success}}
+{% include {{page.version.version}}/misc/multiregion-max-offset.md %}
+{{site.data.alerts.end}}
+
 {% include enterprise-feature.md %}
 
 ## Cluster Regions

v21.2/regional-tables.md

@@ -9,8 +9,10 @@ In a [multi-region deployment](multiregion-overview.html), the [Regional Table L
 - Read and write latency must be low.
 - Rows in the table, and all latency-sensitive queries, can be tied to specific regions.
 
-{{site.data.alerts.callout_info}}
 Tables with the Regional Table Locality Pattern can survive zone or region failures, depending on the database-level [survival goal](multiregion-overview.html#survival-goals) setting.
+
+{{site.data.alerts.callout_success}}
+{% include {{page.version.version}}/misc/multiregion-max-offset.md %}
 {{site.data.alerts.end}}
 
 {{site.data.alerts.callout_info}}

v21.2/when-to-use-regional-vs-global-tables.md

@@ -19,10 +19,12 @@ Use [`REGIONAL` tables](multiregion-overview.html#regional-by-row-tables) if:
 Use [`GLOBAL` tables](multiregion-overview.html#global-tables) if:
 
 - Your application has a "read-mostly" table of reference data that is rarely updated, and that needs to be available to all regions.
-- You can accept that writes to the table will incur higher latencies from any given region, since writes use a novel non-blocking transaction protocol that uses a timestamp "in the future" (documentation forthcoming).
+- You can accept that writes to the table will incur higher latencies from any given region, since writes use a novel [non-blocking transaction protocol](architecture/transaction-layer.html#non-blocking-transactions) that uses a timestamp "in the future". Note that the observed write latency is dependent on the [`--max-offset`](cockroach-start.html#flags-max-offset) setting.
 
-{{site.data.alerts.callout_success}}
 For more information about how to choose an overall multi-region configuration, see [Choosing a multi-region configuration](choosing-a-multi-region-configuration.html).
+
+{{site.data.alerts.callout_success}}
+{% include {{page.version.version}}/misc/multiregion-max-offset.md %}
 {{site.data.alerts.end}}
 
 {% include enterprise-feature.md %}