Deploy a Global Serverless Application

This page guides you through deploying an application and database in multiple regions. It is the fifth and final section of the Develop and Deploy a Global Application tutorial.

Before you begin

Before you begin this section, complete the previous sections of the tutorial, ending with Develop a Multi-Region Web Application. After you finish developing and debugging your multi-region application in a local development environment, you are ready to deploy the application and database in multiple regions.

In addition to the requirements listed in Setting Up a Virtual Environment for Developing Multi-Region Applications:

• Log in to Google Cloud.
• Install the Google Cloud SDK.
• Install a container runtime, such as Docker Desktop, and ensure that it is running in the background.

Multi-region database deployment

In production, you want to start a secure CockroachDB cluster, with nodes on machines located in different areas of the world. To deploy CockroachDB in multiple regions, we recommend using CockroachDB Standard. To use CockroachDB self-hosted instead, refer to Install CockroachDB.

Create a multi-region CockroachDB Standard cluster

1. Create a CockroachDB Cloud account and log in.
2. On the Clusters page, click Create cluster.
3. On the Select a plan page, select Standard.
4. On the Cloud & Regions page, set Cloud provider to GCP.
5. In the Regions section, add us-east1, us-west1, and europe-west1. Keep the default of 3 nodes per region. Click Next: Capacity.
6. Keep the Provisioned capacity at the default value of 1000 RUs/second. Click Next: Finalize.

7. On the Finalize page, optionally name your cluster. If applicable, the 30-day trial code is pre-applied to your cluster.

   Click Create cluster.

   Your cluster will be created in a few seconds and the Create SQL user dialog will display.

8. Enter a username for the SQL user. Click Generate & Save Password. Save the username and password to a secure location such as a password manager. Click Next, then Close.

   The Cluster Overview page appears.

9. On the Cluster Overview page, select Networking, then select the IP Allowlist tab.

10. Click Add Network. From the Network dropdown, select Current Network to auto-populate your local machine's IP address. This allows your local machine to access the cluster's DB Console and to use the CockroachDB client to access the databases.

    Note:

    After setting up your application's GCP project and GCP VPC network, you will need to return to the Networking page to configure GCP Private Service Connect for private connectivity.

Initialize the movr database

1. Open a new terminal window on your local machine, and navigate to the movr-flask project directory.

2. In your web browser, log in to the CockroachDB Cloud Console, then select Connect at the top-right corner of the page.

3. Select the SQL User that you created and the Region closest to you, and then select Next.

4. From the Connection info dialog, click Download CA Certificate, then follow the instructions. This is required only once per client. This root certificate is the same for all regions in a cluster.

5. Under Select option/language, select CockroachDB Client. Copy the command.

6. In a new terminal window, navigate to the movr-flask project directory, then paste the command you just copied. Add the -f dbinit.sql option at the end of the command. For example:

   cockroach sql \
     --url 'postgresql://user:password@cluster.gcp-us-east1.cockroachlabs.cloud:26257/defaultdb?sslmode=verify-full&sslrootcert='$HOME'/Library/CockroachCloud/certs/root.crt' \
     -f dbinit.sql
   

   This command will initialize the movr database on the cluster in CockroachDB Cloud.

Global application deployment

To optimize the latency of requests from the application to the database, you need to deploy the application in multiple regions.

Set up a GCP project

1. From the GCP console, create a Google Cloud project for the application.

   Note:

   Google Cloud automatically creates a default VPC network for each project.

2. In the API Library, enable the following APIs for your project:

   • Container Registry API
   • Cloud Run Admin API
   • Serverless VPC Access API

3. Optional: Enable the Google Maps Embed API, create an API key, restrict the API key to all URLS on your domain name (e.g., https://site.com/*), and retrieve the API key.

   Note:

   The example HTML templates include maps. Not providing an API key to the application will prevent the maps from loading, but will not prevent the rest of the application from functioning.

4. Initialize and log in using the gcloud command-line tool.

   Note:

   gcloud is included with the Google Cloud SDK installation.

   gcloud init
   

   gcloud auth login
   

   gcloud auth application-default login
   

Set up GCP Private Service Connect

GCP Private Service Connect allows your cluster to connect to your Google Cloud project using private cloud infrastructure rather than the public internet. To set up PSC:

1. Once for each cluster region, follow the instructions to Establish private connectivity.

2. To obtain the private connection string your application will use to connect privately to your cluster, click Connect at the top-right corner of the page, then:

   • Select the SQL User that you created.
   • For each cluster region:
     • Select the region.
     • For Connection type, select Private connection, then select the private connection you just created.
     • Under Select option/language, select General connection string. Copy the connection string.

You now have a private connection string for each of the cluster's regions. You will use these connection strings to deploy the application.

Containerize the application

1. Create a new directory named certs at the top level of the movr-flask project, and then copy the root certificate that you downloaded for your cluster to the new directory. The Dockerfile for the application contains instructions to mount this directory onto the container so that it can read the CA certificate.

2. Build the container image locally.

   docker build -t gcr.io/<gcp_project>/movr-app:v1 .
   

   If there are errors, verify that your container runtime is running in the background and try again.

3. Push the container image to the Google Cloud project's container registry.

   docker push gcr.io/<gcp_project>/movr-app:v1
   

The image can now be pulled by container runtimes with access to your Google Cloud project.

Deploy the application

1. Create a Google Cloud Run service for the application, in one of the regions in which the database is deployed:

   • Select the container image that you just pushed your project's registry.

   • Under Advanced settings->Variables & Secrets:

     • Create a new environment variable named DB_URI. Set its value to the private connection string for this region that you copied when you set up GCP Private Service Connect with the following modifications:

       1. Change postgresql:// to cockroachdb://.
       2. Add &sslrootcert=certs/root.crt directly after sslmode=verify-full.

       For example: cockroachdb://user:password@internal-cluster.gcp-us-east1.cockroachlabs.cloud:26257/movr?sslmode=verify-full&sslrootcert=certs/root.crt

     • Create a new environment variable named REGION to the region associated with the connection string.

     • Optional: Enable the Secret Manager API, then create a secret for your Google Maps API key and set the the environment variable API_KEY to its value.

2. Create an external HTTPS load balancer to route requests to the service in each region:

   • For the backend configuration, create separate network endpoint groups (NEGs) for the Google Cloud Run services in each region.
   • For the frontend configuration, use the HTTPS protocol. You can create a managed IP address and a managed SSL cert for the load balancer directly from the load balancer console. For the SSL cert, you will need to specify a domain name.

   For detailed instructions on setting up a load balancer for a multi-region Google Cloud Run backend, see the GCP Load Balancer docs.

3. In the Cloud DNS console (found under Network Services), create a new zone. You can name the zone whatever you want. Enter the same domain name for which you created a certificate earlier.

4. Select your zone, and copy the nameserver addresses Data for the recordset labeled NS.

5. In your domain's DNS provider, add the nameserver addresses to the authoritative nameserver list for your domain.

   Note:

   It can take up to 48 hours for changes to the authoritative nameserver list to take effect.

6. Navigate to the domain name to access and test your application.

Next steps

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 (GCP). CockroachDB supports many more drivers and ORMs for development, 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.

Upgrade your deployment

When pushing changes to update your deployment, remember that you defined the database separate from the application. If you change a data type, for example, in your application, you will also need to modify the database schema to be compatible with your application's requests. For information about making online changes to database schemas, refer to Online Schema Changes.

See also

• CockroachDB Cloud quickstart
• Google Cloud Platform documentation