Mohammed Naser | a546734 | 2024-04-30 00:34:16 -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 | |
vexxhost-bot | da9062e | 2024-08-13 22:00:58 -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 | a546734 | 2024-04-30 00:34:16 -0400 | [diff] [blame] | 57 | |
| 58 | .. code-block:: bash |
| 59 | |
vexxhost-bot | da9062e | 2024-08-13 22:00:58 -0400 | [diff] [blame] | 60 | $ sudo -i |
| 61 | $ apt-get update |
| 62 | $ apt-get install git tox |
Mohammed Naser | a546734 | 2024-04-30 00:34:16 -0400 | [diff] [blame] | 63 | |
| 64 | Once done, you can clone the repository locally and switch to the |
| 65 | ``atmosphere`` directory: |
| 66 | |
| 67 | .. code-block:: bash |
| 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 |
vexxhost-bot | da9062e | 2024-08-13 22:00:58 -0400 | [diff] [blame] | 73 | by running the following command as ``root``: |
Mohammed Naser | a546734 | 2024-04-30 00:34:16 -0400 | [diff] [blame] | 74 | |
| 75 | .. code-block:: bash |
| 76 | |
vexxhost-bot | da9062e | 2024-08-13 22:00:58 -0400 | [diff] [blame] | 77 | $ tox -e molecule-aio-ovn |
Mohammed Naser | f315222 | 2024-07-19 00:40:24 -0400 | [diff] [blame] | 78 | |
| 79 | If you want to use the ML2/Open vSwitch plugin, you can run the following |
| 80 | command: |
| 81 | |
| 82 | .. code-block:: bash |
| 83 | |
vexxhost-bot | da9062e | 2024-08-13 22:00:58 -0400 | [diff] [blame] | 84 | $ tox -e molecule-aio-openvswitch |
Mohammed Naser | a546734 | 2024-04-30 00:34:16 -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 | f315222 | 2024-07-19 00:40:24 -0400 | [diff] [blame] | 131 | You will need ``tox`` installed on your operating system. You will need to make |
Mohammed Naser | a546734 | 2024-04-30 00:34:16 -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 | f315222 | 2024-07-19 00:40:24 -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 | a546734 | 2024-04-30 00:34:16 -0400 | [diff] [blame] | 172 | |
| 173 | .. code-block:: console |
| 174 | |
Mohammed Naser | f315222 | 2024-07-19 00:40:24 -0400 | [diff] [blame] | 175 | $ tox -e molecule-venv -- converge |
Mohammed Naser | a546734 | 2024-04-30 00:34:16 -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 | f315222 | 2024-07-19 00:40:24 -0400 | [diff] [blame] | 184 | $ tox -e molecule-venv -- login -h ctl1 |
Mohammed Naser | a546734 | 2024-04-30 00:34:16 -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 | f315222 | 2024-07-19 00:40:24 -0400 | [diff] [blame] | 194 | $ tox -e molecule-venv -- destroy |
Mohammed Naser | a546734 | 2024-04-30 00:34:16 -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 | |
| 206 | For the CLI, you can ``source /root/openrc`` and then use the ``openstack`` |
| 207 | CLI. For example, if you want to list the networks, you can run the |
| 208 | following command: |
| 209 | |
| 210 | .. code-block:: console |
| 211 | |
| 212 | $ source /root/openrc |
| 213 | $ openstack network list |
| 214 | |
| 215 | For the Horizon dashboard, you can find the URL to access it by running |
| 216 | the following command: |
| 217 | |
| 218 | .. code-block:: console |
| 219 | |
| 220 | $ kubectl -n openstack get ingress/dashboard -ojsonpath='{.spec.rules[0].host}' |
| 221 | |
| 222 | You can find the credentials to login to the dashboard reading the |
| 223 | `/root/openrc` file. You can use the following variables to match |
| 224 | the credentials: |
| 225 | |
| 226 | - Username: ``OS_USERNAME`` |
| 227 | - Password: ``OS_PASSWORD`` |
| 228 | - Domain: ``OS_USER_DOMAIN_NAME`` |