К содержимому

OxL Справочник OxL

Версия

РусскийEnglish

12.1 Объявление кластера

oxl

cluster shop {
  seeds k8s(label: "app=shop")             // dns("…"), static["10.0.0.1:7000", …]
  port 7000
  auth { jwt(issuer: AUTH_ISSUER) }

  defaults {
    timeout STD_TIMEOUT
    idempotency_ttl IDEMPOTENCY_TTL
    topic_retention TOPIC_RETENTION
    drain DRAIN_TIMEOUT
  }

  role api     { serves Users, Orders; hosts Cart; replicas 3..10; expose 443 tls(acme: PUBLIC_DOMAIN) }
  role gpu     { serves Thumbs; needs label("gpu=true") }
  role storage { journal; shards 64; replication 3 }
  role saga    { runs sagas }

  assign by env("OXL_ROLE") else label("oxl/role") else auto
}

Предложение	Значение
`seeds`	способ найти узлы кластера
`port`	порт межузлового протокола (по умолчанию 7000)
`auth`	провайдеры аутентификации пользователей (§13.2)
`defaults`	значения по умолчанию для rpc и рантайма: `timeout`, `idempotency_ttl`, `topic_retention`, `drain`, `db_tx_retries`, `db_tx_retry_budget` (неизвестный ключ — ошибка со списком допустимых; D-8064; D-7780)
`trace_sample r`	доля запросов (`0.0..=1.0`), трассируемых по умолчанию; флаг процесса `--trace-sample` / переменная `OXL_TRACE_SAMPLE` переопределяет
`role имя { … }`	роль узла
`serves S, …`	роль обслуживает сервисы (топикам нужна только роль с journal)
`hosts A, …`	роль размещает шардированные акторы
`runs sagas` / `runs leader("имя")`	роль выполняет саги / задачи-лидеры
`journal`, `shards n`, `replication k`	роль хранит встроенное хранилище
`replicas a..b`	желаемое число узлов роли
`needs …`	требования к узлу (метки, ресурсы)
`expose порт tls(…)`	внешний слушатель gRPC + HTTP/JSON; routes(r) добавляет свои HTTP-маршруты (II.4)
`assign by …`	порядок определения роли узла

Определяется реализацией. Источники seed-узлов (D-8055; DIV-023; D-4259). Необязательная возможность: seeds k8s(label: …). Эта реализация не разрешает k8s(…); работают static[…] и локальный кластер oxl dev.

Определяется реализацией. Размещение по ресурсам (D-8055; DIV-016; D-4601, D-4899). Эта реализация не учитывает ресурсы needs cpu/mem/gpu; needs label(…) участвует в назначении ролей; hosts не управляет размещением шардов (его проверяет только компилятор: актор размещён хотя бы одной ролью).

В программе не больше одного cluster. Без него узел получает неявную роль all, обслуживающую всё, со встроенным хранилищем в режиме одного узла.
Проверки при сборке (ошибка компиляции): каждый сервис с impl обслуживается хотя бы одной ролью; каждый шардированный актор размещён; топики и саги имеют роль с journal и runs sagas; каждая роль в on роль пайплайна существует.
Узел МОЖЕТ иметь несколько ролей: OXL_ROLE=api,saga.

actor-not-hosted, cluster-auth, cluster-decl, cluster-needs, cluster-seeds, placement-conflict, saga-without-role, service-not-served, topic-without-journal, unknown-role

См. также

Исходник: docs/spec/oxl-standard.md