UPGRADE.rst

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 :ref:`ifupdown__ref_changelog` for more details about what has changed.

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

Make sure to read the :ref:`ifupdown__ref_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:

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, 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 debops.ferm_ role 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.