setup.sh: simplify

[grahamc]

Whew this is a bigger PR than I intended, but here goes! Here are some of the larger commits, conceptually, explained.

I understand one of the initial ideas was to have Tinkerbell be "docker-easy" to install, but Tinkerbell is not a trivial tech stack and has specific requirements about the network and what-not. I think it isn't a good idea to put too much smarts in to the setup.sh itself and instead only focus on the things it can reasonably do correctly. Getting fancy here actually made it harder to install Tinkerbell than if some of the steps had been manual in the first place.

The idea here is clarifying what I think setup.sh is for:

• get users from a tinkerbell capable OS to a running tinkerbell without a lot of fuss
• the install is not secure to allow for greater poking and prodding and learning
• a process which is not too fancy to make it easier to follow
• ideally, a senior infra engineer could read the scripts and easily understand how the components should be configured for a production, secure environment

The workflow I'm proposing here is:

1. clone tinkerbell
2. generate an envrc with ./generate-envrc.sh
3. install docker and docker-compose
4. run ./setup.sh
5. run docker-compose up

It isn't totally done, but this PR includes a significant amount of the work required to do it.

What do y'all think?

This PR also makes the script shellcheck-validated.

setup.sh: don't install software automatically

Installing software is complicated, and I think it is reasonable to
ask the user to install some software on their own. We could extend
the error messages with suggestions on how to find the packages, or
links to the install pages for docker and docker-compose.

That said, I'm not sure 82 lines of fairly complex code to cover just
2 distros is worth it.

generate-envrc: make its own, trivial, shell script

Kick the network configuration settings to the user. This fixes
the problem of the very complex bash logic for IP math. This also
makes it safe(r) to re-run setup.sh since the registry password
isn't regenerated automatically.

network configuration

don't try too hard to configure the network. If it isn't easy, tell the user what we want and then let them finish the job.

split mutability

Especially with the cert generation, these changes don't modify files checked in to the repo, and have a specific state directory where all the output goes.

[grahamc]

This is RFR! Note reading the final diff is not easy -- it would be easier to read the setup.sh script start to finish in the final form, or individual commits on the way.

[gianarb]

I like the philosophy behind the refactoring. Only do what is simple, tell the user if something is not trivial. This increases the portability of this script and it makes it a good way to learn the setup workflow along the line:

1. Understanding the requirements
2. Figuring out the networking

for example, are perfect to contextualize Tinkerbell itself.

I will have a look at the setup.sh and I will try it as well very soon. I only have one point at the moment. Do you mind to write in markdown form documentation about the script itself? Do you think we have the structure do it already? I think it will help the reviewer to validate if the installation workflow is a good way to teach the required setup by itself.

[grahamc]

I guess I wonder to what extent should we document the script separately? Probably the most important thing to document is how to configure the networking, as the rest is pretty tedious:

Configure Networking

• have an interface dedicated to tinkerbell
• enable network forwarding
• add your HOST_IP and NGINX_IP

[grahamc]

Of course one of the best things about writing documentation is it points out how needlessly tedious things are. For example, a few things could be simplified:

• make an osie tarball which can just be extracted, not just extracted and then have things moved around
• or: don't even host osie locally, and instead use a caching proxy to fetch osie files directly from the s3 bucket at execution time

and, instead of using fluentbit and elasticsearch, use some other, trivial log aggregator

and, instead of having a local registry, use dockerhub or something

[gianarb]

Yeah, documentation is hard but I think as soon as we structure it (ideally as part of this PR), easier it will be to move forward.

How the structure is:

• Setup
  *. Packet

My feeling (and I am happy to be wrong) is that Setup does not inspire me to move over. I think the setup has to explain Provisioner/Worker and it has to highlight what is generic, and I mean steps:

1. Introduction: worker and provisioner
2. Provider: Tinkerbell works in a lot of different places, right now you can use Vagrant locally and Packet (both will have their own page)
3. General step:
   *. Install git, docker, compose...
   *. Network: it is a good practice to have an independent network used only for the provisioning... it looks like this bla bla if you can use ip or netplan or ....
   *. The repo serves a bunch of scripts that you can use and they work..... they are not mandatory because we think that experienced sysadm will have their own way and we write them in a way that makes the learning process affordable.

In this way, the setup already gives you a bunch of information about what's gon on here. At this point you have to select a provider, for now, Packet. The Packet documentation will go over the same points but with the assumptions the platform has.

1. Introduction: tink repository provides a terraform template that you can use to create provisioned and worker, check it to figure out how they look...
2. Provider: how the network card are setup, VXLAN, Operating System used for this example
3. General step:
   *. apt-get install -y docker git docker-compose...
   *. Network: we use netplan (ideally in the Packet/2. they know how networking looks like) so here we can place yaml and commands to run
   *. clone the repo and run the scripts

This is how I am imagining the documentation right now. The same it will happen for Vagrant as soon as we will have it

[gianarb]

We have to stay strict to what Setup is, so do not goo do deep on everything all in once or it will become unreadable, but we have to write enough context to make the documentation not only a set of steps to follow but a process that at the end will leave the user with reusable knowledge that we can leverage later in other parts of the documentation

[grahamc]

In my most humble of opinions, "add all the docs" shouldn't block a PR mostly focused on "make the script understandable." I agree with your goal here, and in fact my first day I wrote a very long document about the problems of the current documentation and the setup process. My major point of feedback was "Tinkerbell needs a technical writer." Thankfully, Tinkerbell is getting a documentation writer on Monday.

[gianarb]

I didn't have all the background here, so, IN GENERAL, I like to see the documentation included where the code changes, but if this case sounds different I am fine with it 😄 I don't feel powerful enough to block any PR to get merged and even if I am, that won't be the case looking at the last comment somebody else will take care of it 👍

[mrmrcoleman]

My 2 cents. We're very aware of the documentation issues. Once this and the vagrant issue are merged we can list 'local' on the website and then run through again to make things clearer.

In summary: let's not couple all the issues to each other but instead get these through so we can focus on docs as the next P1.

[gianarb]

The code looks good and way simpler compared with the one we had before. It makes more assumption but I think it drives the user to a learning activity that better applies to my way of thinking.

[grahamc]

One thing is the setup.sh can almost run rootless, but a few tricky bits crop up, especially around networking. I guess this is probably okay... but I'm not sure. Should we expect the user to run this as root, or should we call sudo in the script, or..? If we run it as root, we mess up the state directory's permissions.

[mmlb]

what a doozie, lgtm.

[mmlb]

can do cat <<-EOF to avoid indent changes. But for follow up PR is fine.

[mmlb]

I guess no longer need the local but meh.

[rgl]

Just a friendly reminder to let you known that https://github.com/tinkerbell/tink/blob/master/docs/setup.md was not updated to reflect these changes.