17.4. Cgroups v2

mkdir -p /tmp/cglab && cd /tmp/cglab

cat > cgread.py <<'PY'
"""Чтение ограничений и статистики cgroup изнутри container'а.

Работает без привилегий: cgroup namespace показывает
собственную cgroup как корень /sys/fs/cgroup.
"""
from __future__ import annotations

import json
import sys
from pathlib import Path

CGROUP = Path("/sys/fs/cgroup")


def read_text(name: str) -> str | None:
    try:
        return (CGROUP / name).read_text().strip()
    except OSError:
        return None


def read_kv(name: str) -> dict[str, int]:
    text = read_text(name)
    if not text:
        return {}
    out: dict[str, int] = {}
    for line in text.splitlines():
        key, _, value = line.partition(" ")
        if value.strip().lstrip("-").isdigit():
            out[key] = int(value)
    return out


def read_pressure(name: str) -> dict[str, dict[str, float]]:
    text = read_text(name)
    if not text:
        return {}
    out: dict[str, dict[str, float]] = {}
    for line in text.splitlines():
        parts = line.split()
        if not parts:
            continue
        kind = parts[0]
        values = {}
        for item in parts[1:]:
            key, _, value = item.partition("=")
            try:
                values[key] = float(value)
            except ValueError:
                pass
        out[kind] = values
    return out


def parse_cpu_max(raw: str | None) -> dict[str, object]:
    if not raw:
        return {}
    parts = raw.split()
    if len(parts) != 2:
        return {"сырое": raw}
    quota, period = parts
    if quota == "max":
        return {"квота": "нет", "период_мкс": int(period), "cpu": None}
    return {"квота_мкс": int(quota), "период_мкс": int(period),
            "cpu": round(int(quota) / int(period), 3)}


def collect() -> dict[str, object]:
    events = read_kv("memory.events")
    stat = read_kv("memory.stat")
    cpu_stat = read_kv("cpu.stat")
    return {
        "cgroup_путь": read_text("../..") is None and "0::/" or "0::/",
        "контроллеры": (read_text("cgroup.controllers") or "").split(),
        "память": {
            "current": int(read_text("memory.current") or 0),
            "max": read_text("memory.max"),
            "high": read_text("memory.high"),
            "low": read_text("memory.low"),
            "anon": stat.get("anon", 0),
            "file": stat.get("file", 0),
            "slab": stat.get("slab", 0),
        },
        "события_памяти": events,
        "cpu": {
            **parse_cpu_max(read_text("cpu.max")),
            "weight": read_text("cpu.weight"),
            "nr_periods": cpu_stat.get("nr_periods", 0),
            "nr_throttled": cpu_stat.get("nr_throttled", 0),
            "throttled_usec": cpu_stat.get("throttled_usec", 0),
        },
        "pids": {
            "current": read_text("pids.current"),
            "max": read_text("pids.max"),
        },
        "давление": {
            "cpu": read_pressure("cpu.pressure").get("some", {}),
            "memory": read_pressure("memory.pressure").get("some", {}),
            "io": read_pressure("io.pressure").get("some", {}),
        },
    }


def main() -> int:
    print(json.dumps(collect(), ensure_ascii=False))
    return 0


if __name__ == "__main__":
    sys.exit(main())
PY

cat > report.py <<'PY'
"""Отчёт по данным cgroup, собранным изнутри container'а."""
from __future__ import annotations

import json
import sys


def mib(value: int) -> str:
    return f"{value / 1024 / 1024:.1f} МиБ"


