Навыки реальных инженеров: практические практики из .agents

Навыки реальных инженеров: практические практики из .agents

Статья раскрывает набор практических навыков для инженеров, взятых из репозитория mattpocock/skills, с примерами конфигураций, Docker, Proxmox и ZFS.

Системный подход к инженерной работе

Определение задачи до начала реализации

Перед тем как открыть терминал или запустить docker compose up, стоит ответить на несколько вопросов:
Какая именно проблема требует решения?
Какие ограничения уже заданы (бюджет, время, аппаратные ограничения)?
Каков ожидаемый результат и как его будет измерять?

Таким образом задача переходит из «что‑то надо сделать» в конкретную, измеримую цель.
Один из удобных форматов — карточка в системе учёта задач (Jira, YouTrack, GitHub Issues). В ней указываются:

markdownКопировать
# Задача: Настройка резервного копирования Plex‑медиа

- **Краткое описание**: автоматизировать создание снапшотов ZFS‑тома, копировать их на TrueNAS‑шару и проверять целостность.
- **Приоритет**: Средний
- **Срок**: 2 недели
- **Ожидаемый результат**: скрипт, запускаемый по systemd‑таймеру, сохраняющий 7‑дневные копии, проверка контрольной суммы SHA‑256.
- **Ограничения**: использовать только текущий ZFS‑пул, не создавать новых хранилищ.

После оформления задачи удобно добавить спецификацию в отдельный файл TASK_SPEC.md. В ней детализируются шаги, требуемые пакеты и пример конфигураций. Такой подход исключает «попытки‑перебирания» и позволяет сразу перейти к плану действий.

Практический пример
В реальном проекте я начал с того, что выписал в TASK_SPEC.md перечень команд, которые нужно выполнить, и проверил их на тестовом сервере. Это позволило убедиться, что все зависимости (zfs‑utils, rsync) доступны, и подготовить список альтернативных вариантов, если какая‑то часть стека будет недоступна.

Документация оформлении задач в GitHub

---

Методология «предсказуемости» в конфигурациях

Предсказуемость — это не просто «запускать один и тот же скрипт». Это система, где каждый элемент конфигурации известен, воспроизводим и проверяем. Ключевые принципы:

1. Декларативность – описываем желаемое состояние, а не последовательность действий.
   Пример — файл docker-compose.yml для микросервисов:

   yamlКопировать
   version: "3.9"
   services:
     plex:
       image: plexinc/pms-docker:latest
       ports:
         - "32400:32400/tcp"
       volumes:
         - plex-config:/config
         - /mnt/media:/data
       restart: unless-stopped
   
     backup:
       image: alpine:latest
       depends_on:
         - plex
       entrypoint: ["/bin/sh", "-c", "while true; do rsync -a --delete /config/backup/ /mnt/backup/; sleep 86400; done"]
       restart: unless-stopped
   
   volumes:
     plex-config:
   

   Такой файл можно хранить в Git, а при изменении просто выполнять docker compose up -d. Docker сам приведёт систему к описанному состоянию, без «ручных» правок контейнеров.

2. Версионирование конфигураций – любые изменения проходят через pull‑request, проходят lint‑проверку (например, yamllint для YAML, shellcheck для shell‑скриптов).

   bashКопировать
   # Проверка yaml‑файла
   yamllint docker-compose.yml
   # Проверка shell‑скрипта
   shellcheck backup.sh
   

3. Тестирование в изолированной среде – перед тем как применять конфигурацию на продакт‑сервере, запускаем её в Proxmox‑контейнере или в Docker‑Compose‑staging. Пример запуска тестовой среды:

   bashКопировать
   # Создаём отдельный проект Proxmox
   qm create 101 --name test‑env --memory 2048 --net0 virtio,bridge=vmbr0
   qm start 101
   # Копируем конфиг и запускаем
   qm set 101 -scsi0 local-lvm:10
   qm start 101
   

