blob: b52eb2216f40d0f4c2386cfa8ddde335643bcdfe [file] [log] [blame]
Mohammed Naser90128aa2024-04-29 13:21:58 -04001###########
2Quick Start
3###########
4
5There are several ways that you can quickly get started with Atmosphere to explore
6it's capabilities.
7
8**********
9Deployment
10**********
11
12This section covers all of the different ways you can deploy a quick start
13environment 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
21All-in-one
22==========
23
24The easiest way to get started with Atmosphere is to deploy the all-in-one
25installation. This will install an entire stack of Atmosphere, with Ceph
26and 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
35In order to get started, you'll need a **Ubuntu 22.04** system with the
36following minimum system requirements:
37
38- Cores: 8 threads (or vCPUs)
39- Memory: 32GB
40
41If you're looking to run Kubernetes clusters, you'll need more memory
42for the workloads, it following minimum is recommended (but more memory
43is 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 Naser29e9ad82024-08-12 17:53:26 -040055You'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 Naser90128aa2024-04-29 13:21:58 -040057
Giovanni Tirloni1a09d3f2024-08-22 18:14:21 -030058.. code-block:: console
Mohammed Naser90128aa2024-04-29 13:21:58 -040059
Mohammed Naser29e9ad82024-08-12 17:53:26 -040060 $ sudo -i
61 $ apt-get update
62 $ apt-get install git tox
Mohammed Naser90128aa2024-04-29 13:21:58 -040063
64Once done, you can clone the repository locally and switch to the
65``atmosphere`` directory:
66
Giovanni Tirloni1a09d3f2024-08-22 18:14:21 -030067.. code-block:: console
Mohammed Naser90128aa2024-04-29 13:21:58 -040068
69 $ git clone https://github.com/vexxhost/atmosphere.git
70 $ cd atmosphere
71
72Once you're in the directory, you can deploy the all-in-one environment
Mohammed Naser29e9ad82024-08-12 17:53:26 -040073by running the following command as ``root``:
Mohammed Naser90128aa2024-04-29 13:21:58 -040074
Giovanni Tirloni1a09d3f2024-08-22 18:14:21 -030075.. code-block:: console
Mohammed Naser90128aa2024-04-29 13:21:58 -040076
Mohammed Naser29e9ad82024-08-12 17:53:26 -040077 $ tox -e molecule-aio-ovn
Mohammed Naser6080c9b2024-07-18 10:43:09 -040078
79If you want to use the ML2/Open vSwitch plugin, you can run the following
80command:
81
Giovanni Tirloni1a09d3f2024-08-22 18:14:21 -030082.. code-block:: console
Mohammed Naser6080c9b2024-07-18 10:43:09 -040083
Mohammed Naser29e9ad82024-08-12 17:53:26 -040084 $ tox -e molecule-aio-openvswitch
Mohammed Naser90128aa2024-04-29 13:21:58 -040085
86Once the deployment is done, it will have a full deployment of all services
87inside the same host, so you can use the cloud from the same machine by
88referencing the usage section.
89
90Multi-node
91==========
92
93The multi-node intends to provide the most near-production experience possible,
94as it is architected purely towards production-only environments. In order to
95get a quick production-ready experience of Atmosphere, this will deploy a full
96stack of Atmosphere, with Ceph and all the OpenStack services across multiple
97machines in a lab environment.
98
99OpenStack
100---------
101
102You can deploy Atmosphere on top of an existing OpenStack environment where many
103virtual machines will be deployed in the same way that you'd have multiple
104physical machines in a datacenter for a production environment.
105
106The quick start is powered by Molecule and it is used in continuous integration
107running against the VEXXHOST public cloud so that would be an easy target to
108use to try it out.
109
110ou 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
117These resources will be used to create a total of 8 instances broken up as
118follows:
119
120* 3 Controller nodes
121* 3 Ceph OSD nodes
122* 2 Compute nodes
123
124First of all, you'll have to make sure you clone the repository locally to your
125system with `git` by running the following command:
126
127.. code-block:: console
128
129 $ git clone https://github.com/vexxhost/atmosphere
130
Mohammed Naser6080c9b2024-07-18 10:43:09 -0400131You will need ``tox`` installed on your operating system. You will need to make
Mohammed Naser90128aa2024-04-29 13:21:58 -0400132sure that you have the appropriate OpenStack environment variables set (such
133as ``OS_CLOUD`` or ``OS_AUTH_URL``, etc.). You can also use the following
134environment 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 Naser6080c9b2024-07-18 10:43:09 -0400170Once you're ready to get started, you can run the following command to build
171the Heat stack:
Mohammed Naser90128aa2024-04-29 13:21:58 -0400172
173.. code-block:: console
174
Mohammed Naser6080c9b2024-07-18 10:43:09 -0400175 $ tox -e molecule-venv -- converge
Mohammed Naser90128aa2024-04-29 13:21:58 -0400176
177This will create a Heat stack with the name `atmosphere` and start deploying
178the cloud. Once it's complete, you can login to any of the systems by using
179the `login` sub-command. For exampel, to login to the first controller node,
180you can run the following:
181
182.. code-block:: console
183
Mohammed Naser6080c9b2024-07-18 10:43:09 -0400184 $ tox -e molecule-venv -- login -h ctl1
Mohammed Naser90128aa2024-04-29 13:21:58 -0400185
186At this point, you can proceed to the usage section to see how to interact
187with the cloud.
188
189Once you're done with your environment and you need to tear it down, you can
190use the `destroy` sub-command:
191
192.. code-block:: console
193
Mohammed Naser6080c9b2024-07-18 10:43:09 -0400194 $ tox -e molecule-venv -- destroy
Mohammed Naser90128aa2024-04-29 13:21:58 -0400195
196For more information about the different commands used by Molecule, you can
197refer to the Molecule documentation.
198
199*****
200Usage
201*****
202
203Once the deployment is done, you can either use the CLI to interact with
204the OpenStack environment, or you can access the Horizon dashboard.
205
Giovanni Tirloni1a09d3f2024-08-22 18:14:21 -0300206Command Line Interface (CLI)
207============================
208
209When using the CLI, there are two different ways of authenticating
210to the OpenStack environment. You can either use local credentials
211or you can use Single-Sign On (SSO) with the OpenStack CLI.
212
213Local Credentials
214-----------------
215
216On 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
218same machine where you deployed the environment.
219
220For example, if you want to list the networks, you can run the following
221command (you only need to source the file once):
Mohammed Naser90128aa2024-04-29 13:21:58 -0400222
223.. code-block:: console
224
225 $ source /root/openrc
226 $ openstack network list
227
Giovanni Tirloni1a09d3f2024-08-22 18:14:21 -0300228Single-Sign On (SSO)
229--------------------
230
231If you want to use the Keycloak SSO with the OpenStack CLI, you will need
232to install the `keystoneauth-websso <https://github.com/vexxhost/keystoneauth-websso>`_ plugin first.
233
234To install it using ``pip``, run the following command:
235
236.. code-block:: console
237
238 $ pip install keystoneauth-websso
239
240You can create a ``clouds.yml`` file with the following content inside
241of 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
252You can then use OpenStack CLI commands by either setting the ``OS_CLOUD``
253environment variable or using the ``--os-cloud`` option, for example
254to list the networks:
255
256.. code-block:: console
257
258 $ openstack --os-cloud atmosphere network list
259
260Or, alternatively you can use the environment variable:
261
262.. code-block:: console
263
264 $ export OS_CLOUD=atmosphere
265 $ openstack network list
266
267Dashboard
268=========
269
Mohammed Naser90128aa2024-04-29 13:21:58 -0400270For the Horizon dashboard, you can find the URL to access it by running
271the following command:
272
273.. code-block:: console
274
275 $ kubectl -n openstack get ingress/dashboard -ojsonpath='{.spec.rules[0].host}'
276
Giovanni Tirloni1a09d3f2024-08-22 18:14:21 -0300277You can either login to the dashboard using the local credentials or
278using single-sign on (SSO).
279
280Local Credentials
281-----------------
282
Mohammed Naser90128aa2024-04-29 13:21:58 -0400283You can find the credentials to login to the dashboard reading the
Giovanni Tirloni1a09d3f2024-08-22 18:14:21 -0300284`/root/openrc` file on any of the control plane nodes. You can use
285the following variables to match the credentials:
Mohammed Naser90128aa2024-04-29 13:21:58 -0400286
287- Username: ``OS_USERNAME``
288- Password: ``OS_PASSWORD``
289- Domain: ``OS_USER_DOMAIN_NAME``
Giovanni Tirloni1a09d3f2024-08-22 18:14:21 -0300290
291Single-Sign On (SSO)
292--------------------
293
294You can select the "Atmosphere" option in the login page and you will
295be redirected to the Keycloak login page.