Mohammed Naser | 90128aa | 2024-04-29 13:21:58 -0400 | [diff] [blame] | 1 | ########### |
| 2 | Quick Start |
| 3 | ########### |
| 4 | |
| 5 | There are several ways that you can quickly get started with Atmosphere to explore |
| 6 | it's capabilities. |
| 7 | |
| 8 | ********** |
| 9 | Deployment |
| 10 | ********** |
| 11 | |
| 12 | This section covers all of the different ways you can deploy a quick start |
| 13 | environment for Atmosphere. |
| 14 | |
| 15 | .. admonition:: Testing & Development Only |
| 16 | :class: info |
| 17 | |
| 18 | The quick start installation is not for production use, it's perfect |
| 19 | for testing and development. |
| 20 | |
| 21 | All-in-one |
| 22 | ========== |
| 23 | |
| 24 | The easiest way to get started with Atmosphere is to deploy the all-in-one |
| 25 | installation. This will install an entire stack of Atmosphere, with Ceph |
| 26 | and all the OpenStack services inside a single machine. |
| 27 | |
| 28 | .. admonition:: Non-reversible Changes |
| 29 | :class: warning |
| 30 | |
| 31 | The all-in-one will fully take-over the machine by making system-level |
| 32 | changes. It's recommended to run it inside a virtual machine or a |
| 33 | physical machine that can be dedicated to this purpose. |
| 34 | |
| 35 | In order to get started, you'll need a **Ubuntu 22.04** system with the |
| 36 | following minimum system requirements: |
| 37 | |
| 38 | - Cores: 8 threads (or vCPUs) |
| 39 | - Memory: 32GB |
| 40 | |
| 41 | If you're looking to run Kubernetes clusters, you'll need more memory |
| 42 | for the workloads, it following minimum is recommended (but more memory |
| 43 | is always better!): |
| 44 | |
| 45 | - Cores: 16 threads (or vCPUs) |
| 46 | - Memory: 64GB |
| 47 | |
| 48 | .. admonition:: Nested Virtualization |
| 49 | :class: warning |
| 50 | |
| 51 | If you're running this inside a virtual machine, it is **extremely** |
| 52 | important that the virtual machines supported nested virtualization, |
| 53 | otherwise the performance of the VMs will be un-usable. |
| 54 | |
Mohammed Naser | 29e9ad8 | 2024-08-12 17:53:26 -0400 | [diff] [blame] | 55 | You'll need to start by installing all of the necessary dependencies first, |
| 56 | **you also need to make sure you run all of these commands as ``root``**: |
Mohammed Naser | 90128aa | 2024-04-29 13:21:58 -0400 | [diff] [blame] | 57 | |
Giovanni Tirloni | 1a09d3f | 2024-08-22 18:14:21 -0300 | [diff] [blame] | 58 | .. code-block:: console |
Mohammed Naser | 90128aa | 2024-04-29 13:21:58 -0400 | [diff] [blame] | 59 | |
Mohammed Naser | 29e9ad8 | 2024-08-12 17:53:26 -0400 | [diff] [blame] | 60 | $ sudo -i |
| 61 | $ apt-get update |
| 62 | $ apt-get install git tox |
Mohammed Naser | 90128aa | 2024-04-29 13:21:58 -0400 | [diff] [blame] | 63 | |
| 64 | Once done, you can clone the repository locally and switch to the |
| 65 | ``atmosphere`` directory: |
| 66 | |
Giovanni Tirloni | 1a09d3f | 2024-08-22 18:14:21 -0300 | [diff] [blame] | 67 | .. code-block:: console |
Mohammed Naser | 90128aa | 2024-04-29 13:21:58 -0400 | [diff] [blame] | 68 | |
| 69 | $ git clone https://github.com/vexxhost/atmosphere.git |
| 70 | $ cd atmosphere |
| 71 | |
| 72 | Once you're in the directory, you can deploy the all-in-one environment |
Mohammed Naser | 29e9ad8 | 2024-08-12 17:53:26 -0400 | [diff] [blame] | 73 | by running the following command as ``root``: |
Mohammed Naser | 90128aa | 2024-04-29 13:21:58 -0400 | [diff] [blame] | 74 | |
Giovanni Tirloni | 1a09d3f | 2024-08-22 18:14:21 -0300 | [diff] [blame] | 75 | .. code-block:: console |
Mohammed Naser | 90128aa | 2024-04-29 13:21:58 -0400 | [diff] [blame] | 76 | |
Mohammed Naser | 29e9ad8 | 2024-08-12 17:53:26 -0400 | [diff] [blame] | 77 | $ tox -e molecule-aio-ovn |
Mohammed Naser | 6080c9b | 2024-07-18 10:43:09 -0400 | [diff] [blame] | 78 | |
| 79 | If you want to use the ML2/Open vSwitch plugin, you can run the following |
| 80 | command: |
| 81 | |
Giovanni Tirloni | 1a09d3f | 2024-08-22 18:14:21 -0300 | [diff] [blame] | 82 | .. code-block:: console |
Mohammed Naser | 6080c9b | 2024-07-18 10:43:09 -0400 | [diff] [blame] | 83 | |
Mohammed Naser | 29e9ad8 | 2024-08-12 17:53:26 -0400 | [diff] [blame] | 84 | $ tox -e molecule-aio-openvswitch |
Mohammed Naser | 90128aa | 2024-04-29 13:21:58 -0400 | [diff] [blame] | 85 | |
| 86 | Once the deployment is done, it will have a full deployment of all services |
| 87 | inside the same host, so you can use the cloud from the same machine by |
| 88 | referencing the usage section. |
| 89 | |
| 90 | Multi-node |
| 91 | ========== |
| 92 | |
| 93 | The multi-node intends to provide the most near-production experience possible, |
| 94 | as it is architected purely towards production-only environments. In order to |
| 95 | get a quick production-ready experience of Atmosphere, this will deploy a full |
| 96 | stack of Atmosphere, with Ceph and all the OpenStack services across multiple |
| 97 | machines in a lab environment. |
| 98 | |
| 99 | OpenStack |
| 100 | --------- |
| 101 | |
| 102 | You can deploy Atmosphere on top of an existing OpenStack environment where many |
| 103 | virtual machines will be deployed in the same way that you'd have multiple |
| 104 | physical machines in a datacenter for a production environment. |
| 105 | |
| 106 | The quick start is powered by Molecule and it is used in continuous integration |
| 107 | running against the VEXXHOST public cloud so that would be an easy target to |
| 108 | use to try it out. |
| 109 | |
| 110 | ou will need the following quotas set up in your cloud account: |
| 111 | |
| 112 | * 8 instances |
| 113 | * 32 cores |
| 114 | * 128GB RAM |
| 115 | * 360GB storage |
| 116 | |
| 117 | These resources will be used to create a total of 8 instances broken up as |
| 118 | follows: |
| 119 | |
| 120 | * 3 Controller nodes |
| 121 | * 3 Ceph OSD nodes |
| 122 | * 2 Compute nodes |
| 123 | |
| 124 | First of all, you'll have to make sure you clone the repository locally to your |
| 125 | system with `git` by running the following command: |
| 126 | |
| 127 | .. code-block:: console |
| 128 | |
| 129 | $ git clone https://github.com/vexxhost/atmosphere |
| 130 | |
Mohammed Naser | 6080c9b | 2024-07-18 10:43:09 -0400 | [diff] [blame] | 131 | You will need ``tox`` installed on your operating system. You will need to make |
Mohammed Naser | 90128aa | 2024-04-29 13:21:58 -0400 | [diff] [blame] | 132 | sure that you have the appropriate OpenStack environment variables set (such |
| 133 | as ``OS_CLOUD`` or ``OS_AUTH_URL``, etc.). You can also use the following |
| 134 | environment variables to tweak the behaviour of the Heat stack that is created: |
| 135 | |
| 136 | * ``ATMOSPHERE_STACK_NAME``: The name of the Heat stack to be created (defaults to |
| 137 | `atmosphere`). |
| 138 | * ``ATMOSPHERE_PUBLIC_NETWORK``: The name of the public network to attach floating |
| 139 | IPs from (defaults to ``public``). |
| 140 | * ``ATMOSPHERE_IMAGE``: The name or UUID of the image to be used for deploying the |
| 141 | instances (defaults to ``Ubuntu 20.04.3 LTS (x86_64) [2021-10-04]``). |
| 142 | * ``ATMOSPHERE_INSTANCE_TYPE``(Deprecated): The instance type used to deploy all of the |
| 143 | different instances.(It doesn't have its own default value.) |
| 144 | This has been deprecated from v1.4.0. You can configure the instance type per a |
| 145 | machine role using ``ATMOSPHERE_CONTROLLER_INSTANCE_TYPE``, |
| 146 | ``ATMOSPHERE_COMPUTE_INSTANCE_TYPE``, and ``ATMOSPHERE_STORAGE_INSTANCE_TYPE`` |
| 147 | variables. For backwards compatibility, if variables specific to the machine roles |
| 148 | are not set and ``ATMOSPHERE_INSTANCE_TYPE`` is set, ``ATMOSPHERE_INSTANCE_TYPE`` value |
| 149 | is used. |
| 150 | * ``ATMOSPHERE_CONTROLLER_INSTANCE_TYPE``: The instance type used to deploy controller |
| 151 | instances (defaults to ``v3-standard-16``). |
| 152 | * ``ATMOSPHERE_COMPUTE_INSTANCE_TYPE``: The instance type used to deploy compute |
| 153 | instances (defaults to ``v3-standard-4``). |
| 154 | * ``ATMOSPHERE_STORAGE_INSTANCE_TYPE``: The instance type used to deploy storage |
| 155 | instances (defaults to ``v3-standard-4``). |
| 156 | * ``ATMOSPHERE_NAMESERVERS``: A comma-separated list of nameservers to be used for |
| 157 | the instances (defaults to ``1.1.1.1``). |
| 158 | * ``ATMOSPHERE_USERNAME``: The username what is used to login into the instances ( |
| 159 | defaults to ``ubuntu``). |
| 160 | * ``ATMOSPHERE_DNS_SUFFIX_NAME``: The DNS domainname that is used for the API and |
| 161 | Horizon. (defaults to ``nip.io``). |
| 162 | * ``ATMOSPHERE_ACME_SERVER``: The ACME server, currenly this is from LetsEncrypt, |
| 163 | with StepCA from SmallStep it is possible to run a internal ACME server. |
| 164 | The CA of that ACME server should be present in the instance image. |
| 165 | * ``ATMOSPHERE_ANSIBLE_VARS_PATH``: The path for ansible group_vars and host_vars. |
| 166 | This to build a multinode development cluster with own configs, that are not |
| 167 | generated by molecule. This way you can test your configs before you bring |
| 168 | them to production. |
| 169 | |
Mohammed Naser | 6080c9b | 2024-07-18 10:43:09 -0400 | [diff] [blame] | 170 | Once you're ready to get started, you can run the following command to build |
| 171 | the Heat stack: |
Mohammed Naser | 90128aa | 2024-04-29 13:21:58 -0400 | [diff] [blame] | 172 | |
| 173 | .. code-block:: console |
| 174 | |
Mohammed Naser | 6080c9b | 2024-07-18 10:43:09 -0400 | [diff] [blame] | 175 | $ tox -e molecule-venv -- converge |
Mohammed Naser | 90128aa | 2024-04-29 13:21:58 -0400 | [diff] [blame] | 176 | |
| 177 | This will create a Heat stack with the name `atmosphere` and start deploying |
| 178 | the cloud. Once it's complete, you can login to any of the systems by using |
| 179 | the `login` sub-command. For exampel, to login to the first controller node, |
| 180 | you can run the following: |
| 181 | |
| 182 | .. code-block:: console |
| 183 | |
Mohammed Naser | 6080c9b | 2024-07-18 10:43:09 -0400 | [diff] [blame] | 184 | $ tox -e molecule-venv -- login -h ctl1 |
Mohammed Naser | 90128aa | 2024-04-29 13:21:58 -0400 | [diff] [blame] | 185 | |
| 186 | At this point, you can proceed to the usage section to see how to interact |
| 187 | with the cloud. |
| 188 | |
| 189 | Once you're done with your environment and you need to tear it down, you can |
| 190 | use the `destroy` sub-command: |
| 191 | |
| 192 | .. code-block:: console |
| 193 | |
Mohammed Naser | 6080c9b | 2024-07-18 10:43:09 -0400 | [diff] [blame] | 194 | $ tox -e molecule-venv -- destroy |
Mohammed Naser | 90128aa | 2024-04-29 13:21:58 -0400 | [diff] [blame] | 195 | |
| 196 | For more information about the different commands used by Molecule, you can |
| 197 | refer to the Molecule documentation. |
| 198 | |
| 199 | ***** |
| 200 | Usage |
| 201 | ***** |
| 202 | |
| 203 | Once the deployment is done, you can either use the CLI to interact with |
| 204 | the OpenStack environment, or you can access the Horizon dashboard. |
| 205 | |
Giovanni Tirloni | 1a09d3f | 2024-08-22 18:14:21 -0300 | [diff] [blame] | 206 | Command Line Interface (CLI) |
| 207 | ============================ |
| 208 | |
| 209 | When using the CLI, there are two different ways of authenticating |
| 210 | to the OpenStack environment. You can either use local credentials |
| 211 | or you can use Single-Sign On (SSO) with the OpenStack CLI. |
| 212 | |
| 213 | Local Credentials |
| 214 | ----------------- |
| 215 | |
| 216 | On any of the control plane node, you can find the credentials in the |
| 217 | ``/root/openrc`` file. In an all-in-one environment, this will be the |
| 218 | same machine where you deployed the environment. |
| 219 | |
| 220 | For example, if you want to list the networks, you can run the following |
| 221 | command (you only need to source the file once): |
Mohammed Naser | 90128aa | 2024-04-29 13:21:58 -0400 | [diff] [blame] | 222 | |
| 223 | .. code-block:: console |
| 224 | |
| 225 | $ source /root/openrc |
| 226 | $ openstack network list |
| 227 | |
Giovanni Tirloni | 1a09d3f | 2024-08-22 18:14:21 -0300 | [diff] [blame] | 228 | Single-Sign On (SSO) |
| 229 | -------------------- |
| 230 | |
| 231 | If you want to use the Keycloak SSO with the OpenStack CLI, you will need |
| 232 | to install the `keystoneauth-websso <https://github.com/vexxhost/keystoneauth-websso>`_ plugin first. |
| 233 | |
| 234 | To install it using ``pip``, run the following command: |
| 235 | |
| 236 | .. code-block:: console |
| 237 | |
| 238 | $ pip install keystoneauth-websso |
| 239 | |
| 240 | You can create a ``clouds.yml`` file with the following content inside |
| 241 | of the ``~/.config/openstack`` directory: |
| 242 | |
| 243 | .. code-block:: yaml |
| 244 | |
| 245 | clouds: |
| 246 | atmosphere: |
| 247 | auth_type: v3websso |
| 248 | auth_url: https://identity.example.com |
| 249 | identity_provider: atmosphere |
| 250 | protocol: openid |
| 251 | |
| 252 | You can then use OpenStack CLI commands by either setting the ``OS_CLOUD`` |
| 253 | environment variable or using the ``--os-cloud`` option, for example |
| 254 | to list the networks: |
| 255 | |
| 256 | .. code-block:: console |
| 257 | |
| 258 | $ openstack --os-cloud atmosphere network list |
| 259 | |
| 260 | Or, alternatively you can use the environment variable: |
| 261 | |
| 262 | .. code-block:: console |
| 263 | |
| 264 | $ export OS_CLOUD=atmosphere |
| 265 | $ openstack network list |
| 266 | |
| 267 | Dashboard |
| 268 | ========= |
| 269 | |
Mohammed Naser | 90128aa | 2024-04-29 13:21:58 -0400 | [diff] [blame] | 270 | For the Horizon dashboard, you can find the URL to access it by running |
| 271 | the following command: |
| 272 | |
| 273 | .. code-block:: console |
| 274 | |
| 275 | $ kubectl -n openstack get ingress/dashboard -ojsonpath='{.spec.rules[0].host}' |
| 276 | |
Giovanni Tirloni | 1a09d3f | 2024-08-22 18:14:21 -0300 | [diff] [blame] | 277 | You can either login to the dashboard using the local credentials or |
| 278 | using single-sign on (SSO). |
| 279 | |
| 280 | Local Credentials |
| 281 | ----------------- |
| 282 | |
Mohammed Naser | 90128aa | 2024-04-29 13:21:58 -0400 | [diff] [blame] | 283 | You can find the credentials to login to the dashboard reading the |
Giovanni Tirloni | 1a09d3f | 2024-08-22 18:14:21 -0300 | [diff] [blame] | 284 | `/root/openrc` file on any of the control plane nodes. You can use |
| 285 | the following variables to match the credentials: |
Mohammed Naser | 90128aa | 2024-04-29 13:21:58 -0400 | [diff] [blame] | 286 | |
| 287 | - Username: ``OS_USERNAME`` |
| 288 | - Password: ``OS_PASSWORD`` |
| 289 | - Domain: ``OS_USER_DOMAIN_NAME`` |
Giovanni Tirloni | 1a09d3f | 2024-08-22 18:14:21 -0300 | [diff] [blame] | 290 | |
| 291 | Single-Sign On (SSO) |
| 292 | -------------------- |
| 293 | |
| 294 | You can select the "Atmosphere" option in the login page and you will |
| 295 | be redirected to the Keycloak login page. |