Review request - MicroStack single-node quickstart #6
Conversation
Can someone review the text please? Bonus points: Actually go through the instructions Location: https://microstack.run/docs/single-node
pmatulis
added
openstack
|
0k, can do it in the morning |
| 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`) |
There was a problem hiding this comment.
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?
There was a problem hiding this comment.
I had the same question - it doesn't read like this part is happening inside a sandboxed environment
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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.
|
@pmatulis Just to reassure you - i started going through this and do have some useful feedback! Hopefully will finish before EOD |
| @@ -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. | |||
There was a problem hiding this comment.
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...".
| 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`) |
There was a problem hiding this comment.
I had the same question - it doesn't read like this part is happening inside a sandboxed environment
|
|
||
| ### Configure the cloud and obtain credentials | ||
|
|
||
| Now configure the deployed cloud using the `configure` command: |
There was a problem hiding this comment.
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.
| Access instance with `ssh -i /home/ubuntu/.config/openstack/sunbeam ubuntu@10.20.20.200` | ||
| ``` | ||
|
|
||
| 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. |
There was a problem hiding this comment.
Which provided command is this referring to? The previous one? Or one from somewhere else?
There was a problem hiding this comment.
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.
|
|
||
| ## Related howtos | ||
|
|
||
| Now that OpenStack is set up, be sure to check out the following howto guides: |
There was a problem hiding this comment.
| 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: |
There was a problem hiding this comment.
Someone else got seasick by this. I will concede this for now. See you in Riga.
| * [Accessing the OpenStack dashboard](/t/36232) | ||
| * [Using the OpenStack CLI](/t/36231) |
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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.
|
|
||
| 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 |
There was a problem hiding this comment.
| ## Related howtos | |
| ## Related how-tos |
There was a problem hiding this comment.
yes, I feel a little queasy looking at 'howto', but I'm not sure we settled on a style for it
| - 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 | ||
|
|
There was a problem hiding this comment.
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
There was a problem hiding this comment.
I'm having trouble with deployment over here. I will need to circle back to this at a later date.
|
|
||
| ### 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: |
There was a problem hiding this comment.
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
|
|
||
| Deploy the OpenStack cloud using the `cluster bootstrap` command and accept software defaults: | ||
|
|
||
| sunbeam cluster bootstrap --accept-defaults |
There was a problem hiding this comment.
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:~$
There was a problem hiding this comment.
Good one. I raised a bug on the matter.
To avoid excess verbiage, I just added Juju 3.2.x as a requirement.
|
|
||
| ### Install the openstack snap | ||
|
|
||
| Begin by installing the openstack snap: |
There was a problem hiding this comment.
I usually quote the names of snaps when they differ from the actual name of things: OpenStack /openstackor 'openstack'
There was a problem hiding this comment.
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.
|
|
||
| The script will ensure some software requirements are satisfied on the host. In particular, it will: | ||
|
|
||
| * install `openssh-server` if it is not found |
There was a problem hiding this comment.
maybe also mention Juju here
|
|
||
| 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`): |
There was a problem hiding this comment.
normal maybe isn't the best word. Standard? Default? maybe also explain that they are saved to the local file of that name.
| Deploy the OpenStack cloud using the `cluster bootstrap` command and accept software defaults: | ||
|
|
||
| sunbeam cluster bootstrap --accept-defaults | ||
|
|
There was a problem hiding this comment.
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)...
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
Where, in a network sense, was your server? Possible issue with proxies?
There was a problem hiding this comment.
It was my suspicion too. Digging.
| 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 | ||
|
|
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
I brought this to the attention of the devs. No answer.
| 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 | ||
|
|
There was a problem hiding this comment.
It would be useful to at least give some indication of how these files are used, why they should be kept or whatever
|
|
||
| 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 |
There was a problem hiding this comment.
yes, I feel a little queasy looking at 'howto', but I'm not sure we settled on a style for it
|
|
||
| ## Related howtos | ||
|
|
||
| Now that OpenStack is set up, be sure to check out the following howto guides: |
There was a problem hiding this comment.
is there a teardown guide or are we just expecting people to bin the VM? I imagine the latter but maybe worth mentioning
There was a problem hiding this comment.
I'll need to circle back to this as well. Noted.
| 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`) |
There was a problem hiding this comment.
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 <peter.matulis@canonical.com>
|
Unless anyone has anything else to add I'm going to consider this review complete. To recognise that, I will "merge" this PR. |
Can someone review the included text please?
Bonus points: Actually go through the instructions
Location: https://microstack.run/docs/single-node