How to install CockroachDB Cluster on CentOS 8

Share on Social Media

Learn how to install CockroachDB on CentOS 8 with our step-by-step guide. Ensure a smooth installation process and set up your CockroachDB instance efficiently. #centlinux #linux #cockroachdb

What is CockroachDB?

CockroachDB is a distributed SQL database designed for modern cloud applications. It provides high availability, strong consistency, and automatic scaling. Named for its resilience, CockroachDB can survive hardware failures without losing data, making it ideal for mission-critical applications.

Key features include:

Horizontal Scalability: Automatically balances data across nodes, allowing easy scaling by adding more machines.
ACID Transactions: Supports strong transactional consistency across distributed environments.
Fault Tolerance: Ensures data availability and integrity even in the event of node failures.
SQL Interface: Offers a familiar SQL interface for ease of use and compatibility with existing tools and systems.
Geo-Replication: Enables data to be stored and accessed across multiple geographic regions, improving performance and compliance with data locality requirements.
Automatic Failover: Detects and recovers from failures without manual intervention, minimizing downtime.
Flexible Deployment: Can be deployed on-premises, in the cloud, or in hybrid environments.

CockroachDB is especially suitable for applications that require a robust and scalable database solution, such as financial services, e-commerce, and any system needing consistent, low-latency access to data distributed across different locations.

Recommended Online Training: Google Professional Cloud Database Engineer – GCP – Exams

CockroachDB Alternatives

There are several alternatives to CockroachDB, each with its own strengths and use cases. Some of the notable alternatives include:

PostgreSQL

A powerful, open-source relational database system.
Known for its extensibility and support for advanced SQL features.
Suitable for applications requiring a robust, standalone database.

MySQL

One of the most popular open-source relational databases.
Known for its ease of use, reliability, and performance.
Widely used for web applications and content management systems.

Google Cloud Spanner

A fully managed, scalable, and highly available database offered by Google Cloud.
Supports horizontal scaling and strong consistency across regions.
Ideal for applications needing global distribution and high availability.

Amazon Aurora

A MySQL and PostgreSQL-compatible relational database engine offered by AWS.
Provides high performance and availability.
Managed by AWS, reducing operational overhead.

Cassandra

An open-source, distributed NoSQL database.
Designed for high availability and scalability without compromising performance.
Suitable for handling large amounts of data across many commodity servers.

MariaDB

A community-developed fork of MySQL.
Offers similar features to MySQL with additional enhancements.
Known for its performance, scalability, and security features.

Microsoft SQL Server

A relational database management system developed by Microsoft.
Provides a comprehensive set of tools and features for data management and business intelligence.
Available for both Windows and Linux platforms.

TiDB

An open-source, distributed SQL database.
Compatible with MySQL and designed to handle large-scale OLTP (Online Transaction Processing) workloads.
Provides horizontal scalability and strong consistency.

These alternatives offer a range of options depending on the specific needs of your application, such as scalability, consistency, ease of use, and the level of managed services required.

Yugabyte vs CockroachDB

YugabyteDB and CockroachDB are both distributed SQL databases designed for modern, scalable, and fault-tolerant applications. While they share some similarities, they also have distinct differences:

YugabyteDB

Architecture:

Combines the best features of both SQL and NoSQL databases.
Built on a layered architecture with a distributed storage layer (DocDB) and a PostgreSQL-compatible query layer (YSQL).

Compatibility:

PostgreSQL wire-protocol compatibility, making it easier to migrate applications from PostgreSQL.
Supports both SQL (YSQL) and NoSQL (YCQL) APIs, providing flexibility in application development.

Performance:

Optimized for low-latency, high-throughput workloads.
Offers automatic data sharding and rebalancing to maintain performance.

Deployment:

Supports multi-cloud, on-premises, and hybrid deployments.
Provides advanced multi-region deployment capabilities with tunable consistency levels.

Community and Support:

