guilhermesteinmuller | 1d34c05 | 2025-02-07 12:30:55 -0300 | [diff] [blame] | 1 | ############# |
| 2 | Upgrade Guide |
| 3 | ############# |
| 4 | |
| 5 | This 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 | ************************** |
| 22 | Preparing the environment |
| 23 | ************************** |
| 24 | |
| 25 | On the deployment box, or any other place that you have your Ansible inventory, |
| 26 | you should update the ``requirements.yml`` file and point to the target |
| 27 | Atmosphere release you want to upgrade to. |
| 28 | |
| 29 | .. code-block:: yaml |
| 30 | |
| 31 | collections: |
| 32 | - name: vexxhost.atmosphere |
| 33 | version: X.Y.Z |
| 34 | |
| 35 | Once 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 | |
| 41 | It's important to review your inventory, specifically image overrides to make |
| 42 | sure that the image overrides are still necessary, otherwise you may end up |
| 43 | with a broken deployment since the images will not be the ones the Atmosphere |
| 44 | collection expects. |
| 45 | |
| 46 | ******************* |
| 47 | Running the upgrade |
| 48 | ******************* |
| 49 | |
| 50 | You can either execute the entire upgrade by running your site-local playbook |
| 51 | which imports ``vexxhost.atmosphere.site``, call the individual playbooks out |
| 52 | of Atmosphere or run a specific tag if you want to upgrade service-by-service |
| 53 | which gives you the most granular control. |
| 54 | |
| 55 | .. code-block:: console |
| 56 | |
| 57 | $ ansible-playbook -i hosts.ini playbooks/site.yml |
| 58 | |
| 59 | You can also run the Atmosphere provided playbooks by pointing to a specific |
| 60 | playbook 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 | |
| 66 | You also have the most granular control by running the tags of the playbooks, |
| 67 | for example, if you want to upgrade the Keystone service, you can run the |
| 68 | following command: |
| 69 | |
| 70 | .. code-block:: console |
| 71 | |
| 72 | $ ansible-playbook -i hosts.ini vexxhost.atmosphere.openstack --tags keystone |
| 73 | |
| 74 | During the upgrade, you may find it useful to have a monitor on all of the pods |
| 75 | in the cluster to ensure that they are becoming ready and not failing. You can |
| 76 | do 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)'" |