Use init command in local cluster instructions?

[a-robinson]

As was pointed out by a user in cockroachdb/cockroach#20241 (comment), we don't use the init command in our local cluster instructions:

https://www.cockroachlabs.com/docs/stable/start-a-local-cluster.html
https://www.cockroachlabs.com/docs/stable/start-a-local-cluster-in-docker.html

Is there a reason why not other than just not having gotten around to it?

[jseldess]

We updated a bunch of the core benefits tutorials to use init. I think we left the start a local cluster tutorials as they are so as to be able to emphasize the difference between a single-node and multi-node cluster:

At this point, your cluster is live and operational. With just one node, you can already connect a SQL client and start building out your database. In real deployments, however, you'll always want 3 or more nodes to take advantage of CockroachDB's automatic replication, rebalancing, and fault tolerance capabilities. This step helps you simulate a real deployment locally.

But I'm totally open to simplifying and using init everywhere. We might want to make it clear somewhere that it's fine to start a single-node cluster without --join, though.

What are your preferences, @a-robinson?

[bdarnell]

You can't (currently) use the init command unless the node was started with a --join flag. Joining the single node to itself and then using the init command is confusing. I don't think we want to go that far to make the single-node workflow look like multi-node.

We could change things so that the init command is always required even without the join flag. This would look nicer than the self-join currently required (and it eliminates the risk that a node restarts without the join flag and initializes a new cluster), but again it imposes an extra step on what was originally just cockroach start.

I think it might be best if we recognize that single-node clusters are fairly different from multi-node clusters and introduce a new flag/command for them. cockroach start --single-node would init the node automatically and set the default zone config to 1 replica. We may want to go so far as to change the defaults for other flags (for example, a single node might default to --host=localhost). I think if we did this then we'd mandate that either --join or -single-node be used and get rid of the current auto-init by default.

[a-robinson]

The current arrangement seems reasonable. Emphasizing the difference between a single-node cluster and a multi-node one is worthwhile. Thanks for explaining.

I think it might be best if we recognize that single-node clusters are fairly different from multi-node clusters and introduce a new flag/command for them. cockroach start --single-node would init the node automatically and set the default zone config to 1 replica. We may want to go so far as to change the defaults for other flags (for example, a single node might default to --host=localhost). I think if we did this then we'd mandate that either --join or -single-node be used and get rid of the current auto-init by default.

I think there's something there, but changing flag defaults sounds annoying, and that adds the new failure mode of forgetting to change the replication configuration when you do decide to switch from a single node to multiple nodes. I'm going to close this since I don't think there's anything to be done to the docs, regardless.