.. _ifupdown__ref_upgrade_notes:

Upgrade notes
=============

The upgrade notes only describe necessary changes that you might need to make
to your setup in order to use a new role release. Refer to the
changelog for more details about what has changed.


From v0.2.x to v0.3.x
---------------------

Make sure to read the changelog for for detailed list of changes.

All variables are renamed
~~~~~~~~~~~~~~~~~~~~~~~~~

All of the role variables were renamed from ``ifupdown_*`` to ``ifupdown__*``,
and almost all of them have changed the data structures they use, therefore
automatic conversion from the earlier configuration cannot be performed
reliably for the most part. You should check the
:ref:`ifupdown__ref_interfaces` documentation to learn the new network
interface configuration format and modify your existing inventory to match the
new variables.

A few variable names can be updated using this script:

.. literalinclude:: scripts/upgrade-from-v0.2.X-to-v0.3.X
   :language: shell

The script is bundled with this role under
:file:`./docs/scripts/upgrade-from-v0.2.X-to-v0.3.X` and can be invoked from
there.

Changes on remote hosts
~~~~~~~~~~~~~~~~~~~~~~~

The configuration scheme on the remote hosts has also changed, the
configuration files in :file:`/etc/network/interfaces.config.d/` directory
might be duplicated as a result. You should clear them before running the role
on existing hosts (after implementing the new configuration in Ansible
inventory). To do that, you can issue command:

.. code-block:: console

   ansible all -b -m file -a 'path=/etc/network/interfaces.config.d state=absent'

This will remove the existing configuration staging directory and allow the
role to start from scratch. The actual configuration files in
:file:`/etc/network/interfaces.d/` should remain intact; they will be required
to stop the network interfaces properly and new configuration files will
replace them automatically.

The network configuration might require a reboot to be applied correctly in
certain cases with :command:`systemd` init, where the :command:`networking`
service is active in its own cgroup.

Environment and other service detection
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

All of the mechanisms that detected the static network interface configuration,
presence of NetworkManager, POSIX capabilities and different host types were
removed, because the role is no longer enabled by default on all hosts. Make
sure that you use the role only on hosts that are expected to be configured by
the :command:`ifupdown` package, the role will make no attempts to accommodate other
network configuration solutions at this time.

Playbook changes
~~~~~~~~~~~~~~~~

The role uses an internal ``debops.ifupdown/env`` role and :ref:`debops.ferm` to
configure the required firewall rules. Make sure to update your custom
playbooks; see the :ref:`ifupdown__ref_example_playbook` for details.

Compatibility with debops.subnetwork role
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The functionality of the ``debops.subnetwork`` role has been merged into
``debops.ifupdown`` role. You should move existing ``debops.subnetwork``
configuration to the new variables and remove the old role from inventory. You
might need to remove the :command:`ferm` configuration files generated by
``debops.subnetwork`` from remote hosts; ``debops.ifupdown`` maintains its own set of
firewall configuration files.
