In distributed computing, where processing and data are spread over multiple computersusually over a networkwhat’s important is the ability to migrate distributed environments, or any environment, from on premises to the cloud. Another important factor is the ability to run in multiple configurations, such as on-prem, hybrid cloud, cloud, and multi-cloud.

In this post, we introduce two distributed computing technologies to achieve that goal: (1) Red Hat OpenShift Container Platform and (2) CockroachDB. While both are essentially platform agnostic, we’re going to focus here on running them on prem.

Understanding the technologies

OpenShift Container Platform provides an enterprise-grade Kubernetes environment and all the tools and services needed to create, edit, deploy, and manage container-based apps at scale across a hybrid-cloud environment. The service integrates the architecture, processes, platforms, and services that empower development and operations teams to build apps that move contemporary businesses forward, and it allows mission-critical, traditional apps to coexist with cloud-native or container-based apps.

CockroachDB, for its part, was designed from the ground up to act as a shared-nothing, distributed SQL database. It automates data replication, manages quorum across replicas, and guarantees full atomicity, consistency, isolation, and durability (ACID) compliance with serializable isolation between transactions.

CockroachDB’s architecture enables a recovery point objective (RPO) of 0 seconds (no data loss) and a recovery time objective (RTO) of less than 9 seconds for supported failure mode. That 9 seconds is the time it takes the cluster to sense the loss of a lead replica for any portion of the data and elect a new one. By distributing the authority to act on data across the nodes of a cluster, architects and engineers can design a system based on the scenarios they need to survive. For example, the architecture we’ll outline here can survive arbitrary node failure or the failure of an entire site and still meet these RTO and RPO objectives.

Combining CockroachDB with OpenShift Container Platform not only simplifies cloud migration, it creates two environments that can enable enterprises to start on prem and deploy in various configurations: on-prem, hybrid (both on-prem and cloud), cloud, and multi-cloud.

Identifying the learnings

In addition to understanding the capabilities of the combined OpenShift Container Platform/CockroachDB solution, in this post you’ll learn to:

  1. Create a Kubernetes-like, container-based platform. 
  2. Install an operator to build a CockroachDB cluster.
  3. Create and run a distributed transactional database in your container-based platform.

Step 1: Creating a container-based platform

To start deploying CockroachDB on OpenShift Container Platform, you need a container-based environment. I use Red Hat OpenShift in this example, because it allows me to easily create a local, one-node, Kubernetes-like environment with an easy-to-use web interface that simplifies administration. You can use command line, but it’s not necessary. In fact, I can complete this entire process on my MacOS. Remember, OpenShift Platform and CockroachDB together allow for a platform-agnostic implementation. Following is the basic, end-state architecture:

To get to the end state, though, we need to start with OpenShift Container Platform taking these steps:

  1. Go to Red Hat OpenShift. If you don't have a login, you'll need to register, but it’s free.
  2. On the main landing page, click “Clusters.”


  1. Click “Create cluster” to create a local cluster specific to our machine’s operating system.

  1. Choose “Local.”

  1. Choose the download type specific to your environment (i.e., Linux or XOS). In this post, I’m using XOS.
  1. Follow the two steps indicated to download your OCP software.

Installation takes about 30 seconds. Note: Make sure to download or copy pull secret as you’ll use it in the following steps.

  1. Run the crc setup command:

  1. Once the setup is complete, run the crc start command to start the environment.

  1. Once the process is complete, in about 30-60 seconds depending on the laptop, copy the contents of the pull secret into the command line. The system will output the following: 

Note: Make sure to copy this output, as you’ll use it later in this process.


  1. To validate the status of your environment, run crc status:

  1. With the environment started, run the command eval $(crc oc-env). Note: “eval” is a built-in Linux command used to execute arguments as a shell command.
  1. Log in at the command line with user “developer”:

oc login -u developer https://api.crc.testing:6443


  1. Create a project in which to build the environment. For the purposes of this exercise, we’ll call the project “cockroachdb.” The system outputs the following:

  1. Run the command oc new-project cockroachdb:

Now using project "cockroachdb" on server "https://api.crc.testing:6443".

You can add applications to this project with the 'new-app' command. For example, try:

oc new-app rails-postgresql-example

to build a new example application in Ruby. Or use kubectl to deploy a simple Kubernetes application:

kubectl create deployment hello-node


If you receive no errors, the OpenShift environment has installed successfully. For an overview of commands to run, see OpenShift Commands.

Step 2: Installing an operator

Now that we’ve installed our OpenShift Container Platform environment locally, we launch the OpenShift Container Platform console to help install the CockroachDB operator. Note: Recall that the “crc start” command in the previous section output a url and login credentials we’ll use in the next step. 

  1. Cut and paste the url output from the “crc start” command in the previous section. Note: Running crc console at the command line will launch the console, as well.
  2. Enter “kubeadmin” as the username:

  1. Click “Operators” and choose “OperatorHub”:

  1. Search for “Cockroachdb”:

  1. Choose “CockroachDB Operator,” and click “Install”:

  1. In the form that appears, enter the following:

    • In the “Installation Mode” section, select “A specific namespace on the cluster.”
    • Choose the project (pssst: cockroachdb).
    • Click “Install.”