Active open-source community with robust documentation and support options.
Enterprise features available for enhanced support and additional functionalities.

CockroachDB

Architecture:

Designed from the ground up as a distributed SQL database.
Implements a single, monolithic architecture with a key-value storage layer and a SQL layer.

Compatibility:

PostgreSQL wire-protocol compatible, facilitating the migration of applications from PostgreSQL.
Focuses on providing strong consistency and ACID transactions across distributed environments.

Performance:

Prioritizes fault tolerance and high availability.
Uses a distributed architecture to ensure automatic failover and data replication.

Deployment:

Supports deployment on cloud platforms, on-premises, and in hybrid environments.
Designed for global distribution, allowing data to be geographically replicated and accessible with low latency.

Community and Support:

Active open-source community with extensive documentation and support resources.
Offers an enterprise version with additional features and professional support services.

Comparison Summary

YugabyteDB excels in offering a versatile solution with both SQL and NoSQL capabilities, making it a flexible choice for diverse workloads. Its PostgreSQL compatibility and multi-API support provide significant advantages for developers needing both transactional and analytical processing.
CockroachDB focuses on delivering a seamless distributed SQL experience with strong consistency and high availability. It is ideal for applications that require robust ACID transactions and resilience across distributed environments.

Both databases are powerful choices for building scalable, distributed applications. The choice between YugabyteDB and CockroachDB depends on your specific requirements, such as the need for NoSQL support, performance characteristics, and deployment preferences.

Environment Specification

We are using two minimal CentOS 8 virtual machines with following specifications.

Node 1

CPU – 3.4 Ghz (2 cores)
Memory – 2 GB
Storage – 20 GB
Operating System – CentOS 8.2
Hostname – crdb-node-01.centlinux.com
IP Address – 192.168.116.230 /24

Node 2

CPU – 3.4 Ghz (2 cores)
Memory – 2 GB
Storage – 20 GB
Operating System – CentOS 8.2
Hostname – crdb-node-02.centlinux.com
IP Address – 192.168.116.233 /24

Update Linux Server Packages

Use a SSH client to connect with crdb-node-01.centlinux.com as root user.

It is a best practice to update your Linux server packages frequently, especially before installation or configuration of a new software.

With the help of dnf command, update installed packages in your Linux operating system.

# dnf update -y

Check the Linux distro and kernel version of your servers, that are being used in this installation guide.

# uname -r
4.18.0-193.19.1.el8_2.x86_64

# cat /etc/redhat-release
CentOS Linux release 8.2.2004 (Core)

Configure Name Resolution of CockroachDB Cluster Nodes

Name resolution is very critical while setting up a Linux cluster. Because, if a node is unable to resolve the hostname of the other nodes, then the cluster setup will raise different type of errors.

For this purpose, you can either configure an Authoritative DNS server or simply use the local DNS resolver.

Here, we are configuring the local DNS resolver for hostname resolution of the cluster nodes.

Edit /etc/hosts file by using vim editor.

# vi /etc/hosts

Add following entries in this file.

192.168.116.230 crdb-node-01 crdb-node-01.centlinux.com
192.168.116.233 crdb-node-02 crdb-node-02.centlinux.com

These entries are quiet enough to configure name resolution of your cluster nodes.

Setup Time Synchronization on Linux Server

Just like any other clustering setup, CockroachDB cluster also requires time synchronization across all the nodes.

If it unable to synchronize time on any of the cluster node and cause a time drift of more than 500ms, then that node won’t be started until its time is synchronized with the other CockroachDB nodes.

In Red Hat based Linux distros, Chrony is the preferred NTP client/server since RHEL 7.

Therefore, you can install Chrony by using dnf command.

# dnf install -y chrony

Enable and start Chrony service by using following Linux command.

# systemctl enable --now chronyd.service

Execute the following command to check the NTP sources and time synchronization status.

