Yuriy Gavrilov: posts tagged DevOps

faucet-stream и магия Webhook-интеграций

Sat, 31 Oct 2026 01:37:44 +0300

В мире данных мы привыкли к pull-моделям: регулярно опрашивать API, вычитывать базы данных или забирать файлы. Но современные SaaS-сервисы всё чаще используют Webhooks — механизм, при котором событие само «толкается» (push) в ваш эндпоинт.

`faucet-stream` — это декларативный ETL-инструмент на Rust, который идеально подходит для обработки таких событий. Он настраивается через простой YAML-файл и позволяет за пару минут создать надежный конвейер от HTTP-запроса до современного формата хранения данных, например Apache Iceberg.

https://github.com/faucet-hq/faucet-stream

🌐 Где применим кейс с Webhook?

Webhook-источник в `faucet` — это универсальный «швейцарский нож». Вам не нужно писать код для интеграции с десятками сервисов, если они умеют отправлять HTTP-запросы:

Jira / GitLab / GitHub: Ловить события создания, изменения или закрытия задач (issues) и пулл-реквестов для построения аналитики по продуктивности команд.
Stripe / ЮKassa: Принимать уведомления об успешных платежах или подписках в реальном времени.
CRM-системы (HubSpot, amoCRM): Ловить изменения статусов сделок.
IoT-устройства: Отправлять телеметрию при наступлении определенных событий (например, срабатывании датчика).

Вы просто настраиваете в Jira Webhook на URL вашего `faucet`, и все изменения задач автоматически превращаются в строки в вашей Iceberg-таблице без единой строчки кода на Python или Java.

⚠️ Ограничения Webhook-подхода

Несмотря на удобство, важно понимать природу Webhooks:

Доставка «At-most-once» (в лучшем случае): Отправитель (например, Jira) отправляет запрос и ждет ответа `200 OK`. Если ваш сервер временно недоступен (упал, перезагружается), событие будет потеряно навсегда. Webhooks не гарантируют доставку.
Отсутствие идемпотентности: Отправитель может отправить одно и то же событие дважды (сетевые сбои). `faucet` запишет оба события (append-only), поэтому вам нужно самостоятельно чистить дубликаты на этапе аналитики.
Зависимость от отправителя: Если Jira не имеет встроенного механизма повторных попыток (retry) при ошибках, вам придется самостоятельно обеспечивать высокую доступность эндпоинта `faucet`.

Для критически важных данных лучше использовать очереди (Kafka) или CDC (Debezium), но для аналитики, логов и некритичных бизнес-событий Webhook + `faucet` — это самое быстрое и дешевое решение.

🛠️ Пошаговая инструкция: Webhook → Iceberg → Trino

В этой инструкции мы развернем современный Lakehouse-стек:

Silo (S3-совместимое хранилище с поддержкой STS).
Lakekeeper (REST-каталог Iceberg).
Trino (движок запросов).
faucet-stream (приемщик вебхуков).
*(Стек запускается через Podman на macOS).*

📂 Шаг 1: Подготовка файлов

Создайте рабочую директорию и положите в нее три файла.

1. `docker-compose.yaml` (Только инфраструктура):

services:
  silo:
    image: pgsty/silo:RELEASE.2026-09-03T13-18-01Z
    command: server /data --console-address ":9001"
    environment:
      MINIO_ROOT_USER: silo-root-user
      MINIO_ROOT_PASSWORD: silo-root-password
    healthcheck:
      test: ["CMD", "mc", "ready", "local"]
      interval: 2s
      timeout: 10s
      retries: 2
      start_period: 15s
    ports:
      - "9000:9000"
      - "9001:9001"
    networks:
      - iceberg_net

  create-bucket:
    image: pgsty/silo:RELEASE.2026-09-03T13-18-01Z
    depends_on:
      silo:
        condition: service_healthy
    entrypoint: /bin/sh
    command:
      - -c
      - |
        mc alias set local http://silo:9000 silo-root-user silo-root-password &&
        mc mb --ignore-existing local/examples
    networks:
      - iceberg_net

  db:
    image: postgres:17
    environment:
      - POSTGRES_PASSWORD=postgres
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres -p 5432 -d postgres"]
      interval: 2s
      timeout: 10s
      retries: 2
      start_period: 10s
    networks:
      - iceberg_net

  migrate:
    image: quay.io/lakekeeper/catalog:latest-main
    pull_policy: always
    environment:
      - LAKEKEEPER__PG_ENCRYPTION_KEY=This-is-NOT-Secure!
      - LAKEKEEPER__PG_DATABASE_URL_READ=postgresql://postgres:postgres@db:5432/postgres
      - LAKEKEEPER__PG_DATABASE_URL_WRITE=postgresql://postgres:postgres@db:5432/postgres
      - RUST_LOG=info
    restart: "no"
    command: ["migrate"]
    depends_on:
      db:
        condition: service_healthy
    networks:
      - iceberg_net

  lakekeeper:
    image: quay.io/lakekeeper/catalog:latest-main
    pull_policy: always
    environment:
      - LAKEKEEPER__PG_ENCRYPTION_KEY=This-is-NOT-Secure!
      - LAKEKEEPER__PG_DATABASE_URL_READ=postgresql://postgres:postgres@db:5432/postgres
      - LAKEKEEPER__PG_DATABASE_URL_WRITE=postgresql://postgres:postgres@db:5432/postgres
      - RUST_LOG=info
    command: ["serve"]
    healthcheck:
      test: ["CMD", "/home/nonroot/lakekeeper", "healthcheck"]
      interval: 1s
      timeout: 10s
      retries: 3
      start_period: 3s
    depends_on:
      migrate:
        condition: service_completed_successfully
      db:
        condition: service_healthy
      silo:
        condition: service_healthy
      create-bucket:
        condition: service_completed_successfully
    ports:
      - "8181:8181"
    networks:
      - iceberg_net

networks:
  iceberg_net:
    driver: bridge

2. `create-default-warehouse.json` (Настройка каталога):

{
  "warehouse-name": "demo",
  "project-id": "00000000-0000-0000-0000-000000000000",
  "storage-profile": {
    "type": "s3",
    "bucket": "examples",
    "endpoint": "http://silo:9000",
    "region": "us-east-1",
    "path-style-access": true,
    "flavor": "s3-compat",
    "sts-enabled": true
  },
  "storage-credential": {
    "type": "s3",
    "credential-type": "access-key",
    "aws-access-key-id": "silo-root-user",
    "aws-secret-access-key": "silo-root-password"
  }
}

3. `pipeline.yaml` (Конфигурация `faucet` с Webhook):

version: 1
pipeline:
  source:
    type: webhook
    config:
      listen_addr: "0.0.0.0:8080"
      path: "/v1/events"
      auth_token: "123"
      max_payloads: 10
      timeout_secs: 3600

  sink:
    type: iceberg
    config:
      catalog:
        type: rest
        uri: "http://lakekeeper:8181/catalog"
        warehouse: "demo"
        properties:
          # Включаем использование временных ключей от Lakekeeper
          rest.vended-credentials-enabled: "true"
          io-impl: "org.apache.iceberg.aws.s3.S3FileIO"
          s3.endpoint: "http://silo:9000"
          s3.path-style-access: "true"
          s3.region: "us-east-1"
      namespace: ["demo"]
      table: "events"
      create_table: true
      write_mode: append

🚀 Шаг 2: Запуск и инициализация

Выполняйте команды строго по одной в терминале.

1. Поднимаем инфраструктуру:

podman-compose down -v
podman-compose up -d
sleep 10

*Убедитесь, что контейнер `faucet-stream_lakekeeper_1` имеет статус `healthy` (`podman ps`).*

2. Инициализируем Lakekeeper (Bootstrap и создание Warehouse):

# Bootstrap
podman run --rm --network faucet-stream_iceberg_net curlimages/curl \
  -X POST http://lakekeeper:8181/management/v1/bootstrap \
  -H "Content-Type: application/json" \
  --data '{"accept-terms-of-use": true}'

# Создание Warehouse
podman run --rm --network faucet-stream_iceberg_net \
  -v "$(pwd)/create-default-warehouse.json:/tmp/wh.json" \
  curlimages/curl \
  -X POST http://lakekeeper:8181/management/v1/warehouse \
  -H "Content-Type: application/json" --data @/tmp/wh.json

3. Запускаем Trino и настраиваем каталог:

# Запуск Trino
podman run -d --name trino --network faucet-stream_iceberg_net \
  -p 9999:8080 -e CATALOG_MANAGEMENT=dynamic trinodb/trino:476

# Ждем инициализации Trino (20 секунд)
echo "Waiting for Trino to start..."
sleep 20

# Создаем каталог lakekeeper в Trino
podman exec trino trino --execute "
CREATE CATALOG lakekeeper USING iceberg
WITH (
    \"iceberg.catalog.type\" = 'rest',
    \"iceberg.rest-catalog.uri\" = 'http://lakekeeper:8181/catalog',
    \"iceberg.rest-catalog.warehouse\" = 'demo',
    \"iceberg.rest-catalog.nested-namespace-enabled\" = 'true',
    \"iceberg.rest-catalog.vended-credentials-enabled\" = 'true',
    \"iceberg.unique-table-location\" = 'true',
    \"s3.region\" = 'us-east-1',
    \"fs.native-s3.enabled\" = 'true',
    \"s3.path-style-access\" = 'true',
    \"s3.endpoint\" = 'http://silo:9000'
);"