Note: This process may take a few minutes.

  1. Once the download is complete, click “Installed Operators.”

Note: The Cockroach operator will appear in the “Installed Operators” section. It has been created in the project(namespace) that was chosen.

  1. Click the operator name “CockroachDB Operator.”
  1. Under “Provided APIs,” click “Create Instance.” Note: Ensure that “Form View” is selected. In form view, you can enter values without having to worry about YAML formatting. As you add features on the form, only click “YAML View” to see how the operator is constructing the YAML and to identify any programming issues.

Note: For the purposes of this exercise, we’ll use the default setting to create a 3-node CockroachDB database. Make sure the “CockroachDB Version” is a valid one. In this example, I’m using “20.2.8.” 

  1. Click “Create.”
  1. Once you’ve created your cluster, click “Workloads -> Pods.” This will display the 3 CockroachDB nodes you created, as well as confirmation that the operator pod is running. At the terminal window, the command line is “oc get pods.”

notroot@johndoe-mbp-2 openshift % oc get pods
cockroach-operator-manager-58546b8dbf-p9fpl 1/1 Running 1 4d2h
crdb-tls-example-0 1/1 Running 0 76m
crdb-tls-example-1 1/1 Running 0 77m
crdb-tls-example-2 1/1 Running 0 78m


Step 3: Running a distributed transactional database

To this point, we’ve done the following:

  1. Installed OpenShift Container Platform.
  2. Installed the OpenShift operator for CockroachDB.
  3. Created a 3-node cluster.

Now that our OpenShift Container Platform environment is running a 3-node CockroachDB cluster, we can begin testing our database. Remember: Red Hat OpenShift is a Kubernetes-based platform, so we’ll need to create a secure client pod to run sql commands against our database. Following is the YAML file for doing so:

apiVersion: v1
kind: Pod
name: crdb-client-secure
labels: database crdb-tls-example cockroachdb
serviceAccountName: cockroach-operator-sa
- name: crdb-client-secure
imagePullPolicy: IfNotPresent
- name: client-certs
mountPath: /cockroach/cockroach-certs/
- sleep
- "2147483648" # 2^31
terminationGracePeriodSeconds: 0
- name: client-certs
- secret:
name: crdb-tls-example-node
- key: ca.crt
path: ca.crt
- secret:
name: crdb-tls-example-root
- key: tls.crt
path: client.root.crt
- key: tls.key
path: client.root.key
defaultMode: 256


We have two options for creating the pod: (1) command-line or (2) OpenShift Container Platform console.

Option 1: Command-line

  1. Copy the preceding YAML to a file called “secureClient.yaml.”
  2. Now, to create the pod, run the following command:

notroot@johndoe-mbp-2 openshift % oc apply -f secureClient.yaml
pod/crdb-client-secure configured


Note: The OpenShift Container Platform command-line has a similar look and feel to Kubernetes.

  1. To verify that the secure client pod was created, run  oc get pods .

Option 2: OpenShift Container Platform console

To create pods in the console, do the following:

  1. Click “Workloads.”
  2. On the Pods page, click “Create Pod,” and replace the existing YAML with the preceding manifest.
  3. Click “Create.”
  4. Return to the Pods page, and verify that the client pod “crdb-client-secure” is running.
  5. Click “Pods.”
  6. Search for “crdb-client-secure” to ensure the pod was created successfully.
  7. Connect to the database running on your Kubernetes OpenShift Container Platform environment, using the client pod you just created:

oc exec -it crdb-client-secure -- ./cockroach sql --certs-dir=/cockroach/cockroach-certs/ --host=crdb-tls-example-public


The following output shows the database is successfully connected.

notroot@johndoe-mbp-2 openshift % oc exec -it crdb-client-secure -- ./cockroach sql --certs-dir=/cockroach/cockroach-certs/ --host=crdb-tls-example-public
# Welcome to the CockroachDB SQL shell.
# All statements must be terminated by a semicolon.
# To exit, type: \q.
# Server version: CockroachDB CCL v20.2.8 (x86_64-unknown-linux-gnu, built 2021/04/23 13:54:57, go1.13.14) (same version as client)
# Cluster ID: 8f3b43e0-b25f-4f18-98db-6889cf53aab0
# Enter \? for a brief introduction.


And now, with a successful connection, we can begin building out our database. In terms of language for doing so, CockroachDB is an ansi SQL Database, which means it’s PostgreSQL wire compatible. Applications built on PostgreSQL can often be migrated to CockroachDB without changing application code.

Seeing for yourself

As you can see from this exercise, in which we deployed CockroachDB on a Red Hat OpenShift cluster, Red Hat’s OpenShift Container Platform and CockroachDB complement each other to ease the process of migrating applications from on premises to the cloud. Together, they afford flexibility of deployment, whether you’re on prem or the cloud, hybrid cloud, or multi-cloud. But don’t take our word for it—Try it for yourself. To get started with Red Hat OpenShift Container Platform, go to Red Hat OpenShift. To get started with CockroachDB, CockroachDB Severless, or CockroachDB Dedicated, go to: Cockroach Labs.


Kubernetes, OpenShift Container Platform, OpenShift 4, databases

< Back to the blog