Quick Start

There are several ways that you can quickly get started with Atmosphere to explore it’s capabilities.

Deployment

This section covers all of the different ways you can deploy a quick start environment for Atmosphere.

Testing & Development Only

The quick start installation is not for production use, it’s perfect for testing and development.

All-in-one

The easiest way to get started with Atmosphere is to deploy the all-in-one installation. This will install an entire stack of Atmosphere, with Ceph and all the OpenStack services inside a single machine.

Non-reversible Changes

The all-in-one will fully take-over the machine by making system-level changes. It’s recommended to run it inside a virtual machine or a physical machine that can be dedicated to this purpose.

In order to get started, you’ll need a Ubuntu 22.04 system with the following minimum system requirements:

  • Cores: 8 threads (or vCPUs)

  • Memory: 32GB

If you’re looking to run Kubernetes clusters, you’ll need more memory for the workloads, it following minimum is recommended (but more memory is always better!):

  • Cores: 16 threads (or vCPUs)

  • Memory: 64GB

Nested Virtualization

If you’re running this inside a virtual machine, it is extremely important that the virtual machines supported nested virtualization, otherwise the performance of the VMs will be un-usable.

You’ll need to start by installing all of the necessary dependencies first, you also need to make sure you run all of these commands as ``root``:

$ sudo -i
$ apt-get update
$ apt-get install git tox

Once done, you can clone the repository locally and switch to the atmosphere directory:

$ git clone https://github.com/vexxhost/atmosphere.git
$ cd atmosphere

Once you’re in the directory, you can deploy the all-in-one environment by running the following command as root:

$ tox -e molecule-aio-ovn

If you want to use the ML2/Open vSwitch plugin, you can run the following command:

$ tox -e molecule-aio-openvswitch

Once the deployment is done, it will have a full deployment of all services inside the same host, so you can use the cloud from the same machine by referencing the usage section.

Multi-node

The multi-node intends to provide the most near-production experience possible, as it is architected purely towards production-only environments. In order to get a quick production-ready experience of Atmosphere, this will deploy a full stack of Atmosphere, with Ceph and all the OpenStack services across multiple machines in a lab environment.

OpenStack

You can deploy Atmosphere on top of an existing OpenStack environment where many virtual machines will be deployed in the same way that you’d have multiple physical machines in a datacenter for a production environment.

The quick start is powered by Molecule and it is used in continuous integration running against the VEXXHOST public cloud so that would be an easy target to use to try it out.

ou will need the following quotas set up in your cloud account:

  • 8 instances

  • 32 cores

  • 128GB RAM

  • 360GB storage

These resources will be used to create a total of 8 instances broken up as follows:

  • 3 Controller nodes

  • 3 Ceph OSD nodes

  • 2 Compute nodes

First of all, you’ll have to make sure you clone the repository locally to your system with git by running the following command:

$ git clone https://github.com/vexxhost/atmosphere