4. Система управления состоянием (systemd) – каждый сервис, который должен работать постоянно, оформляем как unit‑файл. Это гарантирует автозапуск после перезагрузки и простой мониторинг через systemctl status.

   iniКопировать
   [Unit]
   Description=Plex Media Server
   After=network.target
   
   [Service]
   ExecStart=/usr/bin/docker run --restart unless-stopped -p 32400:32400 -v /config/plex:/config -v /mnt/media:/data --name plexplexinc/pms-docker:latest
   Restart=always
   RestartSec=10
   
   [Install]
   WantedBy=multi-user.target
   

   После размещения файла в /etc/systemd/system/plex.service выполняем systemctl daemon-reload && systemctl enable --now plex.

5. Мониторинг и алерты – без предсказуемости невозможно отследить отклонения от нормы. Настраиваем Prometheus‑exporter для Docker‑контейнеров и правила в Alertmanager, чтобы получать уведомление, если контейнер упал или диск превысил 80 % использования.

   yamlКопировать
   # Пример правила в alert.rules.yml
   groups:
     - name: docker.rules
       rules:
         - alert: ContainerDown
           expr: container_status{state!="running"} == 1
           for: 2m
           labels:
             severity: critical
           annotations:
             summary: "Контейнер {{ $labels.container }} не работает"
             description: "Контейнер {{ $labels.container }} в состоянии {{ $value }} более 2 минут."
   

Следуя этим практикам, вы получаете конфигурацию, которую можно воспроизвести на любой машине, отладку которой занимает минимум времени. Это и есть «предсказуемость» в инженерии: каждый шаг известен, проверен и документирован.

---

Заключение
Если вы хотите, чтобы ваш домашний сервер или кластер работали стабильно годами, начните с чётко сформулированной задачи и перейдите к декларативным, версиированным и протестированным конфигурациям. Только так можно говорить о настоящей инженерной «предсказуемости».

Контейнеризация и оркестрация

Docker и Docker Compose для изоляции сервисов

Во-первых, Docker позволяет запускать приложение в полностью изолированном окружении – контейнере, где всё, что нужно, уже включено в образ. Это удобно, когда на одном домашнем сервере (например, на Proxmox‑виртуалке) хочется держать несколько сервисов без конфликтов зависимостей.

Для простого развёртывания стека из Plex и Nextcloud удобно использовать Docker Compose. Ниже пример файла docker-compose.yml, который можно разместить в директории ~/docker/plex-nextcloud/:

yamlКопировать
version: "3.8"

services:
  plex:
    image: linuxserver/plex
    container_name: plex
    ports:
      - "32400:32400/tcp"
    volumes:
      - /mnt/trueNAS/media:/data
    restart: unless-stopped

  nextcloud:
    image: linuxserver/nextcloud
    container_name: nextcloud
    ports:
      - "8080:80"
    environment:
      - MYSQL_DATABASE=nextcloud
      - MYSQL_USER=nextcloud
      - MYSQL_PASSWORD=nextcloud_pass
      - MYSQL_HOST=db
    volumes:
      - /mnt/trueNAS/nextcloud:/var/www/html
    depends_on:
      - db
    restart: unless-stopped

  db:
    image: mariadb:10.11
    container_name: nextcloud-db
    environment:
      - MYSQL_ROOT_PASSWORD=root_pass
      - MYSQL_DATABASE=nextcloud
      - MYSQL_USER=nextcloud
      - MYSQL_PASSWORD=nextcloud_pass
    volumes:
      - db_data:/var/lib/mysql
    restart: unless-stopped

volumes:
  db_data:

Команды для работы с этим стеком:

bashКопировать
# Создать и запустить контейнеры в фоне
docker compose up -d

# Остановить и удалить все контейнеры, сети и анонимные тома
docker compose down

# Посмотреть логи контейнера plex
docker logs -f plex

