Upgrade notes

Before upgrading a Rudder server, you should make a backup by following the backup procedure.

If you upgrade from 6.x and you changed the default cetificate, you will need to change the Apache2 configuration. Read the guidelines to change the default certificate in 7.x.

Plugins upgrade

If your server is connected to the Internet (directly or through a proxy), and you have configured your account in /opt/rudder/etc/rudder-pkg/rudder-pkg.conf, the upgrade process will take care of upgrading to plugins to a compatible version.

If it is not the case, you will need to download the new ones from downloads.rudder.io. and install them following the usual installation procedure.

You can check the current state of plugins with:

rudder package list --all

Upgrade from Rudder 6.1 or 6.2 to 7.0

Upgrade from Rudder 6.1 or 6.2 is supported.

It is advised to upgrade the root server before upgrading the relays and the nodes, but 7.0 nodes are also compatible with older server. Two cases are unsupported:

  • You can’t upgrade a relay to 7.0 before its root server. You need a 7.0 root server for 7.0 relays.

  • You can’t upgrade a root server and a node behind a relay to 7.0 without upgrading the relay. You need to upgrade the relay before the nodes.

HTTPS certificate

Changed default certificate

The certificate used for HTTPS access is now the same as the one used for policy updates. During the upgrade from 6.x, the HTTPS certificate is replaced by the certificate used by policy update. After the upgrade from 6.x, you will see a warning message indicating the server certificate has changed. This is expected, and you can accept to update the certificate if you used Rudder’s self-signed certificate.

Server side - Use a custom certificate

If you used a custom certificate, you will need to apply manual changes to Rudder’s configuration. As the self-signed certificate is used for internal communication, you will need to create a dedicated virtual host for the Web and API access. You need a way to distinguish access to these two virtual hosts, most often by IP, Port or ServerName (using specific DNS name).

The easiest way is probably to start over from the new default configuration and adapt it to your needs. You can access it as a new configuration file deployed by your package manager or directly in our repository.

You should only edit the virtual hosts in /etc/apache2/sites-available or /etc/httpd/conf.d which is treated as a configuration file by package managers and not automatically replaced. The most common approach is to comment the first virtual host and uncomment the last two virtual hosts, and distinguish either by hostname, IP or by port the virtual host for policy distribution and the virtual host for Web Interface/API

Please note the all /opt/rudder/etc/apache-* files are actually overridden at each upgrade and should not be modified.

Agent side - Server certificate verification

If you use a custom valid certificate and have enabled certificate verification in the settings, you may encounter missing reports and inventories after upgrade. This is caused by 6.X agent trying to validate your custom certificate while 7.0 relies on internal self-signed certificate for node-server communication.

In this specific case, it is necessary to upgrade agents to 7.0 before the server.

If you upgraded without following this step:

  • Policy generation and update will still work, so you can use Rudder to fix the problem. You have two options:

  • Disable certificate verification to get reports and inventories back

  • Upgrade your agents to 7.0, so they can verify the certificates correctly

Reporting

Syslog reporting

Syslog reporting is removed totally from 7.0, so if you had not switched to HTTPS reporting to the settings yet, the switch will be automatically made at upgrade.

We advise you to test HTTPS reporting before upgrading 7.0 to avoid unexpected consequences (as you won’t be able to fall back to syslog on 7.0).

Non-compliant only

If you use the non-compliant only reporting mode you will see missing reporting in the system techniques before the first agent run on you systems. This is due to changes in expected reports in these techniques, and the way the compliance is computed in this case.

Agent

Command output changes

rudder agent version

The version number now comes from Rudder itself and not from the package manager, so its format will slightly change.

rudder agent info

The output has been updated to be more readable, and you may need to adapt tooling if you relied on its output.

rudder agent inventory

/etc/profile is not sourced for inventories anymore, so the set of environment variables sent to the server may change. To properly sent information from the node in the inventory, we advise relying on inventory extension scripts.

Configuration policies

Removed techniques

We have removed deprecated techniques, you are encouraged to use the technique editor to replace them:

  • Routing management

  • NFS client

Recent changes in rules page

The recent changes view is more limited than in previous versions due to the rewrite, but will be improved in following patch releases. In particular no graphs are currently displayed, this will be improved in the upcoming releases.

Removed role-based system groups

We removed the role-based system groups as part of the removal of Rudder server roles. If you had a rule linked to one of these, it will be disabled after upgrade, and you will need to link it to a new group.

Server

Legacy local HTTP API removed

The old local server HTTP API (sometimes known as "v1") that existed before our public authenticated API and was deprecated for several years has finally been removed.

The list of removed endpoints is visible in the documentation.

If you still relied on this API should switch to the public API (which implements all features of the legacy one), and you can use the local system token (present in /var/lib/rudder/api-token) in local scripts.

Server roles and remote postgresql server

If you have an external postgresql database you need to add a little change in your server configuration following the documentation. In short:

  • The roles based on the presence of the rudder-reports package and some configuration in roles files has been removed

  • There is now a rudder.postgresql.local boolean option in the webapp configuration allowing to disable local postgresql configuration. Then you only need to configure the URL to your postgresql server in rudder.jdbc.url , the username in rudder.jdbc.username and the password in /opt/rudder/etc/rudder-passwords.conf and you’re all set.

Upgrade from Rudder 6.0 or older to 7.0

Direct upgrades from 6.0 versions and older are no longer supported on 7.0. If you are still running one of those, either on servers or nodes, please first upgrade to one of the supported versions, and then upgrade to 7.0.

Compatibility between Rudder components

In the tables below:

  • a + sign means any newer versions

  • a - is used to define a range

Table 1. Compatibility table
Server Relay Linux agent Windows agent

6.1

6.0+

5.0+

5.0-6.2

6.2

6.0+

5.0+

6.0+

7.0

6.0+

5.0+

6.2+

Table 2. Compatibility table (with deprecated versions)
Server Relay Linux agent Windows agent

5.0.1-5.0.16

5.0-6.0

5.0-6.0

5.0-6.0

5.0.17

5.0-6.1

5.0-6.1

5.0-6.1

6.1

6.0+

5.0+

5.0-6.2

6.2

6.0+

5.0+

6.0+

7.0

6.0+

5.0+

6.2+


← on SLES on Debian/Ubuntu →