🎯 Шаг 3: Запуск faucet и отправка вебхука

1. В новом окне терминала запускаем `faucet`:

podman run --rm -it --network faucet-stream_iceberg_net \
  -p 8081:8080 -v "$(pwd)/pipeline.yaml:/app/pipeline.yaml" \
  ghcr.io/faucet-hq/faucet-stream:full run /app/pipeline.yaml

2. В третьем окне отправляем тестовый вебхук (имитируем событие из Jira):

curl -X POST http://127.0.0.1:8081/v1/events \
  -H "Authorization: Bearer 123" \
  -H "Content-Type: application/json" \
  -d '{"event_id": "evt-001", "user": "alice", "action": "login"}'

*(В логах `faucet` вы увидите `records_written=10` и `succeeded=1`).*

3. Проверяем результат в Trino:

podman exec trino trino --execute "SELECT * FROM lakekeeper.demo.events;"

Вывод:

"evt-001","alice","login"
"evt-002","alice","login"
...

Готово! Вы только что превратили HTTP-события в структурированную Iceberg-таблицу. 🎉

💡 Дополнение 1: За пределами Webhook: faucet как ETL-платформа

Хотя в этой инструкции мы сфокусировались на кейсе с Webhook, важно понимать, что `faucet-stream` — это не просто приемщик HTTP-запросов, а полноценная ETL-платформа.

Помимо Webhook, он поддерживает десятки других паттернов интеграции: от классического чтения REST API (с пагинацией и инкрементальной загрузкой) и баз данных (включая CDC из PostgreSQL и MySQL) до потоковой передачи из Kafka и чтения файлов из S3. Webhook — это лишь один из самых простых и быстрых способов начать, который идеально ложится на интеграцию с Jira, Stripe, GitHub и другими SaaS-сервисами.

🐛 О решенном баге и версиях

