Review request - MicroStack single-node quickstart #6

pmatulis · 2023-09-19T20:27:55Z

Can someone review the included text please?

Bonus points: Actually go through the instructions

Location: https://microstack.run/docs/single-node

Can someone review the text please? Bonus points: Actually go through the instructions Location: https://microstack.run/docs/single-node

evilnick · 2023-09-19T20:53:52Z

0k, can do it in the morning

lblythen · 2023-09-19T22:12:03Z

microstack/review-single-node-quickstart/single-node-quickstart.md

+The script will ensure some software requirements are satisfied on the host. In particular, it will:
+
+* install `openssh-server` if it is not found
+* configure passwordless sudo for all commands for the current user (`NOPASSWD:ALL`)


I haven't installed OpenStack to review the script, but does it (and if so should it) retain passwordless sudo for the user after everything's finished, or revert to requiring the password?

I had the same question - it doesn't read like this part is happening inside a sandboxed environment

It is sort of suggested that this is to be run in a VM and I was imagining that it would be somewhat ephemeral one that gets binned, but worth noting somehow, somewhere.

It's great to get this concern. I brought it up a long while ago with the team but I'm going to do so again. I think that escalated privileges should be revoked once a node is added to the cluster, which is what needs the privileges.

Filed an issue here.

evilnick · 2023-09-20T14:42:07Z

@pmatulis Just to reassure you - i started going through this and do have some useful feedback! Hopefully will finish before EOD

s-makin

Overall looks good, although I need to caveat that I don't have a computer capable of running this (my laptop is potato) so I wasn't able to try out the commands for myself. Just a few comments and suggestions from me.

s-makin · 2023-09-20T16:05:49Z

microstack/review-single-node-quickstart/single-node-quickstart.md

@@ -0,0 +1,76 @@
+This tutorial shows how to install MicroStack in the simplest way possible. It will deploy an **OpenStack 2023.1** (Antelope) cloud.


I would recommend making this a bit more personal to start off, something like "In this tutorial we will install MicroStack in the simplest way possible, by deploying an...".

s-makin · 2023-09-20T16:18:40Z

microstack/review-single-node-quickstart/single-node-quickstart.md

+The script will ensure some software requirements are satisfied on the host. In particular, it will:
+
+* install `openssh-server` if it is not found
+* configure passwordless sudo for all commands for the current user (`NOPASSWD:ALL`)


I had the same question - it doesn't read like this part is happening inside a sandboxed environment

s-makin · 2023-09-20T16:23:04Z

microstack/review-single-node-quickstart/single-node-quickstart.md

+
+### Configure the cloud and obtain credentials
+
+Now configure the deployed cloud using the `configure` command:


I assume this command automatically accepts the defaults and doesn't require any user input at this stage (based on the --accept-defaults flag). It may be helpful in a tutorial to point this out explicitly just to keep the reader on track with what they're expected to do/see.

s-makin · 2023-09-20T16:24:21Z

microstack/review-single-node-quickstart/single-node-quickstart.md