You will need tox installed on your operating system. You will need to make sure that you have the appropriate OpenStack environment variables set (such as OS_CLOUD or OS_AUTH_URL, etc.). You can also use the following environment variables to tweak the behaviour of the Heat stack that is created:

  • ATMOSPHERE_STACK_NAME: The name of the Heat stack to be created (defaults to atmosphere).

  • ATMOSPHERE_PUBLIC_NETWORK: The name of the public network to attach floating IPs from (defaults to public).

  • ATMOSPHERE_IMAGE: The name or UUID of the image to be used for deploying the instances (defaults to Ubuntu 20.04.3 LTS (x86_64) [2021-10-04]).

  • ATMOSPHERE_INSTANCE_TYPE``(Deprecated): The instance type used to deploy all of the different instances.(It doesn't have its own default value.) This has been deprecated from v1.4.0. You can configure the instance type per a machine role using ``ATMOSPHERE_CONTROLLER_INSTANCE_TYPE, ATMOSPHERE_COMPUTE_INSTANCE_TYPE, and ATMOSPHERE_STORAGE_INSTANCE_TYPE variables. For backwards compatibility, if variables specific to the machine roles are not set and ATMOSPHERE_INSTANCE_TYPE is set, ATMOSPHERE_INSTANCE_TYPE value is used.

  • ATMOSPHERE_CONTROLLER_INSTANCE_TYPE: The instance type used to deploy controller instances (defaults to v3-standard-16).

  • ATMOSPHERE_COMPUTE_INSTANCE_TYPE: The instance type used to deploy compute instances (defaults to v3-standard-4).

  • ATMOSPHERE_STORAGE_INSTANCE_TYPE: The instance type used to deploy storage instances (defaults to v3-standard-4).

  • ATMOSPHERE_NAMESERVERS: A comma-separated list of nameservers to be used for the instances (defaults to 1.1.1.1).

  • ATMOSPHERE_USERNAME: The username what is used to login into the instances ( defaults to ubuntu).

  • ATMOSPHERE_DNS_SUFFIX_NAME: The DNS domainname that is used for the API and Horizon. (defaults to nip.io).

  • ATMOSPHERE_ACME_SERVER: The ACME server, currenly this is from LetsEncrypt, with StepCA from SmallStep it is possible to run a internal ACME server. The CA of that ACME server should be present in the instance image.

  • ATMOSPHERE_ANSIBLE_VARS_PATH: The path for ansible group_vars and host_vars. This to build a multinode development cluster with own configs, that are not generated by molecule. This way you can test your configs before you bring them to production.

Once you’re ready to get started, you can run the following command to build the Heat stack:

$ tox -e molecule-venv -- converge

This will create a Heat stack with the name atmosphere and start deploying the cloud. Once it’s complete, you can login to any of the systems by using the login sub-command. For exampel, to login to the first controller node, you can run the following:

$ tox -e molecule-venv -- login -h ctl1

At this point, you can proceed to the usage section to see how to interact with the cloud.

Once you’re done with your environment and you need to tear it down, you can use the destroy sub-command:

$ tox -e molecule-venv -- destroy

For more information about the different commands used by Molecule, you can refer to the Molecule documentation.

Usage

Once the deployment is done, you can either use the CLI to interact with the OpenStack environment, or you can access the Horizon dashboard.

Command Line Interface (CLI)

When using the CLI, there are two different ways of authenticating to the OpenStack environment. You can either use local credentials or you can use Single-Sign On (SSO) with the OpenStack CLI.

Local Credentials

On any of the control plane node, you can find the credentials in the /root/openrc file. In an all-in-one environment, this will be the same machine where you deployed the environment.

For example, if you want to list the networks, you can run the following command (you only need to source the file once):

$ source /root/openrc
$ openstack network list

Single-Sign On (SSO)

If you want to use the Keycloak SSO with the OpenStack CLI, you will need to install the keystoneauth-websso plugin first.

To install it using pip, run the following command:

$ pip install keystoneauth-websso

You can create a clouds.yml file with the following content inside of the ~/.config/openstack directory:

clouds:
  atmosphere:
    auth_type: v3websso
    auth_url: https://identity.example.com
    identity_provider: atmosphere
    protocol: openid

You can then use OpenStack CLI commands by either setting the OS_CLOUD environment variable or using the --os-cloud option, for example to list the networks:

$ openstack --os-cloud atmosphere network list

Or, alternatively you can use the environment variable:

$ export OS_CLOUD=atmosphere
$ openstack network list

Dashboard

For the Horizon dashboard, you can find the URL to access it by running the following command:

$ kubectl -n openstack get ingress/dashboard -ojsonpath='{.spec.rules[0].host}'

You can either login to the dashboard using the local credentials or using single-sign on (SSO).

Local Credentials

You can find the credentials to login to the dashboard reading the /root/openrc file on any of the control plane nodes. You can use the following variables to match the credentials:

  • Username: OS_USERNAME

  • Password: OS_PASSWORD

  • Domain: OS_USER_DOMAIN_NAME

Single-Sign On (SSO)

You can select the “Atmosphere” option in the login page and you will be redirected to the Keycloak login page.