В ходе настройки мы столкнулись с ошибкой `StorageFactory must be provided for RestCatalog`. На момент выхода версии `v1.15.1` коннектор Iceberg в `faucet` не умел передавать фабрику хранилища для REST-каталогов. Команда проекта оперативно отреагировала на баг-репорт, и исправление уже вошло в последующие релизы (в частности, в рамках PR #966).

Теперь интеграция с Lakekeeper и Silo работает из коробки. Актуальный и стабильный образ всегда можно найти в официальном реестре: ghcr.io/faucet-hq/faucet-stream.

🍏 Почему мы запускали Trino и Faucet вручную на macOS?

Если вы обратили внимание, в инструкции мы запускали инфраструктуру (Silo, Lakekeeper) через `podman-compose`, а `Trino` и `faucet` — отдельными командами `podman run`.

Это не архитектурное требование, а вынужденный обход специфичного бага `podman-compose` на macOS. На Mac этот инструмент часто пытается объединить все контейнеры в один «Pod» и некорректно обрабатывает сложные цепочки зависимостей (`depends_on: condition: service_healthy`). В результате вы получаете общую ошибку `starting some containers: internal libpod error`, за которой невозможно разглядеть реальные логи контейнера.

Ручной запуск через `podman run` с явным указанием сети (`--network faucet-stream_iceberg_net`) гарантирует, что контейнеры стартуют в правильном порядке, а вы всегда видите их реальные логи. На Linux-серверах или в Docker Desktop для Mac этот шаг можно смело делать через стандартный `docker-compose up -d`.

В итоге, объединив мощь `faucet-stream`, современный REST-каталог Lakekeeper и движок Trino, вы получили гибкий и масштабируемый Lakehouse. Теперь любые события из внешних систем могут напрямую попадать в вашу аналитику без единой строчки кода! 🚀 Но не все так просто и радужно, как может показаться 🌈🦄 ...

💡 Дополнение 2: Архитектура faucet-stream, Push vs Pull и будущее потоковой обработки

В завершение статьи важно заглянуть «под капот» `faucet-stream` и обсудить два фундаментальных подхода к интеграции данных: Push (Webhook) и Pull (REST API). Понимание этой разницы критически важно, так как от нее зависит надежность вашего будущего Lakehouse.

📤 Push-модель (Webhook) и её ограничения в faucet

В этой инструкции мы использовали `webhook` — это классическая Push-модель. Отправитель (например, Jira или Stripe) сам «толкает» событие на ваш сервер.

Плюсы: Мгновенная реакция на событие, минимальная задержка, не нужно писать код для опроса.
Ограничения `faucet-stream`: Важно понимать, что источник `webhook` в `faucet` — это временный буфер, а не долгоживущий сервер. Сервер запускается, собирает POST-запросы в память (в течение `timeout_secs` или до `max_payloads`), а затем завершается, сбрасывая данные в Iceberg.
Режим `serve`: Даже при запуске `faucet serve --triggers` триггер выступает лишь оркестратором. Он запускает пайплайн по событию, но само тело вебхука (`${trigger.body}`) не передается в пайплайн как готовый поток записей — его можно использовать только для параметризации источников внутри пайплайна.
Риск потери: Если сервис перезагрузится или окно приема истечет в момент отправки, событие будет потеряно (доставка *at-most-once*). Установка огромного `timeout_secs` не решает проблему, а лишь откладывает ее, создавая риск переполнения памяти (OOM).

📥 Pull-модель (REST API): Надежность для Production

Альтернатива — Pull-модель. Вместо того чтобы ждать вебхук, `faucet` сам регулярно опрашивает API внешней системы (например, Jira) с помощью источника `rest`.

Плюсы: Абсолютная надежность. Если `faucet` упал или был перезапущен, при следующем запуске он просто продолжит чтение с того места, где остановился (благодаря параметру `replication_method: Incremental`). Вы не потеряете ни одного события.
Где использовать: Для критически важных бизнес-данных, аналитики и построения Lakehouse лучше выбирать именно Pull-модель, запуская пайплайн по расписанию (например, через `cron` или `faucet schedule` каждые 5-15 минут).

🌊 Сравнение с RisingWave: Batch/ETL против True Streaming

Учитывая слово `stream` в названии, многие ожидают от `faucet` поведения полноценной потоковой платформы, например, RisingWave.

RisingWave — это потоковая база данных (True Streaming). Она выступает в роли постоянного получателя. Вы создаете таблицу с коннектором `webhook`, и все входящие HTTP-запросы немедленно попадают в нее и обрабатываются с низкой задержкой. Она держит состояние постоянно.
faucet-stream — это, прежде всего, декларативный ETL-инструмент (Batch/ELT). Его парадигма — выполнение задачи (run) от начала до конца. Несмотря на название, на данный момент `faucet` не является долгоживущим стриминговым движком в том же смысле, что RisingWave или Kafka Streams. Его сила — в огромном количестве коннекторов, эффективной пакетной обработке и простоте YAML-конфигурации.

Взгляд в будущее: Слово «stream» в названии оставляет надежду, что в будущих версиях `faucet` может обзавестись более нативными примитивами для непрерывной потоковой обработки. Но на сегодняшний день, если вам нужен постоянный, вечно живой приемник вебхуков с гарантией сохранности каждого байта (что нетривиально при текущем состоянии документации 😁), — это задача для потоковых баз данных (RisingWave) или связки «сервис-приемник + очередь (Kafka/Redis)». Если же вам нужен мощный и гибкий инструмент для периодического перемещения данных (ETL) по расписанию или событию, `faucet-stream` с Pull-моделью — идеальный выбор.

kagent: Kubernetes-нативный рантайм для AI-агентов — архитектура, практика и альтернативы

Fri, 23 Oct 2026 02:27:23 +0300

kagent — это open-source платформа с открытым исходным кодом, которая привносит «агентный» искусственный интеллект в облачные и Kubernetes-среды. Если говорить проще, она позволяет создавать интеллектуальных агентов, которые понимают запросы на естественном языке и автономно выполняют сложные операции по управлению инфраструктурой: диагностируют проблемы с сетью, анализируют логи, управляют развертываниями. https://kagent.dev

kagent был создан компанией Solo.io в 2025 году и является sandbox-проектом CNCF (Cloud Native Computing Foundation). Его главная идея — превратить AI-агента из простого чат-бота в полноценного участника DevOps- и платформенных процессов, управляемого теми же инструментами, что и остальные рабочие нагрузки в кластере.

🎯 Что дает kagent и как он работает

Ключевые возможности

Управление как кодом (GitOps): Агенты определяются как обычные Kubernetes-ресурсы (Custom Resources). Вы можете версионировать их, применять через `kubectl` и управлять ими так же, как и любыми другими компонентами инфраструктуры.
Автоматизация рутины: Агенты самостоятельно выполняют многошаговые задачи по устранению неполадок и мониторингу, снижая нагрузку на специалистов.
Гибкость и отсутствие привязки: kagent поддерживает множество LLM-провайдеров (OpenAI, Anthropic, Gemini и другие), а также любые OpenAI-совместимые эндпоинты, что позволяет использовать практически любую модель, включая вашу собственную.
Интеграция с инструментами: Агенты могут использовать широкий набор инструментов (Tools) через Model Context Protocol (MCP) для взаимодействия с системами: просмотр логов подов, запросы к Prometheus, управление ресурсами Kubernetes и многое другое.
Human-in-the-loop: Встроенные механизмы подтверждения действий, когда агент предлагает изменить ресурс, но ждет одобрения человека, а также поддержка инициативных вопросов от агента.
Долговременная память: Векторная память, позволяющая агентам помнить контекст между сессиями, а не только в рамках последнего запроса.
Agent-to-Agent (A2A): Агенты могут обнаруживать друг друга и вызывать, что позволяет строить многоагентные рабочие процессы с делегированием задач.

Архитектура

Архитектура kagent состоит из трех основных компонентов:

Tools (Инструменты): Это «руки» агента — набор функций, которые агент может вызывать для выполнения реальных действий в инфраструктуре. kagent поставляется с предустановленными инструментами для отображения логов подов, запросов к Prometheus, генерации ресурсов и многого другого.
Agents (Агенты): Это «мозг» системы — автономные системы, которые планируют, выполняют и анализируют задачи, используя доступные инструменты. Вы описываете агента в YAML-файле, указывая его системный промпт (роль), модель LLM и список инструментов, к которым у него есть доступ. Агенты могут объединяться в команды, где планирующий агент распределяет задачи между исполнителями.
Framework (Фреймворк): Гибкий интерфейс, позволяющий запускать агентов как через UI, так и декларативно. Он построен на фреймворке Google ADK, но также поддерживает LangGraph, CrewAI и собственные фреймворки.

🐳 Практический пример: запуск kagent в Podman на macOS

Перейдем от теории к практике. Наш тестовый агент `myagent` был успешно запущен локально на MacBook (Intel) с использованием Podman. Он продемонстрировал возможность вызова инструментов (Tool Calling) и ведения диалога на русском языке.

Ключевые шаги развертывания

Подготовка окружения: Установка Podman и `podman-compose`, а также создание скрипта-обертки `docker-compose`, который перенаправляет вызовы в `podman-compose`, поскольку kagent ожидает наличия именно этой утилиты.
Создание проекта агента: Генерация структуры проекта командой `kagent init adk python myagent`.
Настройка базового образа: В `Dockerfile` базовый образ был заменен на `kagent-adk:0.10.4-full`, так как distroless-вариант не содержит оболочки `/bin/sh`, необходимой для выполнения команд установки зависимостей. Также был добавлен шаг `RUN uv pip install “google-adk[extensions]”` для поддержки LiteLLM и указана переменная `ENV PYTHONPATH=/app`.
Конфигурация подключения к LLM: В файле `agent.py` (и/или `docker-compose.yaml`) были явно указаны параметры для подключения к вашему эндпоинту ProxyAPI:
- Модель: `openai/z-ai/glm-5.3-flash` (обязательный префикс `openai/` для LiteLLM).
- Базовый URL: `https://api.proxyapi.ru/v1`.
- API-ключ: ваш токен от ProxyAPI.
Запуск: Сборка образа и запуск контейнера через `podman-compose up`.

Результат: работающий агент с Tool Calling

На скриншоте видно, как агент `myagent` в интерактивном режиме `kagent run` отвечает на приветствие, а затем по запросу «давай кинем» выполняет вызов инструмента:

Tool Call: `roll_die` с параметром `{“sides”: 6}`.
Tool Result: `{“result”: 1}`.
Ответ агента: «Выпала 1 🎲. На кубике с 6 гранями это минимальный результат — не повезло, но такое бывает! Хочешь бросить ещё раз или проверить число на простоту?»

Этот пример наглядно демонстрирует полный цикл работы агента: понимание запроса, выбор и вызов нужного инструмента, обработка результата и формирование естественно-языкового ответа.

⚖️ Сравнение с альтернативами

kagent — не единственный инструмент в этой нише. Чтобы понять его место, полезно сравнить его с другими решениями, которые решают смежные, но зачастую разные задачи. Подробные обзоры на Asya и Agent Autoscale появятся в отдельных статьях, а здесь мы приведем краткое сравнение.

Инструмент	Категория	Ключевая абстракция	Модель выполнения	Масштабирование	Основной сценарий
kagent	Фреймворк для AI-агентов	`Agent` (системный промпт + инструменты + LLM)	Синхронный запрос/ответ через контроллер и движок ADK	❌ Нет встроенного автомасштабирования (агенты — это процессы, управляемые контроллером)	Одиночные агенты для операционных задач в K8s (troubleshooting, мониторинг)
Asya	Меш акторов для AI-нагрузок	`AsyncActor` (stateless обработчик + очередь + sidecar)	Хореография: сообщение несет свой маршрут через меш акторов	✅ Поакторное масштабирование через KEDA (по глубине очереди), scale-to-zero	Многошаговые AI/ML пайплайны, агентные рабочие процессы в масштабе
Agent Autoscale	Оператор для управления AI-агентами	`SwarmAgent` (LLM-агент с промптом, инструментами, guardrails и автомасштабированием)	Управляется оператором, масштабирование на основе KEDA	✅ Масштабирование на основе спроса и scale-to-zero через KEDA	Управление флотами AI-агентов как first-class ресурсами с автомасштабированием

Другие заметные инструменты в экосистеме

Помимо вышеперечисленных, стоит упомянуть специализированные утилиты, которые часто используются в связке или как альтернативы для конкретных задач:

K8sGPT: AI-ассистент для быстрой диагностики кластера. Он сканирует ресурсы и объясняет проблемы на понятном языке, но по умолчанию не вносит изменений (read-only).
HolmesGPT: Инструмент для более глубокого расследования инцидентов. Он анализирует логи, метрики и состояние кластера для поиска корневой причины, с возможностью опционального исправления с подтверждением.
kubectl-ai: Утилита, которая превращает запросы на естественном языке в команды `kubectl`. Перед выполнением спрашивает подтверждение у пользователя.

💎 Заключение

kagent занимает важную нишу, предлагая Kubernetes-нативный, декларативный подход к управлению AI-агентами. Он идеально подходит для платформенных инженеров и DevOps-специалистов, которые хотят автоматизировать рутинные операции, используя знакомые им инструменты (YAML, `kubectl`, GitOps). В отличие от специализированных ассистентов (K8sGPT, HolmesGPT), kagent — это именно фреймворк для создания собственных агентов под конкретные задачи вашей инфраструктуры.

Хотя kagent не является решением для масштабных асинхронных пайплайнов (как Asya) или автоматического масштабирования флотов агентов (как Agent Autoscale), его сила — в простоте, гибкости и глубокой интеграции с экосистемой Kubernetes.

Успешный запуск агента с поддержкой Tool Calling в локальном окружении подтверждает, что kagent готов к практическому использованию и может стать мощным инструментом в арсенале вашей команды.

Части 3: Настройка HTTPS с самоподписными сертификатами для Traefik и Marimo

Tue, 29 Sep 2026 00:02:00 +0300

В предыдущей части мы настроили балансировку нагрузки через Traefik, но весь трафик ходил по HTTP — незашифрованным. В этой части мы добавим HTTPS с помощью самоподписных сертификатов. Это хороший способ подготовить инфраструктуру к продакшену, где вы сможете заменить их на сертификаты от Let’s Encrypt буквально одной строкой.

Часть 1: HashiCorp Nomad: развертывание интерактивного Python-приложения на macOS
Часть 2: Балансировка нагрузки и сервис-дискавери с Consul и Traefik для Marimo

Зачем нужен HTTPS

Шифрование: данные между браузером и сервером передаются в зашифрованном виде.
Подготовка к продакшену: архитектура с двумя точками входа (HTTP и HTTPS) и автоматическим редиректом — это стандартная схема.
Доверие к сертификатам: локально вы можете использовать самоподписные сертификаты, а в продакшене — Let’s Encrypt, не меняя структуру конфигурации.

Шаг 1: Генерация самоподписного сертификата

Для создания сертификата используем `openssl`, который уже есть в macOS. Важный момент: обязательно указываем Subject Alternative Name (SAN) с именем домена, иначе современные браузеры откажутся считать сертификат валидным.

mkdir -p ~/marimo-app/certs && cd ~/marimo-app/certs

openssl req -x509 -nodes -days 365 \
  -newkey rsa:2048 \
  -keyout marimo.localhost.key \
  -out marimo.localhost.crt \
  -subj "/CN=marimo.localhost" \
  -addext "subjectAltName=DNS:marimo.localhost"

В папке `certs` появятся два файла:

`marimo.localhost.key` — приватный ключ.
`marimo.localhost.crt` — сертификат.

Что произойдёт при открытии сайта: браузер покажет предупреждение, что сертификат не является доверенным. Это ожидаемое поведение — вы можете принять исключение для домена `marimo.localhost`. В продакшене предупреждения не будет, так как сертификаты Let’s Encrypt автоматически доверенные.

Шаг 2: Обновление конфигурации Traefik

Traefik поддерживает разделение конфигурации на статическую (точки входа, провайдеры) и динамическую (маршруты, сертификаты). Мы создадим обе через блоки `template` в задании Nomad.

Статическая конфигурация

Добавим точку входа `websecure` на порту 8443 и настроим автоматический редирект с HTTP на HTTPS:

[entryPoints]
  [entryPoints.web]
    address = ":8080"
    [entryPoints.web.http.redirections.entryPoint]
      to = "websecure"
      scheme = "https"
      permanent = true

  [entryPoints.websecure]
    address = ":8443"

  [entryPoints.traefik]
    address = ":8081"

[api]
  dashboard = true
  insecure  = true

[providers.consulCatalog]
  prefix           = "traefik"
  exposedByDefault = false

  [providers.consulCatalog.endpoint]
    address = "127.0.0.1:8500"
    scheme  = "http"

[providers.file]
  filename = "${NOMAD_TASK_DIR}/dynamic.toml"
  watch    = true

Ключевые моменты:

`websecure` на порту `8443` — точка входа для HTTPS-трафика.
`[entryPoints.web.http.redirections.entryPoint]` — HTTP-запросы автоматически перенаправляются на HTTPS.
`[providers.file]` — подключает динамический провайдер, который читает наш файл с сертификатами.

Динамическая конфигурация

Здесь мы описываем сам сертификат:

[tls]
  [tls.stores]
    [tls.stores.default]
      [tls.stores.default.defaultCertificate]
        certFile = "/Users/yuriygavrilov/marimo-app/certs/marimo.localhost.crt"
        keyFile  = "/Users/yuriygavrilov/marimo-app/certs/marimo.localhost.key"

  [[tls.certificates]]
    certFile = "/Users/yuriygavrilov/marimo-app/certs/marimo.localhost.crt"
    keyFile  = "/Users/yuriygavrilov/marimo-app/certs/marimo.localhost.key"

Обратите внимание, что здесь используются абсолютные пути. Это работает, потому что мы запускаем Traefik через `raw_exec` — процесс работает прямо на хосте и имеет доступ ко всем файлам.

Шаг 3: Полное задание Traefik

Вот итоговый файл `traefik.nomad` с обеими конфигурациями:

job "traefik" {
  region      = "global"
  datacenters = ["dc1"]
  type        = "service"

  group "traefik" {
    count = 1

    network {
      port "http" {
        static = 8080
      }
      port "api" {
        static = 8081
      }
    }

    service {
      name = "traefik"
      check {
        name     = "alive"
        type     = "tcp"
        port     = "http"
        interval = "10s"
        timeout  = "2s"
      }
    }

    task "traefik" {
      driver = "raw_exec"

      # Статическая конфигурация Traefik
      template {
        data = <<EOF
[entryPoints]
  [entryPoints.web]
    address = ":8080"
    [entryPoints.web.http.redirections.entryPoint]
      to = "websecure"
      scheme = "https"
      permanent = true

  [entryPoints.websecure]
    address = ":8443"

  [entryPoints.traefik]
    address = ":8081"

[api]
  dashboard = true
  insecure  = true

[providers.consulCatalog]
  prefix           = "traefik"
  exposedByDefault = false

  [providers.consulCatalog.endpoint]
    address = "127.0.0.1:8500"
    scheme  = "http"

[providers.file]
  filename = "${NOMAD_TASK_DIR}/dynamic.toml"
  watch    = true
EOF
        destination = "local/traefik.toml"
      }

      # Динамическая конфигурация: сертификаты по абсолютному пути
      template {
        data = <<EOF
[tls]
  [tls.stores]
    [tls.stores.default]
      [tls.stores.default.defaultCertificate]
        certFile = "/Users/yuriygavrilov/marimo-app/certs/marimo.localhost.crt"
        keyFile  = "/Users/yuriygavrilov/marimo-app/certs/marimo.localhost.key"

  [[tls.certificates]]
    certFile = "/Users/yuriygavrilov/marimo-app/certs/marimo.localhost.crt"
    keyFile  = "/Users/yuriygavrilov/marimo-app/certs/marimo.localhost.key"
EOF
        destination = "local/dynamic.toml"
      }

      config {
        command = "/usr/local/bin/traefik"
        args = [
          "--configfile",
          "${NOMAD_TASK_DIR}/traefik.toml"
        ]
      }

      resources {
        cpu    = 100
        memory = 128
      }
    }
  }
}

Шаг 4: Обновление тегов Marimo

В задании `marimo-job.nomad` нужно переключить сервис на точку входа `websecure` и включить TLS:

service {
  name = "marimo-app"
  port = "http"
  tags = [
    "traefik.enable=true",
    "traefik.http.routers.marimo.rule=Host(`marimo.localhost`)",
    "traefik.http.routers.marimo.entrypoints=websecure",
    "traefik.http.routers.marimo.tls=true",
    "traefik.http.services.marimo-app.loadbalancer.sticky.cookie=true",
  ]
  check {
    type     = "http"
    path     = "/"
    interval = "2s"
    timeout  = "2s"
  }
}

Что изменилось:

`entrypoints=websecure` — трафик направляется на HTTPS-точку входа.
`tls=true` — включена TLS-терминация для этого маршрута.

Шаг 5: Запуск и проверка

Перезапустите оба задания:

nomad job stop traefik
nomad job run traefik.nomad
nomad job run marimo-job.nomad

Откройте в браузере:

https://marimo.localhost:8443

Браузер покажет предупреждение о недоверенном сертификате. Нажмите «Дополнительно» → «Перейти на marimo.localhost (небезопасно)» или добавьте сертификат в системный раздел доверенных сертов (в macOS это делается через «Связка ключей»).

Если вы попробуете открыть `http://marimo.localhost:8080`, Traefik автоматически перенаправит вас на HTTPS.

Возможные ошибки и их решения

Ошибка: `Unclosed configuration block`

Причина: незакрытые блоки `{ ... }` в HCL-файле.

Решение: внимательно проверьте, что все блоки `job`, `group`, `task`, `config`, `template` закрыты. В HCL отступы не важны, но фигурные скобки — критичны.

Ошибка: `Missing required argument: “command”` при `raw_exec`

Причина: конфигурация скопирована из задания для `docker` (с полями `image`, `volumes`, `network_mode`), но применён драйвер `raw_exec`.

Решение: для `raw_exec` используйте поля `command` и `args`. Файлы конфигурации создавайте через `template`.

Ошибка: `volume_mount` не поддерживается драйвером `raw_exec`

Причина: драйвер `raw_exec` работает напрямую с процессами хоста и не поддерживает монтирование томов.

Решение: используйте абсолютные пути к файлам (как мы сделали в динамической конфигурации). Или переходите на драйвер `docker`/`podman` — там `volume_mount` работает штатно.

Ошибка: `entryPoint “websecure” doesn’t exist`

Причина: имя точки входа в тегах сервиса не совпадает с именем в статической конфигурации Traefik.

Решение: убедитесь, что в конфиге есть блок `[entryPoints.websecure]`, а в тегах указано `traefik.http.routers.marimo.entrypoints=websecure`.

Итог

Мы добавили HTTPS в наш стек. Теперь архитектура выглядит так:

Пользователь (HTTPS)
     │
     ▼
  Traefik  ──►  Marimo 1 / 2 / 3
(8443)              │
     │              ▼
     └─────────► Consul
                    ▲
                    │
             Nomad Cluster

HTTP-трафик на порту 8080 автоматически перенаправляется на HTTPS.
HTTPS-трафик на порту 8443 расшифровывается Traefik и направляется на реплики Marimo.
Сертификаты хранятся на хосте и подключаются через абсолютные пути.

В продакшене достаточно заменить пути к сертификатам и указать Traefik получать их автоматически от Let’s Encrypt — структура конфигурации останется той же. Мы разберём это в следующей части.

А вот еще бонус:

Все это через туннель https://cloudpub.ru/docs/http

Вот так:

yuriygavrilov@MacBookPro ~ % ./clo publish https marimo.localhost:8443
Сервис опубликован: https://marimo.localhost:8443 -> https://thirdly-fast-bushbuck.cloudpub.ru:443

Ну и конечно нужно DNS поправить, но работает и с авторизацией

Но лучше так не делать, все такие весь трафик так проходит через cloudpub

Часть 2: Балансировка нагрузки и сервис-дискавери с Consul и Traefik для Marimo

Mon, 28 Sep 2026 23:37:19 +0300

В первой части мы развернули приложение Marimo через Nomad, используя драйвер `raw_exec` и динамические порты. Приложение работало, но у него был существенный недостаток: каждая реплика была доступна по отдельному порту, а пользователю приходилось вручную искать актуальный адрес. Кроме того, отсутствовала отказоустойчивость — при падении одной реплики трафик не перераспределялся.

Первая часть тут HashiCorp Nomad: развертывание интерактивного Python-приложения на macOS

В этой статье мы решим эти проблемы с помощью Consul (сервис-дискавери) и Traefik (балансировщик нагрузки). Мы также настроим липкие сессии (sticky sessions), которые критически важны для stateful-приложений, таких как Marimo.

Зачем нужны Consul и Traefik?

Consul — распределённый каталог сервисов. Он хранит информацию о работающих репликах, проверяет их здоровье и предоставляет DNS-интерфейс. Без него балансировщик не знал бы, куда направлять трафик.
Traefik — современный обратный прокси и балансировщик нагрузки. Он автоматически обнаруживает сервисы через Consul Catalog Provider и распределяет запросы между здоровыми репликами.
Nomad — оркестратор, который управляет всеми компонентами.

Итоговая архитектура:

Пользователь
     │
     ▼
  Traefik  ──►  Marimo 1 / 2 / 3
(балансировщик)      │
     │               ▼
     └──────────► Consul
                     ▲
                     │
              Nomad Cluster

Предварительные требования

Убедитесь, что у вас есть:

Работающий Nomad в режиме разработки (`nomad agent -dev -bind=0.0.0.0`).
Проект `~/marimo-app` с файлами `app.py`, `pyproject.toml`, `uv.lock` и виртуальным окружением.
Установленный Consul.
Установленный Traefik (мы будем запускать его через Nomad, но бинарник должен быть доступен).

Установка Consul

brew tap hashicorp/tap
brew install hashicorp/tap/consul

Установка Traefik

brew install traefik

Проверьте пути:

which consul   # /usr/local/bin/consul
which traefik  # /usr/local/bin/traefik

Шаг 1: Запуск Consul в режиме разработки

Откройте отдельный терминал и запустите Consul:

consul agent -dev -bind=0.0.0.0 -client=0.0.0.0

Consul будет доступен по адресу `http://127.0.0.1:8500`. Оставьте терминал открытым.

Важно: Consul должен быть запущен до того, как вы запустите Nomad с интеграцией с Consul, иначе сервисы не зарегистрируются.

Шаг 2: Обновление задания Marimo

Мы добавим в задание блок `service`, который зарегистрирует приложение в Consul и снабдит его тегами для Traefik. Также включим липкие сессии, чтобы запросы одного пользователя всегда попадали на одну и ту же реплику.

Создайте файл `marimo-job.nomad`:

job "marimo-app" {
  datacenters = ["dc1"]
  type = "service"

  group "app" {
    count = 3

    network {
      port "http" {}
    }

    service {
      name = "marimo-app"
      port = "http"
      tags = [
        "traefik.enable=true",
        "traefik.http.routers.marimo.rule=Host(`marimo.localhost`)",
        "traefik.http.routers.marimo.entrypoints=web",
        "traefik.http.services.marimo-app.loadbalancer.sticky.cookie=true",
      ]
      check {
        type     = "http"
        path     = "/"
        interval = "2s"
        timeout  = "2s"
      }
    }

    task "marimo" {
      driver = "raw_exec"

      config {
        command = "/Users/yuriygavrilov/marimo-app/.venv/bin/marimo"
        args = [
          "run", "app.py",
          "--headless",
          "--port", "${NOMAD_PORT_http}",
          "--host", "0.0.0.0"
        ]
        work_dir = "/Users/yuriygavrilov/marimo-app"
      }

      resources {
        cpu    = 500
        memory = 256
      }
    }
  }
}

Что изменилось:

`count = 3` — запускаем три реплики.
Блок `service` — регистрирует сервис в Consul.
Теги Traefik:
- `traefik.enable=true` — разрешает Traefik обслуживать сервис.
- `traefik.http.routers.marimo.rule=Host(\`marimo.localhost\`)` — правило маршрутизации по домену.
- `traefik.http.routers.marimo.entrypoints=web` — точка входа (должна совпадать с именем в конфиге Traefik).
- `traefik.http.services.marimo-app.loadbalancer.sticky.cookie=true` — включает липкие сессии на основе cookie.

Примечание про домен `.localhost`

В примере используется домен `marimo.localhost`. Добавлять его в `/etc/hosts` не нужно — имена, заканчивающиеся на `.localhost`, автоматически резолвятся в `127.0.0.1` согласно стандарту RFC 6761 (раздел 6.3) и RFC 6762. Это поведение поддерживается:

системным резолвером macOS (`mDNSResponder`),
всеми современными браузерами (Chrome, Safari, Firefox),
а также большинством инструментов командной строки (`curl`, `ping` и т.д.).

Именно поэтому `http://marimo.localhost:8080` будет работать «из коробки» без правки системных файлов.

Когда `/etc/hosts` всё-таки понадобится:

Если вы хотите использовать другое имя — например, `marimo.dev`, `marimo.internal` или реальный домен вроде `marimo.example.com`, — тогда запись нужна:

echo "127.0.0.1 marimo.dev" | sudo tee -a /etc/hosts

Для локальной разработки и тестирования домен `.localhost` — самый удобный вариант: он не требует никаких дополнительных настроек и работает одинаково на любой машине.

Шаг 3: Создание задания для Traefik

Traefik будет запущен через `raw_exec`. Конфигурационный файл создаётся динамически с помощью шаблона Nomad.

Создайте файл `traefik.nomad`:

job "traefik" {
  region      = "global"
  datacenters = ["dc1"]
  type        = "service"

  group "traefik" {
    count = 1

    network {
      port "http" {
        static = 8080
      }
      port "api" {
        static = 8081
      }
    }

    service {
      name = "traefik"
      check {
        name     = "alive"
        type     = "tcp"
        port     = "http"
        interval = "10s"
        timeout  = "2s"
      }
    }

    task "traefik" {
      driver = "raw_exec"

      # Создаём конфигурационный файл Traefik через шаблон
      template {
        data = <<EOF
[entryPoints]
  [entryPoints.web]
    address = ":8080"
  [entryPoints.traefik]
    address = ":8081"

[api]
  dashboard = true
  insecure  = true

# Включаем Consul Catalog Provider
[providers.consulCatalog]
  prefix           = "traefik"
  exposedByDefault = false

  [providers.consulCatalog.endpoint]
    address = "127.0.0.1:8500"
    scheme  = "http"
EOF
        destination = "local/traefik.toml"
      }

      config {
        command = "/usr/local/bin/traefik"
        args = [
          "--configfile",
          "${NOMAD_TASK_DIR}/traefik.toml"
        ]
      }

      resources {
        cpu    = 100
        memory = 128
      }
    }
  }
}

Ключевые моменты:

`driver = “raw_exec”` — запускаем бинарник напрямую.
`template` — создаёт файл `traefik.toml` в директории задачи.
`command` — полный путь к Traefik.
`args` — указываем путь к созданному конфигу через переменную `${NOMAD_TASK_DIR}`.
В конфиге Traefik точка входа называется `web` (порт 8080). Это имя должно совпадать с тегом `traefik.http.routers.marimo.entrypoints=web`.

Шаг 4: Запуск всех компонентов

Убедитесь, что Consul и Nomad запущены в отдельных терминалах.

Затем в терминале, где вы работаете с заданиями:

cd ~/marimo-app

# Запускаем приложение
nomad job run marimo-job.nomad

# Запускаем Traefik
nomad job run traefik.nomad

Проверьте статус:

nomad job status marimo-app
nomad job status traefik

Шаг 5: Проверка работы

Consul: откройте `http://127.0.0.1:8500` и убедитесь, что сервис `marimo-app` зарегистрирован.

Traefik Dashboard: откройте `http://127.0.0.1:8081/dashboard/`. В разделе HTTP Routers должен быть маршрут `marimo` со статусом Enabled. В HTTP Services — сервис `marimo-app` с тремя здоровыми репликами.

Приложение: откройте `http://marimo.localhost:8080`. Вы должны увидеть интерфейс Marimo с полем ввода имени и диаграммой. Проверьте, что при нажатии кнопки данные обновляются, а ошибка `Invalid session id` не появляется.

Возможные ошибки и их решения

В процессе настройки мы столкнулись с несколькими типичными проблемами. Вот они и способы их устранения.

Ошибка 1: `EntryPoint doesn’t exist entryPointName=web`

Причина: в тегах сервиса указана точка входа `web`, а в конфигурации Traefik она называется иначе (например, `http`).

Решение: приведите имена к единому виду. В нашем случае мы переименовали точку входа в конфиге Traefik в `web`:

[entryPoints]
  [entryPoints.web]
    address = ":8080"

И в тегах указали `traefik.http.routers.marimo.entrypoints=web`.

Ошибка 2: `Invalid session id: s_bpy8u7`

Причина: отсутствие липких сессий. Marimo — stateful-приложение, оно хранит сессию на конкретной реплике. Если запросы распределяются случайно, браузер попадает на разные реплики, и сессия теряется.

Решение: добавьте тег `traefik.http.services.marimo-app.loadbalancer.sticky.cookie=true`. Traefik установит cookie и будет направлять все запросы от одного браузера на одну и ту же реплику.

Ошибка 3: `Missing required argument: “command”` при использовании `raw_exec`

Причина: конфигурация написана для драйвера `docker` (с полями `image`, `volumes`, `network_mode`), но применён `raw_exec`.

Решение: для `raw_exec` используйте `command` и `args`. Файлы конфигурации создавайте через `template`. Пример для Traefik приведён выше.

Ошибка 4: `raw_exec` отключён

Причина: в некоторых сборках Nomad драйвер `raw_exec` отключён по умолчанию.

Решение: добавьте в конфигурацию клиента Nomad (например, `/etc/nomad.d/nomad.hcl`):

plugin "raw_exec" {
  config {
    enabled = true
  }
}

и перезапустите агент Nomad, но в моем случае это не понадобилось.

Итог

Мы добавили к нашему приложению Marimo два важных компонента:

Consul — для сервис-дискавери и проверки здоровья.
Traefik — для балансировки нагрузки и единой точки входа.

Теперь приложение доступно по адресу `http://marimo.localhost:8080`, а трафик автоматически распределяется между тремя репликами. Благодаря липким сессиям пользователи не теряют состояние при работе с интерактивным интерфейсом.

Этот подход является основой для построения отказоустойчивых и масштабируемых систем. В следующих статьях мы рассмотрим настройку TLS/HTTPS, использование Vault для управления секретами и автоматическое масштабирование.

Поздравляю! Теперь ваше приложение готово к более серьёзным нагрузкам. 🚀

HashiCorp Nomad: развертывание интерактивного Python-приложения на macOS

Sun, 27 Sep 2026 00:59:39 +0300

В мире оркестрации контейнеров и приложений существует множество инструментов, но одним из самых гибких и простых в освоении является HashiCorp Nomad. Это оркестратор рабочих нагрузок, который позволяет развертывать как контейнеризированные, так и обычные приложения с использованием единого декларативного подхода.

В этой статье мы разберем, что такое Nomad, установим его на macOS, создадим простое интерактивное приложение на Marimo с полем ввода имени и генерацией случайных данных на столбчатой диаграмме, а затем развернем его с помощью Nomad, используя драйвер `raw_exec`. В конце обсудим ограничения такого подхода и путь к настоящему продакшену.

Что такое HashiCorp Nomad?

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

Ключевые особенности

Универсальность: Nomad может запускать Docker-контейнеры, обычные приложения (без контейнеризации), микросервисы и пакетные задачи на одной инфраструктуре.
Простота: Nomad распространяется как единый бинарный файл, не требует внешних зависимостей для хранения или координации и автоматически обрабатывает сбои приложений, узлов и драйверов.
Масштабируемость: Nomad способен масштабироваться до 10 000+ узлов и имеет встроенную поддержку GPU-нагрузок.
Гибкость: Поддерживает различные типы задач: сервисы, пакетные задания и системные задачи. Работает на Linux, macOS и Windows.

Установка Nomad на macOS

Для установки Nomad на macOS удобнее всего использовать Homebrew. Выполните следующие команды в терминале:

# Добавляем репозиторий HashiCorp
brew tap hashicorp/tap

# Устанавливаем Nomad
brew install hashicorp/tap/nomad

После установки проверьте версию:

nomad version

Пример вывода:

Nomad v2.0.5
BuildDate 2026-08-12T18:22:41Z
Revision 5c8612bba6eb8e44cc3fc434125cb1b13463c309

Важно: На Intel Mac (x86_64) могут возникнуть проблемы с загрузкой бинарников из-за прекращения поддержки Apple. В этом случае рекомендуется использовать VPN для доступа к ресурсам HashiCorp. Если Nomad не устанавливается через Homebrew, можно собрать его из исходников или использовать MacPorts.

Запуск Nomad в режиме разработки

Для тестирования и разработки Nomad поддерживает режим `-dev`, который запускает одноузловой кластер на вашем компьютере:

nomad agent -dev -bind=0.0.0.0

Эта команда запустит Nomad, и веб-интерфейс будет доступен по адресу `http://127.0.0.1:4646`. Оставьте этот терминал открытым — это ваш “сервер” Nomad.

Создание Marimo-приложения

Установка `uv`

`uv` — это современный и быстрый менеджер пакетов для Python. Установите его:

curl -LsSf https://astral.sh/uv/install.sh | sh

Создание проекта

mkdir ~/marimo-app
cd ~/marimo-app
uv init
uv add marimo altair pandas numpy

Написание приложения

Создайте файл `app.py` со следующим содержимым. Приложение будет иметь поле для ввода имени, кнопку для генерации случайных значений и столбчатую диаграмму:

import marimo

__generated_with = "0.11.0"
app = marimo.App()


@app.cell
def _():
    import marimo as mo
    import altair as alt
    import pandas as pd
    import numpy as np
    return alt, mo, np, pd


@app.cell
def _(mo):
    # Поле для ввода имени
    name_input = mo.ui.text(
        placeholder="Введите ваше имя...",
        label="Имя пользователя"
    )
    name_input
    return (name_input,)


@app.cell
def _(mo, name_input):
    # Отображение приветствия
    if name_input.value:
        mo.md(f"## Привет, **{name_input.value}**! 👋")
    else:
        mo.md("## Введите имя выше")
    return


@app.cell
def _(mo):
    # Кнопка для генерации данных
    generate_button = mo.ui.button(
        label="🎲 Сгенерировать данные",
        value=0,
        on_click=lambda value: value + 1
    )
    generate_button
    return (generate_button,)


@app.cell
def _(alt, generate_button, mo, np, pd):
    # Генерация случайных данных при нажатии кнопки
    np.random.seed(generate_button.value)
    categories = ["Категория A", "Категория B", "Категория C", "Категория D", "Категория E"]
    values = np.random.randint(10, 100, size=5)
    
    df = pd.DataFrame({
        "Категория": categories,
        "Значение": values
    })
    
    chart = alt.Chart(df).mark_bar().encode(
        x=alt.X("Категория", sort=None),
        y="Значение",
        color=alt.value("#4C78A8")
    ).properties(
        title="Случайные значения по категориям",
        width=500,
        height=300
    )
    
    mo.ui.altair_chart(chart)
    return (chart,)


if __name__ == "__main__":
    app.run()

Проверка локально

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

uv run marimo run app.py

Убедитесь, что приложение работает: введите имя, нажмите кнопку — диаграмма должна обновиться. Закройте сервер (`Ctrl+C`).

Создание задания для Nomad

Создайте файл `marimo-job.nomad` в папке проекта:

job "marimo-app" {
  datacenters = ["dc1"]
  type = "service"

  group "app" {
    count = 2

    network {
      port "http" {}
    }

    task "marimo" {
      driver = "raw_exec"

      config {
        command = "/Users/yuriygavrilov/marimo-app/.venv/bin/marimo"
        args = [
          "run", "app.py",
          "--headless",
          "--port", "${NOMAD_PORT_http}",
          "--host", "0.0.0.0"
        ]
        work_dir = "/Users/yuriygavrilov/marimo-app"
      }

      resources {
        cpu    = 500
        memory = 256
      }
    }
  }
}

Пояснения:

`driver = “raw_exec”` — запускает процесс напрямую на хосте без изоляции.
`count = 2` — запускаем две реплики приложения. Nomad автоматически распределит их по узлам (в нашем случае — по одному узлу, но на разных портах).
`port “http” {}` — динамический порт. Nomad резервирует случайный свободный порт для каждой аллокации. Такой подход избавляет от конфликтов портов при запуске нескольких реплик.
`command` — полный путь к исполняемому файлу `marimo` в виртуальном окружении.
`${NOMAD_PORT_http}` — Nomad автоматически подставляет динамически выделенный порт через переменную окружения `NOMAD_PORT_`.
`work_dir` — рабочая директория, где находится `app.py`.

Важно: замените `/Users/yuriygavrilov/` на реальный путь к вашей домашней директории.

Запуск задания

Убедитесь, что Nomad работает (в первом терминале). Во втором терминале выполните:

nomad job run marimo-job.nomad

Пример успешного вывода:

==> 2026-09-26T21:26:27+03:00: Monitoring evaluation "cba695bd"
    2026-09-26T21:26:27+03:00: Allocation "2327286c" created: node "7f836ccd", group "app"
==> 2026-09-26T21:26:27+03:00: Monitoring deployment "9ea4ff53"
  ✓ Deployment "9ea4ff53" successful
    
    Deployed
    Task Group  Desired  Placed  Healthy  Unhealthy  Progress Deadline
    app         1        1       1        0

Как узнать порт приложения

После запуска задания выполните:

nomad job status marimo-app

Вы увидите таблицу аллокаций с их ID. Для каждой аллокации выполните:

nomad alloc status <ID_аллокации>

В выводе найдите секцию `Allocation Addresses`:

Allocation Addresses:
Label  Dynamic  Address
*http  yes      127.0.0.1:20938

Откройте в браузере `http://127.0.0.1:20938` — ваше приложение работает.

Повторите команду для остальных аллокаций, чтобы получить порты всех реплик.

Ограничения текущего подхода

Мы успешно запустили приложение, но важно понимать, что это ещё не полноценное масштабированное решение. Вот почему:

1. Нет балансировщика нагрузки

У нас работают две реплики на разных портах (`20938`, `21001` и т.д.). Чтобы обратиться к приложению, пользователь должен знать конкретный порт каждой реплики. Это неудобно:

Нельзя дать пользователям один адрес, например `http://marimo.mycompany.com`.
Нет автоматического распределения трафика между репликами.
Нет отказоустойчивости: если одна реплика упадёт, клиент, знающий только её порт, потеряет доступ.

2. Нет сервис-дискавери

Nomad не регистрирует сервисы автоматически (для этого нужен Consul). Без сервис-дискавери балансировщик не сможет узнать, какие реплики сейчас работают.

3. Минимальная изоляция

Драйвер `raw_exec` запускает процессы прямо на хосте. В продакшене это небезопасно: приложение имеет доступ ко всей файловой системе и может влиять на систему.

Путь к продакшену: что нужно добавить

1. Балансировщик нагрузки (Traefik, NGINX, HAProxy)

Traefik — самый простой вариант для интеграции с Nomad. Он умеет:

Автоматически обнаруживать сервисы через Consul.
Распределять трафик между всеми здоровыми репликами.
Работать с TLS/HTTPS “из коробки”.
Иметь удобную панель управления.

Как это выглядит в задании: вы добавляете специальные теги в блок `service` вашего приложения, и Traefik сам настраивает маршрутизацию:

service {
  name = "marimo-app"
  port = "http"
  tags = [
    "traefik.enable=true",
    "traefik.http.routers.marimo.rule=Host(`marimo.localhost`)",
  ]
}

Затем запускаете Traefik как отдельную задачу в Nomad, и он становится единой точкой входа для всех пользователей.

2. Сервис-дискавери (Consul)

Consul — это распределённый каталог сервисов. Он:

Хранит информацию о том, какие реплики сейчас работают и на каких портах.
Предоставляет DNS-интерфейс: ваше приложение доступно как `marimo-app.service.consul`.
Позволяет балансировщику динамически обновлять список бэкендов.

3. Контейнеризация (Docker/Podman)

В продакшене используйте контейнерные драйверы вместо `raw_exec`:

Изоляция: приложение работает в своём окружении, не влияя на хост.
Воспроизводимость: одинаковое поведение на любой машине.
Безопасность: ограничения по ресурсам и правам доступа.

4. Полноценный кластер Nomad

В продакшене Nomad работает не как один процесс, а как кластер:

3 серверных узла (минимум) — хранят состояние и принимают решения о планировании.
N клиентских узлов — выполняют задачи.
Интеграция с Vault для управления секретами.

Итоговая архитектура для продакшена

Пользователь
     │
     ▼
  Traefik  ──►  Marimo 1 / 2 / 3
(балансировщик)      │
                     ▼
                  Consul
                     ▲
                     │
              Nomad Cluster

Заключение

Мы рассмотрели базовый процесс развертывания Python-приложения с помощью HashiCorp Nomad:

Установили Nomad через Homebrew.
Запустили Nomad в режиме разработки.
Создали Marimo-приложение с полем ввода имени и интерактивной диаграммой.
Написали задание Nomad с драйвером `raw_exec` и динамическим портом.
Запустили две реплики приложения и научились находить их порты.

Этот подход отлично работает для разработки и тестирования. Но для настоящего продакшена необходимо:

Добавить балансировщик нагрузки (Traefik, NGINX, HAProxy), чтобы пользователи обращались к одному адресу.
Внедрить сервис-дискавери (Consul), чтобы балансировщик знал о работающих репликах.
Использовать контейнерные драйверы (Docker, Podman) для изоляции.
Построить полноценный кластер Nomad с тремя серверными узлами.

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

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

Свой Heroku: запустил Dokku дома и накатил новогоднего :)

