Resolving cgroup v2 Memory Issues When Running UMH Lite in Docker on Raspberry Pi

Jeremy Theocharis -

Running containers within Docker on a Raspberry Pi can sometimes present unexpected challenges, especially when dealing with complex setups like Docker-in-Docker (DinD) or deploying Kubernetes lightweight distributions like K3s within Docker. One common issue that arises is related to cgroups, particularly the memory cgroup v2. This article addresses the problem of encountering the “failed to find memory cgroup (v2)” error when deploying UMH Lite in Docker on a Raspberry Pi and provides a step-by-step solution to fix it.

Understanding the Issue

When deploying UMH Lite within Docker on a Raspberry Pi, users may encounter a fatal error related to the memory cgroup v2:

time="2024-10-13T19:19:26Z" level=fatal msg="failed to find memory cgroup (v2)"

This error causes the UMH container to crash and restart in a loop, preventing successful deployment. The root cause of this issue lies in the Raspberry Pi’s default configuration, which does not enable the memory cgroup controller required by certain containers to manage memory resources effectively.

What Are cgroups?

Control groups (cgroups) are a Linux kernel feature that allows the limitation, prioritization, and accounting of resources (CPU, memory, disk I/O, etc.) for collections of processes. Docker relies on cgroups to enforce resource limits and constraints on containers.

There are two versions of cgroups:

  • cgroup v1: The original implementation with separate hierarchies for each resource type.
  • cgroup v2: A unified hierarchy that simplifies resource management and is increasingly adopted by modern systems.

The UMH Lite container requires access to the memory cgroup controller to function correctly. If the host system does not have this enabled, the container cannot manage memory resources, leading to the fatal error.

Why Does This Happen on Raspberry Pi?

By default, Raspberry Pi OS may not enable the memory cgroup controller. This is often the case with minimal or custom Linux distributions aimed at embedded devices to conserve resources. As a result, any Docker containers that rely on cgroup memory management will fail to start properly.

How to Fix the “Failed to Find Memory cgroup (v2)” Error

To resolve this issue, the memory cgroup controller needs to be enabled on the Raspberry Pi. Below are the steps to modify the Raspberry Pi’s boot configuration to activate cgroup memory management.

Prerequisites

  • A Raspberry Pi running a Linux distribution (e.g., Raspberry Pi OS, Debian, Ubuntu).
  • Root or sudo access to modify system configuration files.
  • Docker installed and running on the Raspberry Pi.

Step-by-Step Guide

1. Check Current cgroup Configuration

Before making changes, verify the current cgroup configuration.

mount | grep cgroup

If the output does not show entries for memory or indicates that cgroup v2 is not fully enabled, proceed with the following steps.

2. Edit the Boot Configuration File

Open the boot configuration file /boot/cmdline.txt with a text editor. This file contains kernel parameters that are applied at boot time.

sudo nano /boot/cmdline.txt

Note: All parameters in this file must be on a single line. Do not introduce line breaks.

3. Enable cgroup Memory Controller

Add the following parameters to the existing line in cmdline.txt:

cgroup_enable=memory cgroup_memory=1 swapaccount=1

Your cmdline.txt might look like this after the addition:

console=serial0,115200 console=tty1 root=PARTUUID=... rootfstype=ext4 fsck.repair=yes rootwait cgroup_enable=memory cgroup_memory=1 swapaccount=1

Parameters Explained:

  • cgroup_enable=memory: Enables the memory cgroup subsystem.
  • cgroup_memory=1: Ensures the memory controller is mounted.
  • swapaccount=1: Enables accounting of swap memory usage (optional but recommended for completeness).

4. Save and Exit

Press Ctrl + X, then Y, and Enter to save the changes and exit the editor.

5. Reboot the Raspberry Pi

For the changes to take effect, reboot the system:

sudo reboot

6. Verify the Changes

After rebooting, check that the memory cgroup is now active:

mount | grep cgroup

You should see output indicating that cgroup v2 is mounted and includes the memory controller:

cgroup2 on /sys/fs/cgroup type cgroup2 (rw,nosuid,nodev,noexec,relatime)

Alternatively, verify that Docker recognizes memory limit support:

docker info

Look for the absence of the following warnings:

WARNING: No memory limit support
WARNING: No swap limit support

If these warnings are gone, the memory cgroup controller is successfully enabled.

7. Restart Docker Containers

Now that the memory cgroup controller is active, restart your Docker containers, including UMH Lite. If you are using docker-compose, do this:

docker-compose up -d

Check the logs of the UMH container to ensure it’s running without errors!

Conclusion

By enabling the memory cgroup controller on the Raspberry Pi, the “failed to find memory cgroup (v2)” error is resolved, allowing UMH Lite to run successfully within Docker. This solution is applicable not only to UMH Lite but also to other containers and Kubernetes distributions like K3s that rely on cgroup memory management.

Keywords

  • Docker-in-Docker (DinD): Running Docker inside a Docker container.
  • K3s within Docker: Deploying the lightweight Kubernetes distribution K3s inside Docker.
  • cgroups (Control Groups): Linux kernel feature for limiting and monitoring resource usage.
  • cgroup v2: The second version of cgroups with a unified hierarchy.
  • Raspberry Pi: A small, affordable computer popular for embedded projects.
  • UMH Lite: A lightweight version of the United Manufacturing Hub for industrial IoT applications.

Memory cgroup v2 error: An error indicating the absence of the memory controller in cgroup v2.