Switch branches/tags
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
492 lines (375 sloc) 24.2 KB

Upgrade notes

This document contains information and notes about any changes that are required in the Ansible inventory or the IT infrastructure managed by DebOps to perform the upgrades between different stable releases.


Subordinate UID/GID ranges for root

  • The :ref:`debops.root_account` role will register a set of UID/GID ranges for the root account in the :file:`/etc/subuid` and :file:`/etc/subgid` databases. Depending on the OS distribution and release, these databases might contain existing UID/GID ranges which might interfere with the default set of 100000-165536 UID/GID range selected for the root account.

    In that case you should either disable this functionality, or recreate the host, at which point the UID/GID ranges for root will be reserved first, and any new accounts created by the system will use subsequent UIDs/GIDs. You can also update the UID/GID ranges manually, or select different UID/GID ranges for the root account in the role defaults.

Changes to Redis support in GitLab

  • The Redis support has been removed from the :ref:`debops.gitlab` playbook. Since GitLab still requires Redis to work properly, you need to enable :ref:`debops.redis_server` role explicitly for the GitLab host. GitLab installation instructions have been updated to reflect this fact.
  • To manage Redis on existing GitLab installations, you should enable the :ref:`debops.redis_server` role on them and run the Redis and GitLab playbooks afterwards. The existing Redis instance will be stopped and new Redis instance will be set up, with the same TCP port and password. Since the database will be empty, Gitaly service might stop working. After running the Redis Server and GitLab playbooks, restart the entire GitLab slice to re-populate Redis. You might expect existing GitLab sessions to be invalid and users to have to log in again.
  • The :ref:`debops.redis_server` role will configure APT preferences on Debian Stretch to install Redis from the stretch-backports repository. The playbook run on existing installations will not upgrade the packages automatically, but you might expect it on normal system upgrade.

Changes related to packet forwarding in firewall and sysctl

  • The :ref:`debops.ifupdown` role now uses :ref:`debops.sysctl` role directly as a dependency to generate forwarding configuration for each managed network interface that has it enabled. This might impact packet forwarding on existing systems; run the role with Ansible --diff --check options first to review the planned changes to the host.

  • The :ref:`debops.ferm` role will no longer enable packet forwarding on all network interfaces. Existing :file:`/etc/sysctl.d/30-ferm.conf` configuration file can be removed using the :ref:`debops.debops_legacy` role.

    The :ref:`debops.ferm` role will remove firewall rules that enabled forwarding between "external" and "internal" network interfaces, named forward_external_in, forward_external_out and forward_internal. They are redundant with the similar firewall rules generated by the :ref:`debops.ifupdown` role and their removal shouldn't impact connectivity, however you should check the modifications to the firewall just in case.

Inventory variable changes

  • The :ref:`debops.grub` role was redesigned, most of the grub_* default variables have been removed and the new configuration method has been implemented. The role variables have been namespaced, the role now uses grub__* variabe naming scheme. Check the role documentation for details about configuring GRUB via Ansible inventory.

  • Variables related to :command:`dhcp_probe` in the :ref:`debops.dhcpd` role have been replaced with the variables from the :ref:`debops.dhcp_probe` role. They are now namespaced and mostly with the same value types.

    The new :ref:`debops.dhcp_probe` role utilizes :command:`systemd` templated instances, and might not work correctly on older Debian/Ubuntu releases.

  • The variables related to packet forwarding in the :ref:`debops.ferm` role and related roles have been removed:

    • ferm__forward
    • ferm__forward_accept
    • ferm__external_interfaces
    • ferm__internal_interfaces
    • libvirtd__ferm__forward
    • lxc__ferm__forward

    The related Ansible local fact ansible_local.ferm.forward has also been removed.

    You can use the :ref:`debops.ifupdown` role to configure packet forwarding per network interface, in the firewall as well as via the kernel parameters.

  • Host and domain management has been removed from the :ref:`debops.bootstrap` role. This functionality is now done via the :ref:`debops.netbase` role, included in the bootstrap playbook. Some of the old variables have their new equivalents:

    Old variable name

    New variable name

    Changed value
















    Support for configuring IPv6 loopback address has been removed entirely. This was required when some of the DebOps roles relied on the ansible_fqdn value for task delegation between hosts. Since then, task delegation has been updated to use the inventory_hostname values and ensuring that the IPv6 loopback address resolves to a FQDN address of the host is no longer required.

  • The netbase__*_hosts variables in the :ref:`debops.netbase` role have been redesigned to use YAML lists instead of dictionaries. See :ref:`netbase__ref_hosts` for more details.

Changes related to LXC containers

  • The :ref:`debops.lxc` role will configure new LXC containers to attach to the lxcbr0 bridge by default. Existing LXC containers will not be modified. You can change the default bridge used on container creation using the :ref:`lxc__ref_configuration` variables.

  • The :ref:`debops.lxc` role has been updated to use the :command:`systemd` lxc@.service instances to manage the containers instead of using the :command:`lxc-*` commands directly. Existing LXC containers should not be affected, but it is recommended to switch them under the :command:`systemd` control. To do that, you should disable the container autostart in the :file:`/var/lib/lxc/<container>/config` configuration files: = 0

    This will make sure that the containers are not started by the lxc.service service on boot. Next, after stopping the running containers, enable and start the containers via the :command:`systemd` instance:

    systemctl enable lxc@<container>.service
    systemctl start lxc@<container>.service

    This should ensure that the containers are properly shut down and started with the host system.

