Topology patterns, v2

_includes/sidebar-data-v19.1.json

@@ -134,9 +134,56 @@
             ]
           },
           {
-            "title": "Cluster Topology Patterns",
-            "urls": [
-              "/${VERSION}/cluster-topology-patterns.html"
+            "title": "Topology Patterns",
+            "items": [
+              {
+                "title": "Overview",
+                "urls": [
+                  "/${VERSION}/topology-patterns.html"
+                ]
+              },
+              {
+                "title": "Development",
+                "urls": [
+                  "/${VERSION}/topology-development.html"
+                ]
+              },
+              {
+                "title": "Basic Production",
+                "urls": [
+                  "/${VERSION}/topology-basic-production.html"
+                ]
+              },
+              {
+                "title": "Geo-Partitioned Replicas",
+                "urls": [
+                  "/${VERSION}/topology-geo-partitioned-replicas.html"
+                ]
+              },
+              {
+                "title": "Geo-Partitioned Leaseholders",
+                "urls": [
+                  "/${VERSION}/topology-geo-partitioned-leaseholders.html"
+                ]
+              },
+              {
+                "title": "Duplicate Indexes",
+                "urls": [
+                  "/${VERSION}/topology-duplicate-indexes.html"
+                ]
+              },
+              {
+                "title": "Follower Reads",
+                "urls": [
+                  "/${VERSION}/topology-follower-reads.html"
+                ]
+              },
+              {
+                "title": "Follow-the-Workload",
+                "urls": [
+                  "/${VERSION}/topology-follow-the-workload.html"
+                ]
+              }
             ]
           },
           {

_includes/sidebar-data-v19.2.json

@@ -134,9 +134,56 @@
             ]
           },
           {
-            "title": "Cluster Topology Patterns",
-            "urls": [
-              "/${VERSION}/cluster-topology-patterns.html"
+            "title": "Topology Patterns",
+            "items": [
+              {
+                "title": "Overview",
+                "urls": [
+                  "/${VERSION}/topology-patterns.html"
+                ]
+              },
+              {
+                "title": "Development",
+                "urls": [
+                  "/${VERSION}/topology-development.html"
+                ]
+              },
+              {
+                "title": "Basic Production",
+                "urls": [
+                  "/${VERSION}/topology-basic-production.html"
+                ]
+              },
+              {
+                "title": "Geo-Partitioned Replicas",
+                "urls": [
+                  "/${VERSION}/topology-geo-partitioned-replicas.html"
+                ]
+              },
+              {
+                "title": "Geo-Partitioned Leaseholders",
+                "urls": [
+                  "/${VERSION}/topology-geo-partitioned-leaseholders.html"
+                ]
+              },
+              {
+                "title": "Duplicate Indexes",
+                "urls": [
+                  "/${VERSION}/topology-duplicate-indexes.html"
+                ]
+              },
+              {
+                "title": "Follower Reads",
+                "urls": [
+                  "/${VERSION}/topology-follower-reads.html"
+                ]
+              },
+              {
+                "title": "Follow-the-Workload",
+                "urls": [
+                  "/${VERSION}/topology-follow-the-workload.html"
+                ]
+              }
             ]
           },
           {

_includes/v19.1/prod-deployment/insecure-recommendations.md

@@ -1,5 +1,3 @@
-- If you plan to use CockroachDB in production, carefully review the [Production Checklist](recommended-production-settings.html).
-
 - Consider using a [secure cluster](manual-deployment.html) instead. Using an insecure cluster comes with risks:
     - Your cluster is open to any client that can access any node's IP addresses.
     - Any user, even `root`, can log in without providing a password.

_includes/v19.1/prod-deployment/insecure-requirements.md

@@ -1,3 +1,5 @@
+- Carefully review the [Production Checklist](recommended-production-settings.html) and recommended [Topology Patterns](topology-patterns.html).
+
 - You must have [SSH access]({{page.ssh-link}}) to each machine. This is necessary for distributing and starting CockroachDB binaries.
 
 - Your network configuration must allow TCP communication on the following ports:

_includes/v19.1/prod-deployment/secure-recommendations.md

@@ -1,5 +1,3 @@
-- If you plan to use CockroachDB in production, carefully review the [Production Checklist](recommended-production-settings.html).
-
 - Decide how you want to access your Admin UI:
 
     Access Level | Description

_includes/v19.1/prod-deployment/secure-requirements.md

@@ -1,3 +1,5 @@
+- Carefully review the [Production Checklist](recommended-production-settings.html) and recommended [Topology Patterns](topology-patterns.html).
+
 - You must have [CockroachDB installed](install-cockroachdb.html) locally. This is necessary for generating and managing your deployment's certificates.
 
 - You must have [SSH access]({{page.ssh-link}}) to each machine. This is necessary for distributing and starting CockroachDB binaries.

_includes/v19.1/topology-patterns/fundamentals.md

@@ -0,0 +1,7 @@
+Before choosing a topology pattern:
+
+- Review how data is replicated and distributed across a cluster, and how this affects performance. It is especially important to understand the concept of the "leaseholder". For a summary, see [Reads and Writes in CockroachDB](architecture/reads-and-writes-overview.html). For a deeper dive, see the [CockroachDB Architecture](architecture/overview.html) documentation.
+- Review the concept of [locality](start-a-node.html#locality), which makes CockroachDB aware of the location of nodes and able to intelligently place and balance data based on how you define [replication controls](configure-replication-zones.html).
+- Review the recommendations and requirements in our [Production Checklist](recommended-production-settings.html).
+- This topology doesn't account for hardware specifications, so be sure to follow our [hardware recommendations](recommended-production-settings.html#hardware) and perform a POC to size hardware for your use case.
+- Adopt relevant [SQL Best Practices](performance-best-practices-overview.html) to ensure optimal performance.

_includes/v19.1/topology-patterns/multi-region-cluster-setup.md

@@ -0,0 +1,30 @@
+Each [multi-region topology pattern](topology-patterns.html#multi-region-patterns) assumes the following setup:
+
+<img src="{{ 'images/v19.1/topology-patterns/topology_multi-region_hardware.png' | relative_url }}" alt="Multi-region hardware setup" style="max-width:100%" />
+
+#### Hardware
+
+- 3 regions
+
+- Per region, 3+ AZs with 3+ VMs evenly distributed across them
+
+- Region-specific app instances and load balancers
+    - Each load balancer redirects to CockroachDB nodes in its region.
+    - When CockroachDB nodes are unavailable in a region, the load balancer redirects to nodes in other regions.
+
+#### Cluster
+
+Each node is started with the [`--locality`](start-a-node.html#locality) flag specifying its region and AZ combination, e.g.:
+
+{% include copy-clipboard.html %}
+~~~ shell
+# Example start command for node in the west1 AZ of the us-west region:
+$ cockroach start \
+--locality=region=us-west,zone=west1 \
+--certs-dir=certs \
+--advertise-addr=<node1 internal address> \
+--join=<node1 internal address>:26257,<node2 internal address>:26257,<node3 internal address>:26257 \        
+--cache=.25 \
+--max-sql-memory=.25 \
+--background
+~~~

_includes/v19.1/topology-patterns/see-also.md

@@ -0,0 +1,11 @@
+- [Topology Patterns Overview](topology-patterns.html)
+
+    - Single-region
+        - [Development](topology-development.html)
+        - [Basic Production](topology-basic-production.html)
+
+    - Multi-region
+        - [Geo-Partitioned Replicas](topology-geo-partitioned-replicas.html)
+        - [Geo-Partitioned Leaseholders](topology-geo-partitioned-leaseholders.html)
+        - [Duplicate Indexes](topology-duplicate-indexes.html)
+        - [Follow-the-Workload](topology-follow-the-workload.html)

_includes/v19.2/prod-deployment/insecure-recommendations.md

@@ -1,5 +1,3 @@
-- If you plan to use CockroachDB in production, carefully review the [Production Checklist](recommended-production-settings.html).
-
 - Consider using a [secure cluster](manual-deployment.html) instead. Using an insecure cluster comes with risks:
     - Your cluster is open to any client that can access any node's IP addresses.
     - Any user, even `root`, can log in without providing a password.

_includes/v19.2/prod-deployment/insecure-requirements.md

@@ -1,3 +1,5 @@
+- Carefully review the [Production Checklist](recommended-production-settings.html) and recommended [Topology Patterns](topology-patterns.html).
+
 - You must have [SSH access]({{page.ssh-link}}) to each machine. This is necessary for distributing and starting CockroachDB binaries.
 
 - Your network configuration must allow TCP communication on the following ports:

_includes/v19.2/prod-deployment/secure-recommendations.md

@@ -1,5 +1,3 @@
-- If you plan to use CockroachDB in production, carefully review the [Production Checklist](recommended-production-settings.html).
-
 - Decide how you want to access your Admin UI:
 
     Access Level | Description

_includes/v19.2/prod-deployment/secure-requirements.md

@@ -1,3 +1,5 @@
+- Carefully review the [Production Checklist](recommended-production-settings.html) and recommended [Topology Patterns](topology-patterns.html).
+
 - You must have [CockroachDB installed](install-cockroachdb.html) locally. This is necessary for generating and managing your deployment's certificates.
 
 - You must have [SSH access]({{page.ssh-link}}) to each machine. This is necessary for distributing and starting CockroachDB binaries.

_includes/v19.2/topology-patterns/fundamentals.md

@@ -0,0 +1,7 @@
+Before choosing a topology pattern:
+
+- Review how data is replicated and distributed across a cluster, and how this affects performance. It is especially important to understand the concept of the "leaseholder". For a summary, see [Reads and Writes in CockroachDB](architecture/reads-and-writes-overview.html). For a deeper dive, see the [CockroachDB Architecture](architecture/overview.html) documentation.
+- Review the concept of [locality](start-a-node.html#locality), which makes CockroachDB aware of the location of nodes and able to intelligently place and balance data based on how you define [replication controls](configure-replication-zones.html).
+- Review the recommendations and requirements in our [Production Checklist](recommended-production-settings.html).
+- This topology doesn't account for hardware specifications, so be sure to follow our [hardware recommendations](recommended-production-settings.html#hardware) and perform a POC to size hardware for your use case.
+- Adopt relevant [SQL Best Practices](performance-best-practices-overview.html) to ensure optimal performance.

_includes/v19.2/topology-patterns/multi-region-cluster-setup.md

@@ -0,0 +1,30 @@
+Each [multi-region topology pattern](topology-patterns.html#multi-region-patterns) assumes the following setup:
+
+<img src="{{ 'images/v19.2/topology-patterns/topology_multi-region_hardware.png' | relative_url }}" alt="Multi-region hardware setup" style="max-width:100%" />
+
+#### Hardware
+
+- 3 regions
+
+- Per region, 3+ AZs with 3+ VMs evenly distributed across them
+
+- Region-specific app instances and load balancers
+    - Each load balancer redirects to CockroachDB nodes in its region.
+    - When CockroachDB nodes are unavailable in a region, the load balancer redirects to nodes in other regions.
+
+#### Cluster
+
+Each node is started with the [`--locality`](start-a-node.html#locality) flag specifying its region and AZ combination, e.g.:
+
+{% include copy-clipboard.html %}
+~~~ shell
+# Example start command for node in the west1 AZ of the us-west region:
+$ cockroach start \
+--locality=region=us-west,zone=west1 \
+--certs-dir=certs \
+--advertise-addr=<node1 internal address> \
+--join=<node1 internal address>:26257,<node2 internal address>:26257,<node3 internal address>:26257 \        
+--cache=.25 \
+--max-sql-memory=.25 \
+--background
+~~~

_includes/v19.2/topology-patterns/see-also.md

@@ -0,0 +1,11 @@
+- [Topology Patterns Overview](topology-patterns.html)
+
+    - Single-region
+        - [Development](topology-development.html)
+        - [Basic Production](topology-basic-production.html)
+
+    - Multi-region
+        - [Geo-Partitioned Replicas](topology-geo-partitioned-replicas.html)
+        - [Geo-Partitioned Leaseholders](topology-geo-partitioned-leaseholders.html)
+        - [Duplicate Indexes](topology-duplicate-indexes.html)
+        - [Follow-the-Workload](topology-follow-the-workload.html)

releases/v19.1.0-rc.1.md

@@ -103,7 +103,7 @@ $ docker pull cockroachdb/cockroach-unstable:v19.1.0-rc.1
 
 ### Doc updates
 
-- Added a library of common [Cluster Topology Patterns](../v19.1/cluster-topology-patterns.html). [#4235](https://github.com/cockroachdb/docs/pull/4235)
+- Added a library of common [Cluster Topology Patterns](../v19.1/topology-patterns.html). [#4235](https://github.com/cockroachdb/docs/pull/4235)
 - Documented how [reads and writes](../v19.1/architecture/reads-and-writes-overview.html) are affected by the replicated and distributed nature of data in CockroachDB. [#4543](https://github.com/cockroachdb/docs/pull/4543)
 - Corrected the syntax for [per-replica replication zone constraints](../v19.1/configure-replication-zones.html#scope-of-constraints). [#4569](https://github.com/cockroachdb/docs/pull/4569)
 - Added more thorough documentation on [CockroachDB dependencies](../v19.1/recommended-production-settings.html#dependencies). [#4567](https://github.com/cockroachdb/docs/pull/4567)

releases/v19.1.0.md

@@ -124,7 +124,7 @@ Topic | Description
 **Security** | Added an [overview of CockroachDB security](../v19.1/security-overview.html), with a dedicated page on [authentication](../v19.1/authentication.html), [encryption](../v19.1/encryption.html), [authorization](../v19.1/authorization.html), and [SQL audit logging](../v19.1/sql-audit-logging.html).
 **Troubleshooting** | Added much more guidance on [troubleshooting cluster setup](../v19.1/cluster-setup-troubleshooting.html) and [troubleshooting SQL behavior](../v19.1/query-behavior-troubleshooting.html).
 **Architecture** | Added the [Life of a Distributed Transaction](../v19.1/architecture/life-of-a-distributed-transaction.html), which details the path that a query takes through CockroachDB's architecture, starting with a SQL client and progressing all the way to RocksDB (and then back out again). Also added [Reads and Writes in CockroachDB](../v19.1/architecture/reads-and-writes-overview.html), which explains how reads and writes are affected by the replicated and distributed nature of data in CockroachDB.
-**Production Guidance** | Expanded the [Production Checklist](../v19.1/recommended-production-settings.html) with more current hardware recommendations and additional guidance on storage, file systems, and clock synchronization. Also added a library of common [Cluster Topology Patterns](../v19.1/cluster-topology-patterns.html).
+**Production Guidance** | Expanded the [Production Checklist](../v19.1/recommended-production-settings.html) with more current hardware recommendations and additional guidance on storage, file systems, and clock synchronization. Also added a library of common [Cluster Topology Patterns](../v19.1/topology-patterns.html).
 **ORMs** | Expanded the [SQLAlchemy tutorial](../v19.1/build-a-python-app-with-cockroachdb-sqlalchemy.html) to provide code for transaction retries and best practices for using SQLAlchemy with CockroachDB.
 **Training** | Added [geo-partitioning](../v19.1/training/geo-partitioning.html), [Kubernetes](../v19.1/training/orchestration-with-kubernetes.html), and [TPC-C benchmarking](../v19.1/training/performance-benchmarking.html) modules to the intro to CockroachDB training.