# chronyc sources -v
210 Number of sources = 4

  .-- Source mode  '^' = server, '=' = peer, '#' = local clock.
 / .- Source state '*' = current synced, '+' = combined , '-' = not combined,
| /   '?' = unreachable, 'x' = time may be in error, '~' = time too variable.
||                                                 .- xxxx [ yyyy ] +/- zzzz
||      Reachability register (octal) -.           |  xxxx = adjusted offset,
||      Log2(Polling interval) --.      |          |  yyyy = measured offset,
||                                     |          |  zzzz = estimated error.
||                                 |    |           
MS Name/IP address         Stratum Poll Reach LastRx Last sample
===============================================================================
^+ 141.15.176.182.in-addr.a>     2   6    17     2  -3915us[-2554us] +/-   94ms
^+ 1.200.159.162.in-addr.ar>     3   6    17     2    +25ms[  +27ms] +/-   83ms
^+ 197.19.176.182.in-addr.a>     2   6    17     2    -40ms[  -39ms] +/-  134ms
^* 119.159.246.253               2   6    17     2  +3885us[+5131us] +/-   88ms

Install CockroachDB Prerequisites

CockroachDB requires some software packages, that are usually preinstalled on a minimal installed CentOS 8 operating system.

However, you can also execute the dnf command to install these packages, if they are not already installed.

# dnf install -y glibc ncurses-libs tzdata

Install CockroachDB on CentOS 8

You can download CockroachDB Core edition, free of cost, from GitHub or Cockroach Labs website.

Download CockroachDB by using wget command.

# cd /tmp
# wget https://binaries.cockroachdb.com/cockroach-v20.1.8.linux-amd64.tgz
--2020-10-30 22:52:11--  https://binaries.cockroachdb.com/cockroach-v20.1.8.linux-amd64.tgz
Resolving binaries.cockroachdb.com (binaries.cockroachdb.com)... 13.35.175.7, 13.35.175.57, 13.35.175.91, ...
Connecting to binaries.cockroachdb.com (binaries.cockroachdb.com)|13.35.175.7|:443... connected.
HTTP request sent, awaiting response... 200 OK
Length: 73681901 (70M) [binary/octet-stream]
Saving to: âcockroach-v20.1.8.linux-amd64.tgzâ

cockroach-v20.1.8.l 100%[===================>]  70.27M   253KB/s    in 5m 50s

2020-10-30 22:58:04 (206 KB/s) - âcockroach-v20.1.8.linux-amd64.tgzâ saved [73681901/73681901]

Extract downloaded tarball by using tar command.

# tar xf cockroach-v20.1.8.linux-amd64.tgz

Create directories for CockroachDB software and related files.

# mkdir -p /opt/cockroachdb/{bin,certs,private}

Copy extracted files in /opt/cockroachdb/bin directory.

# cp -i cockroach-v20.1.8.linux-amd64/cockroach /opt/cockroachdb/bin/

Check the file permissions of the cockroach file.

# ls -al /opt/cockroachdb/bin/
total 163100
drwxr-xr-x. 2 root root        23 Oct 31 11:12 .
drwxr-xr-x. 5 root root        45 Oct 31 11:11 ..
-rwxr-xr-x. 1 root root 167014096 Oct 31 11:12 cockroach

Create a Linux user to own CockroachDB software and processes. Also grant the ownership of files to that user.

# useradd -r cockroach
# chown -R cockroach.cockroach /opt/cockroachdb/

Create a soft link for cockroach file in /usr/local/bin/ directory, to make it executable from anywhere.

# ln -s /opt/cockroachdb/bin/cockroach /usr/local/bin/cockroach

Verify the CockroachDB version by executing following command.

# cockroach version
Build Tag:    v20.1.8
Build Time:   2020/10/21 15:46:38
Distribution: CCL
Platform:     linux amd64 (x86_64-unknown-linux-gnu)
Go Version:   go1.13.9
C Compiler:   gcc 6.3.0
Build SHA-1:  ffd029f51aa134f2bce4a39ef1f3ad095c3856ad
Build Type:   release

