17.1. Engine API и Unix socket

docker ps
   │
   ├─ CLI разбирает аргументы
   ├─ формирует HTTP-запрос
   │     GET /v1.51/containers/json
   ├─ отправляет его в /var/run/docker.sock
   │
   ▼
dockerd принимает, выполняет, отвечает JSON
   │
   ▼
CLI форматирует таблицу

DOCKER_API_VERSION=1.51 docker --log-level debug ps 2>&1 | grep -i 'GET\|POST'

GET /v1.51/containers/json     явная версия
GET /containers/json           последняя, поддерживаемая daemon

curl -s --unix-socket /var/run/docker.sock http://localhost/version

[0x01][0x00 0x00 0x00][0x00 0x00 0x00 0x0e]строка в stdout
 поток   зарезервировано      длина 14

{
  "Image": "alpine",
  "Cmd": ["sh"],
  "HostConfig": {
    "Binds": ["/:/host"],
    "Privileged": true
  }
}

mkdir -p /tmp/api && cd /tmp/api

SOCK=/var/run/docker.sock
api() { curl -s --unix-socket "$SOCK" "http://localhost$1"; }

echo "═══ версия API ═══"
api /version | python3 -c "
import json, sys
d = json.load(sys.stdin)
for key in ('Version', 'ApiVersion', 'MinAPIVersion', 'GitCommit', 'Os', 'Arch'):
    print(f'  {key:<16} {d.get(key, \"—\")}')
"

echo "═══ проверка доступности ═══"
api /_ping | sed 's/^/  _ping: /'
echo
curl -s -o /dev/null -w '  код ответа: %{http_code}\n' \
    --unix-socket "$SOCK" http://localhost/_ping

echo "═══ список container'ов ═══"
api /containers/json | python3 -c "
import json, sys
items = json.load(sys.stdin)
print(f'  работает container\'ов: {len(items)}')
for c in items[:5]:
    name = c['Names'][0].lstrip('/')
    print(f\"    {name:<24} {c['Image']:<28} {c['State']}\")
"

═══ версия API ═══
  Version          29.0.1
  ApiVersion       1.51
  MinAPIVersion    1.24
  GitCommit        a1b2c3d
  Os               linux
  Arch             amd64
═══ проверка доступности ═══
  _ping: OK
  код ответа: 200
═══ список container'ов ═══
  работает container'ов: 2
    web                      nginx:1.27                   running
    db                       postgres:17-alpine           running

cd /tmp/api
echo "═══ CLI с отладочным выводом ═══"
docker --log-level debug ps > /dev/null 2>debug.log
grep -oE '(GET|POST|DELETE) [^ "]+' debug.log | head -5 | sed 's/^/  /'

echo "═══ те же запросы через curl ═══"
for path in /_ping "/v1.51/containers/json"; do
    code="$(curl -s -o /dev/null -w '%{http_code}' \
        --unix-socket /var/run/docker.sock "http://localhost$path")"
    printf '  %-34s HTTP %s\n' "$path" "$code"
done

echo "═══ вывод ═══"
cat <<'TXT'
  CLI — это преобразователь: аргументы → HTTP-запрос,
  ответ JSON → таблица.

  Вся работа выполняется daemon. Отсюда:
    · любую команду можно выполнить без CLI
    · права определяются доступом к сокету, а не к CLI
    · CLI можно не устанавливать там, где нужен только запрос
TXT

═══ CLI с отладочным выводом ═══
  GET /_ping
  GET /v1.51/containers/json
═══ те же запросы через curl ═══
  /_ping                             HTTP 200
  /v1.51/containers/json             HTTP 200
═══ вывод ═══
  CLI — это преобразователь: аргументы → HTTP-запрос,
  ответ JSON → таблица.
  ...

cd /tmp/api
SOCK=/var/run/docker.sock

echo "═══ создание container'а ═══"
create_body='{
  "Image": "alpine:3.21",
  "Cmd": ["sh", "-c", "echo привет из API; sleep 30"],
  "HostConfig": {"AutoRemove": false}
}'
cid="$(curl -s --unix-socket "$SOCK" \
    -X POST -H 'Content-Type: application/json' \
    -d "$create_body" \
    'http://localhost/v1.51/containers/create?name=api-demo' \
    | python3 -c "import json,sys; print(json.load(sys.stdin)['Id'][:12])")"
printf '  создан: %s\n' "$cid"

echo "═══ состояние ДО запуска ═══"
curl -s --unix-socket "$SOCK" "http://localhost/v1.51/containers/$cid/json" \
    | python3 -c "
