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...
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.
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.