Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Review request - MicroStack single-node quickstart #6

Open
wants to merge 2 commits into
base: main
Choose a base branch
from
Open

Review request - MicroStack single-node quickstart #6

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
abc370f
Review request - MicroStack single-node quickstart
Sep 19, 2023
da85e5f
Edited as per review comments
Sep 22, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
82 changes: 82 additions & 0 deletions microstack/review-single-node-quickstart/single-node-quickstart.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,82 @@
In this tutorial we will install MicroStack in the simplest way possible, by deploying an **OpenStack 2023.1** (Antelope) cloud.

The cloud will only allow access to its VMs from the local host. To enable access from any host on your network, follow the [Single-node guided](/t/35765) tutorial instead.

## Requirements

You will need a single machine whose requirements are:

- 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
- Juju 3.2.x

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

[note type="caution"]
**Caution:** Any change in IP address of the local host will be detrimental to the deployment. A virtual host will generally have a more stable address.
[/note]

## Deploy the cloud

### Install the **openstack** snap

Begin by installing the **openstack** snap:

sudo snap install openstack --channel 2023.1

### 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:
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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


sunbeam prepare-node-script

or the script can be directly executed in this way:

sunbeam prepare-node-script | bash -x && newgrp snap_daemon

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

* install the `openssh-server` deb package if it is not found
* install the **juju** snap if it is not found
* configure passwordless sudo for all commands for the current user (`NOPASSWD:ALL`)
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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?

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Filed an issue here.


### Bootstrap the cloud

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

sunbeam cluster bootstrap --accept-defaults
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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:~$

Copy link
Author

@pmatulis pmatulis Sep 20, 2023 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Good one. I raised a bug on the matter.

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


Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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)...

Copy link
Author

@pmatulis pmatulis Sep 20, 2023 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It was my suspicion too. Digging.

### Configure the cloud and obtain credentials

Now configure the deployed cloud using the `configure` command. The `--accept-defaults` option will provide sensible default values:

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

The above command provides regular (non-admin) user credentials by saving them to file `demo-openrc`. Admin credentials can be obtained and stored (in file `admin-openrc`) in this way :

sunbeam openrc > admin-openrc

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

These credential files contain standard OpenStack parameters that define the cloud and provide user access to the cloud.

## Launch a VM

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

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Sample output:

``` text
Launching an OpenStack instance ...
Access instance with `ssh -i /home/ubuntu/.config/openstack/sunbeam [email protected]`
```

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

ssh -i /home/ubuntu/.config/openstack/sunbeam [email protected]

## Related how-tos

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

* [Accessing the OpenStack dashboard](/t/36232)
* [Using the OpenStack CLI](/t/36231)
Comment on lines +81 to +82
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.