Above steps (from start of this article) must be executed on each node to effectively install CockroachDB on Linux cluster. Whereas, the steps onwards are specific to nodes and must be executed on the mentioned nodes only.

Setup Secure CockroachDB Cluster on CentOS 8

You have install CockroachDB on Linux successfully. Now you need to configure Database Secure Cluster.

CockroachDB cluster can be configured in secure and insecure modes.

Configuration of CockroachDB cluster in Insecure mode is pretty simple but do not enforce encryption of inter-cluster communication.

Whereas, Secure mode uses SSL/TLS certificates to enforce encryption of inter-cluster communication and authorization.

First of all, you need to create a Certificate Authority (CA), that will be used to digitally sign any certificate that you will generate for your CockroachDB secure cluster.

You can use following cockroach command to create a certificate authority, or you can also create a certificate authority with openssl command.

# cockroach cert create-ca 
> --certs-dir=/opt/cockroachdb/certs 
> --ca-key=/opt/cockroachdb/private/ca.key

Generate a SSL/TLS certificate for our first CockroachDB node (crdb-node-01) with the help of following command.

# cockroach cert create-node 
> 192.168.116.230 
> crdb-node-01 
> localhost 
> --certs-dir=/opt/cockroachdb/certs 
> --ca-key=/opt/cockroachdb/private/ca.key

Generate a SSL/TLS certificate for CockroachDB client by executing following command.

# cockroach cert create-client 
> root 
> --certs-dir=/opt/cockroachdb/certs 
> --ca-key=/opt/cockroachdb/private/ca.key

Copy the SSL/TLS certificates on other nodes of database cluster.

# scp /opt/cockroachdb/certs/* 
> root@crdb-node-02:/opt/cockroachdb/certs/
root@crdb-node-02's password:
ca.crt                                        100% 1111    27.5KB/s   00:00
client.root.crt                               100% 1099   857.5KB/s   00:00
client.root.key                               100% 1675     1.5MB/s   00:00
node.crt                                      100% 1159     1.0MB/s   00:00
node.key                                      100% 1679   108.7KB/s   00:00

Copy the Certificate Authority key on other nodes, so we can create SSL/TLS on that nodes.

# scp /opt/cockroachdb/private/* root@crdb-node-02:/opt/cockroachdb/private/
root@crdb-node-02's password:
ca.key                                        100% 1679    81.3KB/s   00:00

Connect to crdb-node-02.centlinux.com as root user by using ssh command.

Remove the Node certificate/key that we have generated on the crdb-node-01 node.

# rm -f /opt/cockroachdb/certs/node.*

Generate a SSL/TLS certificate for crdb-node-02 node as follows.

# cockroach cert create-node 
> 192.168.116.233 
> crdb-node-02 
> localhost 
> --certs-dir=/opt/cockroachdb/certs 
> --ca-key=/opt/cockroachdb/private/ca.key

Create Systemd Service Unit

To enable auto-start of CockroachDB server during Linux startup, you are required to create a systemd service unit.

Connect with crdb-node-01.centlinux.com as root user by using ssh command.

Create a systemd service unit file by using vim editor.

# vi /etc/systemd/system/cockroachdb.service

Add following directives in this file.

[Unit]
Description=Cockroach Database cluster node
Requires=network.target

[Service]
Type=notify
WorkingDirectory=/opt/cockroachdb
ExecStart=/usr/local/bin/cockroach start --certs-dir=/opt/cockroachdb/certs --advertise-addr=crdb-node-01 --join=crdb-node-01,crdb-node-02
TimeoutStopSec=60
Restart=always
RestartSec=10
StandardOutput=syslog
StandardError=syslog
SyslogIdentifier=cockroach
User=cockroach

[Install]
WantedBy=default.target

You need to replace the –advertise-addr with the hostname of the CockroachDB node on which you are creating this systemd service.

