Развёртывание
nxs-anomaly — Go-бинарник, работающий с PostgreSQL. Может запускаться как единый процесс со встроенным планировщиком или как раздельные API и worker-процессы.
Production-конфигурация рекомендует раздельные компоненты:
- API:
nxs-anomaly serve --no-scheduler(несколько реплик) - Worker:
nxs-anomaly run-worker --poll-interval 5(несколько реплик безопасны: доставка/ретраи — атомарный claim, эскалация шардируется по интеграции)
Оба компонента используют одну БД и одни встроенные миграции.
Доменная модель и жизненные циклы сущностей описаны в DOMAIN_MODEL.md. Это полезно при настройке retention, алертов на метрики и дашбордов по таблицам PostgreSQL.
Контейнерный образ
Именование артефактов релиза
Одно правило на все артефакты: <продукт>[-компонент]-<издание>, издание всегда последним сегментом. Отсюда:
| Артефакт | Community | Enterprise |
|---|---|---|
| Бэкенд | nxs-anomaly | nxs-anomaly-enterprise |
| Фронтенд | nxs-anomaly-frontend | nxs-anomaly-frontend-enterprise |
| Helm chart | nxs-anomaly | nxs-anomaly-enterprise |
Community публикуется в GHCR, enterprise — в приватный реестр по учётной записи, выдаваемой на инсталляцию. Тег у всех один и тот же: vX.Y.Z, он же appVersion чарта, поэтому image.tag в values можно не задавать.
Образ фронтенда собирается отдельно под каждое издание, хотя его исходники одинаковы: интерфейс не содержит кода, зависящего от издания, — он спрашивает сервер через /api/v1/auth/methods и /api/v1/capabilities. Дублирование принято сознательно, чтобы не заставлять читателя манифеста помнить, что один артефакт из трёх живёт по другому правилу.
Имя чарта не попадает в имена объектов: values.yaml фиксирует nameOverride, поэтому оба издания рендерят одинаковые имена и одинаковые селекторы Deployment. Это и делает переход между изданиями обычным helm upgrade — селектор менять нельзя, и без этой фиксации переход был бы переустановкой с потерей PVC.
Сборка
RELEASE_TAG="v$(cat VERSION)"
docker build --build-arg VERSION="$RELEASE_TAG" \
-t "nxs-anomaly-local:$RELEASE_TAG" .Версия передаётся в бинарник через Dockerfile:
ARG VERSION=dev
RUN CGO_ENABLED=0 GOOS=linux go build -mod=vendor -trimpath \
-ldflags="-s -w -X github.com/nixys/nxs-anomaly/internal/server.Version=${VERSION}" \
-o /out/nxs-anomaly ./cmd/nxs-anomalyПосле этого /health возвращает переданную версию в поле version.
Характеристики образа:
- многоэтапная сборка,
CGO_ENABLED=0; - runtime-слой:
gcr.io/distroless/static-debian12:nonroot; - зависимости берутся из
vendor/(-mod=vendor); - Docker HEALTHCHECK через
nxs-anomaly healthcheck; - порт
8080.
PostgreSQL
Создать базу и пользователя:
CREATE USER nxs_anomaly WITH PASSWORD 'change-me';
CREATE DATABASE nxs_anomaly OWNER nxs_anomaly;Задать DSN:
NXS_ANOMALY_DB_DSN='postgres://nxs_anomaly:change-me@postgres:5432/nxs_anomaly?sslmode=disable'Миграции применяются автоматически при старте. Подробности — MIGRATIONS.md.
Kubernetes
Helm chart (рекомендуемый способ)
Официальный чарт — deploy/helm/nxs-anomaly (см. его README). Разворачивает API, worker и frontend; хранилища — встроенные (*.enabled, single-node для dev/test) или внешние (external*). Секреты — из существующего Secret (existingSecret), External Secrets (externalSecrets) или Vault Secrets Operator (vaultSecretOperator); inline — только для dev. Есть PDB, NetworkPolicy, topologySpread, ServiceMonitor и PrometheusRule. Внешний трафик можно опубликовать через обычный Ingress, Istio VirtualService/Gateway или Kubernetes Gateway API HTTPRoute/Gateway; все три механизма выключены по умолчанию и независимы.
# Production: external PostgreSQL and an operator-managed Secret
kubectl create secret generic nxs-anomaly-env \
--from-literal=NXS_ANOMALY_DB_DSN='postgres://user:pass@pg.prod:5432/nxs_anomaly?sslmode=require'
helm install nxs-anomaly deploy/helm/nxs-anomaly \
--set existingSecret.enabled=true --set existingSecret.name=nxs-anomaly-env \
--set inlineSecret.enabled=false --set postgresql.enabled=false \
--set ingress.enabled=true --set ingress.host=nxs-anomaly.example.comПроверки чарта: helm lint, helm unittest -f 'tests/unit/*_test.yaml' и реальный install/upgrade smoke в kind — deploy/helm/nxs-anomaly/tests/e2e/kind-smoke.sh .
Ручные YAML-манифесты ниже описывают то же «под капотом» — для окружений без Helm или для понимания того, что рендерит чарт.
Ручные YAML ниже показывают структуру, а не полную установку. Замените REPLACE_WITH_RELEASE_TAG одной и той же опубликованной версией API и worker. Фронтенд, учётные данные, TLS и полные команды развёртывания описаны в Установка.
Приватный CA для исходящего TLS
Внутренний приёмник webhook или чат-шлюз с сертификатом от корпоративного или кластерного CA падает с x509: certificate signed by unknown authority, а в distroless-образ CA во время работы не добавить. Укажите чарту существующий ConfigMap или Secret с PEM-bundle — цель Bundle от cert-manager trust-manager подходит как есть:
customCA:
configMapName: corp-trust-bundle # or secretName: …, not both
key: trust-bundle.pem # default ca.crtBundle монтируется в поды API и worker, а SSL_CERT_DIR перечисляет его рядом с /etc/ssl/certs, так что CA становится доверенным в дополнение к корням образа — публичные провайдеры продолжают проверяться. Это касается любого исходящего TLS бинаря: webhook, ChatOps, HTTPS-прокси, SMTP со STARTTLS, внешнего PostgreSQL. Bundle читается один раз за жизнь процесса, поэтому после его изменения перезапустите поды (kubectl rollout restart) или поручите это reloader-у. Собственный SSL_CERT_DIR в api.extraEnv/worker.extraEnv имеет приоритет.
Получатель внутри кластера — это ещё и приватный адрес, который SSRF-гейт (в чарте включён) отвергает; пропустите его по имени через config.NXS_ANOMALY_BLOCK_PRIVATE_WEBHOOKS_EXCEPT, а не выключайте гейт — см. SECURITY_PROFILE.md.
Для всего остального, что поду нужно на диске, есть api.extraVolumes/api.extraVolumeMounts и worker.extraVolumes/worker.extraVolumeMounts — тома передаются как написаны.
Секреты
kubectl create namespace nxs-anomaly
kubectl -n nxs-anomaly create secret generic nxs-anomaly-config \
--from-literal=NXS_ANOMALY_DB_DSN='postgres://nxs_anomaly:change-me@postgres.nxs-anomaly.svc.cluster.local:5432/nxs_anomaly?sslmode=disable' \
--from-literal=NXS_ANOMALY_API_KEY='<a random key>'Секреты провайдеров (опционально, можно в тот же Secret или отдельный):
kubectl -n nxs-anomaly create secret generic nxs-anomaly-providers \
--from-literal=NXS_ANOMALY_TELEGRAM_BOT_TOKEN='<token>' \
--from-literal=NXS_ANOMALY_SMTP_HOST='smtp.example.com' \
--from-literal=NXS_ANOMALY_SMTP_USERNAME='alerts@example.com' \
--from-literal=NXS_ANOMALY_SMTP_PASSWORD='<password>'Deployment: API
apiVersion: apps/v1
kind: Deployment
metadata:
name: nxs-anomaly-api
namespace: nxs-anomaly
spec:
replicas: 2
selector:
matchLabels:
app: nxs-anomaly-api
template:
metadata:
labels:
app: nxs-anomaly-api
spec:
containers:
- name: api
image: ghcr.io/nixys/nxs-anomaly:REPLACE_WITH_RELEASE_TAG
args: ["serve", "--host", "0.0.0.0", "--port", "8080", "--no-scheduler"]
ports:
- name: http
containerPort: 8080
envFrom:
- secretRef:
name: nxs-anomaly-config
- secretRef:
name: nxs-anomaly-providers
optional: true
startupProbe:
httpGet:
path: /live # /live answers from the first second, while the DB and migrations are awaited
port: http
periodSeconds: 2
failureThreshold: 30
readinessProbe:
httpGet:
path: /health # includes a DB ping; the pod leaves the Service if the DB is down
port: http
periodSeconds: 10
livenessProbe:
httpGet:
path: /live # cheap, never touches the DB — a DB blip will not restart the pod
port: http
periodSeconds: 20
securityContext:
allowPrivilegeEscalation: false
runAsNonRoot: true
readOnlyRootFilesystem: true
capabilities:
drop: ["ALL"]Deployment: Worker
apiVersion: apps/v1
kind: Deployment
metadata:
name: nxs-anomaly-worker
namespace: nxs-anomaly
spec:
replicas: 1
selector:
matchLabels:
app: nxs-anomaly-worker
template:
metadata:
labels:
app: nxs-anomaly-worker
spec:
containers:
- name: worker
image: ghcr.io/nixys/nxs-anomaly:REPLACE_WITH_RELEASE_TAG
args: ["run-worker", "--poll-interval", "5"]
ports:
- name: telemetry
containerPort: 8081 # /live, /ready, /metrics — NXS_ANOMALY_WORKER_ADDR
envFrom:
- secretRef:
name: nxs-anomaly-config
- secretRef:
name: nxs-anomaly-providers
optional: true
startupProbe:
httpGet:
path: /live
port: telemetry
periodSeconds: 2
failureThreshold: 30
readinessProbe:
httpGet:
path: /ready # the DB is reachable AND cycles are completing
port: telemetry
initialDelaySeconds: 5
periodSeconds: 10
livenessProbe:
httpGet:
path: /live # cheap, never touches the DB
port: telemetry
initialDelaySeconds: 5
periodSeconds: 10
securityContext:
allowPrivilegeEscalation: false
runAsNonRoot: true
readOnlyRootFilesystem: true
capabilities:
drop: ["ALL"]Отдельный run-worker поднимает собственный телеметрийный HTTP-эндпоинт (по умолчанию :8081, см. NXS_ANOMALY_WORKER_ADDR): /live, /ready, /metrics. Это закрывает слепое пятно наблюдаемости — раньше при схеме serve --no-scheduler
run-workerdelivery-метрики (латентность доставки, dead-letter, breaker, skipped/shift, coverage) не экспонировались вовсе, потому что реестр Prometheus жил только в HTTP-сервере API./readyотражает не только доступность БД, но и то, что worker реально завершает циклы: зависший цикл (застрявший запрос, дедлок) выводит реплику из readiness. Порог простоя —NXS_ANOMALY_WORKER_STALL_TIMEOUT_SECONDS(по умолчаниюmax(30s, 4×poll)).
Несколько реплик worker'а безопасны. Доставка и ретраи выбираются атомарным claim (SELECT … FOR UPDATE SKIP LOCKED, уникальный worker_id на процесс), эскалация шардируется по интеграции через per-shard advisory-локи, а брошенные claim-ы реклеймятся (ReclaimStaleClaims). Отсутствие двойной доставки под конкуренцией подтверждено TestMultiWorkerNoDoubleDelivery и профилями worker_kill/retry_storm нагрузочного harness (см. CAPACITY.md). Конкуренция — не то же, что крах: реплика, убитая между отправкой провайдеру и сохранением, отдаёт claim реапперу, и уведомление уходит второй раз. Это at-least-once, гарантия здесь именно такая, и harness сверяет дубли с числом реклеймов, а не с нулём. Единственная реплика лишь упрощает порядок событий, но не является требованием корректности.
При SIGTERM worker не стартует новые циклы, даёт текущему RunWorkerCycle завершиться и штатно гасит телеметрийный HTTP-сервер. API-сервер при shutdown останавливает приём новых HTTP-запросов через http.Server.Shutdown и также ждёт встроенный scheduler, если он включён.
Service
apiVersion: v1
kind: Service
metadata:
name: nxs-anomaly-api
namespace: nxs-anomaly
spec:
selector:
app: nxs-anomaly-api
ports:
- name: http
port: 8080
targetPort: httpОткрыть через ingress-контроллер. Источники webhook-алертов нуждаются в доступе к /integrations/v1/*.
Метрики
Prometheus scrape endpoint:
GET /metricsМетрики реализованы через prometheus/client_golang SDK (кастомный registry на инстанс сервера):
| Метрика | Тип | Описание |
|---|---|---|
nxs_anomaly_alerts_ingested_total | counter | Всего принятых алертов |
nxs_anomaly_alert_groups_open | gauge | Открытые группы (из БД при каждом scrape) |
nxs_anomaly_notifications_delivered_total | counter | Всего доставленных уведомлений |
nxs_anomaly_notifications_failed_total | counter | Всего провалившихся уведомлений |
nxs_anomaly_schedules_degraded | gauge | Расписания с пробелами/выключенные/с несуществующими участниками, через которые ходит escalation chain без allow_uncovered |
nxs_anomaly_schedules_total | gauge | Всего расписаний |
nxs_anomaly_sources_silent | gauge | Интеграции с объявленным heartbeat, не приславшие ничего в срок. Молчание источника снаружи неотличимо от здоровья |
nxs_anomaly_duty_on_call | gauge | Сколько человек расписания ставят на дежурство прямо сейчас |
nxs_anomaly_duty_without_checkin | gauge | Из них не подтвердили смену. Покрытие отвечает «назначен ли кто-то», эта метрика — «ответил ли он» |
nxs_anomaly_shift_notifications_total | counter | Уведомления о начале смены дежурства |
nxs_anomaly_notifications_skipped_total | counter | Уведомления без транспорта (channel, reason); никогда не считаются доставленными |
nxs_anomaly_retention_deleted_total | counter | Строки, удалённые retention-свипом (category). Категория с заданным сроком и плоским счётчиком — свип, который перестал работать. См. DATA_INVENTORY.md |
nxs_anomaly_notifications_retry_queue_depth | gauge | Уведомлений в retry-очереди (из БД) |
nxs_anomaly_notification_batches_pending | gauge | Открытых пакетов (из БД) |
nxs_anomaly_groups_archived_total | counter | Архивированных resolved-групп |
nxs_anomaly_worker_cycles_total | counter | Завершённых worker-циклов |
nxs_anomaly_worker_cycle_duration_seconds | gauge | Длительность последнего цикла |
nxs_anomaly_worker_last_cycle_timestamp_seconds | gauge | Unix-время последнего цикла (для детекта простоя: time() - метрика; НЕ путать с duration) |
nxs_anomaly_db_up | gauge | 1 если последний ping БД прошёл, иначе 0 |
nxs_anomaly_notifications_delivered_by_provider_total | counter | Успешные доставки по каналу (provider); в паре с _delivery_errors_by_provider_total даёт per-provider success-ratio SLI |
nxs_anomaly_oldest_due_escalation_age_seconds | gauge | Возраст самой старой просроченной группы |
nxs_anomaly_oldest_pending_delivery_age_seconds | gauge | Возраст самого старого delivery_scheduled |
nxs_anomaly_stale_claims_reclaimed_total | counter | Реклейм брошенных claim-ов (краш worker'а/короткий claim-timeout) |
nxs_anomaly_worker_cycles_skipped_total | counter | Пропущенные циклы (предыдущий ещё выполнялся) — сигнал, что worker не успевает |
nxs_anomaly_worker_cycle_stage_duration_seconds | histogram | Латентность стадии worker-цикла (stage) |
nxs_anomaly_worker_panics_total | counter | Паники, восстановленные в worker-goroutine'ах, по стадии (stage) |
nxs_anomaly_ingest_duration_seconds | histogram | Латентность приёма по источнику (source) |
nxs_anomaly_ingest_errors_total | counter | Ошибки приёма по источнику (source) |
nxs_anomaly_http_request_duration_seconds | histogram | Латентность HTTP по категории (handler) |
nxs_anomaly_http_requests_total | counter | HTTP-запросы по категории и коду (handler, code) |
nxs_anomaly_http_panics_recovered_total | counter | Восстановленные паники в HTTP-хендлерах |
nxs_anomaly_delivery_errors_by_provider_total | counter | Ошибки доставки по каналу (provider) |
nxs_anomaly_notification_delivery_duration_seconds | histogram | Латентность вызова провайдера по каналу (channel) |
nxs_anomaly_dead_letter_events_total | counter | Уведомления, ставшие permanently failed, по каналу (channel) |
nxs_anomaly_delivery_short_circuited_total | counter | Доставки, пропущенные открытым circuit breaker, по каналу (channel) |
nxs_anomaly_db_pool_acquired_conns | gauge | Соединений, занятых из пула прямо сейчас |
nxs_anomaly_db_pool_idle_conns | gauge | Простаивающих соединений в пуле |
nxs_anomaly_db_pool_total_conns | gauge | Всего соединений в пуле |
nxs_anomaly_db_pool_max_conns | gauge | Максимум соединений пула (NXS_ANOMALY_DB_POOL_MAX) |
nxs_anomaly_db_pool_empty_acquire_total | counter | Запросы соединения, ждавшие из-за исчерпания пула (рост = пул мал или база не успевает) |
И worker, и API экспонируют один и тот же набор — worker на своём порту (:8081 по умолчанию). Delivery-метрики производит worker, поэтому при разнесённой схеме скрейпить нужно оба таргета.
scrape_configs:
- job_name: nxs-anomaly-api
static_configs:
- targets: ['nxs-anomaly-api.nxs-anomaly.svc.cluster.local:8080']
- job_name: nxs-anomaly-worker
static_configs:
- targets: ['nxs-anomaly-worker.nxs-anomaly.svc.cluster.local:8081']Полный набор алертов (PrometheusRule), дашборд Grafana, определения SLI/SLO и нагрузочно-хаос envelope:
- ALERTING_RULES.md — правила и SLI/SLO с PromQL;
- prometheus-rules.yaml — готовый
PrometheusRuleCRD; - grafana-dashboard.json — импортируемый дашборд;
- CAPACITY.md — профили нагрузки, сценарии сбоев, capacity envelope.
Аутентификация API
Для людей используйте парольные сессии в HttpOnly cookie, для автоматизации — явно scoped API keys. Legacy NXS_ANOMALY_API_KEY всегда admin; записи NXS_ANOMALY_API_KEYS должны иметь роль (token:viewer, token:editor, …). Ключ передаётся одним из заголовков:
X-API-Key: <key>
Authorization: Bearer <key>Webhook-эндпоинты аутентифицируются по ключу интеграции в URL. Дополнительная HMAC-валидация payload включается на уровне конкретной интеграции через поле webhook_secret.
Перед production rollout явно выберите retention и egress policy:
NXS_ANOMALY_TEAM_SCOPING=true|false— осознанная граница видимости;- четыре
*_RETENTION_DAYS— сроки аудита, уведомлений, attempts и сессий; NXS_ANOMALY_BLOCKED_CHANNELSиNXS_ANOMALY_EGRESS_ALLOWLIST— разрешённые каналы и назначения.
GET /api/v1/readiness показывает незакрытые решения. Полный перечень данных — DATA_INVENTORY.md, безопасные дефолты — SECURITY_PROFILE.md.
Порядок обновления
- Собрать и опубликовать новый образ.
- Проверить новые миграции в
internal/store/migrations/. - Сделать резервную копию БД.
- Развернуть один pod API или worker — миграции применятся ровно один раз (advisory lock
72544000). - Развернуть остальные поды API.
- Smoke-тест:
curl https://nxs-anomaly.example.com/health
curl https://nxs-anomaly.example.com/metricsПараллельный старт нескольких экземпляров безопасен — миграционный runner защищён advisory lock.