SNO Quickstart doc questions

[webbnh]

The SNO quickstart doc says:

We can now set the ssh vars in the ansible/vars/all.yml file since setup-bastion.yml has completed. For bare metal clusters only ssh_public_key_file is required to be filled out. The recommendation is to copy the public ssh key file from your bastion local to your laptop and set ssh_public_key_file to the location of that file. This file determines which ssh key will be automatically permitted to ssh into the cluster's nodes.

It mentions "For bare metal clusters"...should that say "For SNO clusters"?

It mentions copying the public ssh key file from the bastion to your laptop and then setting the variable to point to that file...if I'm running everything on the bastion, why would I want to point to a file on my laptop? In the BM quickstart, there is no analogous advice between the steps for setup-bastion and bm-deploy...are the comments here obsolete? (At this point, the value of ssh_public_key_file is already set to ~/.ssh/id_rsa.pub which looks reasonable for execution on the bastion.)

[akrzos]

It mentions "For bare metal clusters"...should that say "For SNO clusters"?

It is an artifact from copying and pasting the previous quickstart guide for MNO clusters being deployed from your local laptop. The only cluster type that requires both to be filled out is RWN (Remote Worker Node Clusters). Originally jetlag deployed Remote Worker node clusters, then bare metal clusters (or MNO) was added/validated, then lastly SNO was added.

It mentions copying the public ssh key file from the bastion to your laptop and then setting the variable to point to that file...if I'm running everything on the bastion, why would I want to point to a file on my laptop? In the BM quickstart, there is no analogous advice between the steps for setup-bastion and bm-deploy...are the comments here obsolete? (At this point, the value of ssh_public_key_file is already set to ~/.ssh/id_rsa.pub which looks reasonable for execution on the bastion.)

This guide was written from the perspective that you run jetlag from your laptop instead of your bastion. If you want to ssh from your bastion to your nodes, then you would want the ssh keys off the bastion machine to be used while creating/deploying the cluster. (The opposite is very problematic in a lab environment, never copy your personal ssh keys to a lab machine) The BM or MNO guide was re-written 1 year ago to be the perspective of running directly from the bastion as I personally advise this. That way when someone asks for help I can provide hands on help and show them via tmux. In addition, depending on how folks actually get there work done, they could kick jetlag off off the bastion and not worry about their internet connection as well. There are several advantages to using the bastion as the machine running jetlag, however there is always the confusion that jetlag picks the bastion machine and hence the chicken before the egg discussion in the guide. I also asked folks for help to rewrite all the guides as if they were ran from the bastion here.

[dbutenhof]

I also asked folks for help to rewrite all the guides as if they were ran from the bastion #440.

I've noticed that the IBM Cloud doc seems to be the only exception in that it still talks about setting up the laptop. There is slightly different wording in some of the others, which makes me think about refactoring the bastion setup (including pulling the jetlag repo, setting up the ssh keys and ansible) into a separate document that's linked from all the others.

[akrzos]

I've noticed that the IBM Cloud doc seems to be the only exception in that it still talks about setting up the laptop. There is slightly different wording in some of the others, which makes me think about refactoring the bastion setup (including pulling the jetlag repo, setting up the ssh keys and ansible) into a separate document that's linked from all the others.

This SNO guide is just a copy and paste of the original BM/MNO guide and then adjustments made for SNO. The task I linked is definitely open ended with the goal being less people asking for help. I find keeping the guide as short as possible that way when folks ask how do I do this with jetlag, I can say it is a single page document to go from blank environment to full cluster. I think we should strive to keep it to a single page, more linking of documents makes the docs even less maintained IMO.

[dbutenhof]

I do like the "single page", but I also like "single point of truth" to avoid skews in documentation (or code) like the one we see here. And I'm not sure of any reliable long-term solution short of links to a single description of the installation/startup sequence. (Too bad GitHub markdown doesn't have an "include here" so we could do both.)

[akrzos]

I'm not sure I understand what you mean by skew in documentation? Do you mean that the ibmcloud docs still reference installing from your laptop? You can install/setup jetlag from either your laptop of the bastion machine. Originally I wrote the docs how I would run from my laptop since I would also develop jetlag there and push commits to the repo, as more folks started reusing my tool, I found it better to ask if they would run from the bastion which is actually how I do it when I am not developing for jetlag but running my tests.

[josecastillolema]

May we close this @webbnh ?

[akrzos]

I vote close this