Thu, 01 Jan 2026 22:59:46 +0300

Мы привыкли, что для развертывания веб-приложений нужно платить за VPS или разбираться в дебрях Kubernetes. Но если у вас есть домашний сервер (в моем случае — Asustor), вы можете создать свою собственную PaaS-платформу (Platform as a Service), которая работает по принципу *“git push — и готово”*.

Сегодня я расскажу, как настроить Dokku через Portainer, запустить веселое Python-приложение к Новому 2026 году и поделюсь лайфхаками по оптимизации сборки и масштабированию.

Часть 1. Фундамент: Запуск Dokku в Portainer

Dokku — это Docker-контейнер, который управляет другими Docker-контейнерами. Чтобы он заработал на NAS, его нужно правильно запустить. Я использовал Portainer Stack.

Docker Compose конфигурация

Вот рабочий `docker-compose.yml`, который решает главную проблему — доступность приложений из локальной сети.

# version: '3.2'
services:
  agent:
    image: dokku/dokku:${VERSION}
    pid: host.  # ⚠️ важно для работы на NAS
    network_mode: bridge # ⚠️ важно для работы на NAS
    environment:
      DOKKU_HOSTNAME: ${DOKKU_HOSTNAME}
      DOKKU_HOST_ROOT: ${DOKKU_HOST_ROOT}
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - ${VOLUME_PATH:-/var/lib/dokku}:/mnt/dokku
    ports:
      - "3022:22" # ⚠️ важно для работы через ssh и что бы не конфликтовал с 22 
      - "80:80"    # Внешний порт 80 -> порт 80 внутри контейнера Dokku
      - "443:443"

