.. _rucio_upgrade:

Upgrading Rucio
===============

Rucio's base images are stored on DockerHub. Since DockerHub has pull rate limits, it is best to pull new images into a
proxy cache. To do so (in Harbor), pull the image to the proxy-cache project, e.g. for ``release-1.29.6``

.. code-block:: bash

    docker pull harbor.srcdev.skao.int/rucio-dockerhub-cache/rucio/rucio-daemons:release-1.29.6
    docker pull harbor.srcdev.skao.int/rucio-dockerhub-cache/rucio/rucio-server:release-1.29.6

Database Upgrade
^^^^^^^^^^^^^^^^

For major version updates, the database schema may have changed. Database upgrades proceed via Alembic.

To upgrade, first create a new postgres client container and clone the release of the code that the server is being
upgraded to inside this container.

Next, check the ``etc/alembic.ini.template`` file's ``sqlalchemy.url`` fields and update to point to the Rucio
application database with the correct credentials and schema. Rename this file to ``alembic.ini``.

The Alembic revision should be in the database table ``alembic_version``. This can be checked by issuing
``alembic current`` from inside the postgres client container, e.g.

.. code-block:: bash

    alembic current
    INFO  [alembic.runtime.migration] Context impl PostgresqlImpl.
    INFO  [alembic.runtime.migration] Will assume transactional DDL.
    2190e703eb6e (head)

and can be verified directly against the database by, e.g.

.. code-block:: bash

    psql --host rucio-postgresql -U rucio -d rucio -p 5432
    rucio=> SELECT * FROM test.alembic_version;
    version_num
    --------------
    2190e703eb6e

If the two are consistent, the database can be upgraded via:

.. code-block:: bash

    alembic upgrade head

Otherwise you will need to add this table and field manually to match the current version.

Server/Daemons Upgrade (k8s/helm)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. note::
    The assumption here is that the deployment uses the base Rucio images. This is currently not the case for our
    1.29.* deployment.

First check the helm repository is up to date:

.. code-block:: bash

    helm repo add rucio https://rucio.github.io/helm-charts
    helm repo update

Update the values for ``image.repository`` and ``image.tag`` in the **server** yaml to point to the new images pushed to
the proxy-cache, e.g.

.. code-block:: yaml

    image:
      repository: harbor.srcdev.skao.int/rucio-dockerhub-cache/rucio/rucio-server
      tag: release-X.Y.Z

And install:

.. code-block:: bash

    helm upgrade --install server --namespace <namespace> rucio/rucio-server --version X.Y.Z -f /path/to/server/yaml

Likewise, do the same for the **daemons**:

.. code-block:: yaml

    image:
      repository: harbor.srcdev.skao.int/rucio-dockerhub-cache/rucio/rucio-daemons
      tag: release-1.29.6

.. code-block:: bash

    helm upgrade daemons --namespace <namespace> rucio/rucio-daemons --version X.Y.Z -f /path/to/daemons/yaml