Some comments I have regarding the documentation. It seems like there is a lot describing how to set up a cluster and how to do various SQL operations that most people probably know how to do.
I think the information that should be presented much more clearly are:
1.) How do we have to partition our data/what restrictions are in place? Basically, what considerations are necessary when designing the data model due to the constraints of the technology?
2.) What functionality that we expect from RDBMS do we give up when working across partitions? Can foreign keys exist across partitions? Can joins work? Inner/Right joins?
Head of Docs and Training at Cockroach Labs here. Thanks for this feedback, ralusek. It's spot on, and we're planning to create much more direct and prescriptive guidance and best practices for working with CockroachDB across multiple regions. That's when placement of data (via geo-partitioning or other approaches) is crucial for reducing network latency.
Last month I tried to deploy cockroachdb in Kubernetes and I felt the documentation wanted to treat me like a 5-year-old.
I don't think the your product documentation has to explain what Kubernetes is or its terminologies[1].
The worst part is that it does not tell the cluster admins what need to be setup in the Kubernetes cluster at all, instead, it wraps a bunch of `kubectl` commands in a Python script and says "just download the script and run it"[2]. I know a simple `python setup.py` command is easier for novice to just try out. But it could really gives seasoned Kubernetes admins some headache...Our clusters enforce GitOps and nothing can bypass pull requests. Running some random `kubectl` commands is simply impossible. I ended up spending my day reading and translating the script into Kubernetes object definitions by hand and I didn't enjoy it...
Appreciate this feedback, and sorry those docs didn't help you much. If you'd be willing to open a github issue with some details about your need to translate the commands in our docs into something more useful for your use case, we'll look into this further: https://github.com/cockroachdb/docs/issues. The input would be greatly appreciated.
I'm curious why you would want to deploy CockroachDB in a K8 cluster. Not being critical...genuinely curious. Since it has its own idea of a cluster, it sounds complex to me. Especially since the typical geographically wide CockroachDB cluster would likely span outside a region centric k8s cluster.
(Cockroach Labs developer here) In CockroachDB parlance, a "cluster" is just some number of cockroach binaries that have local storage and can connect to one another via TCP/IP. It's entirely feasible to run a multi-node cluster on a single laptop by just starting several instances of cockroach bound to different port numbers.
The Kubernetes concept of a "cluster" is a much broader term, encompassing the compute nodes and a lot of control-plane software to make all of the magic happen.
Fundamentally, running CockroachDB on a Kubernetes cluster abstracts away the process of getting the cockroach binary running and offers a lot of convenience to the human operator vis-a-vis reliability and service discovery.
We like to say that CockroachDB is "Kubernetes native" in that you can easily build a CRDB cluster using only the basic k8s building blocks, without requiring a separate operator program to manage the deployment.
Utilities like Helm et al. are certainly easier than managing a bunch of YAML configs, but they are entirely optional.
Some other CockroachDB+Kubernetes synergies to consider:
1) When using a StatefulSet and PersistentVolumes, a CockroachDB node will easily survive being rescheduled off of its underlying host (e.g. due to maintenance or hardware failure) with no human effort needed.
2) All cockroach instances are, from the perspective of a client, homogenous. That is, a client can send a SQL query to any member of a CockroachDB cluster and get a meaningful response. This maps exactly onto the k8s Service abstraction.
3) Federated k8s clusters and multi-region network fabrics do exist, although they're not exactly common yet. CockroachDB can maintain its clustering across "non-uniform network architectures" that exist within- and cross-region.
Comments
Some comments I have regarding the documentation. It seems like there is a lot describing how to set up a cluster and how to do various SQL operations that most people probably know how to do.
I think the information that should be presented much more clearly are:
1.) How do we have to partition our data/what restrictions are in place? Basically, what considerations are necessary when designing the data model due to the constraints of the technology?
2.) What functionality that we expect from RDBMS do we give up when working across partitions? Can foreign keys exist across partitions? Can joins work? Inner/Right joins?
Head of Docs and Training at Cockroach Labs here. Thanks for this feedback, ralusek. It's spot on, and we're planning to create much more direct and prescriptive guidance and best practices for working with CockroachDB across multiple regions. That's when placement of data (via geo-partitioning or other approaches) is crucial for reducing network latency.
In case you haven't seen them, for now, we have docs on some data placement patterns for multi-region deployments: https://www.cockroachlabs.com/docs/stable/topology-patterns..... We believe the first and third are best for most cases. This tutorial also walks through the impact of using those patterns in a cluster spread across 3 regions of the US: https://www.cockroachlabs.com/docs/stable/demo-low-latency-m...
But we'll definitely continue working on better guidance here.
Last month I tried to deploy cockroachdb in Kubernetes and I felt the documentation wanted to treat me like a 5-year-old.
I don't think the your product documentation has to explain what Kubernetes is or its terminologies[1].
The worst part is that it does not tell the cluster admins what need to be setup in the Kubernetes cluster at all, instead, it wraps a bunch of `kubectl` commands in a Python script and says "just download the script and run it"[2]. I know a simple `python setup.py` command is easier for novice to just try out. But it could really gives seasoned Kubernetes admins some headache...Our clusters enforce GitOps and nothing can bypass pull requests. Running some random `kubectl` commands is simply impossible. I ended up spending my day reading and translating the script into Kubernetes object definitions by hand and I didn't enjoy it...
1. https://www.cockroachlabs.com/docs/stable/orchestrate-cockro... 2. https://github.com/cockroachdb/cockroach/blob/master/cloud/k...
Appreciate this feedback, and sorry those docs didn't help you much. If you'd be willing to open a github issue with some details about your need to translate the commands in our docs into something more useful for your use case, we'll look into this further: https://github.com/cockroachdb/docs/issues. The input would be greatly appreciated.
I'm curious why you would want to deploy CockroachDB in a K8 cluster. Not being critical...genuinely curious. Since it has its own idea of a cluster, it sounds complex to me. Especially since the typical geographically wide CockroachDB cluster would likely span outside a region centric k8s cluster.
(Cockroach Labs developer here) In CockroachDB parlance, a "cluster" is just some number of cockroach binaries that have local storage and can connect to one another via TCP/IP. It's entirely feasible to run a multi-node cluster on a single laptop by just starting several instances of cockroach bound to different port numbers.
The Kubernetes concept of a "cluster" is a much broader term, encompassing the compute nodes and a lot of control-plane software to make all of the magic happen.
Fundamentally, running CockroachDB on a Kubernetes cluster abstracts away the process of getting the cockroach binary running and offers a lot of convenience to the human operator vis-a-vis reliability and service discovery.
We like to say that CockroachDB is "Kubernetes native" in that you can easily build a CRDB cluster using only the basic k8s building blocks, without requiring a separate operator program to manage the deployment.
You can `kubectl apply` this config and get a fully-functioning cluster. https://github.com/cockroachdb/cockroach/blob/master/cloud/k...
Utilities like Helm et al. are certainly easier than managing a bunch of YAML configs, but they are entirely optional.
Some other CockroachDB+Kubernetes synergies to consider:
1) When using a StatefulSet and PersistentVolumes, a CockroachDB node will easily survive being rescheduled off of its underlying host (e.g. due to maintenance or hardware failure) with no human effort needed.
2) All cockroach instances are, from the perspective of a client, homogenous. That is, a client can send a SQL query to any member of a CockroachDB cluster and get a meaningful response. This maps exactly onto the k8s Service abstraction.
3) Federated k8s clusters and multi-region network fabrics do exist, although they're not exactly common yet. CockroachDB can maintain its clustering across "non-uniform network architectures" that exist within- and cross-region.