Здесь видно, как каждый сервис находится в отдельном контейнере, а общий том db_data используется только для базы данных. Такое разделение обеспечивает предсказуемость: если Plex «западает», Nextcloud остаётся доступным, а при обновлении образа достаточно перезапустить контейнер, не трогая остальные сервисы.

---

k3s и kubeadm: лёгкий кластер Kubernetes

k3s

k3s – это распакованная версия Kubernetes, оптимизированная для resource‑constrained сред, включая домашние лаборатории. Установка занимает одну строку, а после этого получаем полностью рабочий кластер, совместимый с kubectl.

bashКопировать
# Запуск k3s на домашнем сервере (для системы с systemd)
curl -sfL https://get.k3s.io | sh -

После установки проверяем статус:

bashКопировать
sudo k3s status

Вывод покажет, что сервер запущен, версию и что он является «master». Для подключения удалённого kubectl достаточно выполнить:

bashКопировать
export KUBECONFIG=/etc/rancher/k3s/k3s.yaml
kubectl get nodes

k3s автоматически создаёт сетевой плагин Flannel, поэтому дальше можно разворачивать поды без дополнительной настройки CNI.

kubeadm

kubeadm подходит, когда требуется более «чистый» Kubernetes, например, в кластере из нескольких нод, где каждый узел управляется отдельно. Минимальная конфигурация выглядит так:

bashКопировать
# Инициализация master‑узла
sudo kubeadm init --pod-network-cidr=10.244.0.0/16

Для подключения обычного пользователя к кластеру:

bashКопировать
mkdir -p $HOME/.kube
sudo cp -i /etc/kubernetes/admin.conf $HOME/.kube/config
sudo chown $(id -u):$(id -g) $HOME/.kube/config

На нодах‑участниках выполняем команду, полученную в выводе kubeadm init:

bashКопировать
sudo kubeadm join <master-ip>:6443 --token <token> --discovery-token-ca-cert-hash sha256:<hash>

После того как все ноды вступили в кластер, проверяем его состояние:

bashКопировать
kubectl get nodes
kubectl get pods -A

С помощью kubectl можно разворачивать готовые манифесты, например, Deployment для Plex:

yamlКопировать
apiVersion: apps/v1
kind: Deployment
metadata:
  name: plex
spec:
  replicas: 1
  selector:
    matchLabels:
      app: plex
  template:
    metadata:
      labels:
        app: plex
    spec:
      containers:
        - name: plex
          image: linuxserver/plex
          ports:
            - containerPort: 32400

Применяем манифест:

bashКопировать
kubectl apply -f plex-deployment.yaml

Таким образом, k3s обеспечивает быстрый запуск и минимальную нагрузку на домашний сервер, тогда как kubeadm даёт более гибкую основу для многоуровневых кластеров, где каждый узел может иметь свои ограничения и требования. Оба подхода позволяют изолировать сервисы, управлять версиями и масштабировать инфраструктуру без необходимости «гасить пожар» вручную.

Виртуализация и хранилище данных

Proxmox VE: настройка нескольких нод

Во-первых, для создания надёжного кластера в Proxmox VE требуется, чтобы все ноды имели статические IP‑адреса, одинаковую версию Proxmox и синхронные часы (NTP). После этого можно инициировать формирование кластера командой pvecm.

bashКопировать
# На первом сервере (node1) создаём кластер
pvecm create node1
# На втором сервере (node2) добавляем его в существующий кластер
pvecm add 192.168.1.10 node1

При добавлении ноды следует убедиться, что порт 3128 открыт между ними, а также что файлы /etc/hosts содержат корректные имена. Quorum‑механизм Proxmox автоматически учитывает состояние диска и сетевого соединения, поэтому важно, чтобы каждый нод имел хотя бы один «живой» диск, используемый для хранения метаданных кластера.

С практической точки зрения удобно распределять VM‑контейнеры по хранилищу, которое находится на отдельном диске (например, ZFS‑пул), а не на системном диске ноды. Это повышает отказоустойчивость: при потере ноды данные остаются доступными через репликацию.