Enable and start CockroachDB service.

# systemctl enable --now cockroachdb.service
Created symlink /etc/systemd/system/default.target.wants/cockroachdb.service â /etc/systemd/system/cockroachdb.service.

Check the CockroachDB service ports to verify that the CockroachDB service is started without any error.

# ss -tulpn | grep cockroach
tcp     LISTEN   0        128                    *:8080                 *:*      users:(("cockroach",pid=1692,fd=9))
tcp     LISTEN   0        128                    *:26257                *:*      users:(("cockroach",pid=1692,fd=15))

Configure Linux Firewall

CockroachDB default service ports are 8080/tcp for Web Admin UI, 26257/tcp for SQL interface.

You are required to allow both of above service ports in your Linux firewall.

# firewall-cmd --permanent --add-port={8080,26257}/tcp
success
# firewall-cmd --reload
success

Initialize Secure CockroachDB Cluster

CockroachDB configuration are completed, now you can execute the following command on any CockroachDB node to initialize the cluster.

# cockroach init --certs-dir=/opt/cockroachdb/certs --host=crdb-node-01:26257
Cluster successfully initialized

Accessing CockroachDB SQL Shell

Connect to crdb-node-01 SQL shell by using following command.

# cockroach sql --certs-dir=/opt/cockroachdb/certs --host=crdb-node-01:26257
#
# Welcome to the CockroachDB SQL shell.
# All statements must be terminated by a semicolon.
# To exit, type: q.
#
# Server version: CockroachDB CCL v20.1.8 (x86_64-unknown-linux-gnu, built 2020/10/21 15:46:38, go1.13.9) (same version as client)
# Cluster ID: 50a8b514-7e6f-4a4a-936e-8a4d68aa1007
#
# Enter ? for a brief introduction.
#
root@crdb-node-01:26257/defaultdb>

List down available databases in CockroachDB server.

root@crdb-node-01:26257/defaultdb> SHOW DATABASES;
  database_name
-----------------
  defaultdb
  postgres
  system
(3 rows)

Time: 1.742219ms

Create a new database by using CREATE statement.

root@crdb-node-01:26257/defaultdb> CREATE DATABASE contacts;
CREATE DATABASE

Time: 11.39776ms

Create a new table in contacts database.

root@crdb-node-01:26257/defaultdb> USE contacts;
SET

Time: 661.825Âµs

root@crdb-node-01:26257/contacts> CREATE TABLE emails (id INT PRIMARY KEY, email varchar(40));
CREATE TABLE

Time: 164.404539ms

Insert a few rows in emails table.

root@crdb-node-01:26257/contacts> INSERT INTO emails VALUES (1,'ahmer@yahoo.com');
INSERT 1

Time: 2.482089ms

root@crdb-node-01:26257/contacts> INSERT INTO emails VALUES (2,'mahmood@gmail.com');
INSERT 1

Time: 2.278789ms

root@crdb-node-01:26257/defaultdb> q

Now connect with second CockroachDB node, and check has changes been replicated to that database.

# cockroach sql --certs-dir=/opt/cockroachdb/certs --host=crdb-node-02:26257
#
# Welcome to the CockroachDB SQL shell.
# All statements must be terminated by a semicolon.
# To exit, type: q.
#
# Server version: CockroachDB CCL v20.1.8 (x86_64-unknown-linux-gnu, built 2020/10/21 15:46:38, go1.13.9) (same version as client)
# Cluster ID: 50a8b514-7e6f-4a4a-936e-8a4d68aa1007
#
# Enter ? for a brief introduction.
#
root@crdb-node-02:26257/defaultdb> SHOW DATABASES;
  database_name
-----------------
  contacts
  defaultdb
  postgres
  system
(4 rows)

Time: 10.066515ms

root@crdb-node-02:26257/defaultdb> USE contacts;
SET

Time: 2.853712ms

