Install and Configure MicroStack Sunbeam (Single node)

Key Value
Summary Run OpenStack on Kubernetes in minutes with MicroStack and Sunbeam.
Categories cloud
Difficulty 3
Authors Tytus Kurek , Liam Young


Duration: 1:00

What is OpenStack?

OpenStack is a collection of open-source projects designed to work together to form the basis of a cloud. OpenStack can be used for both private and public cloud implementation.

What is MicroStack?

MicroStack is an OpenStack flavour designed for the edge and small-scale data centre deployments, that can be installed and maintained with minimal effort. MicroStack abstracts the complexity behind OpenStack, providing an opinionated approach to its architecture design and straightforward installation instructions.

What is Sunbeam?

Sunbeam is a collection of libraries for writing Kubernetes operators for OpenStack services. Together with MicroStack, Sunbeam delivers distilled OpenStack excellence with native K8s experience.

In this tutorial you will learn how to:

  • Get a single-node OpenStack cloud up and running with MicroStack
  • Interact with OpenStack via the web UI and CLI
  • Launch your first VM on OpenStack and access it

You will need:

  • A machine running Linux, a multi-core amd64 processor and at least 8 GB of RAM

MicroStack has been tested on a physical machine running either Ubuntu 20.04 LTS or Ubuntu 22.04 LTS.

Install MicroStack

Install Microk8s

Duration: 10:00

If you are using an older Ubuntu version or some other Linux distribution, you may have to install snapd first. Refer to snapd documentation for more information on installing snapd on your computer.

Install the microk8s snap:

sudo snap install microk8s --channel 1.25-strict/stable
sudo microk8s status --wait-ready

Configure microk8s dns.:

The IP addresses to use for DNS resolution (here and should be changed if the server does not have access to these.

sudo microk8s enable dns:,

Configure microk8s storage:

sudo microk8s enable hostpath-storage

Configure loadbalancer:

! MetalLB
The range of IP addresses in the sudo microk8s enable metallb command (here should come from the same subnet as your primary network interface if you want to access the OpenStack APIs from another machine. Please reserve at least 10 IP addresses in the range you specify.

sudo microk8s enable metallb

When the last command has completed give your user permissons to use microk8s:

sudo usermod -a -G snap_microk8s $USER
sudo chown -f -R $USER ~/.kube
newgrp snap_microk8s

Prevent microk8s from restarting:

touch /var/snap/microk8s/current/var/lock/no-cert-reissue 

Install Juju

sudo snap install juju --channel 3.0/candidate
mkdir -p .local/share

Install Microstack and hypervisor snaps

Now it is time to install the microstack snap from the sunbeam channel:

sudo snap install microstack  --channel sunbeam/beta

The control plane will be running inside microk8s but the hypervisor runs outside in its own snap, so install the hypervisor snap:

sudo snap install --channel xena/beta openstack-hypervisor

Note that at the time of writing this tutorial, the installed version of OpenStack was Xena.

Being a snap, MicroStack is published in channels which are made up of a track (or a major version), and an expected level of stability. You can run snap info microstack command to see which versions are currently available.

Initialise MicroStack

Duration: 20:00

MicroStack needs to be initialised, so that networks and databases get configured. To do this, run:

microstack bootstrap

If this command results in an error, refer to the “Collecting debug information” part of this tutorial for more information.

Once this completes (15 - 20 minutes) your OpenStack cloud will be up and running!

At this point images, flavors, networks can be manually setup using the standard OpenStack client commands or microstack configure can do some basic setup for you.

microstack configure -o demo_openrc

During the configure step microstack will ask a few straight forward questions and then place credentials into the demo_openrc file that can be used to access the cloud either via the command line or the web UI.

Interact with OpenStack

Duration: 4:00

Admin Credentials

The microstack configure step provides normal user credentials but if admin credentials are required then these can be obtained:

microstack openrc > admin_openrc

Web UI

To get the address of the webUI

juju status -m openstack 2>/dev/null | grep horizon | head -n 1 | awk '{print $9}'       

So to interact with the webUI visit

Type in credentials, use users as a domain name and press the “Sign In” button:

If everything goes fine you should see the landing page:

You can now start playing with your OpenStack installation (i.e. create additional users, launch instances, etc.).


You can also interact with your OpenStack cloud via the CLI by using the standard openstack commands. For details on the syntax see python-openstackclient package. To install the openstack cli tools:

sudo snap install openstackclients

The client can now be used to interact with microstack.

Launch and access a VM

Duration: 5:00

The following assumes that the default setup was applied using microstack configure

Test launch

To launch your first OpenStack instance (VM) called “test” based on the Ubuntu image, run the following:

Set environment variables with access information:

source demo_openrc 

Upload the an public key to use for accessing guests.

openstack keypair create --public-key /home/$USER/.ssh/ mykey

Next launch a server:

openstack server create --image ubuntu-jammy --flavor m1.small --key-name mykey --network demo-network test-server --wait

To access the server it needs to have an external IP address assigned, so the next step is to create one and assign it to the server:
Note that the floating IP address created may be different in your environment.

fip=$(openstack floating ip create external-network -f value -c floating_ip_address)
openstack server add floating ip test-server ${fip}

In order to connect to the instance run the command from the output:

ssh -i /home/ubuntu/.ssh/id_rsa ubuntu@${fip}

Now that you are connected to the instance you can use normal Linux commands:

$ uptime
 14:51:42 up 4 min,  1 users,  load average: 0.00, 0.00, 0.00

To disconnect from the instance, type exit (or Ctrl-d).

Collecting debug information

If there are any problems with installing and configuring microk8s see Microk8s Troubleshooting Guide

If the microstack bootstrap or microstack configure steps fails the try running them again with the -v flag. The output from this can then be included when raising a bug.


microstack -v bootstrap

The deployment information below will be useful when diagagnosing any issues.

Juju overview of the control plane deployment:

juju status --model openstack --format yaml > juju-status.yaml

Logs from the charms:

juju debug-log --model openstack --replay > juju-debug-logs.txt

Status of the pods:

microk8s.kubectl describe -n openstack pods > pods.txt

Status of microk8s:

microk8s.status > microk8s_status.txt

To collect information from a specific OpenStack service the logs for the service can be collected directly from the container. For example to collect the glance logs:

juju ssh --model openstack --container glance-api glance/0 "tar cvf /tmp/glance-logs.tar var/log"
juju scp --model openstack --container glance-api glance/0:/tmp/glance-logs.tar ./glance-logs.tar

Next steps

Learn more by reading the MicroStack documentation.

That’s all folks!

Duration: 1:00

Congratulations! You have made it!

Where to go from here?


Just some additions to the above tutorial:

  1. It should be (for now) “edge” channel (not “beta”) on the microstack snap install.

  2. “microstack configure” does not seem to exist anymore, so just ignore this step.

  3. “microstack openrc” can be used to get the openrc file contents instead of the juju “get-admin-account” command (both are similar but output in the first is nicer).

  4. Before actually being able to create a VM, you need to upload an image to glance, create a flavor, create a tenant network and maybe an external network + router for FIPs. This steps are not shown in the tutorial.

Note: the ability to add FIPs on the single-host scenario is being worked on at the moment.

1 Like

We want end users to install from beta rather than edge so as that’s the intended channel for consumption we should target the docs at this.

I think that the last set of changes are still pending manual review by the snap store team - the configure action will setup all of the configuration needed to actually launch an instance on the cloud as so describe in 4).

Good spot on the “openrc” command - much easier that running the action!

Ah, ok, so I jumped the gun here :slight_smile: Thank you for the clarifications.

1 Like

Thanks for taking the time to give the tutorial a spin. There have been quite a few updates to microstack and to this tutorial since you last tried it. If you have any time to try it again it’d be great to get any feedback.

I was successful at installing. Couple things:

  1. Couldn’t find demo-network when launching server
  2. How do I use SSL for Horizon
  3. How do I access from outside? Can’t see a port 80 going…(possibly 7946?)

Cheers, Dave

After reboot:
ubuntu@fss-cloud01:~$ openstack server create --image ubuntu-jammy --flavor m1.small --key-name mykey --network demo-network test-server --wait
Failed to discover available identity versions when contacting Attempting to parse version from URL.
Could not find versioned identity endpoints when attempting to authenticate. Please check that your auth_url is correct. Unable to establish connection to HTTPConnectionPool(host=‘’, port=80): Max retries exceeded with url: /openstack-keystone (Caused by NewConnectionError(’<urllib3.connection.HTTPConnection object at 0x7f6f562cf898>: Failed to establish a new connection: [Errno 110] Connection timed out’,))

@quasimotoca hey - thanks for giving sunbeam a try out and thankyou for the feedback - responses below:


The demo-network will be named for whatever username you provided during the microstack configure step of the deployment - just with the -network suffix.


This is on the roadmap but for this initial preview SSL is not supported.

External Access

This is possible - when you configure metallb via microk8s you’ll need to provide a range of network addresses that would be externally accessible and usable on the machine you’re deploying on. This will allow access to API’s and Horizon from outside of the machine.

Its also possible to wire the software defined network to the external network as well - this will require use of appropriate values during the configuration phase - just make sure to not configure networking for host only networking at the end of this phase.

You can then add a port to the Open vSwitch bridge manually to provide access to and from instances to the outside world:

sudo openstack-hypervisor.ovs-vsctl add-port br-ex <spare port on machine>

That port needs to not be used for anything else.

Your reboot issue is a know problem that we are working on - currently the mysql service comes back in read only mode which then creates issues for all of the API services.

I tried a the tutorial running on a Multipass 22.04 vm running on macOS 13.0.1. All good until the microstack bootstrap. The vault unit is failing the config-changed hook. A few errors, but this one is an uncaught. Vault was definitely having the issues.

unit-vault-0: 13:31:11 ERROR unit.vault/0.juju-log Uncaught exception while in charm code:
hvac.exceptions.VaultDown: Vault is sealed, on get http://localhost:8200/v1/sys/mounts

I have the logs saved if you’d like to check them out.