v0.8.0 (2018-08-06)

UNIX account and group configuration

GitLab :command:`gitaly` installation

  • The :ref:`debops.gitlab` role will now build and install the :command:`gitaly` service using unprivileged git UNIX account instead of root. To perform the update correctly, you might need to remove directories


    Some files in these directories are owned by root and that can prevent the correct build of the Go binaries. You might also want to stop the gitlab-gitaly.service service and start it afterwards.

    The above steps shouldn't impact new GitLab installations.

UTF8 encoding in MariaDB

Inventory variable changes

v0.7.2 (2018-03-28)

No changes.

v0.7.1 (2018-03-28)

X.509 certificate changes

  • The :ref:`debops.pki` role now generates the default X.509 certificate for the domain PKI realm with a wildcard entry for the host's FQDN (for example, * This will be true by default on new hosts introduced to the cluster; if you want your old hosts to have the new X.509 certificates, you need to recreate the domain PKI realm by removing the :file:`/etc/pki/realms/domain/` directory on the remote hosts and re-running the :ref:`debops.pki` role against them.

    The change is done in the :envvar:`pki_default_realms` variable, if you redefined it in the Ansible inventory, you might want to update your version to include the new SubjectAltName entry.

  • The latest :program:`acme-tiny` Python script uses ACMEv2 API by default, and the :ref:`debops.pki` role is now compatible with the upstream changes. The ACME certificates should work out of the box in new PKI realms, after the :program:`acme-tiny` installation is updated.

    The existing PKI realms will stop correctly regenerating Let's Encrypt certificates, because their configuration is not updated automatically by the role. The presence of the :file:`acme/error.log` file will prevent the :program:`acme-tiny` script from requesting the certificates to not trip the Let's Encrypt rate limits.

    Easiest way to fix this is to remove the entire PKI realm (:file:`/etc/pki/realms/*/` directory) and re-run the :ref:`debops.pki` role against the host. The role will create a new PKI realm based on the previous configuration and ACME certificates should start working again. Services like :program:`nginx` that have hooks in the :file:`/etc/pki/hooks/` directory should be restarted automatically, you might need to manually restart other services as needed.

    Alternatively, you can update the Let's Encrypt API URL in the realm's :file:`config/realm.conf` file by replacing the line:




    This should tell the :program:`pki-realm` script to send requests for new certificates to the correct URL. You still need to run the :ref:`debops.pki` role against the host to install the updated :program:`pki-realm` script and update the :program:`acme-tiny` script.

Role changes

  • The :ref:`debops.debops` role now uses the :ref:`debops.ansible` role to install Ansible instead of doing it by itself. The relevant code has been removed, see the :ref:`debops.ansible` role documentation for new variables.

  • The debops-contrib.kernel_module role has been replaced by the :ref:`debops.kmod` role. All of the variable names have been changed, as well as their usage. See the documentation of the new role for more details.

  • The :ref:`debops.proc_hidepid` role was modified to use a static GID 70 for the procadmins group to allow synchronization between host and LXC containers on that host. The role will apply changes in the :file:`/etc/fstab` configuration file, but it will not change existing :file:`/proc` mount options. You need to remount the filesystem manually, with a command:

    ansible all -b -m command -a 'mount -o remount /proc'

    The :file:`/proc` filesystem mounted inside of LXC containers cannot be remounted this way, since it's most likely mounted by the host itself. You will need to check the LXC container configuration in the :file:`/var/lib/lxc/*/config` files and update the mount point options to use the new static GID. Restart the LXC container afterwards to remount the :file:`/proc` filesystem.

    You will also need to restart all services that rely on the procadmins group, for example :command:`snmpd`, to activate the new GID.

  • The :ref:`debops.sysctl` configuration has been redesigned. The role now uses YAML lists instead of YAML dictionaries as a base value of the sysctl__*_parameters default variables. The kernel parameter configuration format has also been changed to be easy to override via Ansible inventory. Role can now configure multiple files in :file:`/etc/sysctl.d/` directory. Refer to the role documentation for details.

Inventory variable changes

v0.7.0 (2018-02-11)

This is mostly a maintenance release, dedicated to reorganization of the DebOps :command:`git` repository and expanding documentation.

Role changes

  • The :ref:`debops.nodejs` role now installs NPM using a script in upstream :command:`git` repository. This might cause issues with already installed NPM package, because of that it will be automatically removed by the role if found. You should verify that the role behaves correctly on existing systems before applying it in production.
  • The :ref:`debops.gunicorn` role has rewritten configuration model based on :command:`systemd` instanced units. The existing configuration shouldn't interfere, however you might need to update the Ansible inventory configuration variables to the new syntax.

Inventory variable changes

v0.6.0 (2017-10-21)

This is an initial release based off of the previous DebOps roles, playbooks and tools located in separate :command:`git` repositories. There should be no changes needed between the old and the new infrastructure and inventory.