From 98bae79f5142939b779f3a8f81cc273a3e74dbf8 Mon Sep 17 00:00:00 2001 From: Rich Loveland Date: Thu, 29 Jul 2021 15:29:37 -0400 Subject: [PATCH] Update MR docs to recommend 250ms max-offset Fixes cockroachdb/docs#10920 --- _includes/v21.1/faq/clock-synchronization-effects.md | 1 + _includes/v21.1/misc/multiregion-max-offset.md | 1 + _includes/v21.2/faq/clock-synchronization-effects.md | 1 + _includes/v21.2/misc/multiregion-max-offset.md | 1 + v21.1/choosing-a-multi-region-configuration.md | 4 ++++ v21.1/global-tables.md | 4 +++- v21.1/multiregion-overview.md | 4 ++++ v21.1/regional-tables.md | 4 +++- v21.1/when-to-use-regional-vs-global-tables.md | 6 ++++-- v21.2/choosing-a-multi-region-configuration.md | 4 ++++ v21.2/global-tables.md | 4 +++- v21.2/multiregion-overview.md | 4 ++++ v21.2/regional-tables.md | 4 +++- v21.2/when-to-use-regional-vs-global-tables.md | 6 ++++-- 14 files changed, 40 insertions(+), 8 deletions(-) create mode 100644 _includes/v21.1/misc/multiregion-max-offset.md create mode 100644 _includes/v21.2/misc/multiregion-max-offset.md diff --git a/_includes/v21.1/faq/clock-synchronization-effects.md b/_includes/v21.1/faq/clock-synchronization-effects.md index 9090fb5c299..e2d6ba29218 100644 --- a/_includes/v21.1/faq/clock-synchronization-effects.md +++ b/_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 diff --git a/_includes/v21.1/misc/multiregion-max-offset.md b/_includes/v21.1/misc/multiregion-max-offset.md new file mode 100644 index 00000000000..93a2faccba2 --- /dev/null +++ b/_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. diff --git a/_includes/v21.2/faq/clock-synchronization-effects.md b/_includes/v21.2/faq/clock-synchronization-effects.md index 9090fb5c299..0461d7ba230 100644 --- a/_includes/v21.2/faq/clock-synchronization-effects.md +++ b/_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 diff --git a/_includes/v21.2/misc/multiregion-max-offset.md b/_includes/v21.2/misc/multiregion-max-offset.md new file mode 100644 index 00000000000..93a2faccba2 --- /dev/null +++ b/_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. diff --git a/v21.1/choosing-a-multi-region-configuration.md b/v21.1/choosing-a-multi-region-configuration.md index e5a8a64657b..15ea962b077 100644 --- a/v21.1/choosing-a-multi-region-configuration.md +++ b/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) diff --git a/v21.1/global-tables.md b/v21.1/global-tables.md index c038a00b22c..53d37dc087b 100644 --- a/v21.1/global-tables.md +++ b/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}} diff --git a/v21.1/multiregion-overview.md b/v21.1/multiregion-overview.md index 814f945fb55..aa9a400dced 100644 --- a/v21.1/multiregion-overview.md +++ b/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 diff --git a/v21.1/regional-tables.md b/v21.1/regional-tables.md index a49f87cf410..72fa36bc7dc 100644 --- a/v21.1/regional-tables.md +++ b/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}} diff --git a/v21.1/when-to-use-regional-vs-global-tables.md b/v21.1/when-to-use-regional-vs-global-tables.md index 92824b5d0f8..81760a6ac1d 100644 --- a/v21.1/when-to-use-regional-vs-global-tables.md +++ b/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 %} diff --git a/v21.2/choosing-a-multi-region-configuration.md b/v21.2/choosing-a-multi-region-configuration.md index e5a8a64657b..15ea962b077 100644 --- a/v21.2/choosing-a-multi-region-configuration.md +++ b/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) diff --git a/v21.2/global-tables.md b/v21.2/global-tables.md index c038a00b22c..53d37dc087b 100644 --- a/v21.2/global-tables.md +++ b/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}} diff --git a/v21.2/multiregion-overview.md b/v21.2/multiregion-overview.md index f3dca6715b7..5ea7993e6ba 100644 --- a/v21.2/multiregion-overview.md +++ b/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 diff --git a/v21.2/regional-tables.md b/v21.2/regional-tables.md index a49f87cf410..72fa36bc7dc 100644 --- a/v21.2/regional-tables.md +++ b/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}} diff --git a/v21.2/when-to-use-regional-vs-global-tables.md b/v21.2/when-to-use-regional-vs-global-tables.md index 8fb6ae42752..d0569709a62 100644 --- a/v21.2/when-to-use-regional-vs-global-tables.md +++ b/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 %}