[lxc-devel] [lxcfs/master] README: clarify SWAP

[stgraber on Github]

A non-text attachment was scrubbed...
Name: not available
Type: text/x-mailbox
Size: 355 bytes
Desc: not available
URL: <http://lists.linuxcontainers.org/pipermail/lxc-devel/attachments/20201104/9f5f3364/attachment.bin>
-------------- next part --------------
From 8630139a22a0cf580c4ffaf849db98ba51de5df2 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?St=C3=A9phane=20Graber?= <stgraber at ubuntu.com>
Date: Wed, 4 Nov 2020 23:06:00 -0500
Subject: [PATCH] README: clarify SWAP
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Signed-off-by: Stéphane Graber <stgraber at ubuntu.com>
---
 README.md | 36 ++++++++++++++++++++++++++++++++++++
 1 file changed, 36 insertions(+)

diff --git a/README.md b/README.md
index 5272a6c..11e93fd 100644
--- a/README.md
+++ b/README.md
@@ -104,3 +104,39 @@ docker run -it -m 256m --memory-swap 256m \
  In a system with swap enabled, the parameter "-u" can be used to set all values in "meminfo" that refer to the swap to 0.
 
  sudo lxcfs -u /var/lib/lxcfs
+
+## Swap handling
+Swap cgroup handling on Linux is very confusing and there just isn't a perfect way for LXCFS to handle it.
+
+The main issues are:
+ - SWAP accounting is opt-in and requires `swapaccount=1` be passed to the kernel.
+
+ - Both a RAM limit and a RAM+SWAP limit can be set. The delta however
+   isn't the available SWAP space as the kernel is still free to SWAP as
+   much of the RAM as it feels like. This makes it impossible to render
+   a SWAP device size as using the delta between RAM and RAM+SWAP for that
+   wouldn't account for the kernel swapping more pages, leading to swap
+   usage exceeding swap total.
+
+ - It's impossible to disable SWAP in a given container. The closest
+   that can be done is setting swappiness down to 0 which severly limits
+   the risk of swapping pages but doesn't eliminate it.
+
+As a result, LXCFS had to make some compromise which go as follow:
+ - When `swapaccount` isn't enabled, no SWAP space is reported at all.
+   This is simply because there is no way to know the SWAP consumption.
+   The container may very much be using some SWAP though, there's just
+   no way to know how much of it and showing a SWAP device would require
+   some kind of SWAP usage to be reported. Showing the host value would be
+   completely wrong, showing a 0 value would be equallty wrong.
+
+ - Because SWAP usage for a given container can exceed the delta between
+   RAM and RAM+SWAP, the SWAP size is always reported to be the smaller of
+   the RAM limit or the host SWAP device itself. This ensures that at no point SWAP
+   usage will be allowed to exceed the SWAP size.
+
+ - If the swappiness is set to 0 and there is no SWAP usage, no SWAP is reported.
+   However if there is SWAP usage, then a SWAP device of the size of the
+   usage (100% full) is reported. This provides adequate reporting of
+   the memory consumption while preventing applications from assuming more
+   SWAP is available.