Нюансы сети:
Чтобы обращаться к приложениям по красивым домегам типа `my-app.dokku.datahub.mother`, я настроил AdGuard Home в качестве локального DNS-сервера (фильтры получил бонусом – где-то 20% это всякие счетчики, ужас:). Добавил правило Rewrite: `*.dokku.datahub.mother` → `192.168.0.20` (IP моего NAS). Теперь все поддомены (приложения) автоматически ведут на Dokku.

Также для удобства я настроил `~/.ssh/config` на ноутбуке, чтобы не вводить порты вручную:

Host dokku.datahub.mother
  HostName 192.168.0.20
  Port 3022
  User dokku

ну и ключ сам так можно добавить

echo "ВАШ_ПУБЛИЧНЫЙ_КЛЮЧ" | dokku ssh-keys:add dokku

Часть 2. Приложение “my-first-app”: Новогоднее гадание

Для теста я написал простое Flask-приложение, которое рассчитывает ваш возраст в наступающем 2026 году.

Код приложения (`app.py`)

from flask import Flask, request

app = Flask(__name__)

@app.route('/')
def home():
    return """
    <h1>Приветствую в игре Нового 2026 года! 🎉</h1>
    <p>Это веселая интерактивная игра в честь Нового года. Угадай свой возраст на 1 января 2026!</p>
    <p>Введи свой год рождения:</p>
    <form action="/result" method="get">
        <input type="number" name="birth_year" min="1900" max="2025" required>
        <button type="submit">Угадать возраст на Новогодний 2026!</button>
    </form>
    """