import json, sys
s = json.load(sys.stdin)['State']
print(f\"  Status={s['Status']} Running={s['Running']} Pid={s['Pid']}\")
"

echo "═══ запуск ═══"
curl -s -o /dev/null -w '  POST /start → HTTP %{http_code}\n' \
    --unix-socket "$SOCK" -X POST \
    "http://localhost/v1.51/containers/$cid/start"
sleep 2

echo "═══ состояние ПОСЛЕ запуска ═══"
curl -s --unix-socket "$SOCK" "http://localhost/v1.51/containers/$cid/json" \
    | python3 -c "
import json, sys
s = json.load(sys.stdin)['State']
print(f\"  Status={s['Status']} Running={s['Running']} Pid={s['Pid']}\")
"

echo "═══ почему это важно ═══"
cat <<'TXT'
  docker run — НЕ одна операция, а две:
    POST /containers/create   создаёт, не запуская
    POST /containers/ID/start запускает

  Отсюда возможность docker create: получить файловую систему
  container'а без запуска процесса ([урок 15.5]).

  И отсюда же — состояние "created", видимое в docker ps -a.
TXT

═══ создание container'а ═══
  создан: 7c2e9b1a4f83
═══ состояние ДО запуска ═══
  Status=created Running=False Pid=0
═══ запуск ═══
  POST /start → HTTP 204
═══ состояние ПОСЛЕ запуска ═══
  Status=running Running=True Pid=51204
═══ почему это важно ═══
  docker run — НЕ одна операция, а две:
    POST /containers/create   создаёт, не запуская
    POST /containers/ID/start запускает
  ...

cd /tmp/api
SOCK=/var/run/docker.sock

echo "═══ логи через API: сырые байты ═══"
curl -s --unix-socket "$SOCK" \
    "http://localhost/v1.51/containers/api-demo/logs?stdout=1&stderr=1" \
    | head -c 40 | xxd | head -3 | sed 's/^/  /'

echo "═══ разбор кадров ═══"
curl -s --unix-socket "$SOCK" \
    "http://localhost/v1.51/containers/api-demo/logs?stdout=1&stderr=1" \
    > raw.bin
python3 - <<'PY'
"""Разбор мультиплексированного потока Docker.

Каждому фрагменту предшествует заголовок из 8 байт:
  байт 0    — поток: 1 = stdout, 2 = stderr
  байты 1-3 — зарезервированы
  байты 4-7 — длина фрагмента, big-endian
"""
import struct
from pathlib import Path

STREAMS = {0: "stdin", 1: "stdout", 2: "stderr"}
data = Path("raw.bin").read_bytes()

offset = 0
frame = 0
while offset + 8 <= len(data):
    stream, length = struct.unpack(">BxxxI", data[offset:offset + 8])
    payload = data[offset + 8:offset + 8 + length]
    frame += 1
    text = payload.decode("utf-8", "replace").rstrip("\n")
    print(f"  кадр {frame}: поток={STREAMS.get(stream, stream)} "
          f"длина={length} текст={text!r}")
    offset += 8 + length

print(f"  всего кадров: {frame}, байт: {len(data)}")
PY

echo "═══ почему так ═══"
cat <<'TXT'
  Одно соединение переносит ДВА потока: stdout и stderr.
  Заголовок кадра говорит, к какому потоку относится фрагмент.

  Без разбора заголовков в выводе появляются посторонние байты —
  это и есть «мусор» при попытке прочитать логи простым curl.

  Обход: container, созданный с "Tty": true, потоки не разделяет,
  и заголовков нет. Но тогда stdout и stderr неразличимы.
TXT

═══ логи через API: сырые байты ═══
  00000000: 0100 0000 0000 0013 d0bf d180 d0b8 d0b2  ................
  00000010: d0b5 d182 20d0 b8d0 b720 4150 490a       .... ... API.
═══ разбор кадров ═══
  кадр 1: поток=stdout длина=19 текст='привет из API'
  всего кадров: 1, байт: 27
═══ почему так ═══
  Одно соединение переносит ДВА потока: stdout и stderr.
  Заголовок кадра говорит, к какому потоку относится фрагмент.
  ...

cd /tmp/api
SOCK=/var/run/docker.sock

echo "═══ события в реальном времени ═══"
(curl -s -N --unix-socket "$SOCK" \
    "http://localhost/v1.51/events?filters=%7B%22container%22%3A%5B%22api-demo%22%5D%7D" \
    > events.jsonl) &
watcher=$!
sleep 1

curl -s -o /dev/null -X POST --unix-socket "$SOCK" \
    "http://localhost/v1.51/containers/api-demo/stop?t=2"
sleep 3
kill "$watcher" 2>/dev/null
wait "$watcher" 2>/dev/null

python3 - <<'PY'
import json
from pathlib import Path

lines = [l for l in Path("events.jsonl").read_text().splitlines() if l.strip()]
print(f"  получено событий: {len(lines)}")
for line in lines:
    e = json.loads(line)
    name = e.get("Actor", {}).get("Attributes", {}).get("name", "—")
    print(f"    {e.get('Type')}/{e.get('Action'):<16} {name}")
PY

echo "═══ чем поток отличается от обычного ответа ═══"
cat <<'TXT'
  Соединение НЕ закрывается: daemon шлёт по объекту JSON на строку
  по мере наступления событий.

  Флаг -N у curl отключает буферизацию — без него вывод появится
  только при закрытии соединения.

  Ограничить окно: параметры since и until.
    /events?since=1785321600&until=1785325200

  Без until команда не завершится никогда — то же поведение,
  что у docker events ([урок 13.2]).
TXT

═══ события в реальном времени ═══
  получено событий: 2
    container/kill             api-demo
    container/die              api-demo
═══ чем поток отличается от обычного ответа ═══
  Соединение НЕ закрывается: daemon шлёт по объекту JSON на строку
  по мере наступления событий.
  ...

cd /tmp/api
cat > docker-api.py <<'PY'
"""Работа с Docker Engine API без установленного CLI.

Стандартной библиотеки достаточно: HTTP поверх Unix-сокета
реализуется подменой класса соединения.
"""
from __future__ import annotations

import http.client
import json
import socket
import sys
import urllib.parse

SOCKET_PATH = "/var/run/docker.sock"
API_VERSION = "v1.51"


class UnixHTTPConnection(http.client.HTTPConnection):
    """HTTP-соединение поверх Unix-сокета."""

    def __init__(self, path: str, timeout: float = 30.0) -> None:
        super().__init__("localhost", timeout=timeout)
        self.unix_path = path

    def connect(self) -> None:
        sock = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
        sock.settimeout(self.timeout)
        sock.connect(self.unix_path)
        self.sock = sock


def request(method: str, path: str, body: dict | None = None) -> tuple[int, object]:
    conn = UnixHTTPConnection(SOCKET_PATH)
    headers = {"Content-Type": "application/json"} if body is not None else {}
    payload = json.dumps(body) if body is not None else None
    conn.request(method, f"/{API_VERSION}{path}", body=payload, headers=headers)
    response = conn.getresponse()
    raw = response.read()
    conn.close()
    if not raw:
        return response.status, None
    try:
        return response.status, json.loads(raw)
    except json.JSONDecodeError:
        return response.status, raw.decode("utf-8", "replace")


def containers(all_: bool = False) -> list[dict]:
    query = urllib.parse.urlencode({"all": "true"} if all_ else {})
    status, data = request("GET", f"/containers/json?{query}")
    if status != 200:
        raise RuntimeError(f"HTTP {status}: {data}")
    return data


def inspect(name: str) -> dict:
    status, data = request("GET", f"/containers/{name}/json")
    if status != 200:
        raise RuntimeError(f"HTTP {status}: {data}")
    return data


def version() -> dict:
    _, data = request("GET", "/version")
    return data


def main() -> int:
    v = version()
    print(f"  daemon {v['Version']}, API {v['ApiVersion']} "
          f"(минимум {v['MinAPIVersion']})")

    items = containers(all_=True)
    print(f"\n  container'ов всего: {len(items)}")
    print(f"  {'имя':<22} {'образ':<28} {'состояние':<12} создан")
    print("  " + "─" * 78)
    for c in items[:8]:
        name = c["Names"][0].lstrip("/")
        print(f"  {name:<22} {c['Image'][:28]:<28} {c['State']:<12} "
              f"{c['Status']}")

    running = [c for c in items if c["State"] == "running"]
    print(f"\n  из них работает: {len(running)}")
    return 0


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

echo "═══ работа без CLI ═══"
python3 docker-api.py

echo "═══ проверка: CLI не задействован ═══"
docker run --rm -v "$PWD/docker-api.py:/api.py:ro" \
    -v /var/run/docker.sock:/var/run/docker.sock \
    python:3.13-slim sh -c '
    command -v docker > /dev/null 2>&1 && echo "  CLI установлен" \
        || echo "  CLI в образе ОТСУТСТВУЕТ"
    python /api.py 2>&1 | head -4
' 2>/dev/null | sed 's/^/  /'

═══ работа без CLI ═══
  daemon 29.0.1, API 1.51 (минимум 1.24)

  container'ов всего: 3
  имя                    образ                        состояние    создан
  ──────────────────────────────────────────────────────────────────────────────
  api-demo               alpine:3.21                  exited       Exited (137) 1 minute ago
  web                    nginx:1.27                   running      Up 2 hours
  db                     postgres:17-alpine           running      Up 2 hours

  из них работает: 2
═══ проверка: CLI не задействован ═══
    CLI в образе ОТСУТСТВУЕТ
      daemon 29.0.1, API 1.51 (минимум 1.24)
    
      container'ов всего: 3

cd /tmp/api
echo "═══ что принимает POST /containers/create ═══"
cat <<'TXT'
  {
    "Image": "alpine",
    "Cmd": ["sh", "-c", "..."],
    "HostConfig": {
      "Binds": ["/:/host"],        ← монтирование корня host
      "Privileged": true,          ← все привилегии
      "PidMode": "host",           ← PID namespace host
      "NetworkMode": "host"        ← сеть host
    }
  }

  Daemon работает от root и выполняет это без проверки,
  КТО отдал команду. Он проверяет только, что запрос
  пришёл через сокет.
TXT

echo "═══ демонстрация на учебной машине ═══"
python3 - <<'PY'
"""Показывает, что доступ к сокету даёт чтение файлов host.

Выполняется на СОБСТВЕННОЙ учебной машине. Цель — понять механизм
и осознать, почему сокет не монтируют в container'ы ([урок 12.2]).
"""
import http.client
import json
import socket


class UnixHTTPConnection(http.client.HTTPConnection):
    def __init__(self, path):
        super().__init__("localhost", timeout=30)
        self.unix_path = path

    def connect(self):
        s = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
        s.connect(self.unix_path)
        self.sock = s


def call(method, path, body=None):
    conn = UnixHTTPConnection("/var/run/docker.sock")
    headers = {"Content-Type": "application/json"} if body else {}
    conn.request(method, path, json.dumps(body) if body else None, headers)
    r = conn.getresponse()
    data = r.read()
    conn.close()
    return r.status, data


spec = {
    "Image": "alpine:3.21",
    "Cmd": ["head", "-1", "/host/etc/hostname"],
    "HostConfig": {"Binds": ["/:/host:ro"], "AutoRemove": False},
}
status, raw = call("POST", "/v1.51/containers/create?name=api-root-demo", spec)
if status != 201:
    print(f"  создание не удалось: HTTP {status}")
    raise SystemExit(0)

cid = json.loads(raw)["Id"]
call("POST", f"/v1.51/containers/{cid}/start")
call("POST", f"/v1.51/containers/{cid}/wait")
_, logs = call("GET", f"/v1.51/containers/{cid}/logs?stdout=1")

# Разбор мультиплексированного кадра
text = logs[8:].decode("utf-8", "replace").strip() if len(logs) > 8 else ""
print(f"  прочитано /etc/hostname хоста: {text!r}")
print("  через API, без sudo, только доступом к сокету")

call("DELETE", f"/v1.51/containers/{cid}?force=true")
PY

echo "═══ вывод ═══"
cat <<'TXT'
  Ограничения container'а — cap-drop, seccomp, read-only —
  применяются к СОЗДАВАЕМОМУ container'у, а не к тому,
  кто отдаёт команду.

  Поэтому никакая настройка не защищает от доступа к сокету:
  клиент просто попросит создать container без ограничений.

  Отсюда правило из урока 12.2: сокет не монтируют в container'ы,
  а членство в группе docker выдают как права root.
TXT

echo "═══ уборка ═══"
curl -s -o /dev/null -X DELETE --unix-socket /var/run/docker.sock \
    "http://localhost/v1.51/containers/api-demo?force=true"
echo "  container'ы удалены"
cd /tmp && rm -rf /tmp/api

═══ что принимает POST /containers/create ═══
  {
    "Image": "alpine",
    "Cmd": ["sh", "-c", "..."],
    "HostConfig": {
      "Binds": ["/:/host"],        ← монтирование корня host
      "Privileged": true,          ← все привилегии
      "PidMode": "host",           ← PID namespace host
      "NetworkMode": "host"        ← сеть host
    }
  }
  ...
═══ демонстрация на учебной машине ═══
  прочитано /etc/hostname хоста: 'workstation'
  через API, без sudo, только доступом к сокету
═══ вывод ═══
  Ограничения container'а — cap-drop, seccomp, read-only —
  применяются к СОЗДАВАЕМОМУ container'у, а не к тому,
  кто отдаёт команду.
  ...
═══ уборка ═══
  container'ы удалены

curl -s --unix-socket /var/run/docker.sock http://localhost/version | python3 -m json.tool | head
curl -s --unix-socket /var/run/docker.sock http://localhost/v1.51/containers/json | python3 -c "import json,sys; print(len(json.load(sys.stdin)))"
docker ps -q | wc -l
docker --log-level debug ps 2>&1 | grep -oE 'GET [^ "]+' | head -3