Kicking the tires: Automated CockroachDB test cluster deployment in AWS

Last edited on January 11, 2018

0 minute read

    Today, we’re providing an automated way to setup multi-node CockroachDB clusters so developers can easily try out the latest stable and pre-release functionality. To automate test cluster deployment, we combine AWS CloudFormation (Amazon’s infrastructure automation product) with Kubernetes to let users spin up self-healing, horizontally scaling test clusters with just a couple clicks.


    Automated stack creationCopy Icon

    AWS CloudFormation uses templates, which are instructions that their service can follow to reliably provision services or applications they call “stacks.” When you launch our template, you’ll be sent to a form where you can specify settings like CockroachDB version and cluster size. After you click “create”, AWS will slowly (the whole process takes about 15 minutes) but surely create your environment for test cluster deployment, which will include an Amazon Virtual Private Cloud (VPC), Auto Scaling group, and your Kubernetes-orchestrated CockroachDB cluster. Here’s a rough outline of the architecture:


    When your stack is complete, you will have:

    • access to the connection string for your database,

    • an SSH command to access the K8s master node

    • a link to the web UI.

    That’s all you need to get started!

    Why Kubernetes?Copy Icon

    The CockroachDB architecture has no single points of failure, as each node communicates via a peer-to-peer network to intelligently rebalance, repair, and replicate while maintaining data integrity at all times. However, for this stack, we introduce an additional master node to host Kubernetes. This way, you can take advantage of automatic process management, load balancing, and other orchestration goodness that Kubernetes provides.

    How to use this templateCopy Icon

    We specifically designed this template for testing rather than production use. The stack is deployed in a single Availability Zone so this configuration would not survive a zone outage (though this stack will easily survive node failures if you deploy at least 3 nodes). Furthermore, because traffic is not encrypted, other processes living within the VPC can see plaintext data flowing between nodes. Some things you can use these clusters for:

    • Determining what would be involved in migrating an existing application to CockroachDB

    • Creating a sandbox to evaluate pre-release functionality from our roadmap

    • Getting a sense for the general operational aspects of distributed clusters

    If you need data to play with, we have some load generators to get you started! Need more help? Check out these detailed instructions in docs.

    Please note that AWS charges you for all the resources created by CloudFormation templates, so you’ll want to delete stacks when you are finished.


    Our CloudFormation template and scripts are available on GitHub and were initially forked from Heptio’s AWS Quick Start for Kubernetes.

    This template was created as part of our Free Fridays initiative.

    Illustration by Lisk Feng