root@crdb-node-02:26257/contacts> SELECT * FROM emails;
  id |       email
-----+--------------------
   1 | ahmer@yahoo.com
   2 | mahmood@gmail.com
(2 rows)

Time: 123.407227ms

root@crdb-node-02:26257/contacts> q

Data has been replicated to second node, it shows that our CockroachDB cluster has been configured successfully.

Accessing CockroachDB Web Console

To access CockroachDB Web Console, we require a user account. This user must be created within CockroachDB database.

Therefore, connect to SQL shell of any CockroachDB node and create a database user.

root@crdb-node-01:26257/defaultdb> CREATE USER ahmer WITH PASSWORD 'cockroach';
CREATE ROLE

Time: 363.507317ms

You are also required to grant the admin privilege to ahmer user.

root@crdb-node-01:26257/defaultdb> GRANT admin TO ahmer;
GRANT

Time: 1.425956943s

Open URL https://crdb-node-01:8080 in a web browser.

Configure Load Balancer for CockroachDB Cluster

Each node in CockroachDB cluster has its own SQL and Web Admin UI services, that can be access independently by using Node hostname or IP address.

Therefore, it is necessary to configure a reverse proxy load balancer, so the users/applications can access our cluster by a common address/port instead of accessing individual nodes with separate hostname/IP addresses.

For this purpose, you can use HAProxy to configure a software load balancer. You can easily generate a HAProxy configuration file by using cockroach command.

# cockroach gen haproxy --certs-dir=/opt/cockroachdb/certs --host=crdb-node-01

Check the content of haproxy.cfg file.

# cat haproxy.cfg

global
  maxconn 4096

defaults
    mode                tcp
    # Timeout values should be configured for your specific use.
    # See: https://cbonte.github.io/haproxy-dconv/1.8/configuration.html#4-timeout%20connect
    timeout connect     10s
    timeout client      1m
    timeout server      1m
    # TCP keep-alive on client side. Server already enables them.
    option              clitcpka

listen psql
    bind :26257
    mode tcp
    balance roundrobin
    option httpchk GET /health?ready=1
    server cockroach1 $(hostname):26257 check port 8080

This file requires minor adjustments and then it will perfectly work on a HAProxy load balancer.

You can refer to our previous post to configure HAProxy load balancer.

If you having difficulty understanding the steps in this article, then you should buy and read RHCSA Red Hat Enterprise Linux 8: Training and Exam Preparation Guide (EX200), First Edition (PAID LINK) by Asghar Ghori.

Final Thoughts

Installing CockroachDB on CentOS 8 can significantly enhance your database infrastructure with its robust, scalable, and fault-tolerant capabilities. Following the step-by-step guide ensures a smooth installation process, allowing you to leverage CockroachDB’s powerful features for your applications.

For personalized assistance or more detailed guidance, feel free to visit my Fiverr gig: Linux System Administration. I’m here to help you with all your database installation and management needs.

Table of Contents

What is CockroachDB?

CockroachDB Alternatives

PostgreSQL

MySQL

Google Cloud Spanner

Amazon Aurora

Cassandra

MariaDB

Microsoft SQL Server

TiDB

Yugabyte vs CockroachDB

YugabyteDB

Architecture:

Compatibility:

Performance:

Deployment:

Community and Support:

CockroachDB

Architecture:

Compatibility:

Performance:

Deployment:

Community and Support:

Comparison Summary

Environment Specification

Update Linux Server Packages

Configure Name Resolution of CockroachDB Cluster Nodes

Setup Time Synchronization on Linux Server

Install CockroachDB Prerequisites

Install CockroachDB on CentOS 8

Setup Secure CockroachDB Cluster on CentOS 8

Create Systemd Service Unit

Configure Linux Firewall

Initialize Secure CockroachDB Cluster

Accessing CockroachDB SQL Shell

Accessing CockroachDB Web Console

Configure Load Balancer for CockroachDB Cluster

Final Thoughts