Cgroups v1/v2 migration procedure

Overview

This page describes a procedure for migrating a StorPool node between cgroups v1 and cgroups v2.

Prerequisites

Before migrating a machine, make sure that:

the node can be safely rebooted
maintenance is scheduled if the node is part of a production environment
the node’s kernel or the node’s desired kernel supports cgroups v2 - All 6.x and 5.15 kernels have cgroups v2 support
the node’s systemd version is 245+

Procedure

1. Put the node in maintenance

If needed, put the machine in maintenance before changing the cgroup configuration.

This prevents the other nodes in the cluster from entering maintenance while this one is being reconfigured and rebooted.

2. Stop and disable StorPool services

Stop StorPool services and disable them temporarily:

storpool_ctl stop
storpool_ctl disable

This step may be delayed until later, but it is usually safer to do it before changing the configuration because the machine is expected to be rebooted soon after the change.

3. Update `storpool.conf`

Edit storpool.conf and set the desired cgroup mode.

For migration to cgroups v2:

SP_USE_CGROUPS_V2=1

For migration back to cgroups v1, use the expected v1 configuration for the node, for example:

SP_USE_CGROUPS_V2=0

or simply remove SP_USE_CGROUPS_V2 as 0 is the default value

4. (optional - see note below) Regenerate the GRUB configuration

Note

If you are doing an upgrade, this step can usually be skipped. The install.sh script runs the required install-helper actions when installing the new StorPool package.

Run the StorPool install helper for the beacon service:

/usr/lib/storpool/install_helper -m beacon preinst
/usr/lib/storpool/install_helper -m beacon postinst

Run these commands from the directory of the installed StorPool package.

5. (when migrating to v1) Create StorPool cgroup configuration

If you are migrating to cgroups v1 before the machine boots, run:

storpool_cg conf

to generate the cgroups v1 configuration. The tool will detect that SP_USE_CGROUPS_V2=0 and will create a v1 configuration that will be applied at boot time by the cgconfig service.

6. Reboot the machine

Reboot the node.

7. Check the kernel command line and cgroup version

Verify that the kernel command line matches the target cgroup mode.

For cgroups v2, make sure that there are no legacy or cgroups v1-specific settings that would force the machine to boot with the old hierarchy.

cat /proc/cmdline

The command line should not contain options that explicitly force cgroups v1 or legacy cgroup behavior when booted with cgroups v2.

Check what cgroup hierarchies are mounted in

grep cgroup /proc/mounts

On cgroups v2 machines you should see a mount for cgroup2 and on cgroups v1 machines there should be multiple individual controller mounts for cgroup.

8. (when migrating to v2) Create StorPool cgroup configuration

If you are migrating to cgroups v2 after the machine boots, run:

storpool_cg conf

to generate the cgroups v2 configuration, which systemd should apply immediately.

9. Start StorPool services

Start StorPool services:

storpool_ctl start

10. Verify service health

Verify that every StorPool service expected on the machine is running and is running in the proper cgroup.

Useful checks include:

storpool_ctl status
storpool_cg check

11. Enable StorPool services

After the node is verified, enable StorPool services again:

storpool_ctl enable