@app.route('/result')
def result():
    birth_year = request.args.get('birth_year')
    if not birth_year or not birth_year.isdigit():
        return "Ошибка: введи корректный год рождения!"
    
    birth_year = int(birth_year)
    age_in_2026 = 2026 - birth_year
    return f"""
    <h2>Результат: 🎇</h2>
    <p>В 2026 году тебе будет {age_in_2026} лет!</p>
    <p>Счастливого Нового 2026 года! Пусть все твои желания сбудутся!</p>
    <a href="/">Играть снова</a>
    """

if __name__ == '__main__':
    app.run(host='0.0.0.0', port=5000)

Подготовка к деплою

Чтобы Dokku понял, как запускать это чудо, нужны два файла в корне проекта:

`requirements.txt` (зависимости):

Flask==2.3.2
gunicorn==20.1.0
Werkzeug==2.3.3

`Procfile` (команда запуска):

web: gunicorn app:app --bind 0.0.0.0:5000

`.python-version` (опционально, явная версия Python):

3.11.14

Процесс деплоя

Все делается через Git, как на “взрослых” платформах:

Создаем приложение на сервере:

ssh dokku@dokku.datahub.mother apps:create my-first-app

Отправляем код:

git init
    git add .
    git commit -m "Happy New Year 2026 version"
    git remote add dokku dokku@dokku.datahub.mother:my-first-app
    git push dokku master

