diff --git a/tutorial/get-started-with-openstack.rst b/tutorial/get-started-with-openstack.rst index 277e6d6..6e8b777 100644 --- a/tutorial/get-started-with-openstack.rst +++ b/tutorial/get-started-with-openstack.rst @@ -3,151 +3,154 @@ Get started with OpenStack Welcome! -If you are here, this likely means that you decided to give `Canonical OpenStack`_ a try. You might have heard from various sources that OpenStack is a complex piece of software. And you know what? This is true. OpenStack is complex for some very good reasons. However, you should also be aware that with the use of a proper tooling its complexity can be fully tamed. +In this tutorial, you will deploy a `Canonical OpenStack`_ cloud and provision a VM in this cloud. -In this tutorial we will show you how to get started with Canonical OpenStack in a few simple steps. We will walk you through its installation and configuration processes and get your first VM running on top of it. You will only need one machine for this purpose and around 30 minutes to spare. +What you will build ++++++++++++++++++++ -Ready for the adventure? Let's explore OpenStack together! +As a result of completing the tutorial, you will have a functioning single-node Canonical OpenStack cloud. +This cloud will be sufficient to complete all further tutorials in this documentation. .. note :: - This tutorial is intended to serve for learning purposes only. If you've looking for detailed instructions on how to deploy a production-grade cloud, please refer to the :doc:`How-to Guides section` of this documentation instead. + This tutorial is intended for learning purposes. + It intentionally limits OpenStack deployment to a single machine. + APIs and cloud resources provisioned during the tutorial + are accessible only from that machine. + + To deploy a production-grade cloud, refer to detailed instructions in the :doc:`How-to Guides section `. Requirements ++++++++++++ -You will only need one dedicated physical machine with: +To complete the tutorial, you need a single dedicated machine with the following configuration: * 4+ core amd64 processor * minimum of 16 GiB of RAM * minimum of 100 GiB SSD storage on the ``rootfs`` partition -* fresh Ubuntu Desktop 24.04 LTS installed +* a fresh installation of Ubuntu Desktop 24.04 LTS * unlimited access to the Internet -* spare un-formatted disk for MicroCeph +* a spare unformatted disk for MicroCeph You can also use a virtual machine instead, but you can expect some performance degradation in this case. -.. warning :: - - All terminal commands used in this series of tutorials are run from the aforementioned machine. All web browser examples presented in this series of tutorials are run from the aforementioned machine. Neither OpenStack APIs nor any of the provisioned cloud resources, including VMs and floating IPs will be accessible from any other machine in your network than the aforementioned one. Everything runs on that machine. But it runs and it works! - Deploy Canonical OpenStack ++++++++++++++++++++++++++ -.. note :: - - **Duration:** 1 minute (exact time might vary depending on your Internet connection speed) - -Canonical OpenStack can be deployed for sample usage in four simple steps. Once you continue your journey with Canonical OpenStack and move forward with some more advanced scenarios you will find out that those steps are present in every single deployment procedure regardless of the cloud architecture and the bare metal provider being used. Thus, it is worth spending some time learning what exactly happens in each of those steps. Obviously, in more advanced scenarios, the exact procedure might vary slightly and some additional steps might be required. +Canonical OpenStack can be deployed in four steps. +This tutorial guides you through these steps and explains their purpose. -Install the snap ----------------- +Step 1: Install the OpenStack snap +---------------------------------- -We are going to start with installing the `OpenStack snap`_. The ``openstack`` snap includes the -``sunbeam`` command which we'll further use to bootstrap the cloud and to operate it -post-deployment. Sunbeam acts like a high-level interface to Canonical OpenStack, effectively -abstracting its complexity from operators. - -To install the ``openstack`` snap, execute the following terminal command: +Log in to the machine used in this tutorial and run the following command to install the `OpenStack snap`_: .. code-block :: text sudo snap install openstack -Prepare the machine -------------------- +The ``openstack`` snap includes ``sunbeam``, a deployment and operations tool that you will use to deploy a cloud and provision resources. -.. note :: +Step 2: Prepare the machine +--------------------------- - **Duration:** 1 minute +Run the following command to prepare the machine for Canonical OpenStack: -Before we'll be able to bootstrap the cloud, we have to prepare the machine for Canonical OpenStack usage. This process includes: +.. code-block :: text -* ensuring all required software dependencies are installed, including the ``openssh-server``, -* configuring passwordless access to the ``sudo`` command for all terminal commands for the currently logged in user (i.e. ``NOPASSWD:ALL``). + sunbeam prepare-node-script --bootstrap | bash -x && newgrp snap_daemon -In order to facilitate this process, Sunbeam can generate a script that you can further review -and execute step by step: +Once the command completes, the machine is ready to bootstrap a cloud. -.. code-block :: text - - sunbeam prepare-node-script --bootstrap +.. dropdown:: What happens during this step? -However, if you simply want to execute all those commands at once, you can also pipe them directly to Bash instead: + The script generated and executed in the command above performs two actions: -.. code-block :: text - - sunbeam prepare-node-script --bootstrap | bash -x && newgrp snap_daemon + 1. Installs all required software dependencies (including the ``openssh-server``). + 2. Configures passwordless access to the ``sudo`` command for the currently logged in user (i.e. ``NOPASSWD:ALL``). -Bootstrap the cloud -------------------- + You can generate a script file and review the performed actions: -.. note :: + .. code-block :: text - **Duration:** 20 minutes (exact time might vary depending on your Internet connection speed) + sunbeam prepare-node-script --bootstrap -Now, once the machine is ready for Canonical OpenStack usage, we can bootstrap the cloud on top of -it. Even though triggered by a single command, the overall process is relatively complex and takes -a while to complete. In principle, Sunbeam orchestrates the following actions in the background: -* Installs `Canonical Kubernetes `_ for the purpose of hosting - cloud control functions, -* Installs `Canonical Juju`_ and bootstraps a Juju controller on top of Canonical Kubernetes, -* Installs and configures cloud control functions on top of Canonical Kubernetes, -* Installs the `OpenStack Hypervisor snap`_ and plugs it into cloud control services, -* Installs the `MicroCeph snap`_ and plugs it into cloud control services. +Step 3: Bootstrap the cloud +--------------------------- -To bootstrap the cloud for sample usage, execute the following command: +Run the following command to bootstrap a Canonical OpenStack cloud on the machine: .. code-block :: text - - sunbeam cluster bootstrap --accept-defaults --role control,compute,storage -.. important:: - - Bootstrapping may fail if the ``rootfs`` partition does not have sufficient - available storage, or if there is no free, un-partitioned disk for MicroCeph. - If any issue is encountered, consult the :doc:`Troubleshooting guide `. + sunbeam cluster bootstrap --accept-defaults --role control,compute,storage -Once it completes, you should be able to see the following message on your screen: +Once this command completes, you will see the following message: .. code-block :: text - + Node has been bootstrapped with roles: storage, control, compute -.. note :: +.. dropdown:: What happens during this step? - Sunbeam uses a set of credentials for access to the Juju controller. The - authenticated session expires after 24 hours. You can re-authenticate by - running: + During the bootstrap process, Sunbeam orchestrates the following actions: - .. code-block :: text + 1. Installs `Canonical Kubernetes `_ for the purpose of hosting + cloud control functions. + 2. Installs `Canonical Juju`_ and bootstraps a Juju controller on top of Canonical Kubernetes. + 3. Installs and configures cloud control functions on top of Canonical Kubernetes. + 4. Installs the `OpenStack Hypervisor snap`_ and plugs it into cloud control services. + 5. Installs the `MicroCeph snap`_ and plugs it into cloud control services. - sunbeam utils juju-login + .. important:: -Configure the cloud -------------------- + Bootstrap process may fail if the ``rootfs`` partition does not have sufficient + available storage, or if there is no free, un-partitioned disk for MicroCeph. + If any issue is encountered, consult the :doc:`Troubleshooting guide `. -.. note :: + .. note :: - **Duration:** 2 minutes (exact time might vary depending on your Internet connection speed) + Sunbeam creates a set of credentials to access the Juju controller. + An authenticated session expires after 24 hours. + Run the following command to re-authenticate: -At this point your Canonical OpenStack installation is already up and running. However, to be able to demonstrate its capabilities, we have to prepare the cloud for sample use. This includes creating a ``demo`` user, populating the cloud with some common templates and creating a sandbox project with some basic configuration where we'll be able to provision resources. + .. code-block :: text -We will explore in :doc:`another tutorial` how this process usually looks like under the hood. However, for the time being we're simply going to let Sunbeam handle that. + sunbeam utils juju-login -To configure the cloud for sample usage, execute the following command: +Step 4: Configure the cloud +--------------------------- + +Run the following command to apply initial configuration that allows the cloud to provision resources: .. code-block :: text - + sunbeam configure --accept-defaults --openrc demo-openrc -Once it completes, you should be able to see the following message on your screen: +Once the command completes, you will see the following message: .. code-block :: text Writing openrc to demo-openrc ... done +.. dropdown:: What happens during this step? + + The cloud preparation command performs the following actions: + + 1. Creates a ``demo`` user. + 2. Populates the cloud with common templates. + 3. Creates a sandbox project with basic configuration. + + .. note:: + + You will further explore cloud configuration in the following tutorial: :doc:`On-board your users `. + +Conclusion +---------- + +You now have a single-node Canonical OpenStack cloud that is ready to provision resources. +The node, deployed on your dedicated machine or VM, serves the control, compute, and storage roles. + Launch a VM +++++++++++ @@ -155,12 +158,12 @@ Launch a VM **Duration:** 1 minute (first VM launch always takes longer) -The best way to verify whether Canonical OpenStack has been deployed successfully is to try to launch a VM on top of it. We will explore in :doc:`another tutorial` how this process usually looks like under the hood. However, for the time being we're simply going to let Sunbeam handle that. +You can now provision a virtual machine on your Canonical OpenStack cloud using Sunbeam. -In order to launch a test VM, execute the following command: +Execute the following command to provision a VM named "test": .. code-block :: text - + sunbeam launch ubuntu --name test Sample output: @@ -168,34 +171,38 @@ Sample output: .. code-block :: text Launching an OpenStack instance ... - Access instance with `ssh -i /home/ubuntu/snap/openstack/584/sunbeam ubuntu@10.20.20.94` + Access instance with `ssh -i /home/ubuntu/.config/openstack/sunbeam ubuntu@10.20.20.200` + +.. note:: + + You will further explore resource provisioning in the following tutorial: + :doc:`Get familiar with OpenStack `. .. TODO: Update once https://bugs.launchpad.net/snap-openstack/+bug/2045266 is solved -You should now be able to connect to your VM over SSH using the provided command: +Use the provided command to connect to the VM over SSH: .. code-block :: text ssh -i /home/ubuntu/.config/openstack/sunbeam ubuntu@10.20.20.200 -That's it. You're now connected to the VM. You can use regular shell commands to execute various tasks: +You can use regular shell commands to execute various tasks in the VM: .. code-block :: text $ uptime 10:54:29 up 1 min, 1 user, load average: 0.00, 0.00, 0.00 -To disconnect from the VM, type ``exit`` or press CTRL+D instead. +To disconnect from the VM, type ``exit`` or press CTRL+D. Next steps ++++++++++ Congratulations! +You have completed this tutorial. -You have reached the end of this tutorial. - -You can now: +Explore the next steps: -* Move to the next tutorial in this series - :doc:`"Get familiar with OpenStack"`, -* If you need to clean up the node and start over, you can check :doc:`how to remove the node `, -* Explore :doc:`How-to Guides` for instructions on setting up a production-grade environment. +* Move to the next tutorial in this series: :doc:`Get familiar with OpenStack `. +* If you need to clean up and start the tutorial over, read :doc:`Removing the primary node `. +* Learn how to set up a production-grade environment from :doc:`How-to Guides `.