официальная документация о создании кластера Proxmox

---

ZFS на TrueNAS: эффективное сжатие и резервное копирование

Во-первых, ZFS поддерживает несколько алгоритмов сжатия: lz4, gzip, zstd и lzma. На практике lz4 даёт лучший компромисс между скоростью и экономией места, особенно на современных процессорах с поддержкой инструкций AES‑NI. Если данные уже сжаты (например, изображения), лучше использовать gzip или оставить сжатие выключенным.

bashКопировать
# Включаем сжатие LZ4 для основного набора данных
zfs set compression=lz4 tank/data

# Включаем gzip для архивных копий, где уже есть сжатие
zfs set compression=gzip tank/backups

Снимки (snapshots) позволяют быстро перейти к предыдущим состояниям данных без полной копии. Рекомендуется создавать ежедневные снимки корневых наборов и еженедельные – для более длительного хранения.

bashКопировать
# Создаём снимок текущего состояния dataset
zfs snapshot tank/data@$(date +%Y-%m-%d)

# Отправляем инкрементный снимок на удалённый TrueNAS‑сервер по SSH
zfs send -R tank/data@2024-10-01 | ssh user@remote TrueNAS zfs receive -F tank/backup

Для автоматизации резервного копирования удобно добавить запись в crontab:

cronКопировать
0 2 * * * /usr/sbin/zfs snapshot -r tank/data@$(date +\%F) && \
/usr/sbin/zfs send -R tank/data@$(date +\%F) | ssh user@remote zfs receive -F tank/backup

Эта задача будет выполняться каждый день в 02:00, создавая снимок, а затем отправлять инкрементные данные на удалённый узел. При повторных запусках zfs send определит только изменения с момента последнего снимка, что экономит трафик и место на диске.

документация TrueNAS о настройке сжатия и резервного копирования

Автоматизация и мониторинг

Автоматизация и мониторинг

Автоматизация позволяет держать конфигурацию в предсказуемом состоянии, а мониторинг — выявлять отклонения до их влияния на сервис. Я использую Ansible для приведения состояния серверов к требуемому и Prometheus + Grafana для сбора метрик и генерации оповещений.

Ansible для стабильной конфигурации

Ansible удобно применять, когда нужно гарантировать, что пакеты установлены, сервисы запущены и файлы конфигурации соответствуют шаблону. Ниже пример playbook, который:

• обновляет системный пакетный репозиторий;
• устанавливает Nginx;
• копирует пользовательский конфиг и включает сервис.

yamlКопировать
# site.yml
- name: Подготовка веб‑сервера
  hosts: webservers
  become: true
  tasks:
    - name: Обновить кэш пакетов
      apt:
        update_cache: yes
        cache_valid_time: 3600

    - name: Установить Nginx
      apt:
        name: nginx
        state: present

    - name: Скопировать конфиг Nginx
      copy:
        src: files/nginx.conf
        dest: /etc/nginx/nginx.conf
        owner: root
        group: root
        mode: '0644'

    - name: Включить и запустить Nginx
      systemd:
        name: nginx
        state: started
        enabled: yes

bashКопировать
# Запуск playbook
ansible-playbook -i inventory.ini site.yml

inventory.ini — пример инвентаря:

iniКопировать
[webservers]
server1.example.com ansible_user=alexey
server2.example.com ansible_user=alexey

После выполнения playbook Nginx будет установлен и запущен на всех узлах, а конфиг — одно и то же для каждого сервера. При необходимости изменить параметр, достаточно отредактировать шаблон и запустить playbook ещё раз — Ansible гарантирует idempotency.

Prometheus + Grafana: метрики и оповещения

Для сбора метрик я разворачиваю два контейнера — Prometheus и Grafana — через Docker‑Compose. Prometheus отвечает за скрейппинг метрик, а Grafana — за визуализацию и оповещения.

