Two data center (2DC)
Recommended Reading
9 Techniques to Build Cloud-Native, Geo-Distributed SQL Apps with Low Latency highlights the various multi-DC deployment strategies (including 2DC deployments) for a distributed SQL database like YugabyteDB.For details on the two data center (2DC) deployment architecture and supported replication scenarios, see Two data center (2DC) deployments.
Follow the steps on this page to set up a 2DC deployment using either unidirectional (master-follower) or bidirectional (multi-master) replication between your data centers.
Set up your universes
To create your producer and consumer universes, follow these steps:
-
Create the “yugabyte-producer” universe using the Manual deployment steps.
-
Create the the tables for the APIs being used by the producer.
-
Create the “yugabyte-consumer” universe using the Manual deployment steps.
-
Create the tables for the APIs being used by the consumer.
These should be the same tables as you created for the producer universe.
Next, set up unidirectional (master-follower) or bidirectional (multi-master) replication.
Set up unidirectional (master-follower) replication
After you've created the required tables, you can set up asysnchronous replication.
-
Look up the producer universe UUID and the table IDs for the two tables and the index table on the master UI.
To find a universe's UUID in Yugabyte Platform, go to the Universes tab, and click the name of the Universe. The URL of the universe's Overview page ends with the universe's UUID. (For example,http://myPlatformServer/universes/d73833fc-0812-4a01-98f8-f4f24db76dbe
)
To find a table's UUID in Yugabyte Platform, click the Tables tab on the universe's Overview page. Click the table you want, and copy the table's UUID from its Overview tab. -
Run the following
yb-admin
setup_universe_replication
command from the YugabyteDB home directory in the producer universe../bin/yb-admin \ -master_addresses <consumer_universe_master_addresses> \ setup_universe_replication <producer_universe_uuid> \ <producer_universe_master_addresses> \ <table_id>,[<table_id>..]
For example:
./bin/yb-admin \ -master_addresses 127.0.0.11:7100,127.0.0.12:7100,127.0.0.13:7100 \ setup_universe_replication e260b8b6-e89f-4505-bb8e-b31f74aa29f3 \ 127.0.0.1:7100,127.0.0.2:7100,127.0.0.3:7100 \ 000030a5000030008000000000004000,000030a5000030008000000000004005,dfef757c415c4b2cacc9315b8acb539a
Note
There are three table IDs in the preceding command: the first two are YSQL for base table and index, and the third is the YCQL table. Also, be sure to specify all master addresses for producer and consumer universes in the command.
If you want to set up bidirectional replication, continue to the next section. Otherwise, skip to Load data into producer universe.
Set up bidirectional (multi-master) replication
To set up bidirectional replication, repeat the steps in the previous section for the “yugabyte-consumer” universe. This time, set up each “yugabyte-producer” to consume data from “yugabyte-consumer”.
Next, keep reading to load data.
Load data into the producer universe
Once you've set up replication, do the following to load data into the producer universe:
-
Download the YugabyteDB workload generator JAR file (
yb-sample-apps.jar
) from GitHub. -
Start loading data into “yugabyte-producer”.
YSQL example
java -jar yb-sample-apps.jar --workload SqlSecondaryIndex --nodes 127.0.0.1:5433
YCQL example
java -jar yb-sample-apps.jar --workload CassandraBatchKeyValue --nodes 127.0.0.1:9042
-
For bidirectional replication, repeat the preceding step in the "yugabyte-consumer" universe.
Next, continue to the next section to verify that replication is working correctly.
Verify replication
For unidirectional replication, connect to “yugabyte-consumer” universe using the YSQL shell (ysqlsh
) or the YCQL shell (ycqlsh
), and confirm that you can see expected records.
For bidirectional replication, repeat the previous step, but pump data into “yugabyte-consumer”. To avoid primary key conflict errors, keep the key space for the two universes separate.
Checking replication lag
Replication lag is computed at the tablet level as:
replication lag = hybrid_clock_time - last_read_hybrid_time
Where hybrid_clock_time
is the hybrid clock timestamp on the producer's tablet-server, and last_read_hybrid_time
is the hybrid clock timestamp of the latest transaction pulled from the producer.
An example script determine_replication_lag.sh
calculates replication lag for you. The script requires the jq
package.
The following example generates a replication lag summary for all tables on a cluster. You can also request an individual table.
./determine_repl_latency.sh -m 10.150.255.114,10.150.255.115,10.150.255.113
Call determine_repl_latency.sh -h
to get a summary of all command options.
If you're using Yugabyte Platform to manage universes, continue to the next section. If not, you're done!
Enable universes in Platform
If you're using Yugabyte Platform to manage your universes, you need to call the following REST API endpoint on your Platform instance for each universe (producer and consumer) involved in the 2DC replication:
PUT /api/customers/<myUUID>/universes/<myUniUUID>/setup_universe_2dc
Where myUUID
is your customer UUID, and myUniUUID
is the UUID of the universe (producer or consumer). The request should include an X-AUTH-YW-API-TOKEN
header with your Platform API key.
Here is a sample curl
command:
curl -X PUT \
-H "X-AUTH-YW-API-TOKEN: myPlatformApiToken" \
https://myPlatformServer/api/customers/myUUID/universes/myUniUUID/setup_universe_2dc
To find your customer UUID in Yugabyte Platform:
-
Click the person icon at the top left of any Platform page, and navigate to Profile.
-
On the General tab, copy your API token. If the API Token field is blank, click Generate Key, then copy the resulting API token.
Generating a new API token invalidates your existing token. Only the most-recently generated API token is valid. -
From a command line, issue a
curl
command of the following form:curl \ -H "X-AUTH-YW-API-TOKEN: myPlatformApiToken" \ [http|https]://myPlatformServer/api/customers
For example:
curl -X "X-AUTH-YW-API-TOKEN: e5c6eb2f-7e30-4d5e-b0a2-f197b01d9f79" \ http://localhost/api/customers
-
Copy your UUID from the resulting JSON output, without the double quotes and square brackets:
["6553ea6d-485c-4ae8-861a-736c2c29ec46"]
To find a universe's UUID in Yugabyte Platform, click Universes in the left column, then click the name of the Universe. The URL of the universe's Overview page ends with the universe's UUID. (For example, http://myPlatformServer/universes/d73833fc-0812-4a01-98f8-f4f24db76dbe
)