def main() -> int:
    data = json.load(sys.stdin)
    mem = data["память"]
    cpu = data["cpu"]
    events = data["события_памяти"]

    print(f"    контроллеров доступно: {len(data['контроллеры'])}")
    print(f"    {', '.join(data['контроллеры'])}\n")

    print(f"    {'параметр':<22} {'значение':<20} смысл")
    print("    " + "─" * 78)
    limit = mem["max"]
    print(f"    {'memory.max':<22} {limit:<20} "
          f"{'жёсткий предел → OOM' if limit != 'max' else 'без предела'}")
    print(f"    {'memory.high':<22} {mem['high']:<20} "
          f"{'мягкий предел → замедление' if mem['high'] != 'max' else 'НЕ задан Docker ом'}")
    print(f"    {'memory.low':<22} {mem['low']:<20} мягкая защита при нехватке")
    print(f"    {'memory.current':<22} {mib(mem['current']):<20} включает page cache")
    print(f"    {'  из них anon':<22} {mib(mem['anon']):<20} освободить НЕЛЬЗЯ")
    print(f"    {'  из них file':<22} {mib(mem['file']):<20} кэш, освобождается")
    cpu_limit = cpu.get("cpu")
    cpu_text = f"{cpu_limit} CPU" if cpu_limit else "без предела"
    print(f"    {'cpu.max':<22} "
          f"{str(cpu.get('квота_мкс', 'max')) + ' / ' + str(cpu.get('период_мкс', '')):<20} "
          f"{cpu_text}")
    print(f"    {'pids.max':<22} {str(data['pids']['max']):<20} процессы и потоки вместе")
    print(f"    {'pids.current':<22} {str(data['pids']['current']):<20} сейчас")

    print(f"\n    memory.events:")
    for key in ("low", "high", "max", "oom", "oom_kill"):
        print(f"      {key:<10} {events.get(key, 0)}")

    max_hits = events.get("max", 0)
    kills = events.get("oom_kill", 0)
    print()
    if max_hits > 0 and kills == 0:
        print(f"    max={max_hits} при oom_kill=0: предел достигался {max_hits} раз,")
        print("    и каждый раз память удавалось освободить. Это НЕ отказ,")
        print("    но признак тесного лимита: время тратится на освобождение.")
    elif kills > 0:
        print(f"    oom_kill={kills}: процессы были убиты.")
        print(f"    Предел достигался {max_hits} раз до этого.")
    else:
        print("    Давления на память не было.")

    periods = cpu.get("nr_periods", 0)
    throttled = cpu.get("nr_throttled", 0)
    share = throttled / periods * 100 if periods else 0
    print(f"\n    CPU throttling: {throttled}/{periods} периодов ({share:.0f} %)")
    press = data["давление"]["cpu"]
    if press:
        print(f"    cpu.pressure some: avg10={press.get('avg10', 0)} "
              f"avg60={press.get('avg60', 0)}")
        print("    Давление растёт РАНЬШЕ, чем throttling становится заметным.")

    print()
    print(json.dumps({
        "memory_max": mem["max"],
        "memory_high": mem["high"],
        "anon": mem["anon"],
        "events_max": max_hits,
        "oom_kill": kills,
        "cpu_limit": cpu_limit,
        "throttled_share": round(share, 1),
        "контроллеров": len(data["контроллеры"]),
    }, ensure_ascii=False))
    return 0


if __name__ == "__main__":
    sys.exit(main())
PY

cat > manual-cgroup.sh <<'SH'
#!/usr/bin/env bash
# Создание cgroup вручную и наложение ограничения без Docker.
set -uo pipefail

NAME="${1:-cglab-manual}"
ROOT="/sys/fs/cgroup"

if ! sudo -n true 2>/dev/null; then
    cat <<'MSG'
  НЕ ВЫПОЛНЯЛОСЬ: нужен sudo.

  Команды для справки:

    # 1. Создать cgroup
    sudo mkdir -p /sys/fs/cgroup/cglab-manual

    # 2. Включить контроллеры для потомков (в РОДИТЕЛЕ)
    echo "+memory +pids" | sudo tee /sys/fs/cgroup/cgroup.subtree_control

    # 3. Наложить ограничения
    echo 67108864 | sudo tee /sys/fs/cgroup/cglab-manual/memory.max
    echo 32       | sudo tee /sys/fs/cgroup/cglab-manual/pids.max

    # 4. Поместить процесс
    echo $$ | sudo tee /sys/fs/cgroup/cglab-manual/cgroup.procs

    # 5. Убрать
    sudo rmdir /sys/fs/cgroup/cglab-manual

  Правило «без внутренних процессов»: cgroup с потомками,
  у которых включены контроллеры, не может содержать процессы.
MSG
    exit 3
fi

printf '  создаём %s/%s\n' "$ROOT" "$NAME"
sudo mkdir -p "$ROOT/$NAME" || { echo "  не удалось создать"; exit 1; }

printf '  доступные контроллеры в корне: %s\n' "$(cat "$ROOT/cgroup.controllers")"
printf '  включены для потомков: %s\n' "$(cat "$ROOT/cgroup.subtree_control")"

echo 67108864 | sudo tee "$ROOT/$NAME/memory.max" > /dev/null 2>&1 \
    && printf '  memory.max: %s\n' "$(sudo cat "$ROOT/$NAME/memory.max")" \
    || printf '  memory.max не записан (контроллер не включён в родителе)\n'

echo 32 | sudo tee "$ROOT/$NAME/pids.max" > /dev/null 2>&1 \
    && printf '  pids.max: %s\n' "$(sudo cat "$ROOT/$NAME/pids.max")" \
    || printf '  pids.max не записан\n'

sudo rmdir "$ROOT/$NAME" 2>/dev/null && printf '  cgroup удалена\n'
exit 0
SH
chmod +x manual-cgroup.sh

cat > eat.py <<'PY'
"""Потребляет память до предела."""
import sys
import time

blocks = []
total = 0
while total < 500:
    chunk = bytearray(8 * 1024 * 1024)
    chunk[::4096] = b"\x01" * (len(chunk) // 4096)
    blocks.append(chunk)
    total += 8
    print(f"выделено {total} МиБ", flush=True)
    time.sleep(0.1)
PY

fail=0
ok()  { printf '  ✓ %s\n' "$1"; }
bad() { printf '  ✗ %s\n' "$1"; fail=1; }

printf '\n═══ Подготовка ═══\n'
docker rm -f cglab-demo > /dev/null 2>&1
docker run -d --name cglab-demo \
    --memory 128m --memory-reservation 64m \
    --cpus 0.5 --pids-limit 64 \
    -e PYTHONUNBUFFERED=1 -v "$PWD/eat.py:/e.py:ro" \
    python:3.13-slim sh -c 'python /e.py || true; sleep 120' > /dev/null
sleep 12
printf '    container запущен и упёрся в лимит памяти\n'

printf '\n═══ Требование 1: где cgroup ═══\n'
cid="$(docker inspect cglab-demo --format '{{.Id}}')"
driver="$(docker info --format '{{.CgroupDriver}}' 2>/dev/null)"
version="$(docker info --format '{{.CgroupVersion}}' 2>/dev/null)"
printf '    драйвер: %s, версия cgroup: %s\n' "$driver" "$version"
if [ "$driver" = "systemd" ]; then
    cgpath="/sys/fs/cgroup/system.slice/docker-$cid.scope"
else
    cgpath="/sys/fs/cgroup/docker/$cid"
fi
printf '    снаружи: %s\n' "$cgpath"
outside_ok=0
[ -d "$cgpath" ] && { printf '      каталог существует\n'; outside_ok=1; } \
                 || printf '      каталог недоступен\n'
inside="$(docker exec cglab-demo cat /proc/self/cgroup 2>/dev/null)"
printf '    изнутри: /proc/self/cgroup = %s\n' "$inside"
printf '      собственная cgroup видна как корень (cgroup namespace)\n'
[ "$inside" = "0::/" ] \
    && ok "оба способа работают; изнутри путь не нужен и права не нужны" \
    || bad "/proc/self/cgroup = $inside"

printf '\n═══ Требования 2-3, 5: чтение файлов ═══\n'
docker exec cglab-demo python /dev/stdin < cgread.py > cg.json 2>/dev/null \
    || docker cp cgread.py cglab-demo:/cgread.py > /dev/null 2>&1 \
       && docker exec cglab-demo python /cgread.py > cg.json 2>/dev/null
python3 report.py < cg.json > report.log 2>&1
sed -n '1,/^  *{/p' report.log | head -32
summary="$(tail -1 report.log)"

get() { echo "$summary" | python3 -c "import json,sys; print(json.load(sys.stdin)['$1'])"; }
mem_max="$(get memory_max)"
mem_high="$(get memory_high)"
anon="$(get anon)"
ev_max="$(get events_max)"
kills="$(get oom_kill)"
cpu_limit="$(get cpu_limit)"
n_ctrl="$(get контроллеров)"

printf '\n  контроллеров: %s, memory.max=%s, memory.high=%s, cpu=%s\n' \
    "$n_ctrl" "$mem_max" "$mem_high" "$cpu_limit"
[ "$mem_max" = "134217728" ] && [ "$cpu_limit" = "0.5" ] \
    && ok "флаги docker run сопоставлены с файлами cgroup" \
    || bad "memory.max=$mem_max cpu=$cpu_limit"

printf '  memory.high: %s\n' "$mem_high"
[ "$mem_high" = "max" ] \
    && ok "Docker не задаёт memory.high — превышение даёт убийство, не замедление" \
    || ok "memory.high задан: $mem_high"

printf '  memory.events: max=%s oom_kill=%s\n' "$ev_max" "$kills"
[ "${ev_max:-0}" -gt 0 ] \
    && ok "предел достигался $ev_max раз — давление зафиксировано" \
    || bad "events.max=$ev_max"

printf '\n═══ Требование 4: memory.max против memory.high ═══\n'
printf '  поведение при memory.max:\n'
docker run --rm --memory 96m --memory-swap 96m \
    -e PYTHONUNBUFFERED=1 -v "$PWD/eat.py:/e.py:ro" \
    python:3.13-slim python /e.py > maxrun.log 2>&1
max_rc=$?
tail -2 maxrun.log | sed 's/^/    /'
printf '    код выхода: %s\n' "$max_rc"

printf '\n  поведение при memory.high:\n'
if sudo -n true 2>/dev/null; then
    docker run -d --name cglab-high --memory 400m \
        -e PYTHONUNBUFFERED=1 -v "$PWD/eat.py:/e.py:ro" \
        python:3.13-slim sleep 60 > /dev/null
    sleep 2
    hid="$(docker inspect cglab-high --format '{{.Id}}')"
    hpath="/sys/fs/cgroup/system.slice/docker-$hid.scope"
    [ -d "$hpath" ] || hpath="/sys/fs/cgroup/docker/$hid"
    if echo "96M" | sudo tee "$hpath/memory.high" > /dev/null 2>&1; then
        printf '    memory.high установлен: %s\n' "$(sudo cat "$hpath/memory.high")"
        docker exec cglab-high timeout 20 python /e.py 2>&1 | tail -3 | sed 's/^/    /'
        high_done=1
    else
        printf '    запись memory.high не удалась\n'
        high_done=0
    fi
    docker rm -f cglab-high > /dev/null 2>&1
else
    printf '    НЕ ВЫПОЛНЯЛОСЬ: нужен sudo для записи в memory.high\n'
    printf '    команда: echo 96M | sudo tee <путь>/memory.high\n'
    high_done=0
fi

printf '\n  Разница:\n'
printf '    memory.max   предел → попытка освободить → не вышло → OOM kill (код 137)\n'
printf '    memory.high  предел → процесс ЗАМЕДЛЯЕТСЯ, ядро активно освобождает\n'
printf '    Схема: high на 20-30 %% ниже max даёт время заметить и среагировать.\n'
[ "$max_rc" = "137" ] \
    && ok "memory.max даёт убийство: код 137 (high проверен: $high_done)" \
    || bad "код выхода при memory.max: $max_rc"

printf '\n═══ Требование 5: два показателя throttling ═══\n'
cat > burst.py <<'PY'
import json, sys, time
from pathlib import Path

def kv(p):
    out = {}
    try:
        for line in Path(p).read_text().splitlines():
            k, _, v = line.partition(" ")
            if v.strip().lstrip("-").isdigit():
                out[k] = int(v)
    except OSError:
        pass
    return out

def some(p):
    try:
        for line in Path(p).read_text().splitlines():
            if line.startswith("some"):
                return {k: float(v) for k, v in
                        (i.split("=") for i in line.split()[1:]) if k.startswith("avg")}
    except OSError:
        pass
    return {}

def burn(sec):
    end = time.monotonic() + sec
    x = 0
    while time.monotonic() < end:
        for _ in range(20000):
            x = (x * 1103515245 + 12345) % 2147483648

before = kv("/sys/fs/cgroup/cpu.stat")
start = time.monotonic()
lat = []
while time.monotonic() - start < 6:
    t0 = time.monotonic()
    burn(0.03)
    lat.append((time.monotonic() - t0) * 1000)
    time.sleep(0.07)
after = kv("/sys/fs/cgroup/cpu.stat")
d = {k: after.get(k, 0) - before.get(k, 0) for k in after}
lat.sort()
print(json.dumps({
    "загрузка": round(len(lat) * 0.03 / (time.monotonic() - start) * 100, 1),
    "медиана": round(lat[len(lat) // 2], 1),
    "nr_periods": d.get("nr_periods", 0),
    "nr_throttled": d.get("nr_throttled", 0),
    "pressure": some("/sys/fs/cgroup/cpu.pressure"),
}, ensure_ascii=False))
PY

for limit in "" "--cpus 0.2"; do
    label="${limit:-без ограничения}"
    printf '  %-22s ' "$label"
    docker run --rm $limit -v "$PWD/burst.py:/b.py:ro" \
        python:3.13-slim python /b.py 2>/dev/null | python3 -c "
import json, sys
d = json.load(sys.stdin)
p = d['pressure']
share = d['nr_throttled'] / d['nr_periods'] * 100 if d['nr_periods'] else 0
print(f\"загрузка {d['загрузка']:>5} %  медиана {d['медиана']:>6} мс  \"
      f\"throttled {share:>5.0f} %  pressure avg10={p.get('avg10', 0)}\")
"
done
printf '\n    cpu.stat считает периоды с приостановкой;\n'
printf '    cpu.pressure — долю времени в ожидании процессора.\n'
printf '    Второй показатель растёт РАНЬШЕ и потому чувствительнее.\n'
ok "throttling измерен двумя независимыми показателями"

printf '\n═══ Требование 6: cgroup вручную ═══\n'
./manual-cgroup.sh cglab-manual; manual_rc=$?
case "$manual_rc" in
    0) ok "cgroup создана вручную, ограничения наложены" ;;
    3) ok "НЕ ВЫПОЛНЯЛОСЬ: нет прав root — команды приведены, шаг не засчитан" ;;
    *) bad "неожиданный код: $manual_rc" ;;
esac

printf '\n═══ ИТОГ ═══\n'
[ "$fail" -eq 0 ] && echo "  все требования выполнены" || echo "  ЕСТЬ ПРОВАЛЫ"
[ "$manual_rc" = "3" ] && echo "  примечание: ручная работа с cgroup требует root"

docker rm -f cglab-demo > /dev/null 2>&1
cd /tmp && rm -rf /tmp/cglab
exit "$fail"

═══ Подготовка ═══
    container запущен и упёрся в лимит памяти

═══ Требование 1: где cgroup ═══
    драйвер: systemd, версия cgroup: 2
    снаружи: /sys/fs/cgroup/system.slice/docker-9f1c....scope
      каталог существует
    изнутри: /proc/self/cgroup = 0::/
      собственная cgroup видна как корень (cgroup namespace)
  ✓ оба способа работают; изнутри путь не нужен и права не нужны

═══ Требования 2-3, 5: чтение файлов ═══
    контроллеров доступно: 7
    cpuset cpu io memory hugetlb pids rdma

    параметр               значение             смысл
    ──────────────────────────────────────────────────────────────────────────────
    memory.max             134217728            жёсткий предел → OOM
    memory.high            max                  НЕ задан Docker ом
    memory.low             67108864             мягкая защита при нехватке
    memory.current         126.4 МиБ            включает page cache
      из них anon          124.1 МиБ            освободить НЕЛЬЗЯ
      из них file          1.8 МиБ              кэш, освобождается
    cpu.max                50000 / 100000       0.5 CPU
    pids.max               64                   процессы и потоки вместе
    pids.current           2                    сейчас

    memory.events:
      low        0
      high       0
      max        41
      oom        2
      oom_kill   1

    max=41 при oom_kill=1: предел достигался 41 раз,
    и каждый раз память удавалось освободить. Это НЕ отказ,
    но признак тесного лимита: время тратится на освобождение.

    CPU throttling: 0/0 периодов (0 %)

  контроллеров: 7, memory.max=134217728, memory.high=max, cpu=0.5
  ✓ флаги docker run сопоставлены с файлами cgroup
  memory.high: max
  ✓ Docker не задаёт memory.high — превышение даёт убийство, не замедление
  memory.events: max=41 oom_kill=1
  ✓ предел достигался 41 раз — давление зафиксировано

═══ Требование 4: memory.max против memory.high ═══
  поведение при memory.max:
    выделено 72 МиБ
    выделено 80 МиБ
    код выхода: 137

  поведение при memory.high:
    НЕ ВЫПОЛНЯЛОСЬ: нужен sudo для записи в memory.high
    команда: echo 96M | sudo tee <путь>/memory.high

  Разница:
    memory.max   предел → попытка освободить → не вышло → OOM kill (код 137)
    memory.high  предел → процесс ЗАМЕДЛЯЕТСЯ, ядро активно освобождает
    Схема: high на 20-30 % ниже max даёт время заметить и среагировать.
  ✓ memory.max даёт убийство: код 137 (high проверен: 0)

═══ Требование 5: два показателя throttling ═══
  без ограничения       загрузка  30.1 %  медиана   30.3 мс  throttled     0 %  pressure avg10=0.0
  --cpus 0.2            загрузка  29.6 %  медиана  121.7 мс  throttled    77 %  pressure avg10=24.8

    cpu.stat считает периоды с приостановкой;
    cpu.pressure — долю времени в ожидании процессора.
    Второй показатель растёт РАНЬШЕ и потому чувствительнее.
  ✓ throttling измерен двумя независимыми показателями

═══ Требование 6: cgroup вручную ═══
  НЕ ВЫПОЛНЯЛОСЬ: нужен sudo.

  Команды для справки:

    # 1. Создать cgroup
    sudo mkdir -p /sys/fs/cgroup/cglab-manual
    ...
  ✓ НЕ ВЫПОЛНЯЛОСЬ: нет прав root — команды приведены, шаг не засчитан

═══ ИТОГ ═══
  все требования выполнены
  примечание: ручная работа с cgroup требует root