Если вы до этого еще что-то деплоили, то лучше проверить куда гит смотрит

git remote -v

ну и поменяем еще не верное

git remote remove dokku

git init
    git add .
    git commit -m "Happy New Year 2026 version"
    git remote add dokku dokku@dokku.datahub.mother:my-first-app
    git push dokku master

После пуша Dokku сам скачает Python, установит Flask и запустит Gunicorn. Через минуту-две приложение доступно по адресу `http://my-first-app.dokku.datahub.mother`.

Еще нужно домен установить

ssh dokku@dokku.datahub.mother domains:set my-first-app my-first-app.dokku.datahub.mother

или можно сразу глобально его установить:

ssh dokku@dokku.datahub.mother domains:set-global dokku.datahub.mother
# но тогда придется удалить ручную привязку 
ssh dokku@dokku.datahub.mother domains:clear my-first-app

# не забыть перебрать nginx ( на всякий случай ) 
ssh dokku@dokku.datahub.mother proxy:build-config my-first-app

Сертификат сгенерировать

ssh dokku@dokku.datahub.mother certs:generate my-first-app my-first-app.dokku.datahub.mother

и проверить порты

ssh dokku@dokku.datahub.mother ports:report my-first-app

если порты не корректные, то можно их установить так:

ssh dokku@dokku.datahub.mother ports:set my-first-app http:80:5000 https:443:5000

Часть 3. Уровень PRO: Скорость (uv) и Marimo

Аппетит приходит во время еды. После простого Flask-приложения я решил развернуть что-то посерьезнее — Data Science ноутбук на Marimo, и столкнулся с реальными сложностями и особенностями. Для примера брал их дело ноутбук https://marimo.app

1. Ускорение сборки с `uv`

Стандартный `pip` устанавливает пакеты медленно. Если проект большой, деплой может висеть минутами.
Я перешел на uv — новый менеджер пакетов на Rust.

Вместо `requirements.txt` я использовал `pyproject.toml` и `uv.lock`. Dokku (благодаря современным buildpacks) увидел `uv.lock` и переключился на быстрый режим. Время сборки сократилось в разы.

2. Ловушка масштабирования (Scaling)

Marimo — это stateful приложение (хранит состояние в памяти). Flask, который мы делали выше — stateless.

Когда я задеплоил Marimo, Dokku по умолчанию все было хорошо, но потом я решил масштабировать его и сделал так

ssh dokku@dokku.datahub.mother ps:scale my-marimo-app web=3

далее Dokku запустил 3 копии контейнера (`web=3`).
Начался хаос:

Интерфейс открывался.
При нажатии кнопок вылетала ошибка `Invalid server token`.

