diff --git a/src/current/v24.1/set-up-physical-cluster-replication.md b/src/current/v24.1/set-up-physical-cluster-replication.md index 6c678ec3c51..c125eb647be 100644 --- a/src/current/v24.1/set-up-physical-cluster-replication.md +++ b/src/current/v24.1/set-up-physical-cluster-replication.md @@ -39,7 +39,7 @@ The high-level steps in this tutorial are: - To set up each cluster, you can follow [Deploy CockroachDB on Premises]({% link {{ page.version.version }}/deploy-cockroachdb-on-premises.md %}). When you initialize the cluster with the [`cockroach init`]({% link {{ page.version.version }}/cockroach-init.md %}) command, you **must** pass the `--virtualized` or `--virtualized-empty` flag. Refer to the cluster creation steps for the [primary cluster](#initialize-the-primary-cluster) and for the [standby cluster](#initialize-the-standby-cluster) for details. - The [Deploy CockroachDB on Premises]({% link {{ page.version.version }}/deploy-cockroachdb-on-premises.md %}) tutorial creates a self-signed certificate for each {{ site.data.products.core }} cluster. To create certificates signed by an external certificate authority, refer to [Create Security Certificates using OpenSSL]({% link {{ page.version.version }}/create-security-certificates-openssl.md %}). - All nodes in each cluster will need access to the Certificate Authority for the other cluster. Refer to [Manage cluster certificates](#step-3-manage-cluster-certificates-and-generate-connection-strings). -- The primary and standby clusters can have different [region topologies]({% link {{ page.version.version }}/topology-patterns.md %}). However, behavior for features that rely on multi-region primitives, such as Region by Row and Region by Table, may be affected. +- The primary and standby clusters can have different [region topologies]({% link {{ page.version.version }}/topology-patterns.md %}). However, behavior for features that rely on multi-region primitives, such as Region by Row and Region by Table, may be affected. For more information, refer to [Multi-region behavior and best practices]({% link {{ page.version.version }}/physical-cluster-replication-technical-overview.md %}#multi-region-behavior-and-best-practices). ## Step 1. Create the primary cluster diff --git a/src/current/v24.3/physical-cluster-replication-technical-overview.md b/src/current/v24.3/physical-cluster-replication-technical-overview.md index 1b779db9c25..1c503d81673 100644 --- a/src/current/v24.3/physical-cluster-replication-technical-overview.md +++ b/src/current/v24.3/physical-cluster-replication-technical-overview.md @@ -68,3 +68,11 @@ When a PCR stream is started with a `readonly` virtual cluster, the job will del After reverting any necessary data, the standby virtual cluster is promoted as available to serve traffic and the replication job ends. For details on failing back to the primary cluster following a failover, refer to [Fail back to the primary cluster]({% link {{ page.version.version }}/failover-replication.md %}#failback). + +### Multi-region behavior and best practices + +You can use PCR to replicate between clusters with different [cluster regions]({% link {{ page.version.version }}/multiregion-overview.md %}#cluster-regions), [database regions]({% link {{ page.version.version }}/multiregion-overview.md %}#database-regions), and [table localities]({% link {{ page.version.version }}/table-localities.md %}). Mismatched regions and localities do not impact the [failover process]({% link {{ page.version.version }}/failover-replication.md %}) or ability to access clusters after failover, but they do impact [leaseholders]({% link {{ page.version.version }}/architecture/glossary.md %}#leaseholder) and locality-dependent settings. + +If the localities on the primary cluster do not match the localities on the standby cluster, the standby cluster may be unable to satisfy replicating locality constraints. For example, if a replicated `REGIONAL BY ROW` table has partitions in `us-east`, `us-central`, and `us-west`, and the standby cluster only has nodes with the locality tags `us-east` and `us-central`, the standby cluster cannot satisfy the `REGIONAL BY ROW` `us-west` partition constraint. Data with unsatisfiable partition constraints is placed in an arbitrary location on the standby cluster, which can cause performance issues in the case of a failover event due to latency between regions. + +After a failover event involving clusters in different regions, do not change any configurations on your standby cluster if you plan to [fail back to the original primary cluster]({% link {{ page.version.version }}/failover-replication.md %}#failback). If you plan to start using the standby cluster for long-running production traffic rather than performing a failback, adjust the configurations on the standby cluster to optimize for your traffic. When adjusting configurations, ensure that the new settings can be satisfied on the standby cluster. In particular, ensure that the cluster does not have pinned leaseholders for a region that does not exist on the cluster. diff --git a/src/current/v24.3/set-up-physical-cluster-replication.md b/src/current/v24.3/set-up-physical-cluster-replication.md index 1902fc7d837..1ae382402e3 100644 --- a/src/current/v24.3/set-up-physical-cluster-replication.md +++ b/src/current/v24.3/set-up-physical-cluster-replication.md @@ -36,7 +36,7 @@ The high-level steps in this tutorial are: - The [Deploy CockroachDB on Premises]({% link {{ page.version.version }}/deploy-cockroachdb-on-premises.md %}) tutorial creates a self-signed certificate for each {{ site.data.products.core }} cluster. To create certificates signed by an external certificate authority, refer to [Create Security Certificates using OpenSSL]({% link {{ page.version.version }}/create-security-certificates-openssl.md %}). - All nodes in each cluster will need access to the Certificate Authority for the other cluster. Refer to [Manage cluster certificates](#step-3-manage-cluster-certificates-and-generate-connection-strings). - An [{{ site.data.products.enterprise }} license]({% link {{ page.version.version }}/licensing-faqs.md %}#types-of-licenses) on the primary **and** standby clusters. You must use the system virtual cluster on the primary and standby clusters to enable your {{ site.data.products.enterprise }} license. -- The primary and standby clusters can have different [region topologies]({% link {{ page.version.version }}/topology-patterns.md %}). However, behavior for features that rely on multi-region primitives, such as Region by Row and Region by Table, may be affected. +- The primary and standby clusters can have different [region topologies]({% link {{ page.version.version }}/topology-patterns.md %}). However, behavior for features that rely on multi-region primitives, such as Region by Row and Region by Table, may be affected. For more information, refer to [Multi-region behavior and best practices]({% link {{ page.version.version }}/physical-cluster-replication-technical-overview.md %}#multi-region-behavior-and-best-practices). {{site.data.alerts.callout_info}} To set up PCR from an existing CockroachDB cluster, which will serve as the primary cluster, refer to [Set up PCR from an existing cluster](#set-up-pcr-from-an-existing-cluster). diff --git a/src/current/v25.2/physical-cluster-replication-technical-overview.md b/src/current/v25.2/physical-cluster-replication-technical-overview.md index 1f7fb41af43..897b4ad6205 100644 --- a/src/current/v25.2/physical-cluster-replication-technical-overview.md +++ b/src/current/v25.2/physical-cluster-replication-technical-overview.md @@ -68,3 +68,11 @@ When a PCR stream is started with a `readonly` virtual cluster, the job will del After reverting any necessary data, the standby virtual cluster is promoted as available to serve traffic and the replication job ends. For details on failing back to the primary cluster following a failover, refer to [Fail back to the primary cluster]({% link {{ page.version.version }}/failover-replication.md %}#failback). + +### Multi-region behavior and best practices + +You can use PCR to replicate between clusters with different [cluster regions]({% link {{ page.version.version }}/multiregion-overview.md %}#cluster-regions), [database regions]({% link {{ page.version.version }}/multiregion-overview.md %}#database-regions), and [table localities]({% link {{ page.version.version }}/table-localities.md %}). Mismatched regions and localities do not impact the [failover process]({% link {{ page.version.version }}/failover-replication.md %}) or ability to access clusters after failover, but they do impact [leaseholders]({% link {{ page.version.version }}/architecture/glossary.md %}#leaseholder) and locality-dependent settings. + +If the localities on the primary cluster do not match the localities on the standby cluster, the standby cluster may be unable to satisfy replicating locality constraints. For example, if a replicated `REGIONAL BY ROW` table has partitions in `us-east`, `us-central`, and `us-west`, and the standby cluster only has nodes with the locality tags `us-east` and `us-central`, the standby cluster cannot satisfy the `REGIONAL BY ROW` `us-west` partition constraint. Data with unsatisfiable partition constraints is placed in an arbitrary location on the standby cluster, which can cause performance issues in the case of a failover event due to latency between regions. + +After a failover event involving clusters in different regions, do not change any configurations on your standby cluster if you plan to [fail back to the original primary cluster]({% link {{ page.version.version }}/failover-replication.md %}#failback). If you plan to start using the standby cluster for long-running production traffic rather than performing a failback, adjust the configurations on the standby cluster to optimize for your traffic. When adjusting configurations, ensure that the new settings can be satisfied on the standby cluster. In particular, ensure that the cluster does not have pinned leaseholders for a region that does not exist on the cluster. diff --git a/src/current/v25.2/set-up-physical-cluster-replication.md b/src/current/v25.2/set-up-physical-cluster-replication.md index 427a06a745e..db501867bd9 100644 --- a/src/current/v25.2/set-up-physical-cluster-replication.md +++ b/src/current/v25.2/set-up-physical-cluster-replication.md @@ -39,7 +39,7 @@ To set up PCR from an existing CockroachDB cluster, which will serve as the prim - To set up each cluster, you can follow [Deploy CockroachDB on Premises]({% link {{ page.version.version }}/deploy-cockroachdb-on-premises.md %}). When you initialize the cluster with the [`cockroach init`]({% link {{ page.version.version }}/cockroach-init.md %}) command, you **must** pass the `--virtualized` or `--virtualized-empty` flag. Refer to the cluster creation steps for the [primary cluster](#initialize-the-primary-cluster) and for the [standby cluster](#initialize-the-standby-cluster) for details. - The [Deploy CockroachDB on Premises]({% link {{ page.version.version }}/deploy-cockroachdb-on-premises.md %}) tutorial creates a self-signed certificate for each {{ site.data.products.core }} cluster. To create certificates signed by an external certificate authority, refer to [Create Security Certificates using OpenSSL]({% link {{ page.version.version }}/create-security-certificates-openssl.md %}). - All nodes in each cluster will need access to the Certificate Authority for the other cluster. Refer to [Manage cluster certificates](#step-3-manage-cluster-certificates-and-generate-connection-strings). -- The primary and standby clusters can have different [region topologies]({% link {{ page.version.version }}/topology-patterns.md %}). However, behavior for features that rely on multi-region primitives, such as Region by Row and Region by Table, may be affected. +- The primary and standby clusters can have different [region topologies]({% link {{ page.version.version }}/topology-patterns.md %}). However, behavior for features that rely on multi-region primitives, such as Region by Row and Region by Table, may be affected. For more information, refer to [Multi-region behavior and best practices]({% link {{ page.version.version }}/physical-cluster-replication-technical-overview.md %}#multi-region-behavior-and-best-practices). ## Step 1. Create the primary cluster diff --git a/src/current/v25.3/physical-cluster-replication-technical-overview.md b/src/current/v25.3/physical-cluster-replication-technical-overview.md index ba0a7211b8a..cec24c3edb8 100644 --- a/src/current/v25.3/physical-cluster-replication-technical-overview.md +++ b/src/current/v25.3/physical-cluster-replication-technical-overview.md @@ -68,3 +68,11 @@ When a PCR stream is started with a `readonly` virtual cluster, the job will del After reverting any necessary data, the standby virtual cluster is promoted as available to serve traffic and the replication job ends. For details on failing back to the primary cluster following a failover, refer to [Fail back to the primary cluster]({% link {{ page.version.version }}/failover-replication.md %}#failback). + +### Multi-region behavior and best practices + +You can use PCR to replicate between clusters with different [cluster regions]({% link {{ page.version.version }}/multiregion-overview.md %}#cluster-regions), [database regions]({% link {{ page.version.version }}/multiregion-overview.md %}#database-regions), and [table localities]({% link {{ page.version.version }}/table-localities.md %}). Mismatched regions and localities do not impact the [failover process]({% link {{ page.version.version }}/failover-replication.md %}) or ability to access clusters after failover, but they do impact [leaseholders]({% link {{ page.version.version }}/architecture/glossary.md %}#leaseholder) and locality-dependent settings. + +If the localities on the primary cluster do not match the localities on the standby cluster, the standby cluster may be unable to satisfy replicating locality constraints. For example, if a replicated `REGIONAL BY ROW` table has partitions in `us-east`, `us-central`, and `us-west`, and the standby cluster only has nodes with the locality tags `us-east` and `us-central`, the standby cluster cannot satisfy the `REGIONAL BY ROW` `us-west` partition constraint. Data with unsatisfiable partition constraints is placed in an arbitrary location on the standby cluster, which can cause performance issues in the case of a failover event due to latency between regions. + +After a failover event involving clusters in different regions, do not change any configurations on your standby cluster if you plan to [fail back to the original primary cluster]({% link {{ page.version.version }}/failover-replication.md %}#failback). If you plan to start using the standby cluster for long-running production traffic rather than performing a failback, adjust the configurations on the standby cluster to optimize for your traffic. When adjusting configurations, ensure that the new settings can be satisfied on the standby cluster. In particular, ensure that the cluster does not have pinned leaseholders for a region that does not exist on the cluster. diff --git a/src/current/v25.3/set-up-physical-cluster-replication.md b/src/current/v25.3/set-up-physical-cluster-replication.md index fdb01f48d74..9db23dae9aa 100644 --- a/src/current/v25.3/set-up-physical-cluster-replication.md +++ b/src/current/v25.3/set-up-physical-cluster-replication.md @@ -39,7 +39,7 @@ To set up PCR from an existing CockroachDB cluster, which will serve as the prim - To set up each cluster, you can follow [Deploy CockroachDB on Premises]({% link {{ page.version.version }}/deploy-cockroachdb-on-premises.md %}). When you initialize the cluster with the [`cockroach init`]({% link {{ page.version.version }}/cockroach-init.md %}) command, you **must** pass the `--virtualized` or `--virtualized-empty` flag. Refer to the cluster creation steps for the [primary cluster](#initialize-the-primary-cluster) and for the [standby cluster](#initialize-the-standby-cluster) for details. - The [Deploy CockroachDB on Premises]({% link {{ page.version.version }}/deploy-cockroachdb-on-premises.md %}) tutorial creates a self-signed certificate for each {{ site.data.products.core }} cluster. To create certificates signed by an external certificate authority, refer to [Create Security Certificates using OpenSSL]({% link {{ page.version.version }}/create-security-certificates-openssl.md %}). - All nodes in each cluster will need access to the Certificate Authority for the other cluster. Refer to [Manage cluster certificates](#step-3-manage-cluster-certificates-and-generate-connection-strings). -- The primary and standby clusters can have different [region topologies]({% link {{ page.version.version }}/topology-patterns.md %}). However, behavior for features that rely on multi-region primitives, such as Region by Row and Region by Table, may be affected. +- The primary and standby clusters can have different [region topologies]({% link {{ page.version.version }}/topology-patterns.md %}). However, behavior for features that rely on multi-region primitives, such as Region by Row and Region by Table, may be affected. For more information, refer to [Multi-region behavior and best practices]({% link {{ page.version.version }}/physical-cluster-replication-technical-overview.md %}#multi-region-behavior-and-best-practices). ## Step 1. Create the primary cluster diff --git a/src/current/v25.4/physical-cluster-replication-technical-overview.md b/src/current/v25.4/physical-cluster-replication-technical-overview.md index fdcbc96f4cf..b222ed4a26d 100644 --- a/src/current/v25.4/physical-cluster-replication-technical-overview.md +++ b/src/current/v25.4/physical-cluster-replication-technical-overview.md @@ -68,3 +68,11 @@ When a PCR stream is started with a `readonly` virtual cluster, the job will del After reverting any necessary data, the standby virtual cluster is promoted as available to serve traffic and the replication job ends. For details on failing back to the primary cluster following a failover, refer to [Fail back to the primary cluster]({% link {{ page.version.version }}/failover-replication.md %}#failback). + +### Multi-region behavior and best practices + +You can use PCR to replicate between clusters with different [cluster regions]({% link {{ page.version.version }}/multiregion-overview.md %}#cluster-regions), [database regions]({% link {{ page.version.version }}/multiregion-overview.md %}#database-regions), and [table localities]({% link {{ page.version.version }}/table-localities.md %}). Mismatched regions and localities do not impact the [failover process]({% link {{ page.version.version }}/failover-replication.md %}) or ability to access clusters after failover, but they do impact [leaseholders]({% link {{ page.version.version }}/architecture/glossary.md %}#leaseholder) and locality-dependent settings. + +If the localities on the primary cluster do not match the localities on the standby cluster, the standby cluster may be unable to satisfy replicating locality constraints. For example, if a replicated `REGIONAL BY ROW` table has partitions in `us-east`, `us-central`, and `us-west`, and the standby cluster only has nodes with the locality tags `us-east` and `us-central`, the standby cluster cannot satisfy the `REGIONAL BY ROW` `us-west` partition constraint. Data with unsatisfiable partition constraints is placed in an arbitrary location on the standby cluster, which can cause performance issues in the case of a failover event due to latency between regions. + +After a failover event involving clusters in different regions, do not change any configurations on your standby cluster if you plan to [fail back to the original primary cluster]({% link {{ page.version.version }}/failover-replication.md %}#failback). If you plan to start using the standby cluster for long-running production traffic rather than performing a failback, adjust the configurations on the standby cluster to optimize for your traffic. When adjusting configurations, ensure that the new settings can be satisfied on the standby cluster. In particular, ensure that the cluster does not have pinned leaseholders for a region that does not exist on the cluster. diff --git a/src/current/v25.4/set-up-physical-cluster-replication.md b/src/current/v25.4/set-up-physical-cluster-replication.md index c7ea8a871cf..b1f23e4c8ed 100644 --- a/src/current/v25.4/set-up-physical-cluster-replication.md +++ b/src/current/v25.4/set-up-physical-cluster-replication.md @@ -39,7 +39,7 @@ To set up PCR from an existing CockroachDB cluster, which will serve as the prim - To set up each cluster, you can follow [Deploy CockroachDB on Premises]({% link {{ page.version.version }}/deploy-cockroachdb-on-premises.md %}). When you initialize the cluster with the [`cockroach init`]({% link {{ page.version.version }}/cockroach-init.md %}) command, you **must** pass the `--virtualized` or `--virtualized-empty` flag. Refer to the cluster creation steps for the [primary cluster](#initialize-the-primary-cluster) and for the [standby cluster](#initialize-the-standby-cluster) for details. - The [Deploy CockroachDB on Premises]({% link {{ page.version.version }}/deploy-cockroachdb-on-premises.md %}) tutorial creates a self-signed certificate for each {{ site.data.products.core }} cluster. To create certificates signed by an external certificate authority, refer to [Create Security Certificates using OpenSSL]({% link {{ page.version.version }}/create-security-certificates-openssl.md %}). - All nodes in each cluster will need access to the Certificate Authority for the other cluster. Refer to [Manage cluster certificates](#step-3-manage-cluster-certificates-and-generate-connection-strings). -- The primary and standby clusters can have different [region topologies]({% link {{ page.version.version }}/topology-patterns.md %}). However, behavior for features that rely on multi-region primitives, such as Region by Row and Region by Table, may be affected. +- The primary and standby clusters can have different [region topologies]({% link {{ page.version.version }}/topology-patterns.md %}). However, behavior for features that rely on multi-region primitives, such as Region by Row and Region by Table, may be affected. For more information, refer to [Multi-region behavior and best practices]({% link {{ page.version.version }}/physical-cluster-replication-technical-overview.md %}#multi-region-behavior-and-best-practices). ## Step 1. Create the primary cluster diff --git a/src/current/v26.1/physical-cluster-replication-technical-overview.md b/src/current/v26.1/physical-cluster-replication-technical-overview.md index 8a465f0175c..1c0cbd99a62 100644 --- a/src/current/v26.1/physical-cluster-replication-technical-overview.md +++ b/src/current/v26.1/physical-cluster-replication-technical-overview.md @@ -68,3 +68,11 @@ When a PCR stream is started with a `readonly` virtual cluster, the job will del After reverting any necessary data, the standby virtual cluster is promoted as available to serve traffic and the replication job ends. For details on failing back to the primary cluster following a failover, refer to [Fail back to the primary cluster]({% link {{ page.version.version }}/failover-replication.md %}#failback). + +### Multi-region behavior and best practices + +You can use PCR to replicate between clusters with different [cluster regions]({% link {{ page.version.version }}/multiregion-overview.md %}#cluster-regions), [database regions]({% link {{ page.version.version }}/multiregion-overview.md %}#database-regions), and [table localities]({% link {{ page.version.version }}/table-localities.md %}). Mismatched regions and localities do not impact the [failover process]({% link {{ page.version.version }}/failover-replication.md %}) or ability to access clusters after failover, but they do impact [leaseholders]({% link {{ page.version.version }}/architecture/glossary.md %}#leaseholder) and locality-dependent settings. + +If the localities on the primary cluster do not match the localities on the standby cluster, the standby cluster may be unable to satisfy replicating locality constraints. For example, if a replicated `REGIONAL BY ROW` table has partitions in `us-east`, `us-central`, and `us-west`, and the standby cluster only has nodes with the locality tags `us-east` and `us-central`, the standby cluster cannot satisfy the `REGIONAL BY ROW` `us-west` partition constraint. Data with unsatisfiable partition constraints is placed in an arbitrary location on the standby cluster, which can cause performance issues in the case of a failover event due to latency between regions. + +After a failover event involving clusters in different regions, do not change any configurations on your standby cluster if you plan to [fail back to the original primary cluster]({% link {{ page.version.version }}/failover-replication.md %}#failback). If you plan to start using the standby cluster for long-running production traffic rather than performing a failback, adjust the configurations on the standby cluster to optimize for your traffic. When adjusting configurations, ensure that the new settings can be satisfied on the standby cluster. In particular, ensure that the cluster does not have pinned leaseholders for a region that does not exist on the cluster. \ No newline at end of file diff --git a/src/current/v26.1/set-up-physical-cluster-replication.md b/src/current/v26.1/set-up-physical-cluster-replication.md index c7ea8a871cf..b1f23e4c8ed 100644 --- a/src/current/v26.1/set-up-physical-cluster-replication.md +++ b/src/current/v26.1/set-up-physical-cluster-replication.md @@ -39,7 +39,7 @@ To set up PCR from an existing CockroachDB cluster, which will serve as the prim - To set up each cluster, you can follow [Deploy CockroachDB on Premises]({% link {{ page.version.version }}/deploy-cockroachdb-on-premises.md %}). When you initialize the cluster with the [`cockroach init`]({% link {{ page.version.version }}/cockroach-init.md %}) command, you **must** pass the `--virtualized` or `--virtualized-empty` flag. Refer to the cluster creation steps for the [primary cluster](#initialize-the-primary-cluster) and for the [standby cluster](#initialize-the-standby-cluster) for details. - The [Deploy CockroachDB on Premises]({% link {{ page.version.version }}/deploy-cockroachdb-on-premises.md %}) tutorial creates a self-signed certificate for each {{ site.data.products.core }} cluster. To create certificates signed by an external certificate authority, refer to [Create Security Certificates using OpenSSL]({% link {{ page.version.version }}/create-security-certificates-openssl.md %}). - All nodes in each cluster will need access to the Certificate Authority for the other cluster. Refer to [Manage cluster certificates](#step-3-manage-cluster-certificates-and-generate-connection-strings). -- The primary and standby clusters can have different [region topologies]({% link {{ page.version.version }}/topology-patterns.md %}). However, behavior for features that rely on multi-region primitives, such as Region by Row and Region by Table, may be affected. +- The primary and standby clusters can have different [region topologies]({% link {{ page.version.version }}/topology-patterns.md %}). However, behavior for features that rely on multi-region primitives, such as Region by Row and Region by Table, may be affected. For more information, refer to [Multi-region behavior and best practices]({% link {{ page.version.version }}/physical-cluster-replication-technical-overview.md %}#multi-region-behavior-and-best-practices). ## Step 1. Create the primary cluster