Updated multi-region application tutorial for 21.1 #10735
Conversation
|
This change is |
|
✔️ Netlify Preview 🔨 Explore the source changes: 73e1ff4 🔍 Inspect the deploy log: https://app.netlify.com/sites/cockroachdb-docs/deploys/60d9f2dc8af4b800088b8e58 😎 Browse the preview: https://deploy-preview-10735--cockroachdb-docs.netlify.app/docs/v21.1/movr-flask-use-case |
There was a problem hiding this comment.
As discussed on slack, I've reviewed v21.1/movr-flask-use-case.md and v21.1/movr-flask-database.md -- these look good to me. I left a minor suggestion on the use-case.md, but it's your call on whether it's worth including.
Reviewable status:
complete! 0 of 0 LGTMs obtained (waiting on @ericharmeling)
v21.1/movr-flask-use-case.md, line 18 at r2 (raw file):
For an application to be resilient to system failures, the application and database need to be deployed on multiple machines (i.e., part of a distributed deployment). In distributed CockroachDB deployments, all data is replicated and distributed across the instances of the database that make up the deployment. For more information about data replication and distribution in CockroachDB, see [The Raft Protocol in CockroachDB](https://www.youtube.com/watch?v=k5BR9m8o9ec&feature=youtu.be). The replication and distribution of data across multiple machines in a *single region* makes the deployment resilient to individual node failures within the region. Replication and distribution across *multiple regions* makes the deployment resilient to entire regional failures. To achieve the highest level of resiliency, we use a multi-region deployment for MovR database and application.
Would it make sense to add the concept of zone failure here (as we offer that in our multi-region abstractions as the default) or is it too overkill?
|
TFTR, @arulajmani !
I don't think we need to add it here, TBH, as this app's multi-region configuration doesn't explicitly use zones. But that could be an enhancement later on. |
ericharmeling
force-pushed
the
21.1-movr-flask
branch
from
6b236b3
to
5678f34
Compare
There was a problem hiding this comment.
Looks good! Some suggestions; most pretty minor. You'll see that in several places I suggested that movr-flask repo be changed to \movr-flask` repository. This is very much your call - still an open style discussion. Heads up that I think I missed a couple instances. Might be better for a global find/replace locally.
| @@ -0,0 +1,7 @@ | |||
| {{site.data.alerts.callout_info}} | |||
| CockroachDB versions v21.1+ support [new multi-region capabilities, with different SQL syntax](https://www.cockroachlabs.com/docs/v21.1/multiregion-overview.html). | |||
There was a problem hiding this comment.
| CockroachDB versions v21.1+ support [new multi-region capabilities, with different SQL syntax](https://www.cockroachlabs.com/docs/v21.1/multiregion-overview.html). | |
| CockroachDB versions v21.1 and above support [new multi-region capabilities, with different SQL syntax](https://www.cockroachlabs.com/docs/v21.1/multiregion-overview.html). |
| {{site.data.alerts.callout_info}} | ||
| CockroachDB versions v21.1+ support [new multi-region capabilities, with different SQL syntax](https://www.cockroachlabs.com/docs/v21.1/multiregion-overview.html). | ||
|
|
||
| For the latest version of the application and database schema built on v21.1 multi-region features, see the [movr-flask repo](https://github.com/cockroachlabs/movr-flask). |
There was a problem hiding this comment.
| For the latest version of the application and database schema built on v21.1 multi-region features, see the [movr-flask repo](https://github.com/cockroachlabs/movr-flask). | |
| For the latest version of the application and database schema built on v21.1 multi-region features, see the [`movr-flask` repository](https://github.com/cockroachlabs/movr-flask). |
| @@ -0,0 +1,7 @@ | |||
| {{site.data.alerts.callout_info}} | |||
| CockroachDB versions v21.1+ support [new multi-region capabilities, with different SQL syntax](https://www.cockroachlabs.com/docs/v21.1/multiregion-overview.html). | |||
There was a problem hiding this comment.
| CockroachDB versions v21.1+ support [new multi-region capabilities, with different SQL syntax](https://www.cockroachlabs.com/docs/v21.1/multiregion-overview.html). | |
| CockroachDB versions v21.1 and above support [new multi-region capabilities, with different SQL syntax](https://www.cockroachlabs.com/docs/v21.1/multiregion-overview.html). |
| @@ -0,0 +1,7 @@ | |||
| {{site.data.alerts.callout_info}} | |||
| CockroachDB versions v21.1+ support [new multi-region capabilities, with different SQL syntax](https://www.cockroachlabs.com/docs/v21.1/multiregion-overview.html). | |||
There was a problem hiding this comment.
| CockroachDB versions v21.1+ support [new multi-region capabilities, with different SQL syntax](https://www.cockroachlabs.com/docs/v21.1/multiregion-overview.html). | |
| CockroachDB versions v21.1 and above support [new multi-region capabilities, with different SQL syntax](https://www.cockroachlabs.com/docs/v21.1/multiregion-overview.html). |
| {{site.data.alerts.callout_info}} | ||
| CockroachDB versions v21.1+ support [new multi-region capabilities, with different SQL syntax](https://www.cockroachlabs.com/docs/v21.1/multiregion-overview.html). | ||
|
|
||
| For the latest version of the application and database schema built on v21.1 multi-region features, see the [movr-flask repo](https://github.com/cockroachlabs/movr-flask). |
There was a problem hiding this comment.
| For the latest version of the application and database schema built on v21.1 multi-region features, see the [movr-flask repo](https://github.com/cockroachlabs/movr-flask). | |
| For the latest version of the application and database schema built on v21.1 multi-region features, see the [`movr-flask` repository](https://github.com/cockroachlabs/movr-flask). |
v21.1/movr-flask-deployment.md
Outdated
| - Under **Advanced settings**->**Variables & Secrets**, do the following: | ||
| - Set an environment variable named `DB_URI` to the connection string for a gateway node on the CC cluster, in the region in which this first Cloud Run service is located (e.g., `cockroachdb://user:password@movr-db.gcp-us-east1.cockroachlabs.cloud:26257/movr?sslmode=verify-full&sslrootcert=certs/movr-db-ca.crt`). | ||
| - Set an environment variable named `REGION` to the CC region (e.g., `gcp-us-east1`). | ||
| - Create a secret for the CC certificate, and mount it on the `certs` volume, with a full path ending in the name of the cert (e.g., `certs/movr-db-ca.crt`). This is the cert downloaded from the CC Console, and referenced in the `DB_URI` connection string. |
There was a problem hiding this comment.
| - Create a secret for the CC certificate, and mount it on the `certs` volume, with a full path ending in the name of the cert (e.g., `certs/movr-db-ca.crt`). This is the cert downloaded from the CC Console, and referenced in the `DB_URI` connection string. | |
| - Create a secret for the CockroachCloud certificate and mount it on the `certs` volume with a full path ending in the name of the cert (e.g., `certs/movr-db-ca.crt`). This is the cert downloaded from the CockroachCloud Console and referenced in the `DB_URI` connection string. |
v21.1/movr-flask-deployment.md
Outdated
|
|
||
| ### Develop your own application | ||
|
|
||
| This tutorial demonstrates how to develop and deploy an example multi-region application. Most of the development instructions are specific to Python, Flask, and SQLAlchemy, and most of the deployment instructions are specific to Google Cloud Platform. CockroachDB supports [many more drivers and ORM's for development](hello-world-example-apps.html), and you can deploy applications using a number of cloud provider orchestration tools and networking services. We encourage you to modify the code and deployments to fit your framework and use case. |
There was a problem hiding this comment.
| This tutorial demonstrates how to develop and deploy an example multi-region application. Most of the development instructions are specific to Python, Flask, and SQLAlchemy, and most of the deployment instructions are specific to Google Cloud Platform. CockroachDB supports [many more drivers and ORM's for development](hello-world-example-apps.html), and you can deploy applications using a number of cloud provider orchestration tools and networking services. We encourage you to modify the code and deployments to fit your framework and use case. | |
| This tutorial demonstrates how to develop and deploy an example multi-region application. Most of the development instructions are specific to Python, Flask, and SQLAlchemy, and most of the deployment instructions are specific to Google Cloud Platform (GCP). CockroachDB supports [many more drivers and ORMs for development](hello-world-example-apps.html), and you can deploy applications using a number of cloud provider orchestration tools and networking services. We encourage you to modify the code and deployments to fit your framework and use case. |
| The replication and distribution of data across multiple machines in a *single region* makes the deployment resilient to individual node failures within the region. Replication and distribution across *multiple regions* makes the deployment resilient to entire regional failures. To achieve the highest level of resiliency, we use a multi-region deployment for MovR database and application. | ||
|
|
||
| {{site.data.alerts.callout_info}} | ||
| In the [example deployment](movr-flask-deployment.html), the application and the database deployments are separate and not co-located on the same machine. |
There was a problem hiding this comment.
So far this section talks about the benefits of the distribution of your CockroachDB nodes, and doesn't discuss whether to host the application on separate machines. Here, we're simply saying that in the example, the app and database are not 'on the same machine'; so that's a new concept that perhaps should be introduced prior to the note, but also, won't there be multiple DB machines, given the multi-region focus?
Not sure I'm explaining this well, but I'd consider additional detail on best practices above, and then more clarity in the note re. the architecture of the example and how it might differ from what you'd do in production (if that's the case).
v21.1/movr-flask-use-case.md
Outdated
|
|
||
| ## Latency in global applications | ||
|
|
||
| If the MovR application and database are deployed in a single region, latency can become a serious problem when users are located in cities outside the deployment region. And deploying the application and database in multiple regions is not guaranteed to improve latency if client requests are sent to any regional deployment, without consideration for the client's location. |
There was a problem hiding this comment.
| If the MovR application and database are deployed in a single region, latency can become a serious problem when users are located in cities outside the deployment region. And deploying the application and database in multiple regions is not guaranteed to improve latency if client requests are sent to any regional deployment, without consideration for the client's location. | |
| If the MovR application and database are deployed in a single region, latency can become a serious problem when users are located in cities outside the deployment region. Deploying the application and database in multiple regions is not guaranteed to improve latency if client requests are sent to any regional deployment, without consideration for the client's location. |
v21.1/movr-flask-use-case.md
Outdated
|
|
||
| ### Reducing application latency | ||
|
|
||
| To limit the latency between client and application server requests, you need to deploy your application such that requests are routed to the application deployment closest to the client. This requires a global load balancer that can redirect traffic to application deployments, based on client location. |
There was a problem hiding this comment.
| To limit the latency between client and application server requests, you need to deploy your application such that requests are routed to the application deployment closest to the client. This requires a global load balancer that can redirect traffic to application deployments, based on client location. | |
| To limit the latency between client and application server requests, you need to deploy your application such that requests are routed to the application deployment closest to the client. This requires a global load balancer that can redirect traffic to application deployments based on client location. |
ericharmeling
force-pushed
the
21.1-movr-flask
branch
from
5678f34
to
8f24df4
Compare
ericharmeling
force-pushed
the
21.1-movr-flask
branch
from
8f24df4
to
73e1ff4
Compare
There was a problem hiding this comment.
@mikeCRL TFTR!
I think I got to all of your comments (and accepted all of your suggestions).
re: "movr-flask repository", I think I got to all of them.
Reviewable status:
_includes/v19.2/misc/movr-flask-211.md, line 2 at r3 (raw file):
Previously, mikeCRL (Mike Lewis) wrote…
CockroachDB versions v21.1 and above support [new multi-region capabilities, with different SQL syntax](https://www.cockroachlabs.com/docs/v21.1/multiregion-overview.html).
Done.
_includes/v19.2/misc/movr-flask-211.md, line 4 at r3 (raw file):
Previously, mikeCRL (Mike Lewis) wrote…
For the latest version of the application and database schema built on v21.1 multi-region features, see the [`movr-flask` repository](https://github.com/cockroachlabs/movr-flask).
Done.
_includes/v19.2/misc/movr-live-demo.md, line 4 at r3 (raw file):
Previously, mikeCRL (Mike Lewis) wrote…
Note that the backend for the live demo uses a newer version of the application, built on the [multi-region syntax introduced in v21.1](https://www.cockroachlabs.com/docs/v21.1/multiregion-overview.html). This newer application is also deployed using a simplified, serverless workflow. For more details, see the [`movr-flask` repository's README](https://github.com/cockroachlabs/movr-flask).
Done.
_includes/v20.1/misc/movr-flask-211.md, line 2 at r3 (raw file):
Previously, mikeCRL (Mike Lewis) wrote…
CockroachDB versions v21.1 and above support [new multi-region capabilities, with different SQL syntax](https://www.cockroachlabs.com/docs/v21.1/multiregion-overview.html).
Done.
_includes/v20.1/misc/movr-flask-211.md, line 4 at r3 (raw file):
Previously, mikeCRL (Mike Lewis) wrote…
For the latest version of the application and database schema built on v21.1 multi-region features, see the [`movr-flask` repo](https://github.com/cockroachlabs/movr-flask).
Done.
_includes/v20.1/misc/movr-live-demo.md, line 4 at r3 (raw file):
Previously, mikeCRL (Mike Lewis) wrote…
Note that the backend for the live demo uses a newer version of the application, built on the [multi-region syntax introduced in v21.1](https://www.cockroachlabs.com/docs/v21.1/multiregion-overview.html). This newer application is also deployed using a simplified, serverless workflow. For more details, see the [`movr-flask` repository's README](https://github.com/cockroachlabs/movr-flask).
Done.
_includes/v20.2/misc/movr-flask-211.md, line 2 at r3 (raw file):
Previously, mikeCRL (Mike Lewis) wrote…
CockroachDB versions v21.1 and above support [new multi-region capabilities, with different SQL syntax](https://www.cockroachlabs.com/docs/v21.1/multiregion-overview.html).
Done.
_includes/v20.2/misc/movr-flask-211.md, line 4 at r3 (raw file):
Previously, mikeCRL (Mike Lewis) wrote…
For the latest version of the application and database schema built on v21.1 multi-region features, see the [`movr-flask` repository](https://github.com/cockroachlabs/movr-flask).
Done.
_includes/v20.2/misc/movr-live-demo.md, line 4 at r3 (raw file):
Previously, mikeCRL (Mike Lewis) wrote…
Note that the backend for the live demo uses a newer version of the application, built on the [multi-region syntax introduced in v21.1](https://www.cockroachlabs.com/docs/v21.1/multiregion-overview.html). This newer application is also deployed using a simplified, serverless workflow. For more details, see the [`movr-flask` repository's README](https://github.com/cockroachlabs/movr-flask).
Done.
v19.2/multi-region-overview.md, line 19 at r3 (raw file):
Previously, mikeCRL (Mike Lewis) wrote…
Throughout the tutorial, we reference the source code for an example web application for the fictional vehicle-sharing company [MovR](movr.html). The source code for this application is open source and available on GitHub, in the [`movr-flask` repository](https://github.com/cockroachlabs/movr-flask/tree/v1.0). The code is well-commented, with docstrings defined at the beginning of each class and function definition.
Done.
v21.1/movr-flask-database.md, line 34 at r3 (raw file):
Previously, mikeCRL (Mike Lewis) wrote…
A distributed CockroachDB deployment consists of multiple, regional instances of CockroachDB that communicate as a single, logical entity. In [CockroachDB terminology](architecture/overview.html#terms), each instance is called a *node* and together, the nodes form a *cluster*.
Done.
v21.1/movr-flask-database.md, line 48 at r3 (raw file):
Previously, mikeCRL (Mike Lewis) wrote…
Here is the [`CREATE DATABASE`](create-database.html) statement for the `movr` database:
Done.
v21.1/movr-flask-database.md, line 65 at r3 (raw file):
Wasn't sure on whether to recommend "locality setting" or "locality mode" to introduce this, rather than just starting out with the "locality" term. As-is, it was a little unclear that "locality" is a setting/mode in this context.
Locality is also location metadata for a node. Perhaps we should say "table locality setting". (This term is does have a precedent in the multi-region reference docs).
But I definitely think we can take LOCALITY out of the name of the setting itself, which is consistent with existing docs, e.g. this heading: "Set the table locality to REGIONAL BY ROW".
Agreed!
should this be "optimizes ... for a single region"?
This should actually stay as-is. The reads and writes are optimized based on the location of the node from which rows are queried.
v21.1/movr-flask-database.md, line 67 at r3 (raw file):
Previously, mikeCRL (Mike Lewis) wrote…
The `movr` database contains tables with rows of data that need to be accessed by users in more than one region. As a result, none of the tables benefit from using a `REGIONAL BY TABLE` locality. Instead, all three tables in the `movr` database schema should use a [`REGIONAL BY ROW` locality](multiregion-overview.html#regional-by-row-tables). For `REGIONAL BY ROW` tables, CockroachDB automatically assigns each row to a region based on the locality of the node from which the row is inserted. It then optimizes subsequent read and write queries executed from nodes located in the region assigned to the rows being queried.
Done.
v21.1/movr-flask-database.md, line 70 at r3 (raw file):
Are we saying that the values are populated according to the region of the node where the query creating the row originates?
Exactly. I've updated this to say that more clearly.
v21.1/movr-flask-deployment.md, line 22 at r3 (raw file):
Previously, mikeCRL (Mike Lewis) wrote…
Remove extra lines
Done.
v21.1/movr-flask-deployment.md, line 65 at r3 (raw file):
Previously, mikeCRL (Mike Lewis) wrote…
You can also deploy CockroachDB manually. For instructions, see the [Manual Deployment](manual-deployment.html) page of the Cockroach Labs documentation site.
Done.
v21.1/movr-flask-deployment.md, line 73 at r3 (raw file):
Previously, mikeCRL (Mike Lewis) wrote…
This example deploys a secure web application. To serve a secure web application that takes HTTPS requests, the application must be accessible using a public domain name. SSL certificates are not assigned to IP addresses.
Done.
v21.1/movr-flask-deployment.md, line 78 at r3 (raw file):
I'm wondering if this should be in the Before You Begin section
Done
I think we should mention that the gcloud CLI, which we'll be using, is included as part of the Google Cloud SDK
Good idea. Done.
v21.1/movr-flask-deployment.md, line 80 at r3 (raw file):
Previously, mikeCRL (Mike Lewis) wrote…
1. From the [GCP console](https://console.cloud.google.com/), create a Google Cloud project for the application.
Done.
v21.1/movr-flask-deployment.md, line 82 at r3 (raw file):
Previously, mikeCRL (Mike Lewis) wrote…
The example appears to show 'all URLs on your domain' but not all subdomains. Not sure whether the description or the example are correct.
The description is incorrect. Good catch!
v21.1/movr-flask-deployment.md, line 85 at r3 (raw file):
Previously, mikeCRL (Mike Lewis) wrote…
A bit unclear if not providing an API key simply means the maps won't load, but that otherwise this will not break the application. That's what I'd expect, but this could be more explicit here.
Done.
v21.1/movr-flask-deployment.md, line 88 at r3 (raw file):
Previously, mikeCRL (Mike Lewis) wrote…
See other comment on mentioning here or in the prereqs that this is installed as part of the SDK?
Done.
v21.1/movr-flask-deployment.md, line 114 at r3 (raw file):
Previously, mikeCRL (Mike Lewis) wrote…
1. Push the Docker image to the Google Cloud project's container registry.
Done.
v21.1/movr-flask-deployment.md, line 126 at r3 (raw file):
Previously, mikeCRL (Mike Lewis) wrote…
- Set an environment variable named `DB_URI` to the connection string for a gateway node on the CockroachCloud cluster, in the region in which this first Cloud Run service is located (e.g., `cockroachdb://user:password@movr-db.gcp-us-east1.cockroachlabs.cloud:26257/movr?sslmode=verify-full&sslrootcert=certs/movr-db-ca.crt`).
Done.
v21.1/movr-flask-deployment.md, line 127 at r3 (raw file):
Previously, mikeCRL (Mike Lewis) wrote…
- Set an environment variable named `REGION` to the CockroachCloud region (e.g., `gcp-us-east1`).
Done.
v21.1/movr-flask-deployment.md, line 128 at r3 (raw file):
Previously, mikeCRL (Mike Lewis) wrote…
- Create a secret for the CockroachCloud certificate and mount it on the `certs` volume with a full path ending in the name of the cert (e.g., `certs/movr-db-ca.crt`). This is the cert downloaded from the CockroachCloud Console and referenced in the `DB_URI` connection string.
Done.
v21.1/movr-flask-deployment.md, line 155 at r3 (raw file):
Previously, mikeCRL (Mike Lewis) wrote…
This tutorial demonstrates how to develop and deploy an example multi-region application. Most of the development instructions are specific to Python, Flask, and SQLAlchemy, and most of the deployment instructions are specific to Google Cloud Platform (GCP). CockroachDB supports [many more drivers and ORMs for development](hello-world-example-apps.html), and you can deploy applications using a number of cloud provider orchestration tools and networking services. We encourage you to modify the code and deployments to fit your framework and use case.
Done.
v21.1/movr-flask-use-case.md, line 21 at r3 (raw file):
Previously, mikeCRL (Mike Lewis) wrote…
So far this section talks about the benefits of the distribution of your CockroachDB nodes, and doesn't discuss whether to host the application on separate machines. Here, we're simply saying that in the example, the app and database are not 'on the same machine'; so that's a new concept that perhaps should be introduced prior to the note, but also, won't there be multiple DB machines, given the multi-region focus?
Not sure I'm explaining this well, but I'd consider additional detail on best practices above, and then more clarity in the note re. the architecture of the example and how it might differ from what you'd do in production (if that's the case).
I think we can just remove this note altogether, to be honest. It's out-of-place (as you noted), and I don't think it adds anything important in the context of this page.
v21.1/movr-flask-use-case.md, line 26 at r3 (raw file):
Previously, mikeCRL (Mike Lewis) wrote…
If the MovR application and database are deployed in a single region, latency can become a serious problem when users are located in cities outside the deployment region. Deploying the application and database in multiple regions is not guaranteed to improve latency if client requests are sent to any regional deployment, without consideration for the client's location.
Done.
v21.1/movr-flask-use-case.md, line 49 at r3 (raw file):
Previously, mikeCRL (Mike Lewis) wrote…
To limit the latency between client and application server requests, you need to deploy your application such that requests are routed to the application deployment closest to the client. This requires a global load balancer that can redirect traffic to application deployments based on client location.
Done.
Fixes #10394.
This PR includes updates to the 21.1 multi-region application tutorial, following the refactor for https://github.com/cockroachlabs/movr-flask/releases/tag/v2.0.
The code for 19.2, 20.1, 20.2, and 21.1 now remote-include directly from the source code in doc-tagged branches of the correct application versions.