+Access instance with `ssh -i /home/ubuntu/.config/openstack/sunbeam [email protected]`
+```
+
+Connect to the VM over SSH using the provided command. Note that the VM will not be ready instantaneously; waiting time is mostly determined by the cloud's available resources.


Which provided command is this referring to? The previous one? Or one from somewhere else?

I'd also recommend adding some sample output of what the user sees when they successfully SSH into the VM, just so they know they've completed the tutorial successfully or not. I'd also suggest adding a closing sentence or two highlighting what the user has successfully just done and how to close it all down again. And possibly how to revert the sudo access if necessary.

s-makin · 2023-09-20T16:24:42Z

microstack/review-single-node-quickstart/single-node-quickstart.md

+
+## Related howtos
+
+Now that OpenStack is set up, be sure to check out the following howto guides:


Suggested change

Now that OpenStack is set up, be sure to check out the following howto guides:

Now that OpenStack is set up, be sure to check out the following how-to guides:

Someone else got seasick by this. I will concede this for now. See you in Riga.

s-makin · 2023-09-20T16:25:34Z

microstack/review-single-node-quickstart/single-node-quickstart.md

+* [Accessing the OpenStack dashboard](/t/36232)
+* [Using the OpenStack CLI](/t/36231)


I usually try to use more active language when it comes to naming how-to guides, so I'd suggest changing these to "Access the..." and "Use the..." respectively.

Yeah, I'm not going to change this here since all my how-tos use "subject gerunds" in this way (possibly another topic for team discussion). Unlike a tutorial, since a how-to can potentially cover a number of closely related subjects (e.g. Working with TLS certificates) that a gerund is the way to go; it's more general sounding.

s-makin · 2023-09-20T16:25:55Z

microstack/review-single-node-quickstart/single-node-quickstart.md

+
+Connect to the VM over SSH using the provided command. Note that the VM will not be ready instantaneously; waiting time is mostly determined by the cloud's available resources.
+
+## Related howtos


Suggested change

## Related howtos

## Related how-tos

yes, I feel a little queasy looking at 'howto', but I'm not sure we settled on a style for it

I'll change.

evilnick

some feedback!

evilnick · 2023-09-20T14:26:38Z

microstack/review-single-node-quickstart/single-node-quickstart.md

+- physical or virtual machine running Ubuntu 22.04 LTS
+- a multi-core amd64 processor ideally with 4+ cores
+- a minimum of 16 GiB of free memory
+


maybe a disk space requirement would be useful - I was setting up a VM for this and had no idea what storage I would need

I'm having trouble with deployment over here. I will need to circle back to this at a later date.

evilnick · 2023-09-20T14:29:29Z

microstack/review-single-node-quickstart/single-node-quickstart.md

+
+### Prepare the machine
+
+Sunbeam can generate a script to ensure that the machine has all of the required dependencies installed and is configured correctly for use in MicroStack - you can review this script using:


It's non-obvious what 'sunbeam' is or that the command is included with the openstack snap. I appreciate this may be covered elsewhere but I'm not sure a simple explanation would hurt

evilnick · 2023-09-20T15:28:29Z

microstack/review-single-node-quickstart/single-node-quickstart.md

+
+Deploy the OpenStack cloud using the `cluster bootstrap` command and accept software defaults:
+
+ sunbeam cluster bootstrap --accept-defaults


This failed for me first time. My VM had already installed the juju snap default version (3.1.5) so the script failed to install the required version. I'm not sure whether the script should do a better job of checking or you want to document around this (worked fine when I snap refreshed to the version I found in the script)

evilnick@jammy:~$ juju version 3.1.5-genericlinux-amd64 evilnick@jammy:~$ sunbeam cluster bootstrap --accept-defaults Error bootstrapping Juju Traceback (most recent call last): File "/snap/openstack/247/lib/python3.10/site-packages/sunbeam/commands/juju .py", line 290, in run process = subprocess.run(cmd, capture_output=True, text=True, check=True) File "/usr/lib/python3.10/subprocess.py", line 526, in run raise CalledProcessError(retcode, process.args, subprocess.CalledProcessError: Command '['/snap/openstack/247/juju/bin/juju', 'bootstrap', 'sunbeam', 'sunbeam-controller', '--agent-version=3.2.0']' returned non-zero exit status 2. ERROR this client can only bootstrap 3.1 agents Error: Command '['/snap/openstack/247/juju/bin/juju', 'bootstrap', 'sunbeam', 'sunbeam-controller', '--agent-version=3.2.0']' returned non-zero exit status 2. evilnick@jammy:~$

Good one. I raised a bug on the matter.

To avoid excess verbiage, I just added Juju 3.2.x as a requirement.

evilnick · 2023-09-20T15:31:41Z

microstack/review-single-node-quickstart/single-node-quickstart.md

+
+### Install the openstack snap
+
+Begin by installing the openstack snap:


I usually quote the names of snaps when they differ from the actual name of things: OpenStack /openstackor 'openstack'

Yeah, my years-old style guide leaves charm names unformatted and I applied that to snap names. I tried to avoid confusion when referring to application names and unit names, which I do format. But I agree that there is something unsatisfactory using these names as-is. 🤔 I'll try bold.

evilnick · 2023-09-20T15:33:17Z

microstack/review-single-node-quickstart/single-node-quickstart.md

+
+The script will ensure some software requirements are satisfied on the host. In particular, it will:
+
+* install `openssh-server` if it is not found


maybe also mention Juju here

evilnick · 2023-09-20T15:38:17Z

microstack/review-single-node-quickstart/single-node-quickstart.md

+
+ sunbeam configure --accept-defaults --openrc demo-openrc
+
+The above command provides normal user credentials (file `demo-openrc`). Admin credentials can be obtained in this way (file `admin-openrc`):


normal maybe isn't the best word. Standard? Default? maybe also explain that they are saved to the local file of that name.

evilnick · 2023-09-20T16:20:23Z

microstack/review-single-node-quickstart/single-node-quickstart.md

+Deploy the OpenStack cloud using the `cluster bootstrap` command and accept software defaults:
+
+ sunbeam cluster bootstrap --accept-defaults
+


it may be worth mentioning that this process can take some amount of time - took around an hour on a reasonably specced VM (6 cores, 32GB RAM)...

My environment timed out on a physical server of 256 GiB of memory and 36 cores. There's something fishy going on if you got it to work in your VM and I could not on this system. There is a lot of image downloading involved but my network should also be very good.

Where, in a network sense, was your server? Possible issue with proxies?

It was my suspicion too. Digging.

evilnick · 2023-09-20T17:15:03Z

microstack/review-single-node-quickstart/single-node-quickstart.md

+Verify the cloud by launching a VM called 'test' based on the 'ubuntu' image (Ubuntu 22.04 LTS). The `launch` command is used:
+
+ sunbeam launch ubuntu --name test
+


evilnick@jammy:~$ sunbeam launch ubuntu --name test
Launching an OpenStack instance ...
Found sunbeam key in OpenStack!
Instance creation request failed: HttpException: 500: Server Error for
url: http://10.20.21.12/openstack-nova/v2.1/images?name=ubuntu,
Unexpected API Error. Please report this at
http://bugs.launchpad.net/nova/ and attach the Nova API log if
possible.
<class 'nova.exception.NotFound'>
Error: Unable to request new instance. Please run sunbeam configure first.

I brought this to the attention of the devs. No answer.

evilnick · 2023-09-20T17:16:07Z

microstack/review-single-node-quickstart/single-node-quickstart.md

+The above command provides normal user credentials (file `demo-openrc`). Admin credentials can be obtained in this way (file `admin-openrc`):
+
+ sunbeam openrc > admin-openrc
+


It would be useful to at least give some indication of how these files are used, why they should be kept or whatever

evilnick · 2023-09-20T17:24:53Z

microstack/review-single-node-quickstart/single-node-quickstart.md

+
+Connect to the VM over SSH using the provided command. Note that the VM will not be ready instantaneously; waiting time is mostly determined by the cloud's available resources.
+
+## Related howtos


yes, I feel a little queasy looking at 'howto', but I'm not sure we settled on a style for it

evilnick · 2023-09-20T17:25:58Z

microstack/review-single-node-quickstart/single-node-quickstart.md

+
+## Related howtos
+
+Now that OpenStack is set up, be sure to check out the following howto guides:


is there a teardown guide or are we just expecting people to bin the VM? I imagine the latter but maybe worth mentioning

I'll need to circle back to this as well. Noted.

evilnick · 2023-09-20T17:27:38Z

microstack/review-single-node-quickstart/single-node-quickstart.md

+The script will ensure some software requirements are satisfied on the host. In particular, it will:
+
+* install `openssh-server` if it is not found
+* configure passwordless sudo for all commands for the current user (`NOPASSWD:ALL`)


It is sort of suggested that this is to be run in a VM and I was imagining that it would be somewhat ephemeral one that gets binned, but worth noting somehow, somewhere.

Signed-off-by: Peter Matulis <[email protected]>

pmatulis · 2023-09-28T17:16:53Z

Unless anyone has anything else to add I'm going to consider this review complete. To recognise that, I will "merge" this PR.

Review request - MicroStack single-node quickstart

abc370f

Can someone review the text please? Bonus points: Actually go through the instructions Location: https://microstack.run/docs/single-node

pmatulis added openstack OpenStack products review request Review content submitted as PR labels Sep 19, 2023

pmatulis assigned evilnick Sep 19, 2023

lblythen reviewed Sep 19, 2023

View reviewed changes

s-makin reviewed Sep 20, 2023

View reviewed changes

evilnick reviewed Sep 20, 2023

View reviewed changes

Edited as per review comments

da85e5f

Signed-off-by: Peter Matulis <[email protected]>

		@@ -0,0 +1,76 @@
		This tutorial shows how to install MicroStack in the simplest way possible. It will deploy an OpenStack 2023.1 (Antelope) cloud.


		### Configure the cloud and obtain credentials

		Now configure the deployed cloud using the `configure` command:


		## Related howtos

		Now that OpenStack is set up, be sure to check out the following howto guides:

		* [Accessing the OpenStack dashboard](/t/36232)
		* [Using the OpenStack CLI](/t/36231)


		Connect to the VM over SSH using the provided command. Note that the VM will not be ready instantaneously; waiting time is mostly determined by the cloud's available resources.

		## Related howtos


		### Prepare the machine

		Sunbeam can generate a script to ensure that the machine has all of the required dependencies installed and is configured correctly for use in MicroStack - you can review this script using:


		Deploy the OpenStack cloud using the `cluster bootstrap` command and accept software defaults:

		sunbeam cluster bootstrap --accept-defaults


		### Install the openstack snap

		Begin by installing the openstack snap:


		The script will ensure some software requirements are satisfied on the host. In particular, it will:

		* install `openssh-server` if it is not found


		sunbeam configure --accept-defaults --openrc demo-openrc

		The above command provides normal user credentials (file `demo-openrc`). Admin credentials can be obtained in this way (file `admin-openrc`):

		Verify the cloud by launching a VM called 'test' based on the 'ubuntu' image (Ubuntu 22.04 LTS). The `launch` command is used:

		sunbeam launch ubuntu --name test

		The above command provides normal user credentials (file `demo-openrc`). Admin credentials can be obtained in this way (file `admin-openrc`):

		sunbeam openrc > admin-openrc

Review request - MicroStack single-node quickstart #6

Are you sure you want to change the base?

Review request - MicroStack single-node quickstart #6

Conversation

pmatulis commented Sep 19, 2023

evilnick commented Sep 19, 2023

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

evilnick commented Sep 20, 2023

s-makin left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

evilnick left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

pmatulis Sep 20, 2023 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

pmatulis Sep 20, 2023 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

pmatulis Sep 20, 2023 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

pmatulis commented Sep 28, 2023

pmatulis Sep 20, 2023 •

edited

Loading

pmatulis Sep 20, 2023 •

edited

Loading

pmatulis Sep 20, 2023 •

edited

Loading