blob: b3c3fcf891e3c7d88cf42116f90eb936a4f60314 [file] [log] [blame]
guilhermesteinmuller1d34c052025-02-07 12:30:55 -03001#############
2Upgrade Guide
3#############
4
5This document shows the most common way of upgrading your Atmosphere deployment.
6
7.. admonition:: Avoid jumping Atmosphere major releases
8 :class: warning
9
10 It is important to avoid jumping major versions in Atmosphere, which is the
11 same advice in OpenStack.
12
13 For example, If you are running Atmosphere Zed release (version 1) and want
14 to move to Bobcat (version 3) you should perform 2 upgrades: version 1 to
15 version 2 and then version 3.
16
17 If you dont do this, you may face database inconsistencies and failures on
18 services like Nova or Neutron, or failed upgrades of components such as
19 RabbitMQ.
20
21**************************
22Preparing the environment
23**************************
24
25On the deployment box, or any other place that you have your Ansible inventory,
26you should update the ``requirements.yml`` file and point to the target
27Atmosphere release you want to upgrade to.
28
29.. code-block:: yaml
30
31 collections:
32 - name: vexxhost.atmosphere
33 version: X.Y.Z
34
35Once that is done, you should update your collections by running:
36
37.. code-block:: console
38
39 $ ansible-galaxy install -r requirements.yml --force
40
41It's important to review your inventory, specifically image overrides to make
42sure that the image overrides are still necessary, otherwise you may end up
43with a broken deployment since the images will not be the ones the Atmosphere
44collection expects.
45
46*******************
47Running the upgrade
48*******************
49
50You can either execute the entire upgrade by running your site-local playbook
51which imports ``vexxhost.atmosphere.site``, call the individual playbooks out
52of Atmosphere or run a specific tag if you want to upgrade service-by-service
53which gives you the most granular control.
54
55.. code-block:: console
56
57 $ ansible-playbook -i hosts.ini playbooks/site.yml
58
59You can also run the Atmosphere provided playbooks by pointing to a specific
60playbook of the Ansible collection, in this case, the Ceph playbook:
61
62.. code-block:: console
63
64 $ ansible-playbook -i hosts.ini vexxhost.atmosphere.ceph
65
66You also have the most granular control by running the tags of the playbooks,
67for example, if you want to upgrade the Keystone service, you can run the
68following command:
69
70.. code-block:: console
71
72 $ ansible-playbook -i hosts.ini vexxhost.atmosphere.openstack --tags keystone
73
74During the upgrade, you may find it useful to have a monitor on all of the pods
75in the cluster to ensure that they are becoming ready and not failing. You can
76do this by running the following command:
77
78.. code-block:: console
79
80 $ watch -n1 "kubectl get pods --all-namespaces -owide | egrep -v '(Completed|1/1|2/2|3/3|4/4|6/6|7/7)'"