Почему? Браузер загружал страницу с *Контейнера 1*, а WebSocket-запрос улетал в *Контейнер 2*, который ничего не знал про мою сессию.

Решение:
Для интерактивных приложений (Streamlit, Marimo, Jupyter) всегда принудительно ставьте одну реплику:
Ну ли придется делать липкие сессии на nginx или еще что-то.

ssh dokku.datahub.mother ps:scale my-marimo-app web=1 # все вернуло в рабочее состояние.

А если не хватает мощности — лучше дайте этому единственному контейнеру больше ресурсов, чем пытаться плодить клонов или дайте каждому запускать свой:

Вот так можно установить лимиты или повысить их:

ssh dokku.datahub.mother resource:limit my-marimo-app --memory 2G --cpu 2

3. SSL в локальной сети

Браузеры блокируют микрофон и иногда WebSockets на HTTP-сайтах. Для локальной сети Let’s Encrypt не сработает (нет публичного IP), ну и его чуть сложнее запускать.
Я решил вопрос генерацией самоподписанного сертификата одной командой Dokku:

ssh dokku.datahub.mother certs:generate my-first-app my-first-app.dokku.datahub.mother

Браузер ругается, но приложение работает полноценно.

Еще я прогнал стресс тесты

ab -n 10000 -k -c 2000 ...

Много они не показали, решением было подкрутить nginx, настроить кеш ssl, горизонтальное масштабирование не приносило больших результатов. я упирался в ограничения клиента при тестах нагрузки.

Итог

Dokku на домашнем сервере — это отличный инструмент.

Для простых API (Flask/FastAPI): Работает “из коробки” идеально.
Для сложных задач: Использование `uv` делает работу комфортной, а понимание разницы между *Stateless* и *Stateful* приложениями спасает от занудных ошибок и отладки.

Теперь my-first-app готово предсказывать возраст всем гостям на Новый год, а сервер готов к новым экспериментам! 🎄 Пожалуй оставлю его для будущих экспериментов. Прижился как-то быстро. Кстати у Dokku есть коммерческая PRO версия, а точнее не версия, а полноценный UI с кнопочками и стоит он 900$. https://dokku.com/docs/enterprise/pro/

Пора чего-нибудь накатить новогоднего еще :)

KubeVela: Современная доставка приложений

Mon, 08 Dec 2025 01:10:10 +0300

В мире Cloud-Native технологий Kubernetes стал операционной системой облака. Однако, как было отмечено в материалах про Rainbond, «ванильный» Kubernetes сложен для разработчиков. Если Rainbond решает эту проблему, предлагая готовый PaaS «из коробки» с упором на UI, то KubeVela подходит к задаче с другой стороны: это двигатель для построения собственной платформы (Platform Engine), основанный на модели OAM (Open Application Model).

https://kubevela.io

KubeVela позволяет создавать простые и ориентированные на приложение (Application-centric) абстракции, сохраняя при этом полную гибкость и управляемость через код (Infrastructure as Code).

Основная философия: OAM и разделение ответственности

В основе KubeVela лежит стандарт OAM (Open Application Model). Эта модель разделяет ответственность между двумя ролями:

Разработчиĸи (Developers): Описывают что нужно запустить (образ контейнера, порт, параметры запуска).
Платформенные инженеры (Platform Engineers): Описывают ĸаĸ это должно работать (инфраструктура, политики масштабирования, Ingress, безопасность).

Математически модель приложения в KubeVela можно выразить формулой:

$$ Application = Components + Traits + Workflow $$

Где:

Components: Основная рабочая нагрузка (Workload). Например, Docker-образ, Helm-чарт или даже Terraform-модуль.
Traits (Свойства/Черты): Операционные характеристики, подключаемые к компоненту. Например: `ingress`, `scaler`, `sidecar`.
Workflow: Цепочка шагов доставки (Deploy -> Test -> Promote).

Пример манифеста KubeVela

Вместо десятков Kubernetes-ресурсов (Deployment, Service, Ingress, HPA), разработчик пишет один упрощенный файл:

apiVersion: core.oam.dev/v1beta1
kind: Application
metadata:
  name: website
spec:
  components:
    - name: frontend
      type: webservice
      properties:
        image: nginx
      traits:
        - type: scaler
          properties:
            replicas: 3
        - type: gateway
          properties:
            domain: test.example.com

Сравнение: KubeVela vs Rainbond

Основываясь на прошлой статье про Rainbond, сделаем детальное сравнение. Оба инструмента решают проблему сложности Kubernetes, но нацелены на разные аудитории.

Хараĸтеристиĸа	Rainbond	KubeVela
Философия	No-Code / Low-Code PaaS. Готовая платформа с полным UI. Ориентация на визуальное управление.	Platform Engine / IaC. Инструментарий для создания платформы. Ориентация на GitOps и конфигурацию как код.
Входной порог	Очень низкий. Не нужно знать Kubernetes. Можно собрать приложение из `.jar` или исходного кода одной кнопкой.	Средний. Требует понимания концепций OAM. Инженерам платформы нужно знать CUE (язык конфигурации).
Гибĸость	Ограничена возможностями UI платформы. Сложно кастомизировать внутреннюю логику деплоя нестандартных вещей.	Высочайшая. Любая абстракция настраивается через X-Definitions (на языке CUE). Можно описать любой ресурс K8s или Terraform.
Интеграция IaC	Базируется на внутренних механизмах.	Нативная интеграция с Terraform. KubeVela может разворачивать облачные базы данных (AWS RDS, Cloud SQL) как часть приложения.
Multi-cluster	Есть управление несколькими кластерами, но фокус на единой панели управления.	Сильная сторона. Мощный движок развертывания приложений сразу в несколько кластеров с политиками (Placement Policies).
Для ĸого	SMB, стартапы, команды без сильной экспертизы в K8s, желающие получить опыт Heroku на своих серверах.	Enterprise, Platform Engineering команды, желающие построить свой внутренний PaaS (IDP) по стандартам Spotify/Netflix.

Сравнение с другими аналогами

Crossplane:
- Crossplane фокусируется на «Инфраструктуре» (создание баз данных, кластеров, сетей в облаках через K8s API).
- KubeVela фокусируется на «Приложении».
- Итог: Они часто используются вместе. KubeVela использует Crossplane для заказа ресурсов.

ArgoCD / Flux (GitOps):
- Это инструменты непрерывной доставки (CD), которые синхронизируют Git и K8s.
- KubeVela может использовать их под капотом или использовать свой собственный Workflow-контроллер для сложных сценариев (например, «засуспендить деплой, пока не пройдет тест, затем отправить уведомление в Slack»).

Backstage:
- Backstage — это «Портал» (Frontend). KubeVela — это «Движок» (Backend).
- Существует плагин `vela-backstage`, который позволяет визуализировать приложения KubeVela внутри интерфейса Backstage. Это идеальная связка для построения IDP.

Ключевые возможности KubeVela

1. Программируемая абстраĸция (CUE Language)

В отличие от Helm, где шаблонизация — это просто подстановка строк, KubeVela использует язык CUE (Configure Unify Execute). Это позволяет платформенным инженерам создавать «умные» шаблоны.

Пример логики на CUE внутри KubeVela: «Если пользователь не указал CPU, автоматически поставить `requests: 100m`, но если это ‘prod’ окружение, то поставить `500m`».

2. Единый Workflow для всего

KubeVela позволяет оркестрировать не только Kubernetes-ресурсы. В одном пайплайне вы можете:

Создать S3 бакет в AWS (через Terraform/Crossplane).
Дождаться готовности.
Задеплоить Deployment в Kubernetes.
Отправить уведомление в Telegram.

3. Отсуствие «Config Drift»

KubeVela активно борется с дрейфом конфигураций, постоянно сверяя желаемое состояние приложения с реальным (State Reconciliation).

Итог и реĸомендации

Выбор между Rainbond и KubeVela зависит от того, ĸто будет обслуживать платформу и ĸаĸие цели стоят перед бизнесом.

Выбирайте Rainbond, если:

У вас небольшая или средняя команда разработчиков.
Нет выделенного отдела Platform Engineering / DevOps.
Нужно «вчера» перенести легаси (Java/PHP/Monolith) в контейнеры без переписывания кода.
Вам нужен визуальный интерфейс для управления связями сервисов и мониторинга без написания YAML.
Цель: Быстрый Time-to-market с минимальными затратами на инженерию.

Выбирайте KubeVela, если:

Вы строите серьезный Internal Developer Platform (IDP) в крупной компании.
У вас есть инженеры, знающие Kubernetes, но вы хотите скрыть его сложность от продуктовых разработчиков.
Вам нужен строгий GitOps подход (все через репозиторий).
Требуется гибридное развертывание: часть в K8s, часть в Serverless, часть в облачных RDS.
Вы планируете использовать Backstage в качестве фронтенда.
Цель: Стандартизация, масштабируемость, полный контроль над абстракциями (Platform as Product).

Рекомендация по стеĸу для Enterprise:
Для максимальной эффективности современный стек платформенной инженерии часто выглядит так:
$$ \text{Backstage (UI)} + \text{KubeVela (Engine)} + \text{Crossplane (Infra)} $$
Эта связка дает удобство портала (как в Rainbond), мощь оркестрации (KubeVela) и управление облаком (Crossplane).