From 0eb159e4b42198b0c3f1cd213837258757715d3f Mon Sep 17 00:00:00 2001 From: Jesse Seldess Date: Thu, 8 Oct 2020 14:46:03 -0400 Subject: [PATCH] De-emphasize follow-the-workload - Remove follow-the-workload tutorial - Update links to redirect to the ftw topology pattern doc Fixes #8450. --- .../cockroachcloud/app/see-also-links.md | 1 - _includes/sidebar-data-v20.1.json | 6 - _includes/sidebar-data-v20.2.json | 6 - _includes/v20.1/app/see-also-links.md | 1 - .../v20.1/misc/explore-benefits-see-also.md | 1 - _includes/v20.2/app/see-also-links.md | 1 - .../v20.2/misc/explore-benefits-see-also.md | 1 - _redirects | 6 + .../demo-follow-the-workload.md | 0 v20.1/architecture/replication-layer.md | 2 +- v20.1/cockroach-start.md | 2 +- v20.1/configure-replication-zones.md | 2 +- v20.1/show-range-for-row.md | 3 +- v20.1/show-ranges.md | 3 +- v20.1/topology-follow-the-workload.md | 2 +- v20.2/architecture/replication-layer.md | 2 +- v20.2/cockroach-start.md | 2 +- v20.2/configure-replication-zones.md | 2 +- v20.2/demo-follow-the-workload.md | 286 ------------------ v20.2/show-range-for-row.md | 3 +- v20.2/show-ranges.md | 3 +- v20.2/topology-follow-the-workload.md | 2 +- 22 files changed, 18 insertions(+), 319 deletions(-) rename {v20.1 => archived}/demo-follow-the-workload.md (100%) delete mode 100644 v20.2/demo-follow-the-workload.md diff --git a/_includes/cockroachcloud/app/see-also-links.md b/_includes/cockroachcloud/app/see-also-links.md index 2335936901d..ba47496c23f 100644 --- a/_includes/cockroachcloud/app/see-also-links.md +++ b/_includes/cockroachcloud/app/see-also-links.md @@ -5,5 +5,4 @@ You might also be interested in the following pages: - [Fault Tolerance & Recovery](../stable/demo-fault-tolerance-and-recovery.html) - [Automatic Rebalancing](../stable/demo-automatic-rebalancing.html) - [Cross-Cloud Migration](../stable/demo-automatic-cloud-migration.html) -- [Follow-the-Workload](../stable/demo-follow-the-workload.html) - [Automated Operations](../stable/orchestrate-a-local-cluster-with-kubernetes-insecure.html) diff --git a/_includes/sidebar-data-v20.1.json b/_includes/sidebar-data-v20.1.json index d4c53c00c9a..a7626a219e2 100644 --- a/_includes/sidebar-data-v20.1.json +++ b/_includes/sidebar-data-v20.1.json @@ -92,12 +92,6 @@ "/${VERSION}/demo-automatic-cloud-migration.html" ] }, - { - "title": "Follow-the-Workload", - "urls": [ - "/${VERSION}/demo-follow-the-workload.html" - ] - }, { "title": "Orchestration with Kubernetes", "urls": [ diff --git a/_includes/sidebar-data-v20.2.json b/_includes/sidebar-data-v20.2.json index 0df496ed123..666e2308e4e 100644 --- a/_includes/sidebar-data-v20.2.json +++ b/_includes/sidebar-data-v20.2.json @@ -93,12 +93,6 @@ "/${VERSION}/demo-automatic-cloud-migration.html" ] }, - { - "title": "Follow-the-Workload", - "urls": [ - "/${VERSION}/demo-follow-the-workload.html" - ] - }, { "title": "Orchestration with Kubernetes", "urls": [ diff --git a/_includes/v20.1/app/see-also-links.md b/_includes/v20.1/app/see-also-links.md index e5dd6173c99..2d28fdf412b 100644 --- a/_includes/v20.1/app/see-also-links.md +++ b/_includes/v20.1/app/see-also-links.md @@ -5,5 +5,4 @@ You might also be interested in the following pages: - [Fault Tolerance & Recovery](demo-fault-tolerance-and-recovery.html) - [Automatic Rebalancing](demo-automatic-rebalancing.html) - [Cross-Cloud Migration](demo-automatic-cloud-migration.html) -- [Follow-the-Workload](demo-follow-the-workload.html) - [Automated Operations](orchestrate-a-local-cluster-with-kubernetes-insecure.html) diff --git a/_includes/v20.1/misc/explore-benefits-see-also.md b/_includes/v20.1/misc/explore-benefits-see-also.md index 72cbc961e3b..6b1a3afed71 100644 --- a/_includes/v20.1/misc/explore-benefits-see-also.md +++ b/_includes/v20.1/misc/explore-benefits-see-also.md @@ -3,6 +3,5 @@ - [Low Latency Multi-Region Deployment](demo-low-latency-multi-region-deployment.html) - [Serializable Transactions](demo-serializable.html) - [Cross-Cloud Migration](demo-automatic-cloud-migration.html) -- [Follow-the-Workload](demo-follow-the-workload.html) - [Orchestration](orchestrate-a-local-cluster-with-kubernetes-insecure.html) - [JSON Support](demo-json-support.html) diff --git a/_includes/v20.2/app/see-also-links.md b/_includes/v20.2/app/see-also-links.md index e5dd6173c99..2d28fdf412b 100644 --- a/_includes/v20.2/app/see-also-links.md +++ b/_includes/v20.2/app/see-also-links.md @@ -5,5 +5,4 @@ You might also be interested in the following pages: - [Fault Tolerance & Recovery](demo-fault-tolerance-and-recovery.html) - [Automatic Rebalancing](demo-automatic-rebalancing.html) - [Cross-Cloud Migration](demo-automatic-cloud-migration.html) -- [Follow-the-Workload](demo-follow-the-workload.html) - [Automated Operations](orchestrate-a-local-cluster-with-kubernetes-insecure.html) diff --git a/_includes/v20.2/misc/explore-benefits-see-also.md b/_includes/v20.2/misc/explore-benefits-see-also.md index 72cbc961e3b..6b1a3afed71 100644 --- a/_includes/v20.2/misc/explore-benefits-see-also.md +++ b/_includes/v20.2/misc/explore-benefits-see-also.md @@ -3,6 +3,5 @@ - [Low Latency Multi-Region Deployment](demo-low-latency-multi-region-deployment.html) - [Serializable Transactions](demo-serializable.html) - [Cross-Cloud Migration](demo-automatic-cloud-migration.html) -- [Follow-the-Workload](demo-follow-the-workload.html) - [Orchestration](orchestrate-a-local-cluster-with-kubernetes-insecure.html) - [JSON Support](demo-json-support.html) diff --git a/_redirects b/_redirects index 11d52c74537..dcb2732abd7 100644 --- a/_redirects +++ b/_redirects @@ -12,6 +12,12 @@ layout: null /docs/advisories/ /docs/advisories/index.html 200! /docs/*/contribute-to-cockroachdb.html https://wiki.crdb.io/wiki/spaces/CRDB/pages/73204033/Contributing+to+CockroachDB 301! +# Removed pages +/docs/v20.1/demo-follow-the-workload.html /docs/v20.1/topology-follow-the-workload.html 301! +/docs/v20.2/demo-follow-the-workload.html /docs/v20.2/topology-follow-the-workload.html 301! +/docs/stable/demo-follow-the-workload.html /docs/stable/topology-follow-the-workload.html 301! +/docs/dev/demo-follow-the-workload.html /docs/dev/topology-follow-the-workload.html 301! + # Old training pages redirect to Cockroach University /docs/*/training/* https://university.cockroachlabs.com 301! diff --git a/v20.1/demo-follow-the-workload.md b/archived/demo-follow-the-workload.md similarity index 100% rename from v20.1/demo-follow-the-workload.md rename to archived/demo-follow-the-workload.md diff --git a/v20.1/architecture/replication-layer.md b/v20.1/architecture/replication-layer.md index e73944f6eed..07d8f531323 100644 --- a/v20.1/architecture/replication-layer.md +++ b/v20.1/architecture/replication-layer.md @@ -85,7 +85,7 @@ Because CockroachDB serves reads from a range's leaseholder, it benefits your cl {{site.data.alerts.callout_info}} -This feature is also called [Follow-the-Workload](../demo-follow-the-workload.html) in our documentation. +This feature is also called [Follow-the-Workload](../topology-follow-the-workload.html) in our documentation. {{site.data.alerts.end}} diff --git a/v20.1/cockroach-start.md b/v20.1/cockroach-start.md index 3adb2298163..823df34fdc5 100644 --- a/v20.1/cockroach-start.md +++ b/v20.1/cockroach-start.md @@ -100,7 +100,7 @@ The `--locality` flag accepts arbitrary key-value pairs that describe the locati - CockroachDB spreads the replicas of each piece of data across as diverse a set of localities as possible, with the order determining the priority. Locality can also be used to influence the location of data replicas in various ways using [replication zones](configure-replication-zones.html#replication-constraints). -- When there is high latency between nodes (e.g., cross-datacenter deployments), CockroachDB uses locality to move range leases closer to the current workload, reducing network round trips and improving read performance, also known as ["follow-the-workload"](demo-follow-the-workload.html). In a deployment across more than 3 datacenters, however, to ensure that all data benefits from "follow-the-workload", you must increase your replication factor to match the total number of datacenters. +- When there is high latency between nodes (e.g., cross-datacenter deployments), CockroachDB uses locality to move range leases closer to the current workload, reducing network round trips and improving read performance, also known as ["follow-the-workload"](topology-follow-the-workload.html). In a deployment across more than 3 datacenters, however, to ensure that all data benefits from "follow-the-workload", you must increase your replication factor to match the total number of datacenters. - Locality is also a prerequisite for using the [table partitioning](partitioning.html) and [**Node Map**](enable-node-map.html) enterprise features. diff --git a/v20.1/configure-replication-zones.md b/v20.1/configure-replication-zones.md index 24b4bc8b724..636688e1c05 100644 --- a/v20.1/configure-replication-zones.md +++ b/v20.1/configure-replication-zones.md @@ -98,7 +98,7 @@ When starting a node with the [`cockroach start`](cockroach-start.html) command, Attribute Type | Description ---------------|------------ -**Node Locality** | Using the [`--locality`](cockroach-start.html#locality) flag, you can assign arbitrary key-value pairs that describe the location of the node. Locality might include region, country, datacenter, rack, etc. The key-value pairs should be ordered into _locality tiers_ that range from most inclusive to least inclusive (e.g., region before datacenter as in `region=eu,dc=paris`), and the keys and the order of key-value pairs must be the same on all nodes. It's typically better to include more pairs than fewer. For example:

`--locality=region=east,datacenter=us-east-1`
`--locality=region=east,datacenter=us-east-2`
`--locality=region=west,datacenter=us-west-1`

CockroachDB attempts to spread replicas evenly across the cluster based on locality, with the order of locality tiers determining the priority. Locality can also be used to influence the location of data replicas in various ways using replication zones.

When there is high latency between nodes, CockroachDB uses locality to move range leases closer to the current workload, reducing network round trips and improving read performance. See [Follow-the-workload](demo-follow-the-workload.html) for more details. +**Node Locality** | Using the [`--locality`](cockroach-start.html#locality) flag, you can assign arbitrary key-value pairs that describe the location of the node. Locality might include region, country, datacenter, rack, etc. The key-value pairs should be ordered into _locality tiers_ that range from most inclusive to least inclusive (e.g., region before datacenter as in `region=eu,dc=paris`), and the keys and the order of key-value pairs must be the same on all nodes. It's typically better to include more pairs than fewer. For example:

`--locality=region=east,datacenter=us-east-1`
`--locality=region=east,datacenter=us-east-2`
`--locality=region=west,datacenter=us-west-1`

CockroachDB attempts to spread replicas evenly across the cluster based on locality, with the order of locality tiers determining the priority. Locality can also be used to influence the location of data replicas in various ways using replication zones.

When there is high latency between nodes, CockroachDB uses locality to move range leases closer to the current workload, reducing network round trips and improving read performance. See [Follow-the-workload](topology-follow-the-workload.html) for more details. **Node Capability** | Using the `--attrs` flag, you can specify node capability, which might include specialized hardware or number of cores, for example:

`--attrs=ram:64gb` **Store Type/Capability** | Using the `attrs` field of the `--store` flag, you can specify disk type or capability, for example:

`--store=path=/mnt/ssd01,attrs=ssd`
`--store=path=/mnt/hda1,attrs=hdd:7200rpm` diff --git a/v20.1/show-range-for-row.md b/v20.1/show-range-for-row.md index 5044c6a3e9a..b9311a9a200 100644 --- a/v20.1/show-range-for-row.md +++ b/v20.1/show-range-for-row.md @@ -82,5 +82,4 @@ Field | Description - [`CREATE INDEX`](create-index.html) - [Indexes](indexes.html) - [Partitioning tables](partitioning.html) -+ [Follow-the-Workload](demo-follow-the-workload.html) -+ [Architecture Overview](architecture/overview.html) +- [Architecture Overview](architecture/overview.html) diff --git a/v20.1/show-ranges.md b/v20.1/show-ranges.md index 26cee3922aa..4bcfd8c7b10 100644 --- a/v20.1/show-ranges.md +++ b/v20.1/show-ranges.md @@ -121,5 +121,4 @@ Field | Description - [`CREATE INDEX`](create-index.html) - [Indexes](indexes.html) - [Partitioning tables](partitioning.html) -+ [Follow-the-Workload](demo-follow-the-workload.html) -+ [Architecture Overview](architecture/overview.html) +- [Architecture Overview](architecture/overview.html) diff --git a/v20.1/topology-follow-the-workload.md b/v20.1/topology-follow-the-workload.md index 461a62e0c81..a36170c8851 100644 --- a/v20.1/topology-follow-the-workload.md +++ b/v20.1/topology-follow-the-workload.md @@ -27,7 +27,7 @@ If read performance is your main focus for a table, but you want low-latency rea ## Configuration -Aside from [deploying a cluster across three regions](#cluster-setup) properly, with each node started with the [`--locality`](cockroach-start.html#locality) flag specifying its region and AZ combination, this pattern requires no extra configuration. CockroachDB will balance the replicas for a table across the three regions and will assign the range lease to the replica in the region with the greatest demand at any given time (the [follow-the-workload](demo-follow-the-workload.html) feature). This means that read latency in the active region will be low while read latency in other regions will be higher due to having to leave the region to reach the leaseholder. Write latency will be higher as well due to always involving replicas in multiple regions. +Aside from [deploying a cluster across three regions](#cluster-setup) properly, with each node started with the [`--locality`](cockroach-start.html#locality) flag specifying its region and AZ combination, this pattern requires no extra configuration. CockroachDB will balance the replicas for a table across the three regions and will assign the range lease to the replica in the region with the greatest demand at any given time (the follow-the-workload feature). This means that read latency in the active region will be low while read latency in other regions will be higher due to having to leave the region to reach the leaseholder. Write latency will be higher as well due to always involving replicas in multiple regions. Follower reads topology diff --git a/v20.2/architecture/replication-layer.md b/v20.2/architecture/replication-layer.md index e73944f6eed..07d8f531323 100644 --- a/v20.2/architecture/replication-layer.md +++ b/v20.2/architecture/replication-layer.md @@ -85,7 +85,7 @@ Because CockroachDB serves reads from a range's leaseholder, it benefits your cl {{site.data.alerts.callout_info}} -This feature is also called [Follow-the-Workload](../demo-follow-the-workload.html) in our documentation. +This feature is also called [Follow-the-Workload](../topology-follow-the-workload.html) in our documentation. {{site.data.alerts.end}} diff --git a/v20.2/cockroach-start.md b/v20.2/cockroach-start.md index 7e540c57a57..c7c896d3a61 100644 --- a/v20.2/cockroach-start.md +++ b/v20.2/cockroach-start.md @@ -100,7 +100,7 @@ The `--locality` flag accepts arbitrary key-value pairs that describe the locati - CockroachDB spreads the replicas of each piece of data across as diverse a set of localities as possible, with the order determining the priority. Locality can also be used to influence the location of data replicas in various ways using [replication zones](configure-replication-zones.html#replication-constraints). -- When there is high latency between nodes (e.g., cross-datacenter deployments), CockroachDB uses locality to move range leases closer to the current workload, reducing network round trips and improving read performance, also known as ["follow-the-workload"](demo-follow-the-workload.html). In a deployment across more than 3 datacenters, however, to ensure that all data benefits from "follow-the-workload", you must increase your replication factor to match the total number of datacenters. +- When there is high latency between nodes (e.g., cross-datacenter deployments), CockroachDB uses locality to move range leases closer to the current workload, reducing network round trips and improving read performance, also known as ["follow-the-workload"](topology-follow-the-workload.html). In a deployment across more than 3 datacenters, however, to ensure that all data benefits from "follow-the-workload", you must increase your replication factor to match the total number of datacenters. - Locality is also a prerequisite for using the [table partitioning](partitioning.html) and [**Node Map**](enable-node-map.html) enterprise features. diff --git a/v20.2/configure-replication-zones.md b/v20.2/configure-replication-zones.md index 24b4bc8b724..636688e1c05 100644 --- a/v20.2/configure-replication-zones.md +++ b/v20.2/configure-replication-zones.md @@ -98,7 +98,7 @@ When starting a node with the [`cockroach start`](cockroach-start.html) command, Attribute Type | Description ---------------|------------ -**Node Locality** | Using the [`--locality`](cockroach-start.html#locality) flag, you can assign arbitrary key-value pairs that describe the location of the node. Locality might include region, country, datacenter, rack, etc. The key-value pairs should be ordered into _locality tiers_ that range from most inclusive to least inclusive (e.g., region before datacenter as in `region=eu,dc=paris`), and the keys and the order of key-value pairs must be the same on all nodes. It's typically better to include more pairs than fewer. For example:

`--locality=region=east,datacenter=us-east-1`
`--locality=region=east,datacenter=us-east-2`
`--locality=region=west,datacenter=us-west-1`

CockroachDB attempts to spread replicas evenly across the cluster based on locality, with the order of locality tiers determining the priority. Locality can also be used to influence the location of data replicas in various ways using replication zones.

When there is high latency between nodes, CockroachDB uses locality to move range leases closer to the current workload, reducing network round trips and improving read performance. See [Follow-the-workload](demo-follow-the-workload.html) for more details. +**Node Locality** | Using the [`--locality`](cockroach-start.html#locality) flag, you can assign arbitrary key-value pairs that describe the location of the node. Locality might include region, country, datacenter, rack, etc. The key-value pairs should be ordered into _locality tiers_ that range from most inclusive to least inclusive (e.g., region before datacenter as in `region=eu,dc=paris`), and the keys and the order of key-value pairs must be the same on all nodes. It's typically better to include more pairs than fewer. For example:

`--locality=region=east,datacenter=us-east-1`
`--locality=region=east,datacenter=us-east-2`
`--locality=region=west,datacenter=us-west-1`

CockroachDB attempts to spread replicas evenly across the cluster based on locality, with the order of locality tiers determining the priority. Locality can also be used to influence the location of data replicas in various ways using replication zones.

When there is high latency between nodes, CockroachDB uses locality to move range leases closer to the current workload, reducing network round trips and improving read performance. See [Follow-the-workload](topology-follow-the-workload.html) for more details. **Node Capability** | Using the `--attrs` flag, you can specify node capability, which might include specialized hardware or number of cores, for example:

`--attrs=ram:64gb` **Store Type/Capability** | Using the `attrs` field of the `--store` flag, you can specify disk type or capability, for example:

`--store=path=/mnt/ssd01,attrs=ssd`
`--store=path=/mnt/hda1,attrs=hdd:7200rpm` diff --git a/v20.2/demo-follow-the-workload.md b/v20.2/demo-follow-the-workload.md deleted file mode 100644 index c120acc3e07..00000000000 --- a/v20.2/demo-follow-the-workload.md +++ /dev/null @@ -1,286 +0,0 @@ ---- -title: Follow-the-Workload -summary: CockroachDB can dynamically optimize read latency for the location from which most of the workload is originating. -toc: true ---- - -"Follow-the-workload" refers to CockroachDB's ability to dynamically optimize read latency for the location from which most of the workload is originating. This page explains how "follow-the-workload" works and walks you through a simple demonstration using a local cluster. - -{{site.data.alerts.callout_info}} -In practice, follow-the-workload is most useful when a CockroachDB cluster is running across multiple regions, with high latency between them, but other patterns are often preferable. For more details, see [Multi-Region Topology Patterns](topology-patterns.html#multi-region-patterns). -{{site.data.alerts.end}} - -## Before you begin - -### Basic concepts - -To understand how "follow-the-workload" works, it's important to start with some basic concepts: - -Concept | Description ---------|------------ -**Range** | CockroachDB stores all user data (tables, indexes, etc.) and almost all system data in a giant sorted map of key-value pairs. This keyspace is divided into "ranges", contiguous chunks of the keyspace, so that every key can always be found in a single range. -**Replica** | CockroachDB replicates each range (3 times by default) and stores each replica on a different node. -**Leaseholder** | For each range, one of the replicas holds the "range lease". This replica, referred to as the "leaseholder", is the one that receives and coordinates all read and write requests for the range.

Unlike writes, read requests access the leaseholder and send the results to the client without needing to coordinate with any of the other range replicas. This reduces the network round trips involved and is possible because the leaseholder is guaranteed to be up-to-date due to the fact that all write requests also go to the leaseholder. - -### How it works - -"Follow-the-workload" is based on the way **range leases** handle read requests. Read requests bypass the Raft consensus protocol, accessing the range replica that holds the range lease (the leaseholder) and sending the results to the client without needing to coordinate with any of the other range replicas. Bypassing Raft, and the network round trips involved, is possible because the leaseholder is guaranteed to be up-to-date due to the fact that all write requests also go to the leaseholder. - -This increases the speed of reads, but it doesn't guarantee that the range lease will be anywhere close to the origin of requests. If requests are coming from the US West, for example, and the relevant range lease is on a node in the US East, the requests would likely enter a gateway node in the US West and then get routed to the node with the range lease in the US East. - -However, you can cause the cluster to actively move range leases for even better read performance by starting each node with the [`--locality`](cockroach-start.html#locality) flag. With this flag specified, the cluster knows about the location of each node, so when there's high latency between nodes, the cluster will move active range leases to a node closer to the origin of the majority of the workload. This is especially helpful for applications with workloads that move around throughout the day (e.g., most of the traffic is in the US East in the morning and in the US West in the evening). - -{{site.data.alerts.callout_success}} -To enable "follow-the-workload", you just need to start each node of the cluster with the `--locality` flag, as shown in the tutorial below. No additional user action is required. -{{site.data.alerts.end}} - -### Example - -In this example, let's imagine that lots of read requests are going to node 1, and that the requests are for data in range 3. Because range 3's lease is on node 3, the requests are routed to node 3, which returns the results to node 1. Node 1 then responds to the clients. - -Follow-the-workload example - -However, if the nodes were started with the [`--locality`](cockroach-start.html#locality) flag, after a short while, the cluster would move range 3's lease to node 1, which is closer to the origin of the workload, thus reducing the network round trips and increasing the speed of reads. - -Follow-the-workload example - -## Step 1. Install prerequisites - -In this tutorial, you'll use CockroachDB, the `comcast` network tool to simulate network latency on your local workstation, and the `tpcc` workload built into CockroachDB to simulate client workloads. Before you begin, make sure these applications are installed: - -- Install the latest version of [CockroachDB](install-cockroachdb.html). -- Install [Go](https://golang.org/doc/install) version 1.9 or higher. If you're on a Mac and using Homebrew, use `brew install go`. You can check your local version by running `go version`. -- Install the [`comcast`](https://github.com/tylertreat/comcast) network simulation tool: `go get github.com/tylertreat/comcast` - -Also, to keep track of the data files and logs for your cluster, you may want to create a new directory (e.g., `mkdir follow-workload`) and start all your nodes in that directory. - -## Step 2. Start the cluster - -Use the [`cockroach start`](cockroach-start.html) command to start 3 nodes on your local workstation, using the [`--locality`](cockroach-start.html#locality) flag to pretend that each node is in a different region of the US. - -1. Start a node in the "US West": - - {% include copy-clipboard.html %} - ~~~ shell - $ cockroach start \ - --insecure \ - --locality=region=us-west \ - --store=follow1 \ - --listen-addr=localhost:26257 \ - --http-addr=localhost:8080 \ - --join=localhost:26257,localhost:26258,localhost:26259 \ - --background - ~~~ - -2. Start a node in the "US Midwest": - - {% include copy-clipboard.html %} - ~~~ shell - $ cockroach start \ - --insecure \ - --locality=region=us-midwest \ - --store=follow2 \ - --listen-addr=localhost:26258 \ - --http-addr=localhost:8081 \ - --join=localhost:26257,localhost:26258,localhost:26259 \ - --background - ~~~ - -3. Start a node in the "US East": - - {% include copy-clipboard.html %} - ~~~ shell - $ cockroach start \ - --insecure \ - --locality=region=us-east \ - --store=follow3 \ - --listen-addr=localhost:26259 \ - --http-addr=localhost:8082 \ - --join=localhost:26257,localhost:26258,localhost:26259 \ - --background - ~~~ - -4. Use the [`cockroach init`](cockroach-init.html) command to perform a one-time initialization of the cluster: - - {% include copy-clipboard.html %} - ~~~ shell - $ cockroach init \ - --insecure \ - --host=localhost:26257 - ~~~ - -## Step 3. Simulate network latency - -"Follow-the-workload" only kicks in when there's high latency between the nodes of the CockroachDB cluster. In this tutorial, you'll run 3 nodes on your local workstation, with each node pretending to be in a different region of the US. To simulate latency between the nodes, use the `comcast` tool that you installed earlier. - -1. Start `comcast` as follows: - - {% include copy-clipboard.html %} - ~~~ shell - $ comcast --device lo0 --latency 100 - ~~~ - - For the `--device` flag, use `lo0` if you're on Mac or `lo` if you're on Linux. If neither works, run the `ifconfig` command and find the interface responsible for `127.0.0.1` in the output. - - This command causes a 100 millisecond delay for all requests on the loopback interface of your local workstation. It will only affect connections from the machine to itself, not to/from the Internet. - -2. To verify the delay between nodes, check the **Network Latency** page of the Admin UI: - - CockroachDB Admin UI - -## Step 4. Simulate traffic in the US East - -Now that the cluster is live, use CockroachDB's [built-in version the `tpcc` benchmark](cockroach-workload.html) to simulate multiple client connections to the node in the "US East". - -1. Load the initial schema and data, pointing it at port `26259`, which is the port of the node with the `us-east` locality: - - {% include copy-clipboard.html %} - ~~~ shell - $ cockroach workload init tpcc \ - 'postgresql://root@localhost:26259?sslmode=disable' - ~~~ - -2. Let the workload run to completion. - -## Step 5. Check the location of the range lease - -The load generator created a `tpcc` database with several tables that map to underlying key-value ranges. Verify that the range lease for the `customer` table moved to the node in the "US East" as follows. - -1. Run the [`cockroach node status`](cockroach-node.html) command against any node: - - {% include copy-clipboard.html %} - ~~~ shell - $ cockroach node status --insecure --host=localhost:26259 - ~~~ - - ~~~ - id | address | sql_address | build | started_at | updated_at | locality | is_available | is_live - +----+-----------------+-----------------+-----------------------------------------+----------------------------------+----------------------------------+-------------------+--------------+---------+ - 1 | localhost:26257 | localhost:26257 | v19.2.0-alpha.20190606-2491-gfe735c9a97 | 2019-09-28 03:14:20.566372+00:00 | 2019-09-28 03:18:41.866604+00:00 | region=us-west | true | true - 2 | localhost:26259 | localhost:26259 | v19.2.0-alpha.20190606-2491-gfe735c9a97 | 2019-09-28 03:14:21.353188+00:00 | 2019-09-28 03:18:38.165272+00:00 | region=us-east | true | true - 3 | localhost:26258 | localhost:26258 | v19.2.0-alpha.20190606-2491-gfe735c9a97 | 2019-09-28 03:14:21.862969+00:00 | 2019-09-28 03:18:38.577831+00:00 | region=us-midwest | true | true - (3 rows) - ~~~ - -2. In the response, note the ID of the node running on port `26259` (in this case, node 2). - -3. Connect the [built-in SQL shell](cockroach-sql.html) to any node: - - {% include copy-clipboard.html %} - ~~~ shell - $ cockroach sql --insecure --host=localhost:26259 - ~~~ - -4. Check where the range lease is for the `tpcc.customer` table: - - {% include copy-clipboard.html %} - ~~~ sql - > SHOW RANGES FROM TABLE tpcc.customer; - ~~~ - - ~~~ - start_key | end_key | range_id | range_size_mb | lease_holder | lease_holder_locality | replicas | replica_localities - +-----------+---------+----------+---------------+--------------+-----------------------+----------+---------------------------------------------------+ - NULL | NULL | 28 | 19.194141 | 2 | region=us-east | {1,2,3} | {region=us-west,region=us-east,region=us-midwest} - (1 row) - ~~~ - - `lease_holder` and `replicas` indicate the node IDs. As you can see, the lease for the range holding the `customer` table's data is on node 2, which is the same ID as the node on port `26259`. - -5. Exit the SQL shell: - - {% include copy-clipboard.html %} - ~~~ sql - > \q - ~~~ - -## Step 6. Simulate traffic in the US West - -1. Run the [`cockroach workload run tpcc`](cockroach-workload.html) command to generate more load, this time pointing it at port `26257`, which is the port of the node with the `us-west` locality: - - {% include copy-clipboard.html %} - ~~~ shell - $ cockroach workload run tpcc \ - --duration=5m \ - 'postgresql://root@localhost:26257?sslmode=disable' - ~~~ - - You'll see per-operation statistics print to standard output every second. - -2. Let the workload run to completion. This is necessary since the system will still "remember" the earlier requests to the other locality. - - {{site.data.alerts.callout_info}} - The latency numbers printed by the workload will be over 200 milliseconds because the 100 millisecond delay in each direction (200ms round-trip) caused by the `comcast` tool also applies to the traffic going from the `tpcc` process to the `cockroach` process. If you were to set up more advanced rules that excluded the `tpcc` process's traffic or to run this on a real network with real network delay, these numbers would be down in the single-digit milliseconds. - {{site.data.alerts.end}} - -## Step 7. Check the location of the range lease - -Verify that the range lease for the `customer` table moved to the node in the "US West" as follows. - -1. Connect the [built-in SQL shell](cockroach-sql.html) to any node: - - {% include copy-clipboard.html %} - ~~~ shell - $ cockroach sql --insecure --host=localhost:26257 - ~~~ - -2. Check where the range lease is for the `tpcc.customer` table: - - {% include copy-clipboard.html %} - ~~~ sql - > SHOW RANGES FROM TABLE tpcc.customer; - ~~~ - - ~~~ - start_key | end_key | range_id | range_size_mb | lease_holder | lease_holder_locality | replicas | replica_localities - +-----------+---------+----------+---------------+--------------+-----------------------+----------+---------------------------------------------------+ - NULL | NULL | 28 | 19.194141 | 1 | region=us-west | {1,2,3} | {region=us-west,region=us-east,region=us-midwest} - (1 row) - ~~~ - - As you can see, the lease for the range holding the `customer` table's data is now on node 1, which is the same ID as the node on port `26257`. - -## Step 8. Clean up - -1. Once you're done with this tutorial, you will not want a 100 millisecond delay for all requests on your local workstation, so stop the `comcast` tool: - - {% include copy-clipboard.html %} - ~~~ shell - $ comcast --device lo0 --stop - ~~~ - -2. Use the [`cockroach quit`](cockroach-quit.html) command to gracefully shut down each node: - - {% include copy-clipboard.html %} - ~~~ shell - $ cockroach quit --insecure --host=localhost:26257 - ~~~ - - {% include copy-clipboard.html %} - ~~~ shell - $ cockroach quit --insecure --host=localhost:26258 - ~~~ - - {{site.data.alerts.callout_info}} - For the last node, the shutdown process will take longer (about a minute each) and will eventually force the node to stop. This is because, with only 1 of 3 nodes left, a majority of replicas are not available, and so the cluster is no longer operational. - {{site.data.alerts.end}} - - {% include copy-clipboard.html %} - ~~~ shell - $ cockroach quit --insecure --host=localhost:26259 - ~~~ - -3. To restart the cluster at a later time, run the same `cockroach start` commands as earlier from the directory containing the nodes' data stores. - - If you do not plan to restart the cluster, you may want to remove the nodes' data stores: - - {% include copy-clipboard.html %} - ~~~ shell - $ rm -rf follow1 follow2 follow3 - ~~~ - -## What's next? - -Explore other core CockroachDB benefits and features: - -{% include {{ page.version.version }}/misc/explore-benefits-see-also.md %} diff --git a/v20.2/show-range-for-row.md b/v20.2/show-range-for-row.md index 5044c6a3e9a..b9311a9a200 100644 --- a/v20.2/show-range-for-row.md +++ b/v20.2/show-range-for-row.md @@ -82,5 +82,4 @@ Field | Description - [`CREATE INDEX`](create-index.html) - [Indexes](indexes.html) - [Partitioning tables](partitioning.html) -+ [Follow-the-Workload](demo-follow-the-workload.html) -+ [Architecture Overview](architecture/overview.html) +- [Architecture Overview](architecture/overview.html) diff --git a/v20.2/show-ranges.md b/v20.2/show-ranges.md index 26cee3922aa..4bcfd8c7b10 100644 --- a/v20.2/show-ranges.md +++ b/v20.2/show-ranges.md @@ -121,5 +121,4 @@ Field | Description - [`CREATE INDEX`](create-index.html) - [Indexes](indexes.html) - [Partitioning tables](partitioning.html) -+ [Follow-the-Workload](demo-follow-the-workload.html) -+ [Architecture Overview](architecture/overview.html) +- [Architecture Overview](architecture/overview.html) diff --git a/v20.2/topology-follow-the-workload.md b/v20.2/topology-follow-the-workload.md index 882ac86ed3c..19b175875da 100644 --- a/v20.2/topology-follow-the-workload.md +++ b/v20.2/topology-follow-the-workload.md @@ -27,7 +27,7 @@ If read performance is your main focus for a table, but you want low-latency rea ## Configuration -Aside from [deploying a cluster across three regions](#cluster-setup) properly, with each node started with the [`--locality`](cockroach-start.html#locality) flag specifying its region and AZ combination, this pattern requires no extra configuration. CockroachDB will balance the replicas for a table across the three regions and will assign the range lease to the replica in the region with the greatest demand at any given time (the [follow-the-workload](demo-follow-the-workload.html) feature). This means that read latency in the active region will be low while read latency in other regions will be higher due to having to leave the region to reach the leaseholder. Write latency will be higher as well due to always involving replicas in multiple regions. +Aside from [deploying a cluster across three regions](#cluster-setup) properly, with each node started with the [`--locality`](cockroach-start.html#locality) flag specifying its region and AZ combination, this pattern requires no extra configuration. CockroachDB will balance the replicas for a table across the three regions and will assign the range lease to the replica in the region with the greatest demand at any given time (the follow-the-workload feature). This means that read latency in the active region will be low while read latency in other regions will be higher due to having to leave the region to reach the leaseholder. Write latency will be higher as well due to always involving replicas in multiple regions. Follower reads topology