How-To: From single node to multi-node cratedb clusters

[joemoe]

from a cab interview:

Setting CrateDB up locally
Where customers would encounter problems as well, is setting up CrateDB outside of the Cloud. While the Cloud "obviously does everything that you want it to do", it's really hard to do a setup of CrateDB outside of the Cloud and run it locally.

For example, there is no easy way from a single-node installation to a multi-node installation, a setup, with which many people start when using CrateDB, Walter assumes.

Once you start it up on the first node, Crate says: I’m alone in this world and no one ever gonna join my tribe.

It is hard to go from one node to a multi-node setup.

[matthijskrul]

Can be combined with https://github.com/crate/new-tech-content/issues/36 possibly - though it's not completely the same use case

[nomicode]

the changes made to https://crate.io/docs/crate/howtos/en/latest/clustering/multi-node-setup.html since this issue was created should address this

the "Single-host auto-bootstrapping" section ought to mention this limitation. however, it currently does not and I am not confident enough about my understanding of CrateDB bootstrapping to know what the potential problem is (as reported by Joe), so I don't know what to suggest

some questions:

• can you go from one node to multiple nodes when using single-host auto-bootstrapping? (I suspect the answer is yes)

• can you go from one node to multiple nodes when using manual bootstrapping? (I also suspect the answer is yes)

if the answer to both of those is yes, perhaps the issue is not going from one node to multiple nodes, but rather going from auto-bootstrapping to manual bootstrapping

the WARNING admonition seems related, but also seems to be describing a separate problem

@mkleen can you weigh in on this? I would like input from a core engineer. I could just experiment with a local CrateDB node but I can imagine that swallowing a few hours and maybe you have a quick answer! :)

I expect the fix for this issue is to update multi-node-setup.html. perhaps clarifying the WARNING admonition, or perhaps adding an additional section or admonition

in addition, I notice a few small stylistic issues (lack of sentence case for list items) and a small typo (errant closing parenthesis in the WARNING) that could be fixed at the same time

[mkleen]

• can you go from one node to multiple nodes when using single-host auto-bootstrapping? (I suspect the answer is yes)
• can you go from one node to multiple nodes when using manual bootstrapping? (I also suspect the answer is yes)

I would say yes in both cases. @seut what is your take here ?

[nomicode]

merging https://github.com/crate/tech-writing-domain/issues/222 into this issue

[nomicode]

updated labels and removed "content pitch" boilerplate as I expect this is can be resolved with some edits to the existing material. however, the questions above still need clarification before we can move forward

[nomicode]

@mfussenegger can I get your input here?

[mfussenegger]

Based on the original issue I think the content would require a bit more work than just slapping on a warning. Instead it should guide the user more based on what the user wants to accomplish.

First scenario is running CrateDB on a local machine for development or testing. In that case the auto-bootstrapping is the best option.

Second scenario is setting up a single node system for production.
Third scenario is adding one or more nodes to an existing node or cluster.

[nomicode]

@jordi thanks for the feedback

I have been trying to think of a way to insert that content into this page, but the more I think about it the more it doesn't seem to fit

do you think it would be a good idea to create a new document called "CrateDB single-node setup"? that doc would presumably explain why you might want to do this, how to do it, and end with a section telling you what you need to know if you want to migrate to a multi-node setup (but letting the existing doc on multi-node setups do the heavy lifting for anything not specifically related to that migration process)

related question: I am presuming that there are indeed situations in which running a single-node setup is desirable. is that the case? if it is not the case, then my proposal above doesn't make sense to me. I would rather add a short section to the multi-node doc, sandwiched in between the single-host autobootstrapping section and the manual bootstrapping section, explaining why a single-node setup is not a good idea, and instructing people on how to migrate in case they already have a single node system running

[mfussenegger]

I am presuming that there are indeed situations in which running a single-node setup is desirable. is that the case?

Yes, for a cheap staging/dev environment it can certainly make sense. Or even in production when your HA requirements allow for it and you don't have the load yet to justify scaling out.

To me this is also a bit related to https://github.com/crate/tech-writing-domain/issues/390

There are different angles that users can come from. Trying out CrateDB. Setting it up for production and scaling out. I think covering them from a use-case perspective would make sense.

I assume @WalBeh and @proddata would also have inputs about this.

[proddata]

I think it would be a good idea to have a separate article on single node setups. We definitely also see production use cases with single nodes (e.g. if crate is running on a industrial pc right next to a machine). I'd think that some of the mechanics are different and it especially important to follow routines for stopping/upgrading those single nodes. I will try to share some insights soonish.

[hlcianfagna]

Partially addressed with https://community.crate.io/t/how-to-add-new-nodes-to-an-existing-cluster/1546