yamlКопировать
# docker-compose.yml
version: '3.8'
services:
  prometheus:
    image: prom/prometheus:v2.51.0
    volumes:
      - ./prometheus.yml:/etc/prometheus/prometheus.yml:ro
    ports:
      - "9090:9090"
    restart: unless-stopped

  grafana:
    image: grafana/grafana:10.2.0
    environment:
      - GF_SECURITY_ADMIN_PASSWORD=admin
    volumes:
      - grafana-data:/var/lib/grafana
    ports:
      - "3000:3000"
    restart: unless-stopped

volumes:
  grafana-data:

yamlКопировать
# prometheus.yml
global:
  scrape_interval: 15s

scrape_configs:
  - job_name: 'node_exporter'
    static_configs:
      - targets: ['node-exporter:9100']

bashКопировать
# Запуск стека
docker compose up -d

После старта Prometheus доступен по http://<host>:9090, Grafana — по http://<host>:3000. В Grafana создаю дашборд, добавляя источник данных Prometheus, а в настройках оповещений задаю правила, например:

yamlКопировать
# alert.rules.yml
groups:
  - name: node_alerts
    rules:
      - alert: HighCpuUsage
        expr: 100 - (avg by (instance) (rate(node_cpu_seconds_total{mode="idle"}[5m])) * 100) > 80
        for: 5m
        labels:
          severity: critical
        annotations:
          summary: "Высокий уровень загрузки CPU на {{ $labels.instance }}"
          description: "CPU загружен более 80 % в течение 5 минут."

В Grafana открываю панель Alerting, импортирую файл alert.rules.yml и привязываю его к дашборду. При превышении порога Prometheus генерирует событие, которое Grafana передаёт в Alertmanager (встроенный в образ prometheus) — отправляет уведомление в Telegram, Slack или по e‑mail.

Таким образом, автоматизация конфигурации и система мониторинга работают в паре: Ansible обеспечивает, чтобы сервисы были в нужном состоянии, а Prometheus + Grafana — сообщают, если что‑то отклоняется от ожидаемого. Оба инструмента легко интегрировать в CI/CD, чтобы каждое изменение проходило проверку на соответствие Baseline.

Часто задаваемые вопросы

Как внедрить системный подход, если задачи прилетают хаотично?

С практической точки зрения, важно не пытаться изменить весь рабочий процесс сразу, а начать с фиксации входящих запросов. Даже если в компании нет привычки писать подробные спецификации, начните вести свой локальный TASK_SPEC.md для каждой крупной задачи. Это поможет вам не тратить время на переспрашивание условий и обеспечит предсказуемость результата, даже если окружение вокруг нестабильно.

Нужно ли описывать каждый шаг в TASK_SPEC.md?

Не стоит превращать спецификацию в пошаговый учебник, иначе её поддержка станет обузой. Достаточно зафиксировать ключевые этапы, зависимости и ожидаемые результаты, которые можно измерить. Если вы планируете использовать systemd для автоматизации, в спецификации стоит прописать требования к логам и механизму уведомлений об ошибках, чтобы потом не гадать, почему сервис не поднялся.

Помогает ли предварительное планирование в Docker-среде?

Безусловно, планирование помогает избежать ситуации, когда контейнеры запускаются, но не могут взаимодействовать друг с другом из-за конфликтов сетей или прав доступа к томам. Если вы заранее определите структуру docker-compose.yml и пропишете зависимости между сервисами, процесс деплоя станет гораздо более контролируемым. Это избавляет от необходимости «на лету» пересобирать образы или менять конфигурацию монтирования дисков.

Как проверить, что задача выполнена правильно?

Результат считается достигнутым только тогда, когда он соответствует критериям из вашей задачи. Если в описании указано, что бэкап должен проверяться по контрольной сумме, то просто наличие файла в хранилище не является завершением работы. С точки зрения инженера, правильный финал — это когда вы можете продемонстрировать работающий механизм мониторинга или лог, подтверждающий успешное выполнение всех условий спецификации.