Commit a81d47b6 authored by Filippos Giannakos's avatar Filippos Giannakos
Browse files

docs: Update upgrade release-0.16 guide

parent 64b2c3c4
......@@ -9,8 +9,9 @@ for the Pithos Service. Archipelago will act as a storage abstraction layer
between Pithos and NFS, RADOS or any other storage backend driver that
Archipelago supports. In order to use the Pithos Service you must install
Archipelago on the node that runs the Pithos and Cyclades workers.
Additionally, you must install snf-image version 0.16 on the Ganeti nodes since
this is the first version that supports Archipelago.
Additionally, you must install Archipelago on the Ganeti nodes and upgrade
snf-image to version 0.16 since this is the first version that supports
Archipelago.
Until now the Pithos mapfile was a simple file containing a list of hashes that
make up the stored file in a Pithos container. After this consolidation the
......@@ -27,17 +28,19 @@ The upgrade to v0.16 consists of the following steps:
0. Upgrade / Install Archipelago and snf-image.
1. Bring down services and backup databases.
1. Install Archipelago on Pithos and Cyclades nodes
2. Upgrade packages, migrate the databases and configure settings.
2. Bring down services and backup databases.
3. Inspect and adjust resource limits.
3. Upgrade packages, migrate the databases and configure settings.
4. Tweak Archipelago and Gunicorn settings on Pithos node
4. Inspect and adjust resource limits.
5. Bring up all services.
5. Tweak Gunicorn settings on Pithos and Cyclades node
6. Add unique names to disks of all Ganeti instances
6. Bring up all services.
7. Add unique names to disks of all Ganeti instances
.. warning::
......@@ -49,21 +52,190 @@ The upgrade to v0.16 consists of the following steps:
0. Upgrade / Install Archipelago and snf-image
==============================================
Archipelago Installation
------------------------
If you have never used Archipelago before, make sure to install Archipelago 0.4
on all Ganeti VM-capable nodes.
on all Ganeti VM-capable nodes. Please refer to the
`Archipelago installation guide. <https://www.synnefo.org/docs/archipelago/latest/install-guide.html>`_
If you use an NFS-based setup, you must make sure the ``archip_dir``
configuration option of all ``blockerm`` and ``blockerb`` peers point to the
right Pithos NFS shares (e.g. ``/srv/pithos/data/maps``,
``/srv/pithos/data/blocks`` repectively). You must also create and share a new
directory named ``locks``. For now it can have the same permissions as the
``blocks`` or ``maps`` directories. We will adjust them on the following steps.
Then you must make sure that this directory is configured properly on all
Archipelago nodes using the newly introduced ``lock_dir`` configuration option
of ``blockerm``.
If you are using a RADOS-based setup, make sure that the relevant ``pool``
option of all ``blockerm`` and ``blockerb`` peers point to the Pithos RADOS
pools (e.g. ``maps``, ``blocks``).
.. warning:: If you are using NFS, make sure that you perform no Archipelago
action on Ganeti nodes until the directory permissions are
adjusted on the following steps.
Archipelago Upgrade
-------------------
If you're upgrading from Archipelago 0.3.5, make sure to upgrade Archipelago
on all Ganeti nodes before starting the upgrade process. For more
information, check the Archipelago
`upgrade notes <https://www.synnefo.org/docs/archipelago/latest/upgrades/archipelago_upgrade_v04.rst>`_.
`upgrade notes. <https://www.synnefo.org/docs/archipelago/latest/upgrades/upgrade-0.4.html>`_.
If you use an NFS-based setup, you must make sure the 'archip_dir' configuration
option of all ``blockerm`` and ``blockerb`` peers point to the right Pithos NFS
shares (e.g. ``/srv/pithos/data/maps``, ``/srv/pithos/data/blocks``
repectively). You can skip the ``locks`` dir for now and apply the relevant
Archipelago upgrade step when appropriate.
If you are using a RADOS-based setup, make sure that the relevant ``pool``
option of all ``blockerm`` and ``blockerb`` peers point to the Pithos RADOS
pools (e.g. ``maps``, ``blocks``).
Once you have Archipelago 0.4 up and running, you can install snf-image 0.16.
1. Install Archipelago on Pithos and Cyclades nodes
===================================================
At this point, you should also install Archipelago 0.4 on the Pithos and
Cyclades workers.
.. code-block:: console
# apt-get install archipelago
Archipelago does not start automatically after installation. Do not start it
manually until it is configured properly.
If you use an NFS-based setup, you must also follow the following steps to
adjust the directory permissions. Otherwise, skip them.
* **Adjust Pithos umask setting**
On the Pithos node, edit the file
``/etc/synnefo/20-snf-pithos-app-settings.conf`` and uncomment or add the
``PITHOS_BACKEND_BLOCK_UMASK`` setting and set it to value ``0o002``.
Then perform a gunicorn restart on both nodes:
.. code-block:: console
# service gunicorn restart
This way, all files and directories created by Pithos will be writable by the
group Pithos gunicorn worker runs as.
* **Change Pithos data group permissions**
Ensure that every file and folder under Pithos data directory has correct
permissions.
.. code-block:: console
# find /srv/pithos/data -type d -exec chmod g+rwxs '{}' \;
# find /srv/pithos/data -type f -exec chmod g+rw '{}' \;
* **Change Pithos data group owner**
Make ``archipelago`` group the group owner of every file under the Pithos data
directory.
.. code-block:: console
# chgrp archipelago /srv/pithos/data
# find /srv/pithos/data -type d -exec chgrp archipelago '{}' \;
# find /srv/pithos/data -type f -exec chgrp archipelago '{}' \;
From now on, every file or directory created under the Pithos data directory
will belong to the ``archipelago`` group because of the directory SET_GUID bit
that we set on the previous step. Plus the ``archipelago`` group will have
full read/write access because of the adjusted Pithos umask setting.
* **Change Archipelago user and group**
If you upgraded from Archipelago v0.3.5, now we can change the Archipelago
configuration on all Archipelago nodes, to run as
``archipelago``:``archipelago`` user and group, since it no longer requires
root priviledges.
For each Archipelago node:
* Stop Archipelago
.. code-block:: console
# archipelago stop
* Change the ``USER`` and ``GROUP`` configuration option to ``archipelago``
user. The configuration file is located under
``/etc/archipelago/archipelago.conf``
* Start Archipelago
1. Bring web services down, backup databases
.. code-block:: console
# archipelago start
After installing Archipelago on the Pithos and Cyclades node
we need to adjust the configuration file according to our deployment needs.
The configuration file is located on ``/etc/archipelago/archipelago.conf``.
For NFS installations we need to adjust carefully the following options:
* ``BLKTAP_ENABLED``: Must be set to false for the node, if the node does not
host VMs (a.k.a is not VM_CAPABLE)
* ``SEGMENT_SIZE``: Adjust shared memory segment size according to your
machine's RAM. The default value is 2GB which in some situations might exceed
your machine's physical RAM.
* ``archip_dir`` in ``blockerm`` section must be set to the directory that
the Pithos mapfiles resided until now (e.g., ``/srv/pithos/data/maps``).
* ``archip_dir`` in ``blockerb`` section must be set to the directory that
the Pithos data blocks resided until now (e.g., ``/srv/pithos/data/blocks``).
For a new Archipelago NFS installation you should also adjust now the
``lock_dir`` configuration option of ``blockerm`` to point to the ``locks``
directory (e.g. ``/srv/pithos/data/locks``).
For RADOS installations you should use the archipelago.conf.rados_example
configuration file shipped with the archipelago-rados package as your base
configuration. Then adjust carefully the following options
* ``BLKTAP_ENABLED``: Must be set to false for the node, if the node does not
host VMs (a.k.a is not VM_CAPABLE)
* ``SEGMENT_SIZE``: Adjust shared memory segment size according to your
machine's RAM. The default value is 2GB which in some situations might exceed
your machine's physical RAM.
* The ``pool`` setting in ``blockerm`` must be set to the RADOS pool where
Pithos mapfiles reside.
* The ``pool`` setting in ``blockerb`` must be set to the RADOS pool where
Pithos data blocks reside.
If this is a new Archipelago NFS installation, you should also adjust the
``lock_dir`` of ``blockerm`` to point on the right location.
After configuring Archipelago, you can safely start it on both nodes:
.. code-block:: console
# archipelago start
2. Upgrade snf-image 0.16
=========================
Once you have Archipelago 0.4 up and running, you can install snf-image 0.16 on
all Ganeti nodes. You should set the the ``PITHCAT_UMASK`` setting of snf-image
to ``007``. On the file ``/etc/default/snf-image`` uncomment or create the
relevant setting and set its value.
3. Bring web services down, backup databases
============================================
1. All web services must be brought down so that the database maintains a
......@@ -78,10 +250,10 @@ Cyclades workers.
3. Keep the database servers running during the migration process.
2. Upgrade Synnefo and configure settings
4. Upgrade Synnefo and configure settings
=========================================
2.1 Install the new versions of packages
4.1 Install the new versions of packages
----------------------------------------
::
......@@ -114,11 +286,7 @@ Cyclades workers.
snf-branding \
snf-pithos-backend \
snf-pithos-app \
snf-pithos-webclient \
libxseg0 \
python-xseg \
python-archipelago \
archipelago
snf-pithos-webclient
ganeti.node$ apt-get install \
python-objpool \
......@@ -145,7 +313,7 @@ Cyclades workers.
a workaround.
2.2 Sync and migrate the database
4.2 Sync and migrate the database
---------------------------------
.. note::
......@@ -164,7 +332,7 @@ Cyclades workers.
pithos-host$ pithos-migrate upgrade head
2.3 Configure snf-vncauthproxy
4.3 Configure snf-vncauthproxy
------------------------------
Synnefo 0.16 replaces the Java VNC client with an HTML5 Websocket client and
......@@ -190,7 +358,7 @@ snf-vncauthproxy `documentation <https://www.synnefo.org/docs/snf-vncauthproxy/l
and `upgrade notes <https://www.synnefo.org/docs/snf-vncauthproxy/latest/upgrade/upgrade-1.6.html>`_.
3. Inspect and adjust resource limits
5. Inspect and adjust resource limits
=====================================
Synnefo 0.16 brings significant changes at the project mechanism. Projects
......@@ -242,45 +410,34 @@ projects and will need to *reassign* some of their reserved resources to
another project in order to overcome this restriction.
4. Tweak Archipelago and Gunicorn settings on Pithos node
=========================================================
After installing Archipelago on the Pithos node we need to adjust the
configuration files according to our deployment needs.
For Archipelago the configuration file is located on
``/etc/archipelago/archipelago.conf``, where we need to adjust carefully at
least six configuration options:
* ``BLKTAP_ENABLED``: Must be set to false for the Pithos node, if the node does
not host VMs (a.k.a is not VM_CAPABLE)
* ``USER``: The user that Archipelago will run as must be the same as the
Gunicorn user.
* ``GROUP``: The group that Archipelago will run as must be the same as the
Gunicorn group.
* ``SEGMENT_SIZE``: Adjust shared memory segment size according to your machine's
RAM. The default value is 2GB which in some situations might exceed your
machine's physical RAM.
* ``archip_dir`` in ``blockerm`` section must be set to the directory that
Pithos mapfiles reside until now (e.g., ``/srv/pithos/data/maps``).
For RADOS installations the ``pool`` setting must be set to the RADOS pool
that Pithos mapfiles reside.
* ``archip_dir`` in ``blockerb`` section must be set to the directory that
Pithos data blocks reside until now (e.g., ``/srv/pithos/data/blocks``).
For RADOS installations the ``pool`` setting must be set to the RADOS pool
that Pithos data blocks reside.
6. Tweak Gunicorn settings on Pithos and Cyclades node
======================================================
For Gunicorn the configuration file is located on ``/etc/gunicorn.d/synnefo``
where we need to change:
* ``--worker-class=gevent`` to ``--worker-class=pithos.workers.gevent_archipelago.GeventArchipelagoWorker``
* Set ``group`` to the group that Archipelago runs as (defaults to
``archipelago``)
On the Pithos and Cyclades node you also have to set the following:
and set:
* ``--worker-class=gevent`` to ``--worker-class=pithos.workers.gevent_archipelago.GeventArchipelagoWorker``
* ``--config=/etc/synnefo/pithos.conf.py``
Then, on both nodes we must manually change group ownership of the following
directories to the group specified above:
* ``/var/log/gunicorn/`` directory
* ``/etc/synnefo/`` directory and all the files inside it.
.. code-block:: console
# chgrp archipelago /var/log/gunicorn/
# chgrp -R archipelago /etc/synnefo/
5. Bring all services up
7. Bring all services up
========================
After the upgrade is finished, we bring up all services:
......@@ -290,13 +447,12 @@ After the upgrade is finished, we bring up all services:
astakos.host # service gunicorn start
cyclades.host # service gunicorn start
pithos.host # service archipelago start
pithos.host # service gunicorn start
cyclades.host # service snf-dispatcher start
6. Add unique names to disks of all Ganeti instances
8. Add unique names to disks of all Ganeti instances
=====================================================
Synnefo 0.16 introduces the Volume service which can handle multiple disks
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment