17.5. OverlayFS

mkdir -p /tmp/ovllab && cd /tmp/ovllab

cat > overlay_manual.sh <<'SH'
#!/usr/bin/env bash
# Сборка overlay вручную и проверка перекрытия слоёв.
set -uo pipefail

BASE="${1:-$PWD/manual}"
rm -rf "$BASE"
mkdir -p "$BASE"/{lower1,lower2,upper,work,merged}

echo "нижний слой 1" > "$BASE/lower1/only1.txt"
echo "версия из слоя 1" > "$BASE/lower1/shadowed.txt"
echo "будет скрыт" > "$BASE/lower1/hidden.txt"
echo "нижний слой 2" > "$BASE/lower2/only2.txt"
echo "версия из слоя 2" > "$BASE/lower2/shadowed.txt"

if ! sudo -n true 2>/dev/null; then
    cat <<'MSG'
  НЕ ВЫПОЛНЯЛОСЬ: монтирование overlay требует root.

  Команда для справки:
    sudo mount -t overlay overlay \
      -o lowerdir=$BASE/lower2:$BASE/lower1,\
upperdir=$BASE/upper,workdir=$BASE/work \
      $BASE/merged

  Что было бы видно:
    merged/only1.txt      из lower1
    merged/only2.txt      из lower2
    merged/shadowed.txt   «версия из слоя 2» — lower2 указан первым
    merged/hidden.txt     из lower1

  Требования к монтированию:
    workdir на ТОЙ ЖЕ файловой системе, что upperdir
    workdir и merged должны быть пустыми
    порядок lowerdir: справа налево по старшинству
MSG
    exit 3
fi

sudo mount -t overlay overlay \
    -o "lowerdir=$BASE/lower2:$BASE/lower1,upperdir=$BASE/upper,workdir=$BASE/work" \
    "$BASE/merged" || { echo "  монтирование не удалось"; exit 1; }

printf '  merged: %s\n' "$(ls "$BASE/merged" | tr '\n' ' ')"
printf '  shadowed.txt: %s\n' "$(cat "$BASE/merged/shadowed.txt")"

echo "тронуто" >> "$BASE/merged/shadowed.txt"
printf '  после записи файл появился в upper: %s\n' \
    "$(ls "$BASE/upper" | tr '\n' ' ')"

sudo rm -f "$BASE/merged/hidden.txt"
printf '  после удаления в upper: %s\n' "$(ls -a "$BASE/upper" | tr '\n' ' ')"
printf '  тип записи hidden.txt в upper: %s\n' \
    "$(stat -c '%F' "$BASE/upper/hidden.txt" 2>/dev/null || echo 'не найдено')"

sudo umount "$BASE/merged" 2>/dev/null
exit 0
SH
chmod +x overlay_manual.sh

cat > Dockerfile <<'EOF'
# syntax=docker/dockerfile:1
FROM alpine:3.21
# Слой 1
RUN echo "версия из слоя 1" > /shadowed.txt \
 && echo "только в слое 1" > /only1.txt \
 && echo "СЕКРЕТНОЕ-СОДЕРЖИМОЕ-XYZ" > /to-delete.txt
# Слой 2: перекрывает shadowed.txt
RUN echo "версия из слоя 2" > /shadowed.txt \
 && echo "только в слое 2" > /only2.txt
# Слой 3: удаление — но файл остаётся в слое 1
RUN rm -f /to-delete.txt
EOF

cat > Dockerfile.big <<'EOF'
# syntax=docker/dockerfile:1
FROM alpine:3.21
RUN dd if=/dev/zero of=/big.bin bs=1M count=128 2>/dev/null
EOF

cat > measure_copyup.py <<'PY'
"""Измерение стоимости copy-up.

Запись в файл нижнего слоя копирует его ЦЕЛИКОМ в upperdir.
Создание нового файла copy-up не вызывает.
"""
from __future__ import annotations

import json
import os
import subprocess
import sys
import time


def run_in(image: str, script: str) -> str:
    result = subprocess.run(
        ["docker", "run", "--rm", image, "sh", "-c", script],
        capture_output=True, text=True)
    return result.stdout.strip()


def main(image: str) -> int:
    # Запись одного байта в файл из нижнего слоя
    append = run_in(image, """
        start=$(date +%s%N)
        echo "x" >> /big.bin
        end=$(date +%s%N)
        echo $(( (end - start) / 1000000 ))
    """)

    # Создание нового файла того же размера
    create = run_in(image, """
        start=$(date +%s%N)
        dd if=/dev/zero of=/new.bin bs=1M count=128 2>/dev/null
        end=$(date +%s%N)
        echo $(( (end - start) / 1000000 ))
    """)

    # Создание маленького нового файла
    small = run_in(image, """
        start=$(date +%s%N)
        echo "x" > /small.txt
        end=$(date +%s%N)
        echo $(( (end - start) / 1000000 ))
    """)

    # chmod на файле нижнего слоя — тоже copy-up
    chmod = run_in(image, """
        start=$(date +%s%N)
        chmod 600 /big.bin
        end=$(date +%s%N)
        echo $(( (end - start) / 1000000 ))
    """)

    def num(value: str) -> int:
        return int(value) if value.isdigit() else -1

    result = {
        "дописать_байт_в_большой": num(append),
        "создать_новый_128МиБ": num(create),
        "создать_маленький": num(small),
        "chmod_на_большом": num(chmod),
    }
    print(json.dumps(result, ensure_ascii=False))
    return 0


if __name__ == "__main__":
    sys.exit(main(sys.argv[1] if len(sys.argv) > 1 else "ovllab:big"))
PY

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

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

printf '\n═══ Требование 2: перекрытие слоёв средствами Docker ═══\n'
docker build -q -t ovllab:layers . > /dev/null 2>&1
docker run --rm ovllab:layers sh -c '
    printf "    shadowed.txt: %s\n" "$(cat /shadowed.txt)"
    printf "    only1.txt:    %s\n" "$(cat /only1.txt)"
    printf "    only2.txt:    %s\n" "$(cat /only2.txt)"
    printf "    to-delete.txt: %s\n" "$(test -e /to-delete.txt && echo есть || echo НЕТ)"
' 2>/dev/null
shadowed="$(docker run --rm ovllab:layers cat /shadowed.txt 2>/dev/null)"
deleted_gone="$(docker run --rm ovllab:layers sh -c \
    'test -e /to-delete.txt && echo есть || echo нет' 2>/dev/null)"
[ "$shadowed" = "версия из слоя 2" ] && [ "$deleted_gone" = "нет" ] \
    && ok "верхний слой перекрывает нижний; удалённого файла в container'е нет" \
    || bad "shadowed=$shadowed удалён=$deleted_gone"

printf '\n═══ Требование 3: удалённый файл остался в слоях ═══\n'
docker save ovllab:layers -o layers.tar 2>/dev/null
rm -rf unpacked && mkdir -p unpacked
tar -xf layers.tar -C unpacked 2>/dev/null
found_file=0
found_content=0
while read -r layer; do
    if tar -tf "$layer" 2>/dev/null | grep -q 'to-delete.txt'; then
        found_file=$((found_file + 1))
        content="$(tar -xOf "$layer" \
            "$(tar -tf "$layer" | grep 'to-delete.txt' | head -1)" 2>/dev/null)"
        case "$content" in
            *СЕКРЕТНОЕ*) found_content=$((found_content + 1))
                printf '    содержимое из слоя: %s\n' "$content" ;;
        esac
    fi
done < <(find unpacked -name '*.tar' 2>/dev/null)
printf '    вхождений файла в слоях: %s\n' "$found_file"
printf '    из них с читаемым содержимым: %s\n' "$found_content"
printf '\n    Файл удалён инструкцией RUN rm, в container е его нет,\n'
printf '    но в слое он остался. В верхнем слое — whiteout-запись.\n'
printf '    Это то же явление, что извлечение секрета ([урок 12.6]).\n'
rm -rf unpacked layers.tar
[ "$found_file" -ge 1 ] \
    && ok "удалённый файл найден в слоях образа" \
    || bad "вхождений: $found_file"

printf '\n═══ Требования 4-5: стоимость copy-up ═══\n'
docker build -q -f Dockerfile.big -t ovllab:big . > /dev/null 2>&1
python3 measure_copyup.py ovllab:big > copyup.json 2>/dev/null
python3 - <<'PY'
import json
from pathlib import Path

d = json.loads(Path("copyup.json").read_text())
rows = [
    ("дописать 1 байт в файл 128 МиБ", d["дописать_байт_в_большой"],
     "copy-up: копируется ВЕСЬ файл"),
    ("chmod на файле 128 МиБ", d["chmod_на_большом"],
     "copy-up: метаданные хранятся с файлом"),
    ("создать новый файл 128 МиБ", d["создать_новый_128МиБ"],
     "без copy-up: сразу в upperdir"),
    ("создать маленький новый файл", d["создать_маленький"],
     "без copy-up"),
]
print(f"    {'операция':<34} {'время':>9}  причина")
print("    " + "─" * 80)
for name, ms, why in rows:
    value = f"{ms} мс" if ms >= 0 else "—"
    print(f"    {name:<34} {value:>9}  {why}")

append = d["дописать_байт_в_большой"]
small = d["создать_маленький"]
if append > 0 and small >= 0:
    print()
    print(f"    Один байт в файл нижнего слоя стоит {append} мс,")
    print(f"    маленький новый файл — {small} мс.")
    print("    Разница — стоимость копирования 128 МиБ.")
PY

printf '\n    размер writable layer после copy-up:\n'
docker rm -f ovllab-cu > /dev/null 2>&1
docker run -d --name ovllab-cu ovllab:big sh -c 'echo x >> /big.bin; sleep 60' > /dev/null
sleep 3
docker ps -s --filter 'name=ovllab-cu' --format '      {{.Names}}: {{.Size}}' 2>/dev/null
printf '      docker diff:\n'
docker diff ovllab-cu 2>/dev/null | head -3 | sed 's/^/        /'
layer_size="$(docker ps -s --filter 'name=ovllab-cu' --format '{{.Size}}' 2>/dev/null \
    | cut -d' ' -f1)"
docker rm -f ovllab-cu > /dev/null 2>&1

append_ms="$(python3 -c "
import json
from pathlib import Path
print(json.loads(Path('copyup.json').read_text())['дописать_байт_в_большой'])")"
small_ms="$(python3 -c "
import json
from pathlib import Path
print(json.loads(Path('copyup.json').read_text())['создать_маленький'])")"
printf '\n    writable layer: %s (записан 1 байт)\n' "$layer_size"
[ "${append_ms:-0}" -gt "${small_ms:-0}" ] \
    && ok "copy-up измерен: запись байта дороже создания файла" \
    || bad "байт=$append_ms мс, маленький файл=$small_ms мс"

printf '\n═══ Требование 6: какое хранилище образов ═══\n'
driver="$(docker info --format '{{.Driver}}' 2>/dev/null)"
printf '    Driver: %s\n' "$driver"
docker info --format '{{range .DriverStatus}}    {{index . 0}}: {{index . 1}}
{{end}}' 2>/dev/null | head -3

graph_data="$(docker inspect ovllab:layers --format '{{json .GraphDriver.Data}}' 2>/dev/null)"
printf '    GraphDriver.Data: %s\n' \
    "$(echo "$graph_data" | cut -c1-50)"

is_containerd=0
echo "$graph_data" | grep -qE '^(null|\{\})$' && is_containerd=1
docker info 2>/dev/null | grep -qi 'snapshotter' && is_containerd=1

python3 - <<'PY'
ROWS = [
    ("Где слои", "/var/lib/docker/overlay2/", "/var/lib/docker/containerd/"),
    ("Кто управляет", "dockerd", "containerd snapshotter"),
    ("GraphDriver.Data", "пути к каталогам", "пусто или иное"),
    ("Механизм", "OverlayFS", "OverlayFS — ТОТ ЖЕ"),
    ("Поиск слоя", "docker inspect", "ctr --namespace moby snapshots"),
]
print()
print(f"    {'свойство':<20} {'классический overlay2':<28} containerd image store")
print("    " + "─" * 84)
for name, old, new in ROWS:
    print(f"    {name:<20} {old:<28} {new}")
print()
print("    Механизм объединения слоёв НЕ МЕНЯЕТСЯ — это тот же OverlayFS.")
print("    Меняется, кто им управляет и где хранятся данные.")
print("    Практическое следствие: привычные поля docker inspect могут")
print("    быть пустыми, и путь к слоям ищут через ctr.")
PY
printf '\n    определено: %s\n' \
    "$([ "$is_containerd" = "1" ] && echo "containerd image store" || echo "классический overlay2")"
ok "хранилище определено; названо, что оно меняет и что остаётся тем же"

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

docker rmi -f ovllab:layers ovllab:big > /dev/null 2>&1
cd /tmp && rm -rf /tmp/ovllab
exit "$fail"

═══ Требование 1: overlay вручную ═══
  НЕ ВЫПОЛНЯЛОСЬ: монтирование overlay требует root.

  Команда для справки:
    sudo mount -t overlay overlay \
      -o lowerdir=$BASE/lower2:$BASE/lower1,upperdir=$BASE/upper,workdir=$BASE/work \
      $BASE/merged
  ...
  ✓ НЕ ВЫПОЛНЯЛОСЬ: нет прав root — команды приведены, шаг не засчитан

═══ Требование 2: перекрытие слоёв средствами Docker ═══
    shadowed.txt: версия из слоя 2
    only1.txt:    только в слое 1
    only2.txt:    только в слое 2
    to-delete.txt: НЕТ
  ✓ верхний слой перекрывает нижний; удалённого файла в container'е нет

═══ Требование 3: удалённый файл остался в слоях ═══
    содержимое из слоя: СЕКРЕТНОЕ-СОДЕРЖИМОЕ-XYZ
    вхождений файла в слоях: 1
    из них с читаемым содержимым: 1

    Файл удалён инструкцией RUN rm, в container е его нет,
    но в слое он остался. В верхнем слое — whiteout-запись.
    Это то же явление, что извлечение секрета ([урок 12.6]).
  ✓ удалённый файл найден в слоях образа

═══ Требования 4-5: стоимость copy-up ═══
    операция                               время  причина
    ────────────────────────────────────────────────────────────────────────────────
    дописать 1 байт в файл 128 МиБ         184 мс  copy-up: копируется ВЕСЬ файл
    chmod на файле 128 МиБ                 178 мс  copy-up: метаданные хранятся с файлом
    создать новый файл 128 МиБ             142 мс  без copy-up: сразу в upperdir
    создать маленький новый файл             3 мс  без copy-up

    Один байт в файл нижнего слоя стоит 184 мс,
    маленький новый файл — 3 мс.
    Разница — стоимость копирования 128 МиБ.

    размер writable layer после copy-up:
      ovllab-cu: 134.2MB (virtual 141.8MB)
      docker diff:
        C /big.bin

    writable layer: 134.2MB (записан 1 байт)
  ✓ copy-up измерен: запись байта дороже создания файла

═══ Требование 6: какое хранилище образов ═══
    Driver: overlayfs
    driver-type: io.containerd.snapshotter.v1
    GraphDriver.Data: {}

    свойство             классический overlay2        containerd image store
    ────────────────────────────────────────────────────────────────────────────────────
    Где слои             /var/lib/docker/overlay2/    /var/lib/docker/containerd/
    Кто управляет        dockerd                      containerd snapshotter
    GraphDriver.Data     пути к каталогам             пусто или иное
    Механизм             OverlayFS                    OverlayFS — ТОТ ЖЕ
    Поиск слоя           docker inspect               ctr --namespace moby snapshots

    Механизм объединения слоёв НЕ МЕНЯЕТСЯ — это тот же OverlayFS.
    ...
    определено: containerd image store
  ✓ хранилище определено; названо, что оно меняет и что остаётся тем же

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