b601c4636f
feat(swagger): OAuth2/Keycloak PKCE flow в Swagger UI + docs links
...
OpenApiConfig:
- Добавлена OAuth2 security scheme (authorization_code flow с Keycloak
realm `nstart`). Auth/token URLs из ordinis.openapi.oauth.issuer-uri
configuration property (default: auth.nstart.space/realms/nstart).
- BearerAuth scheme сохранён secondary — для pre-issued tokens из CI/scripts.
- Servers list переупорядочен — prod первый, staging второй.
- Description обновлён с pointer на /docs/ для full integration guide.
application.yml:
- springdoc.swagger-ui.oauth: client-id (env override), use-pkce-with-
authorization-code-grant=true. Public client `ordinis-swagger`
настраивается отдельно в Keycloak — see keycloak-setup-swagger-client.md
в ordinis-infra repo.
- ORDINIS_OPENAPI_OAUTH_ISSUER_URI env var для override realm на разных
окружениях.
docs/integration/api/read-endpoints.md:
- Swagger UI section обновлён: акцент на Authorize button + Keycloak
PKCE login (no client_secret needed), tip про bearerAuth fallback.
docs/index.md:
- Добавлен tab "Я хочу пощупать API" с link на Swagger UI.
После deploy:
- https://ordinis.k8s.264.nstart.cloud/swagger-ui.html — Swagger UI
- https://ordinis.k8s.264.nstart.cloud/v3/api-docs — OpenAPI spec
Authorize → выбрать oauth2 → Keycloak login (PKCE) → Try it out с JWT.
2026-05-08 00:08:29 +03:00
cfe26a07a7
docs: Dockerfile + nginx + CI publish для deploy на ordinis.k8s.264.nstart.cloud/docs/
...
Multi-stage Dockerfile: yfm build (Node 20 alpine) → nginx 1.27 alpine
serving static HTML. Nginx config:
- /healthz endpoint для k8s probes
- /docs/ alias → /usr/share/nginx/html/ (Diplodoc делает relative links,
alias корректно работает без URL rewriting)
- Hash-named assets (_bundle/) — cache 1y immutable
- HTML pages — cache 5min must-revalidate
- /docs (без trailing slash) → 301 → /docs/
- Security headers (X-Content-Type-Options, X-Frame-Options, Referrer-Policy)
CI:
- build-docs (sanity check) — теперь только на non-main branches и MR
(для preview без push). Production build идёт через docker-docs.
- docker-docs (NEW) — multi-stage Dockerfile build + push в repo.nstart.cloud
через standard .docker_base + .publish_script pattern. Path-filtered на
docs/**, manual через web UI.
- resolve-tag: emit RESOLVED_DOCS_TAG (= IMAGE_TAG, тот же что для backend).
- trigger-deploy-{staging,prod}: pass DOCS_IMAGE_TAG в downstream pipeline.
Local verify:
cd docs && docker build -t ordinis-docs:test .
docker run --rm -p 18088:8080 ordinis-docs:test
curl localhost:18088/healthz → 200
curl -I localhost:18088/docs → 301 → /docs/
curl localhost:18088/docs/ → 200 index.html
curl localhost:18088/docs/integration/api/auth.html → 200
curl localhost:18088/docs/missing.html → 404
Соответствующие infra-side изменения (Helm chart docs deployment + Ingress
path /docs/, values, deploy script) — commit в ordinis-infra repo.
2026-05-07 23:44:03 +03:00
bcfb07f547
docs: split integrator guide (Diplodoc) vs internal docs + add build-docs CI
...
Чёткое разделение audiences:
- docs/ — consumer-facing only, Diplodoc-built. Public contract для
интеграторов (Альтум, BI, third-party).
- docs-internal/ — operator runbooks, status snapshots, legacy tech pages.
НЕ в Diplodoc build, НЕ публикуются.
Изменения:
- Move docs/{ops,status,tech} → docs-internal/{ops,status,tech}
- docs/toc.yaml: убраны секции Operations, Архитектура (legacy), Status
- docs/index.md: убран tab "оператор / on-call", focus на integrators
- docs/README.md: rewritten — scope только integrator guide, editorial
guidelines (no leak internal architecture, stable API contract)
- .yfm: убран явный ignore status/* (теперь не нужно — папка переехала)
- docs-internal/README.md: index для внутренней документации с rationale
разделения
Scrubbing implementation details из Diplodoc страниц:
- events.md: убраны Strimzi/cluster.142 references, OutboxPoller детали,
internal alert names (OrdinisOutboxLagHigh, OrdinisOutboxDLQNonEmpty),
metric names (nsi_outbox_*). Заменены на consumer-observable contract.
- webhooks.md: убраны metric names (nsi_webhook_ssrf_rejected_total),
alert table (OrdinisWebhookHighFailureRate и т.д.). Retry policy
переписана на user-side perspective.
- errors.md: убран alert name OrdinisReadApiErrorBudgetBurnFast, Tempo
endpoint URL, internal connection details.
- x-references.md: OrphanReferenceScanner → general "Ordinis периодически
детектирует". Убраны metric/alert names. Cascade roadmap без link на
internal design doc.
- auth.md: убран file path ScopeContext.java.
- bundle-cuod.md: убран Maven module path.
- caching.md: cascade design link заменён на text reference.
CI:
- .gitlab-ci.yml: новый job build-docs (stage: build) — Node 20 alpine,
pnpm install --frozen-lockfile + pnpm build, artifact docs/_dist на
неделю. Triggers: auto на docs/**, либо manual web. Готов к follow-up
pages-deploy job когда host решён.
- Новый pattern .docs-changes для rules.
Build verified clean: 13 HTML pages, 6.9M, no broken links/refs.
2026-05-07 23:27:03 +03:00
d5268b9395
docs: Diplodoc setup + полное руководство интеграции по API
...
Новая документация-as-code на платформе Diplodoc (Yandex open-source) с
YFM (Yandex Flavored Markdown). Build → static HTML, deployable куда угодно.
Что добавлено:
- package.json + .yfm + toc.yaml — Diplodoc setup, навигация для sidebar
- index.md — главная страница с tabs для разных audiences
- README.md — инструкция для contributors
Раздел integration/api/ — 11 страниц про интеграцию consumers:
- index — обзор + глоссарий
- auth — Keycloak service accounts, scope mapping
- read-endpoints — GET /dictionaries, list/by-key, spatial filters
- events — Kafka outbox топики, partition keys, idempotency, DLQ
- webhooks — HMAC, SSRF guard, retry policy, test ping endpoint
- bitemporal — validFrom/validTo + history, future-dated entries, bulk close/export
- x-references — FK syntax, validation errors, scope hiding, orphan scanner, v2 cascade preview
- caching — TTL / push / snapshot strategies, hybrid pattern
- errors — full error code reference (validation/auth/conflict/server), retry strategy
- best-practices — 33 numbered rules для consumers
- bundle-cuod — все 40 справочников с FK графом и сценариями
Обновлены:
- ops/README.md — link на новую integration/api/, убран inline <br>
- ops/slo.md — broken cross-repo links заменены на text references
Build:
cd docs && pnpm install && pnpm build
→ ./_dist (20 HTML files, 7.1M)
pnpm serve # → http://localhost:8088
CI deploy job для GitLab Pages — в roadmap (см. docs/README.md).
Существующий tech/api-integration.md оставлен в toc как legacy
(содержимое мигрировано + расширено в integration/api/).
2026-05-07 23:19:02 +03:00
0c79821f8e
docs(roadmap): merge lineage + FK cascade в единый epic с design draft
...
Объединил два отдельных backlog item'а (Lineage / dependency graph + Cross-
dictionary FK с cascade rules) в один epic "Dictionary relationships v2" —
они complementary halves: lineage = read-side (discovery), cascade = write-side
(close semantics). Operate over same FK metadata, удобнее spec'ить вместе.
Design DRAFT 318 строк / 15KB:
- 3 stakeholder pain points (data stewards, Альтум consumers, schema editors)
- IN scope: A (lineage discovery 4 endpoints+UI), B (cascade rules block/warn/cascade), C (cross-cutting outbox+SLO)
- OUT scope (defer): schema-time validation, graph viz, multi-hop, cross-bundle
- 3 architecture options per area + recommendation (A=in-memory+MV hybrid, B=sync для v2)
- 4 D-questions для plan-eng-review
- 3 pre-code assignment items (Альтум behavior, UX preference, bundle versioning)
- 4-phase implementation (3-5 нед CC total)
- 4 risks + mitigations
- Success criteria с конкретными SLO targets
2026-05-07 23:05:18 +03:00
e307c15e27
docs(status): mark KafkaTopic orphan fix applied + k6-tests ConfigMap created
...
- Section "В процессе": KafkaTopics READY=False теперь struck-through, applied
evening 2026-05-07 (все 3 topics annotated strimzi.io/managed=false, alerts
больше не срабатывают, projection-writer connected).
- Section 0.1 artifacts: topic-orphan-fix.sh — added "✅ applied" note inline.
- Section 0.1 artifacts: synthetic smoke pre-flight — отмечено что k6-tests
ConfigMap уже создан, остаётся k6-keycloak-creds Secret (Keycloak SA
client_secret) и apply CronJob + helm upgrade.
2026-05-07 23:01:25 +03:00
6046c5aef6
docs(status): v1.0.1 — post-cutover hardening + image arch incident postmortem
...
Evening update к v1.0:
- SPOF на staging registry CLOSED (postgis-barman mirrored в repo.nstart.cloud:18.3-3.6.2-2)
- Monitoring artifacts ready (k6 prod variant, synthetic smoke + CronJob, 2 alerts)
- KafkaTopics READY=False janitorial fix (script ready)
- CI build job на 401 known-issue (manual fallback)
Section 0.1 добавлена с подробным postmortem image arch incident:
1. arm64 image из mac M-series попал в registry без --platform
2. kubelet cache на node удерживал stale arm64 layer под тем же тегом
3. Pod stuck Terminating 14 мин (CNPG gracePeriod=1800s)
Lessons закреплены в docker/postgis-barman/README.md (anti-footgun).
2026-05-07 22:53:32 +03:00
f0f84b1baa
docs(status): v1.0 — production LIVE на cluster.142, Альтум переехал
...
Snapshot после Phase 1-5 production stand-up done:
- prod (cluster.142): LIVE, helm rev 22 на main-4252ad93, Альтум blue/green cutover завершён
- staging (cluster.265): теперь dev environment, не consumer-facing
- v0.9 → v1.0 anchor
Что задеплоено в prod (8 commits сегодня):
- bulk close + bulk export CSV
- audit URL persistence + chips
- pagination для records list (50/page)
- WebhookE2ETest re-enabled (no-op scheduler)
- 23 новых тестов
Operational artifacts (ordinis-infra):
- k8s/kafka/cluster-prod.yaml (Kafka recovery)
- scripts/vault/{setup,populate}.sh + README
Открытые items: KafkaTopics READY=False (orphaned),
postgis-barman image mirror в prod registry, k6 prod benchmark,
real ЦУОД data integration epic.
Approval workflow v2 deferred — design doc сохранён, re-evaluate
через 1-2 месяца после observed compliance needs.
2026-05-07 15:24:03 +03:00
81c959b7e2
docs(status): snapshot v0.9 (2026-05-06)
...
Закрыло за сутки: bundle 7→40 справочников, Альтум pull verified,
Tempo+Loki+Grafana+SLO burn rate alerts (Google SRE multi-window),
UI scope grouping + accents, INTERNAL словари visibility (rolesClaim),
CNPG 1.24→1.25.4 + spec.probes, CI helm --atomic + auto-rollback,
config-server startupProbe, 75→109 unit тестов.
Готовы к prod (manifests + runbooks): multi-instance Postgres HA,
external S3 backup, k6 benchmark setup. Block — DNS/cert prod,
S3 provider creds, real ЦУОД data.
Прогресс: 21/33 (v0.5) → 27/39 требований (v0.9). 1-2 недели до v1.
v0.5 файл оставлен как историческая запись.
2026-05-06 13:27:31 +03:00
bcedddef71
docs(ops): SLO/SLI definitions + error budget framework
...
7 SLI с конкретными порогами и justification:
- read-api availability (99.5% v1 target)
- read-api p99 latency < 500ms target / 1s alert
- writer 5xx error rate < 1%
- outbox publish lag (≤ 50 normal, alert > 100)
- outbox DLQ size = 0 strict
- outbox publish error rate ~0
- postgres availability (99.9% v1 target)
Error budget framework для 99.5% уровня (~216 мин/мес downtime).
Burn rate alerts — TODO.
Notification routing — TODO (Slack/Telegram per severity).
Что не покрывает v1: Grafana dashboards, distributed tracing, log
aggregation, capacity planning. См. observability stack roadmap для v2.
2026-05-05 20:32:37 +03:00
adc40aca22
docs(ops): operator runbook — kafka, outbox DLQ, db migrations + index
...
Карточки процедур для on-call. Self-contained: можно открыть в момент
инцидента без необходимости понимать всю архитектуру.
- README.md — index by symptom + быстрые гайды по 401, 500, admin-ui 502.
- kafka-restart.md — pause/unpause, replicas=0 fix, force-delete, restart
consumer'ов после Kafka up.
- outbox-dlq.md — диагностика DLQ через UI/API/SQL, типичные причины
(orphan topic, ACL, broken payload), replay через UPDATE dlq_at=NULL.
- db-migrations.md — Liquibase changelog, добавление, откат, recovery
failed migration через DELETE databasechangelog.
Vault unseal был отдельным коммитом ранее.
2026-05-05 17:26:30 +03:00
0fb20dc8d4
docs(ops): vault unseal runbook + auto-unseal migration plan
...
Triage card для on-call: где взять unseal-keys (1Password placeholder,
уточнить с DevOps lead), как запустить script либо ручную процедуру,
что проверить после, troubleshooting типовых проблем.
Также: §7 — план миграции на auto-unseal (Transit / Yandex KMS) когда
определимся с master Vault или KMS-backend.
2026-05-05 16:56:45 +03:00
2fc9b451e4
fix(cuod+docs): Resurs-P/Канопус/Метеор/Электро/Арктика в seed + правильный read-api путь
...
Альтум-команда обнаружила что /api/v1/dictionaries/{name}/records даёт 500
и spacecraft_codes ссылаются на несуществующий "RESURS-P-3". Оба бага мои:
1. Read-api живёт на /api/v1/{name}/records (БЕЗ /dictionaries/ префикса).
/dictionaries/* — это admin-write контроллер, у него GET-list нет.
Fix: docs/integration/altum-imaging-order.md + docs/tech/api-integration.md
обновлены с правильными URL'ами + примером ответа из live staging.
2. spacecraft seed имел только 4 КА (Terra, Sentinel-1A/2A, Кондор-ФКА),
а mission.spacecraft_codes ссылался на пустые/RESURS-P-3 — каскад в
"Заказ съёмки" не работал бы.
Fix: добавлено 10 российских КА (Ресурс-П 1-4, Канопус-В 1+5, Метеор-М 2+2-2,
Электро-Л 2, Арктика-М 1) с COSPAR designators как businessKey.
3. mission.records.json + instrument.records.json: spacecraft_codes теперь
ссылается на реально существующие COSPAR-ключи. Каскад работает:
instrument MSU-MR → spacecraft [2014-037A, 2019-038A] → Метеор-М № 2 / 2-2.
После redeploy и идемпотентного пересева:
spacecraft 14 (было 4, +10 РФ)
mission 9 (existing 9, references фиксированы)
instrument 11 (было 10, +МСУ-ГСМ Арктики)
2026-05-04 18:27:36 +03:00
930df5b888
feat(api): Swagger UI + docs/integration для Альтума и других consumer'ов
...
Springdoc-openapi генерирует OpenAPI 3 spec из аннотаций контроллеров —
интеграторам не нужно поддерживать markdown-ТЗ синхронно с кодом.
- /swagger-ui.html (UI), /v3/api-docs (JSON), /v3/api-docs.yaml.
- OpenApiConfig: title/description/contact/servers (staging+prod+local),
bearerAuth security scheme (Keycloak JWT).
- SecurityConfig: permitAll на swagger paths.
Документация:
- docs/integration/altum-imaging-order.md — ТЗ интеграции «Заказ съёмки».
Согласованы: m2m service account через Keycloak, BFF в altum-backend
(FastAPI), 4 справочника со схемами, cascading select через
instrument.supported_*_codes, snapshot strategy для аудита.
- docs/tech/api-integration.md — общий гайд для интеграторов: auth flow,
endpoints, кэш-стратегии, bitemporal модель, current dictionaries,
cross-refs, best practices.
Скрипты codegen openapi-generator-cli работают off /v3/api-docs.
2026-05-04 15:45:09 +03:00
Zimin A.N.