VictoriaTraces: Tracing, Observability та OpenTelemetry
5 (2)

19 Травня 2026

На проекті потроху доросли до того, що пора вже мати повноцінний трейсінг – аби побудувати реальний observability, а не просто моніторинг.

Колись давно робив аналогічне з Jaeger – монстр, і десь він так в чорнетках 2019 чи 2020 року і залишився, ну а так як зараз у нас весь стек VictoriaMetrics – сама VictoriaMetrics для метрик та VictoriaLogs для логів – то і для трейсів будемо використовувати рішення від команди VictoriaMetrics – VictoriaTraces.

Тим більш VictoriaTraces набагато легша як в ресурсах – так і в налаштуванні. Мабуть, можна порівняти Loki та VictoriaLogs та Jaeger з VictoriaTraces – аналогічно набагато простіший сетап, набагато менше ресурсів CPU/RAM.

Цей пост планувався першим в серії по traces – тому тут спочатку буде більше теорії по Observability та OpenTelemetry, а далі вже запустимо VictoriaTraces в Kubernetes.

В попередньому пості OpenTelemetry: OTel Collectors в Kubernetes та інтеграція з VictoriaMetrics stack описаний чисто OpenTelemetry stack для метрик і логів, і в цьому пості буду на нього посилатись.

І вже в наступній, третій – подивимось як створювати трейси з Python.

Monitoring vs Observability

“Monitoring is a passive action. Observability is an active practice” – з чудової книги Learning OpenTelemetry, Setting Up and Operating a Modern Observability System.

Перше, про що хочеться написати окремо – це, власне, розібрати різницю між “monitoring” та “observability“.

Їх часто плутають або використовують як взаємозамінні – але хоча вони і дотичні, це все ж про різні концепти.

Отже, Monitoring – це коли ми заздалегідь знаємо, що може зламатись та налаштовуємо перевірки саме на це: “CPU більше 90% => алерт. Диск зайнятий більш ніж на 85% => алерт. Помилки 5xx на ALB => алерт.”

Тобто, ми відповідаємо на питання, які сформулювали наперед. По суті – це dashboard-driven підхід: дивимось на відомі метрики, реагуємо на відомі проблеми.

Observability – це коли система дозволяє відповідати на питання, які ми заздалегідь не формулювали: відбувається щось “дивне”, і ми можемо “розкопати” причину – навіть якщо ніколи раніше з таким не стикалися.

Ключове слово тут – explorability: можливість дослідити зв’язки і причини проблем.

Як приклад – виріс Backend API latency. Моніторинг просто скаже – “латенсі високий” (алерт спрацював), а observability дозволить виконати drill down – пройти весь ланцюжок і знайти root cause: latency спайк на конкретному endpoint? конкретний tenant? конкретний Kubernetes Pod? Може один upstream повільний? Тобто, ми йдемо від симптому – до причини через дані, які вже є в системі.

Власне, тому і кажуть про “three pillars of observability” – Metrics, Logs, Traces. Саме traces (distributed tracing) – це те, що зазвичай відрізняє “просто моніторинг” від observability на практиці, бо саме трейси дають можливість дослідити невідому проблему – бачити шлях запиту через сервіси та знаходити bottleneck, якого ми не передбачували.

Втім, observability – це не про якісь “магічні динамічні алерти”: ми все ще залишаємо в системі звичайні pre-defined алерти типу “якщо 5хх більше 1% – слати повідомлення в Slack”.

Але змінюється те, що відбувається після того, як алерт спрацював: ми не просто бачимо “цей домен повертає помилки” і йдемо вручну грепати логи в VictoriaLogs – а маємо можливість пройти повний шлях: від алерта в Slack – через AWS ALB – через Kubernetes Pod – до компонента в цьому Pod, і врешті-решт до конкретного method() в коді, який повертає помилку та до юзера, на запити від якого цей метод генерує помилки.

Тобто алертинг – це все ще “моніторинг” частина: observability починається в момент, коли алерт спрацював і тобі треба зрозуміти чому.

Observability – це не про виявлення проблем, а про їх дослідження.

What is: Tracing

Tracing (або distributed tracing) – це спосіб відстежити шлях одного запиту через всю систему: від моменту, коли він прийшов на ALB – через Kubernetes Pod – до бази даних, зовнішнього API або LLM-виклику, і назад.

Далі будемо говорити про VictoriaTraces, яка побудована на VictoriaLogs – бо, власне, концепт трейсінгу той самий, що і у логів: сервіс записує кожен свій “чіх” – кожен виклик, кожну дію, кожен запит до зовнішніх систем. Різниця з “просто логгінгом” в тому, що у traces є ID, який об’єднує всі пов’язані виклики в дерево, що дозволяє будувати повний шлях запиту.

Один такий шлях називається trace. Trace складається зі spans, де кожен span це одна операція – конкретний HTTP-запит, SQL-запит, виклик іншого сервісу, обробка в черзі. Span-и зв’язані між собою в дерево через trace_id (спільний для всього trace) та parent_id (хто викликав цей span).

Виглядає це приблизно так:

trace_id: abc123

[HTTP GET /api/orders]                                        # root span (120ms)
  ├─ [auth-service: validate token]                           # child span (8ms)
  ├─ [orders-service: get orders]                             # child span (95ms)
  │    ├─ [PostgreSQL: SELECT * FROM orders WHERE user_id=42] # (80ms)
  │    └─ [Redis: GET cache:user:42]                          # (2ms)
  └─ [response serialization]                                 # child span (12ms)

Кожен span цього трейсу має поле з trace_id, кожен span має поля parent_id та span_id: у root span поле parent_id буде пусте, у другого span буде parent_id == span_id першого span цього трейсу і так далі.

Кожен span окрім часу виконання може містити атрибути – key-value пари з додатковим контекстом: частина атрибутів додається автоматично (HTTP method, status code, DB statement), частина – вручну розробниками (tenant_id, row_count, cache_hit). Чим більше контексту в атрибутах – тим більше можна дослідити не додаючи нових метрик чи логів.

Наприклад (це вже з наступного посту, там розберемо детальніше):

...
orders-api  |     "attributes": {
orders-api  |         "http.scheme": "http",
orders-api  |         "http.host": "172.25.0.3:8000",
orders-api  |         "net.host.port": 8000,
orders-api  |         "http.flavor": "1.1",
orders-api  |         "http.target": "/api/orders/by-customer/Vasya",
orders-api  |         "http.url": "http://172.25.0.3:8000/api/orders/by-customer/Vasya",
orders-api  |         "http.method": "GET",
orders-api  |         "http.server_name": "localhost:8000",
orders-api  |         "http.user_agent": "curl/8.20.0",
orders-api  |         "net.peer.ip": "172.25.0.1",
orders-api  |         "net.peer.port": 54900,
orders-api  |         "http.route": "/api/orders/by-customer/{name}",
orders-api  |         "customer.name": "Vasya",
orders-api  |         "customer.orders_count": 3,
orders-api  |         "http.status_code": 200
orders-api  |     },
...

Фактично, атрибути в traces – це labels в метриках Prometheus-формату, які ми потім можемо використовувати для пошуку трейсів і – головне – для кореляції пов’язаних метрик, логів та трейсів.

Приклад дебагу з tracing

Повернемось до прикладу, який описувався вище: маємо алерт в Slack, який каже, що Backend API latency на ендпоінт /coach виріс до 20 секунд:

В алерті є лінк на Grafana dashboard зі статусом AWS Application Load Balancer, в дашборді є посилання на VictoriaLogs з логами ALB та Backend API, лінк на дашборду з Kubernetes Pods нашого Backend API та його AWS RDS.

Метрики в Grafana dashboard показують спайк, логи – нічого підозрілого. Без трейсів далі починається гадання – йдемо дивитись CPU/RAM на Kubernetes WorkerNodes, навантаження на пов’язані Pods, Grafana dashboard для AWS RDS з PostgreSQL, намагаємось побудувати картину – де у нас виникає проблема.

З трейсами ми відкриваємо повільні traces для цього endpoint і одразу бачимо: із загальних 120ms на обробку всього реквесту – 80ms йде на виконання одного SQL-запиту. Дивимось атрибути цього span-у – db.statement: SELECT * FROM orders WHERE user_id=42, індекс не використовується: root cause знайдено за хвилину.

What is: the OpenTelemetry

OpenTelemetry (OTel) – це перш за все набір загальних “правил” по тому як дані мають збиратись і які метадані в них мають бути присутні.

Вище згадувались “three pillars of observability” – Metrics, Logs, Traces: кожна дія сервісу та його компоненту – це events, або Signals в термінології OTel.

OpenTelemetry та його OpenTelemetry Protocol (див. OTLP Specification 1.10.0) описують яким чином дані повинні передаватись (HTTP/gRPC), та які поля і заголовки вони повинні мати, таким чином уніфікуючи метрики, логи та трейси в єдиний формат.

З OTel ми збираємо ці сигнали на рівні коду, з Kubernetes Pods/Nodes або з AWS API, обробляємо, додаючи атрибути та об’єднуючи їх в загальний контекст, і передаємо до бекенду, в якому ці дані зберігаються – метрики до VictoriaMetrics, логи до VictoriaLogs, трейси до VictoriaTraces.

OpenTelemetry vs Prometheus

Коли ми працюємо VictoriaMetrics або Prometheus – у нас є звичний підхід до метрик: exporter виставляє endpoint /metrics, VictoriaMetrics з VMAgent ходить на цей ендпоінт та збирає метрики (PULL-модель). Формат метрик – простий текстовий типу metric_name{label="value"} 123.45.

В OpenTelemetry (OTel) інший підхід, бо зазвичай він працює за PUSH-моделлю: сервіс сам відправляє дані в OTel Collector, а той вже роутить їх куди треба – у VictoriaMetrics, VictoriaLogs, VictoriaTraces чи будь-який інший бекенд.

Втім, OTel Collector receivers можуть і самі виконувати запити до якихось API, наприклад – k8s_cluster робить запити до Kubernetes API /apis/apps/v1/deployments для отримання додаткової інформації по Kubernetes Pods.

Навіщо OpenTelemetry, якщо є Prometheus

Для метрик Prometheus формат і справді працює чудово, але Prometheus – це тільки метрики: він не вміє в трейси, не вміє в structured logs, і головне – не вміє зв’язати метрику, лог і трейс між собою: у нас вже є VictoriaLogs для логів, VictoriaMetrics для метрик – але все це окремі системи зі своїми форматами, тому зв’язати конкретну метрику з конкретним логом і конкретним трейсом – складно, бо в них немає спільного контексту.

OTel вирішує саме цю проблему: коли метрики, логи і трейси проходять через один SDK, то вони автоматично отримують спільний контекст – trace_id, service.name, deployment.environment, kubernetes.pod.name. В результаті ми з алерту по metric_name можемо перейти до трейсу конкретного запиту, а з трейсу – до логів конкретного span-у. Без OTel ці три системи живуть окремо, і зв’язувати їх доводиться вручну.

Компоненти OpenTelemetry

OpenTelemetry складається з трьох основних частин:

OTel SDK: вбудовується в код і генерує телеметрію
- для auto-instrumentation це кілька рядків при старті сервісу – і ми одразу отримуємо span-и для HTTP, gRPC, SQL (див. Instrumentation нижче)
OTel Collector: окремий сервіс (DaemonSet або Deployment в Kubernetes), який приймає дані від SDK в сервісах, обробляє і відправляє далі до бекендів
- той жеж Collector в ролі агента може сам збирати метрики і логи з Kubernetes чи AWS – теж описано в попередньому пості
OTLP (OpenTelemetry Protocol): це формат і протокол передачі даних, який працює поверх gRPC або HTTP і підтримується практично всіма сучасними бекендами – VictoriaMetrics, Grafana Tempo, Jaeger, Datadog

OpenTelemetry Instrumentation

Сам термін instrumentation в контексті OpenTelemetry і трейсингу – це процес додавання специфічного коду до сервісу або системи, який дозволяє виконувати observability цього коду.

Див. Instrumentation та Zero-code Instrumentation.

З OpenTelemetry є три шляхи виконати instrumentation:

zero-code instrumentation: ми взагалі нічого не міняємо в коді – виклик нашого сервісу відбувається через зовнішній wrapper, який перехоплює виклики нашого коду і сам додає потрібні дані
- швидко, зручно – але найменш гнучко, бо не дає можливості самому вирішувати що і де додавати
auto instrumentation: OTel SDK вміє автоматично створювати span-и для HTTP-запитів, DB-клієнтів, gRPC-викликів, додавати необхідні атрибути
- для auto-instrumentation використовуємо OTel SDK шляхом додавання бібліотек в наш код, який через власні методи і функції додає інформацію до викликів методів і функцій нашого коду
manual instrumentation: можемо додавати власні custom spans та атрибути в коді для бізнес-логіки, яку auto-instrumentation не бачить
- наприклад, створювати span на обробку одного елементу в batch job, або атрибут order.total_items в SQL-виклику на span обробки замовлення

Як правило, починають з auto-instrumentation (щоб одразу отримати базову картину), а потім додають manual instrumentation поступово – там, де не вистачає контексту для дебагу конкретних проблем.

What is: VictoriaTraces

Документація – VictoriaTraces та Key concepts.

Репозиторій проекту – VictoriaTraces.

VictoriaTraces побудована на VictoriaLogs: вона отримує дані від OTel Collector у вигляді JSON в форматі OTLP та записує їх у власному форматі, трансформуючи імена полів.

Проект поки в статусі This project is currently a work in progress, тому зміни можливі – але вже цілком робочий.

Як і VictoriaLogs, VictoriaTraces формує stream fields, які використовують для оптимізації збереження даних та пошуку логів чи трейсів.

В результаті кожний записаний trace span зберігається як частина конкретного stream – аналогічно до того, як кожен log record у VictoriaLogs – це частина якогось одного конкретного log stream.

У VictoriaTraces для поля stream використовується атрибут service.name, і кожне унікальне значення в stream field впливає на те, скільки даних буде сформоване в VictoriaTraces storage та IndexDB, яка використовується для пошуку даних коли ми робимо sum by (label_name).

Див. VictoriaMetrics: Churn Rate, High cardinality, метрики та IndexDB – бо суть зберігання даних в VictoriaMetrics, VictoriaLogs та VictoriaTraces однакова.

Як і VictoriaMetrics та VictoriaLogs, у VictoriaTraces є власний VM UI, в якому з LogsQL можемо виконувати пошук трейсів:

Хоча для відображення дерева трейсів краще використовувати Grafana – далі зробимо.

Також див. документацію VictoriaTraces по Monitoring – можемо збирати метрики та Retention – трейси, як і логи та метрики, теж зберігаються на диску, тому треба мати на увазі зайняте місце.

І дуже смачна можливість – створювати власні метрики з traces, зробимо в цьому пості далі.

Запуск VictoriaTraces в Kubernetes

Як і у VictoriaLogs, VictoriaTraces є single instance та cluster mode для High Availability – але в моєму випадку single isntance вистачає з головою, тому поки будемо використовувати його.

Для запуску VictoriaTraces в Kubernetes є окремі Helm-чарти – victoria-traces-single та victoria-traces-cluster.

Документація по чарту – VictoriaTraces Single.

Додаємо репозиторій:

$ helm repo add vm https://victoriametrics.github.io/helm-charts/
$ helm repo update

Знаходимо останню доступну версію чарту:

$ helm search repo vm/victoria-traces-single
NAME                            CHART VERSION   APP VERSION     DESCRIPTION                                       
vm/victoria-traces-single       0.0.7           v0.8.0          The VictoriaTraces single Helm chart deploys Vi...

Пишемо values.yaml, дефолтні значення є в репозиторії чарту, наприклад:

victoria-traces-single:
  enabled: true
  server:
    mode: deployment
    ingress:
      enabled: true
      ingressClassName: alb
      annotations:
        alb.ingress.kubernetes.io/group.name: ops-1-33-internal-alb
        alb.ingress.kubernetes.io/target-type: ip
        alb.ingress.kubernetes.io/certificate-arn: arn:aws:acm:us-east-1:492***148:certificate/ad0ae28d-1843-412d-b3e1-05235186ea11
      hosts:
        - name: vmtraces.monitoring.1-33.ops.example.co
          path:
            - /
          port: http
    resources:
      requests:
        cpu: 100m
        memory: 256Mi
    persistentVolume:
      enabled: true
      storageClassName: gp3-retain
      size: 50Gi
    retentionPeriod: 30d
    vmServiceScrape:
      enabled: true

Я тут задав тип деплою з Deployment замість StatefulSet та додав Ingress через AWS ALB.

В persistentVolume створюємо диск, в retentionPeriod міняємо дефолтне значення 7 днів на місяць.

Деплоїмо, перевіряємо:

$ kk get deploy atlas-victoriametrics-vt-single-server
NAME                                     READY   UP-TO-DATE   AVAILABLE   AGE
atlas-victoriametrics-vt-single-server   1/1     1            1           44h

Перевіряємо Kubernetes Service:

$ kk get svc atlas-victoriametrics-vt-single-server
NAME                                     TYPE        CLUSTER-IP   EXTERNAL-IP   PORT(S)     AGE
atlas-victoriametrics-vt-single-server   ClusterIP   None         <none>        10428/TCP   2d20h

VictoriaTraces приймає OTLP/HTTP на endpoint /insert/opentelemetry/v1/traces.

Можемо з curl пушнути трейс для тесту – відкриваємо порт:

$ kk port-forward svc/atlas-victoriametrics-vt-single-server 10428

Відправляємо JSON з полями, які потім буде створювати наш OTel SDK:

$ curl -v -X POST "http://localhost:10428/insert/opentelemetry/v1/traces" -H "Content-Type: application/json" -d "{\"resourceSpans\":[{\"resource\":{\"attributes\":[{\"key\":\"service.name\",\"value\":{\"stringValue\":\"test-curl\"}}]},\"scopeSpans\":[{\"scope\":{\"name\":\"manual-test\"},\"spans\":[{\"traceId\":\"aaaaaaaaaaaaaaaabbbbbbbbbbbbbbbb\",\"spanId\":\"cccccccccccccccc\",\"name\":\"test-span\",\"kind\":2,\"startTimeUnixNano\":\"$(date +%s)000000000\",\"endTimeUnixNano\":\"$(date +%s)000000000\",\"attributes\":[{\"key\":\"http.method\",\"value\":{\"stringValue\":\"GET\"}},{\"key\":\"http.route\",\"value\":{\"stringValue\":\"/api/test\"}}],\"status\":{\"code\":1}}]}]}]}"

Перевіряємо у VM UI – http://localhost:10428/select/vmui/:

Формат запитів – стандартний LogsQL:

{name="test-span"} trace_id:"aaaaaaaaaaaaaaaabbbbbbbbbbbbbbbb"

І, власне, VictoriaTraces готова до роботи. Залишилось додати instrumentation в наш код – детальніше в наступній частині, тут просто для прикладу як воно взагалі може виглядати – тут auto instrumentation для FastAPI та asyncpg:

import os
from fastapi import FastAPI, HTTPException
from contextlib import asynccontextmanager
import asyncpg

from opentelemetry.instrumentation.fastapi import FastAPIInstrumentor
from opentelemetry.instrumentation.asyncpg import AsyncPGInstrumentor

from opentelemetry import trace
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import ConsoleSpanExporter, SimpleSpanProcessor, BatchSpanProcessor
from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter


pool = None


@asynccontextmanager
async def lifespan(app: FastAPI):
    global pool
    pool = await asyncpg.create_pool(
        host=os.getenv("DB_HOST", "postgres-test"),
        port=int(os.getenv("DB_PORT", "5432")),
        user=os.getenv("DB_USER", "postgres"),
        password=os.getenv("DB_PASSWORD", "testpass"),
        database=os.getenv("DB_NAME", "demo"),
        min_size=2,
        max_size=10,
    )
    yield
    await pool.close()


# Set up OTel tracer provider
provider = TracerProvider()

# Console exporter (for local debugging)
provider.add_span_processor(SimpleSpanProcessor(ConsoleSpanExporter()))
# OTLP exporter to VictoriaTraces
provider.add_span_processor(BatchSpanProcessor(OTLPSpanExporter()))

trace.set_tracer_provider(provider)

app = FastAPI(title="Orders API", lifespan=lifespan)

FastAPIInstrumentor.instrument_app(app)
AsyncPGInstrumentor().instrument()

@app.get("/healthz")
async def healthz():
    return {"status": "ok"}


@app.get("/api/orders")
async def list_orders():
    rows = await pool.fetch("SELECT * FROM orders ORDER BY id")
    return [dict(r) for r in rows]


@app.get("/api/orders/{order_id}")
async def get_order(order_id: int):
    row = await pool.fetchrow("SELECT * FROM orders WHERE id = $1", order_id)
    if not row:
        raise HTTPException(status_code=404, detail="Order not found")
    return dict(row)


@app.get("/api/orders/by-customer/{name}")
async def orders_by_customer(name: str):
    # catch currently processing span
    current_span = trace.get_current_span()
    # add attribute to the current span: customer name
    current_span.set_attribute("customer.name", name)
    # fetch orders from the database
    rows = await pool.fetch(
        "SELECT * FROM orders WHERE customer_name = $1 ORDER BY id", name
    )
    # add attribute to the current span: number of orders fetched
    current_span.set_attribute("customer.orders_count", len(rows))
    return [dict(r) for r in rows]

VMAlert та Recording Rules з VictoriaTraces

Цікава фішка – можемо мати Recording Rules, в яких буде використовуватись VictoriaTraces – див. Alerting with traces.

Логіка та сама, як і для Recording Rules і метрик з логів у VictoriaLogs: описуємо правило з type="vlogs" – vmalert генерить метрику, а потім цю метрику можемо використати в алертах чи Grafana.

Єдиний нюанс тут – якщо вже є інстанс vmalert для логів, то треба робити другий інстанс – бо в Recording Rules тип однаковий (vlogs), і для самого VMAlert треба вказувати інший datasource.url.

Додавання VMAlert

vmalert можна встановити з Helm chart victoria-metrics-alert, або, як в моєму випадку при використанні victoria-metrics-k8s-stack і VictoriaMetrics Kubernetes Operator – то створити другий інстанс через kind=VMAlert.

Документація по самому vmalert – тут>>>.

Приклад з kind: VMAlert:

apiVersion: operator.victoriametrics.com/v1beta1
kind: VMAlert
metadata:
  name: vmalert-traces
spec:
  datasource:
    url: http://atlas-victoriametrics-vt-single-server:10428
  remoteWrite:
    url: http://vmsingle-vm-k8s-stack:8428
  notifiers:
    - url: http://vmalertmanager-vm-k8s-stack.ops-monitoring-ns.svc.cluster.local:9093
  ruleSelector: 
    matchLabels:
      app: vmalert-traces

Тут:

datasource.url: задаємо ендпоінт VictoriaTraces – vmalert буде ходити до нього, аби отримати трейси
remoteWrite: куди писати згенеровані метрики

remoteRead тут optional – бо цей інстанс тільки генерить метрики.

А от notifiers обов’язковий – хоча алертів він генерити не буде.

В ruleSelector задаємо які саме VMRules використовувати – інакше в ConfigMap цього інстансу VMAlert будуть додані все VMRules.

Додавання VMRule

Спершу в самій VictoriaTraces перевіряємо якийсь запит, наприклад:

{resource_attr:service.name="kraken-prod"} "span_attr:http.route":!""
| stats by ("resource_attr:service.name", "span_attr:http.route", "span_attr:http.status_code") quantile(0.95, duration) p95_duration

Тут отримуємо всі spans з resource_attr:service.name="kraken-prod", вибираємо тільки ті, у яких присутній span_attr:http.route і рахуємо 95 percentile по полю duration:

Описуємо сам VMRule, в labels задаємо app="vmalert-traces" – по ньому ruleSelector буде вибирати тільки цей VMRule:

apiVersion: operator.victoriametrics.com/v1beta1
kind: VMRule
metadata:
  name: recording-rules-vmalert-traces
  labels:
    app: vmalert-traces
spec:
  groups:
    - name: Traces.VictoriaTraces.Logs.rules
      type: vlogs
      interval: 5m

      rules:

        # Target Status: metrics on events from Target Status logs
        - record: vmtraces:kraken:http:request_duration:p95
          expr: |
            {resource_attr:service.name=~"kraken-.*"} "span_attr:http.route":!""
            | stats by ("resource_attr:service.name", "span_attr:http.route", "span_attr:http.status_code") quantile(0.95, duration) p95_duration

Деплоїмо і перевіряємо об’єкти vmalert:

$ kk get vmalert 
NAME             STATUS        REPLICACOUNT   AGE
vm-k8s-stack     operational   1              343d
vmalert-traces   operational                  42m

Тут vm-k8s-stack – це дефолтний vmalert з чарту victoria-metrics-k8s-stack – він займається алертами і має Recording Rules для логів (потім, мабуть, винесу окремими інстансами – один для алертів, один для Recording Rules з логів, один для VictoriaTraces).

І, відповідно, маємо новий Kubernetes Pod:

$ kk get pod | grep vmalert 
vmalert-vm-k8s-stack-f6cdd77d9-mcnks                              2/2     Running     0               3d23h
vmalert-vmalert-traces-b8f77656c-jqzbp                            2/2     Running     0               4m29s

Для якого створена власна ConfigMap:

$ kk get pod vmalert-vmalert-traces-b8f77656c-jqzbp -o yaml | yq '.spec.volumes'
...
  {
    "configMap": {
      "defaultMode": 420,
      "name": "vm-vmalert-traces-rulefiles-0"
    },
    "name": "vm-vmalert-traces-rulefiles-0"
  },
...

В якій містяться правила з VMRule recording-rules-vmalert-traces:

$ kk describe cm vm-vmalert-traces-rulefiles-0 
Name:         vm-vmalert-traces-rulefiles-0
...
Data
====
ops-monitoring-ns-recording-rules-vmalert-traces.yaml:
----
groups:
- name: Traces.VictoriaTraces.Logs.rules
  interval: 5m
  rules:
  - record: vmtraces:kraken:http:request_duration:p95
    expr: |
      {resource_attr:service.name=~"kraken-.*"} "span_attr:http.route":!""
      | stats by ("resource_attr:service.name", "span_attr:http.route", "span_attr:http.status_code") quantile(0.95, duration) p95_duration

Деплоїмо і за хвилину маємо нові метрики в VictoriaMetrics:

VictoriaTraces та Grafana

Аби зручно працювати в трейсами – додамо Grafana data source.

Для VictoriaTraces поки використовується дефолтний Jaeger, пізніше, думаю, створять власний плагін – для VictoriaMetrics спочатку теж використовувався звичайний Prometheus plugin, для VictoriaLogs був Loki plugin, потім команда вже додала свої.

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

$ kk get svc | grep vt
atlas-victoriametrics-vt-single-server                   ClusterIP   None             <none>        10428/TCP                    24h

Перевіряємо Jaeger плагін:

Додаємо новий data source:

Задаємо URL як http://atlas-victoriametrics-vt-single-server:10428/select/jaeger:

Можна включити Trace to Logs and Metrics – тоді в Grafana Explore по trace_id будуть генеруватись лінки на повязані метрики та логи:

Зберігаємо, перевіряємо:

Переходимо в Explore і шукаємо по Trace ID:

VictoriaLogs, Derived Fields та VictoriaTraces

VictoriaLogs plugin підтримує створення derived fields: можна прямо з логів VictoriaLogs створювати лінк на VictoriaTraces.

Налаштовується в Grafana Connections > VictoriaLogs: вказуємо ім’я, вибираємо тип – в моєму випадку логи в JSON, тому через “Regex in log line”:

"trace_id":\s*"([a-f0-9]{32})"

В поле URL використовуємо ${__value.raw} – сюди буде підставлено значення trace_id.

В Example log message можна перевірити чи вірно працює regex:

Після чого відкриваємо лог з полем trace_id – справа з’явиться блок “Links”:

Який відкриє посилання на цей трейс:

Власне, на цьому сьогодні все.

В наступному пості вже подивимось як використовувати OpenTelemetry instrumentation і з Python app створювати трейси.

OpenTelemetry: OTel Collectors в Kubernetes та інтеграція з VictoriaMetrics stack
5 (3)

16 Травня 2026

Сьогодні поговоримо про те, як запустити OpenTelemetry в Kubernetes та інтегрувати його з VictoriaMetrics stack – VictoriaMetrics для метрик, VictoriaLogs для логів, та VictoriaTraces для трейсів.

Взагалі-то цей пост не планувався взагалі, а коли все ж з’явилась його чорнетка – то він мав бути третім в серії, але врешті-решт вирішив зробити його першим.

Вже після нього допишу два інших поста – перший про Observability та tracing з VictoriaTraces, другий – по OpenTelemetry instrumentation в Python та запису трейсів до VictoriaTraces, а потім – про LLM Observability та моніторингу.

Власне, саме так OpenTelemetry на моєму поточному проекті і з’явився – захотіли ми подивитись детальніше по тому, що у нас по роботі з різними LLM-провайдерами, а там все “заточено” під OpenTelemetry, бо формат Prometheus metrics для цього не підходить.

Тому першим ділом додав VictoriaTraces та запис трейсів в з нашого Backend API, потім подивився на це всі діло, подумав, що мені замало контексту – і вирішив додати повний OpenTelemetry стек.

Власне, з контексту і почнемо.

Див. другу частину – VictoriaTraces: Tracing, Observability та OpenTelemetry.

OpenTelemetry, Observability та Context

Головна суть observability – в контексті, бо context – це, surprise, не тільки про AI/LLM, а і про моніторинг та Observability.

Про Monitoring vs Observability будемо говорити в наступному пості (який мав бути першим), а сьогодні подивимось як запустити OpenTelemetry в Kubernetes.

Але, якщо коротко, то Observability будується на “three pillars of observability” – Metrics, Logs, Traces.

Але просто мати метрики, логи та трейси мало – бо всі наші three pillars повинні мати якісь загальні ознаки, загальні дані, які дозволять робити “наскрізний observability” – тобто, мати можливість в єдиному контексті дослідити і метрики EC2, і метрики AWS Application Load Balancer, і конкретні Kubernetes Pods самого Backend API та, врешті решт – до конкретних викликів функцій, бізнес-логіки, яка виконується в цьому Pod у відповідь на реквест, який прийшов з AWS ALB від конкретного юзеру – тобто, побудувати observability pipeline.

А для того, аби всі дані мали цей загальний контекст – вони повинні мати якісь загальні риси, ознаки, за якими ми можемо всі отримані – тобто labels.

Проте при використанні “дефолтного” Prometheus-стеку ми маємо купу різних експортерів для метрик, окремі експортери для логів, ще і на додачу трейси в OTel-форматі – і кожен пише лейбли на свій лад. Тому, аби якось це все об’єднати в Grafana dashboards або алертах доводиться гемороїтись зі всякими label_replace.

Живий приклад з одного з мої алертів:

- record: aws:node:cpu_utilization:percent
  expr: |
    100 * (1 - avg by(instance, cluster) (
      label_replace(
        rate(node_cpu_seconds_total{mode="idle"}[5m]),
        "instance",
        "ip-${1}-${2}-${3}-${4}.ec2.internal",
        "instance",
        "(.*)\\.(.*)\\.(.*)\\.(.*):9100"
      )
    ))

Тут з метрики node_cpu_seconds_total береться значення лейбли instance типу 10.0.50.18 і створюється нове значення виду ip-10-0-50-18.ec2.internal, яке потім використовується в Grafana dashboards для фільтрів – бо якась інша метрика віддає ім’я хоста в такому вигляді, а метрика від node_exporter не має дефолтної лейбли у вигляді node_name="ip-10-0-50-18.ec2.internal".

Тому можна піти іншим шляхом – замінити те, як ми ці метрики отримуємо: замість того, щоб мати 10 різних експортерів для метрик – node_exporter для EC2, YACE exporter для AWS CloudWatch, окремого експортеру k8s-event-logger для експорту Kubernetes Events в логи, замість окремого AWS ALB Logs collector із S3 – ми можемо мати єдину систему, яка все це робить сама і, головне – сама додає загальний загальні лейбли до всіх signals – metrics, logs, traces.

Плюси та мінуси OpenTelemetry

Звісно, не все так просто: OpenTelemetry Collector трохи складніший в налаштуванні, споживає більше ресурсів, потребує додаткового моніторингу.

Власне, це цілком очікувано, бо якщо система “з коробки” дає більше можливостей – то і її конфігурація буде трохи складнішою, ніж для якогось одного Prometheus Node Exporter.

Те саме і по ресурсам – коли експортер займається збором і метрик і логів – то він буде споживати більше ресурсів, ніж один експортер, який “заточений” тільки під одну задачу: вже те, що OTel має захист від OOMKiller “з коробки” про щось говорить.

Втім, якщо порахувати споживання CPU/RAM всіма експортерами Prometheus-формату і порівняти з одним Kubernetes Pod для OpenTelemetry Collector – то ще питання, що буде легше.

Крім того – формат OTel для метрик за розміром більший, ніж Prometheus-метрики – бо сам формат в собі містить більше даних.

І останній нюанс, який зараз приходить в голову – це те, що 95% всяких алертів та Grafana dahsboards заточені саме під метрики в Prometheus-форматі та від Prometheus-експортерів на кшталт node_exporter та cAdvisor.

Тому якщо впроваджувати OTel в якості основної системи для збору даних – то треба мати на увазі, що треба буде оновлювати і всі пов’язані ресурси.

Втім, конкретно в моєму випадку – ми ще маленький стартап, а основні Grafana dashboards я все одно роблю сам руками, тому з LLM задачка це все оновити вирішується відносно швидко.

Отже, спробую, запущу поки що паралельно з існуючим Prometheus-like стеком експортерів та логів і подивлюсь, що з цього вийде.

VictoriaTraces і трейси у нас теж вже є, але про це будемо говорити окремо.

VictoriaMetrics та мій поточний стек моніторингу

У нас на проекті все працює в AWS на Elastic Kubernetes Service – Backend API та інші сервіси проекту, сам VictoriaMetrics стек моніторингу, плюс різні сервіси самого AWS – RDS, CloudFront, DynamoDB etc.

Що залишиться без змін – це наші “storages”: VictoriaMetrics для метрик, VictoriaLogs – для логів, VictoriaTraces – для трейсів.

Що зміниться – це те, як ми ці дані отримуємо: замість пачки Prometheus exporters та VMAgent, який до них ходить і збирає метрики – у нас буде окремий сервіс OTel Gateway, який отримує дані від OTel Collector. А OTel Collector замінить весь зоопарк Prometheus Exporters та Log collectors.

Окремо від цієї інфраструктури є багато інтеграцій з AI-провайдерами – Anthropic, OpenAI – але їхній моніторинг це вже зовсім окрема тема, про які буду (сподіваюсь) писати далі.

OpenTelemetry – загальна архітектура та компоненти

Для збору даних – метрик, логів та трейсів – у OpenTelemetry є власний OpenTelemetry Collector, який може відігравати різні ролі.

Власне, це один і той самий binary-файл, поведінка якого залежить від того, що ми йому передаємо в налаштуваннях:

роль Kubernetes Collector: збираємо Kubernetes events, метрики Kubernetes WorkerNodes, Kubernetes Pods, контейнерів, логи
роль AWS Collector: збирає метрики з CloudWatch та/або логи з AWS ALB через S3 та/або VPC Flow Log
роль OpenTelemetry Gateway: агенти (OTel Collectors) пушать свої дані до Gateway, а Gateway вже передає їх до конкретних бекендів – VictoriaMetrics, VictoriaLogs, VictoriaTraces

Схематично це може виглядати якось так:

Єдиний момент перед тим, як продовжити: я називаю OTel Collectors і як “collector“, і як “agent“, але назва суті не міняє – це просто роль, яку сервіс виконує.

Структура конфігурації OpenTelemetry Collector

В інтернеті багато прикладів файлів, наприклад в офіційному репозиторії k8s/otel-config.yaml, або невелика колекція Cloud-Architect-Emma/opentelemetry-collector-examples.

Але аби ними користуватись або писати власні – треба трохи глянути за загальний синтаксис та компоненти, які в конфігурації описані.

Документація:

Configuration reference
Agent pattern
Gateway pattern
Agent-to-Gateway pattern
Components registry (всі receivers/processors/exporters з пошуком)
Contrib repo

В кожному компоненті ми будемо задавати власні параметри – але структура у всіх однакова:

receivers: описують звідки отримувати дані – Kubernetes API, AWS API, логи
- для Kubernetes Collector тут будуть hostmetrics (метрики як від node_exporter), kubeletstats (метрики контейнерів), filelog (логи Pods)
- у Gateway у receivers буде otlp – приймати дані від Collectors, та k8s_cluster і k8sobjects – він сам буде збирати дані від Kubernetes API та kubelet
processors: трансформації даних – додає метадані (атрибути, лейбли), фільтрує або видаляє зайве, групує, виконує трансформації – перейменування полів, нормалізація
exporters: куди дані відправляємо
- у Gateway у exporters будуть otlphttp/vmetrics, otlphttp/vlogs, otlphttp/vtraces.
- в Agent у exporters буде otlp_grpc (з адресою Gateway)
extensions: додаткові capabilities (аутентифікація, health check, encoding extensions тощо)
connectors: об’єднує різні pipelines
service: об’єднує і активує описані конфіги – recievers, processors, etc

OpenTelemetry Pipelines

Всі отримані сигнали проходять через pipeline: тобто receiver – отримав сигнал, processor його обробив, exporter – кудись відправив.

Для кожного типу сигналів – метрик, логів та трейсів – у нас будуть власні пайплайни – бо дані хоч і пов’язані, але оброблюються по різному.

Кожен пайплайн може мати власний ідентифікатор – просто ім’я, аби простіше було читати конфіг, наприклад:

connectors:
  spanmetrics:
    # config...

service:
  pipelines:
    traces:
      receivers: [otlp]
      exporters: [otlphttp/vtraces, spanmetrics]  # spanmetrics here is an exporter
    
    metrics/from_traces:
      receivers: [spanmetrics]                    # the same spanmetrics here is an receiver
      exporters: [otlphttp/vmetrics]

Тепер можемо починати писати власні конфіги та запускати колектори.

OpenTelemetry: запуск в Kubernetes

Є кілька варіантів запусту стека – “голими” контейнерами, Helm chart, або OpenTelemetry Operator, див. Install the Collector.

Для VictoriaMetrics я користуюсь Helm chart victoria-metrics-k8s-stack, який встановлює VictoriaMetrics Operator, VMAgent, VMAlert, Alertmanager, Grafana, а всі налаштування виконуються з VictoriaMetrics CRD resources.

Про цей сетап писав у VictoriaMetrics: створення Kubernetes monitoring stack з власним Helm-чартом, а про Kubernetes Operators та CRD – у Kubernetes: що таке Kubernetes Operator та CustomResourceDefinition.

Для OpenTelemetry поки зроблю просто з Helm chart – бо простіше буде розібратись з основними компонентами і не витрачати час на документацію оператора та його CRD.

А вже коли це все діло піде у production – можна буде замінити на OpenTelemetry Operator.

Робити будемо у вигляді трьох окремих компонентів:

OTel Gateway: отримує дані від Kubernetes API, Kubernetes та AWS Collectors, оброблює їх, передає до бекендів – VictoriaMetrics, VictoriaLogs, VictoriaTraces
Kubernetes Agent: запускається на кожній Kubernetes WorkerNode, збирає дані від kubelet та логи Pods
AWS Agent: збирає дані від AWS – метрики, логи

Почнемо саме з OTel Gateway, бо всі інші компоненти будуть слати дані саме через нього, саме він буде виконувати всі операції, і саме він буде відправляти дані до VictoriaMetrics stack.

Додаємо собі Helm-репозиторій:

$ helm repo add open-telemetry https://open-telemetry.github.io/opentelemetry-helm-charts
$ helm repo update

Перевіряємо наявність чартів:

$ helm search repo open-telemetry/opentelemetry-collector
NAME                                    CHART VERSION   APP VERSION     DESCRIPTION                                      
open-telemetry/opentelemetry-collector  0.155.0         0.151.0         OpenTelemetry Collector Helm chart for Kubernetes

Всі компоненти – OTel Gateway, Kubernetes Agent, AWS Agent – будуть встановлюватись з нього, але кожний з власними values.

Запуск OpenTelemetry Gateway

Готуємо файл otel-gateway-values.yaml – це будуть values для нашого OTel Gateway:

# OTel Collector - Gateway role (Deployment)
#
# Responsibilities at this phase:
#   - Accept OTLP from future Agents (DaemonSet)
#   - Collect cluster-level metrics via k8s_cluster receiver
#   - Collect K8s events as logs via k8sobjects receiver
#   - Enrich all signals with K8s metadata (k8sattributes processor)
#   - Export metrics to VictoriaMetrics, logs to VictoriaLogs
#
# Traces pipeline is intentionally not enabled yet - that's Phase 2

# docs: https://opentelemetry.io/docs/collector/architecture/

mode: deployment

replicaCount: 2

# contrib image has all the receivers/processors/exporters we need
image:
  repository: otel/opentelemetry-collector-contrib

resources:
  limits:
    cpu: 1000m
    memory: 2Gi
  requests:
    cpu: 200m
    memory: 512Mi

# RBAC for k8sattributes (pod metadata lookup) and k8s_cluster (cluster state).
# Full list of required permissions:
# https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/receiver/k8sclusterreceiver
clusterRole:
  create: true
  rules:
    - apiGroups: [""]
      resources:
        - pods
        - namespaces
        - nodes
        - nodes/stats
        - nodes/proxy
        - events
        - services
        - resourcequotas
        - replicationcontrollers
        - replicationcontrollers/status
      verbs: ["get", "list", "watch"]
    - apiGroups: ["apps"]
      resources: ["replicasets", "deployments", "statefulsets", "daemonsets"]
      verbs: ["get", "list", "watch"]
    - apiGroups: ["extensions"]
      resources: ["replicasets"]
      verbs: ["get", "list", "watch"]
    - apiGroups: ["batch"]
      resources: ["jobs", "cronjobs"]
      verbs: ["get", "list", "watch"]
    - apiGroups: ["autoscaling"]
      resources: ["horizontalpodautoscalers"]
      verbs: ["get", "list", "watch"]
    - apiGroups: ["events.k8s.io"]
      resources: ["events"]
      verbs: ["get", "list", "watch"]

# Self-monitoring port
ports:
  metrics:
    enabled: true
    containerPort: 8888
    servicePort: 8888
    protocol: TCP

service:
  type: ClusterIP

config:
  receivers:
    # PUSH receiver
    # Accepts data from Agents and from apps
    # OTel TracerProvider() for the Backend API will send traces to this receiver
    otlp:
      protocols:
        grpc:
          endpoint: 0.0.0.0:4317
          # Agent batches of logs may exceed default 4 MiB gRPC limit
          max_recv_msg_size_mib: 16
        http:
          endpoint: 0.0.0.0:4318

    # PULL receiver
    # Will go to the Kubernetes API to get the cluster-level state
    # Runs only on Gateway (one place per cluster)
    # uses GET /api/v1/nodes, GET /apis/apps/v1/deployments etc.
    # converts responses to metircs like k8s.deployment.available, k8s.node.condition_ready, k8s.hpa.current_replicas
    # returns them to a corresponding pipeline
    k8s_cluster:
      collection_interval: 30s
      node_conditions_to_report: [Ready, MemoryPressure, DiskPressure, PIDPressure]
      allocatable_types_to_report: [cpu, memory, ephemeral-storage]

    # PULL receiver
    # Will go to the Kubernetes API, but uses `watch` mode
    # uses the 'events.k8s.io/v1/events' endpoint to receive event stream in real time
    # converts Kubernetes Events to Log records
    # returns them to the logs pipeline
    k8sobjects:
      objects:
        - name: events
          mode: watch
          group: events.k8s.io

  processors:
    # Memory protection against traffic spikes to avoid OOM kills
    memory_limiter:
      check_interval: 1s
      limit_percentage: 80
      spike_limit_percentage: 25

    # Enrich every signal with K8s pod metadata - this is what unifies labels
    # across metrics, logs and traces
    # docs: https://opentelemetry.io/docs/platforms/kubernetes/collector/components/#kubernetes-attributes-processor
    k8sattributes:
      auth_type: serviceAccount
      passthrough: false
      extract:
        # data taken from the Kubernetes API - fields from the Pod object to be added as attributes
        # i.e. a Kubernetes Namespace 'dev-backend-api-ns' for a Pod will be set as k8s.namespace.name="dev-backend-api-ns"
        # https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/processor/k8sattributesprocessor#configuration
        metadata:
          - k8s.namespace.name
          - k8s.pod.name
          - k8s.pod.uid
          - k8s.pod.start_time
          - k8s.deployment.name
          - k8s.statefulset.name
          - k8s.daemonset.name
          - k8s.cronjob.name
          - k8s.job.name
          - k8s.node.name
        # add custom labels from the Pod object
        # i.e. a Pod with label 'app.kubernetes.io/component=backend' will be set as app.label.component="backend"
        labels:
          - tag_name: app.label.component
            key: app.kubernetes.io/component
            from: pod
          - tag_name: app.label.name
            key: app.kubernetes.io/name
            from: pod
      # pod_association processor is used to associate signals (metrics, logs, traces) with the correct Pod
      # e.g. when the Gateway receive a metric from a Pod, it need to know how to find that Pod in the Kubernetes API
      # for example, our Kubernetes Agent will send a metric from 'kubeletstats' for a container
      # but this metrics will not have a corresponding 'k8s.deployment.name'
      # so here, k8sattributes proecessor will ask the Kubernetes API to get additional metadata and set it as attributes
      pod_association:
        - sources:
            - from: resource_attribute
              name: k8s.pod.ip
        - sources:
            - from: resource_attribute
              name: k8s.pod.uid
        - sources:
            - from: connection

    # similar to the k8sattributes.extract.labels above, but for the resource attributes to all signals
    # sets hard-coded values
    resource:
      attributes:
        # action may be set as:
        # - insert: add only if not exists
        # - update: update if exists
        # - upsert: insert if not exists, update if exists
        # - delete: delete if exists
        - key: k8s.cluster.name
          value: eks-ops-1-33
          action: upsert
        - key: cloud.provider
          value: aws
          action: upsert

    # Batch records for efficient export
    # collects data to its buffer and sends it to the exporter in batches
    # docs: https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/processor/batchprocessor
    batch:
      send_batch_size: 8192
      timeout: 10s

  # Where to send the data to - in our case, to VictoriaMetrics and VictoriaLogs
  # docs: https://docs.victoriametrics.com/opentelemetry/
  exporters:
    # VictoriaMetrics - OTLP endpoint
    # docs: https://docs.victoriametrics.com/victoriametrics/data-ingestion/opentelemetry-collector/
    # the '/v1/metrics' part will be added by the exporter itself
    otlphttp/vmetrics:
      endpoint: http://vmsingle-vm-k8s-stack.ops-monitoring-ns.svc.cluster.local:8428/opentelemetry
      tls:
        insecure: true

    # VictoriaLogs - OTLP endpoint
    # docs: https://docs.victoriametrics.com/victorialogs/data-ingestion/opentelemetry/
    # the '/v1/logs' part will be added by the exporter itself
    otlphttp/vlogs:
      endpoint: http://atlas-victoriametrics-victoria-logs-single-server.ops-monitoring-ns.svc.cluster.local:9428/insert/opentelemetry
      tls:
        insecure: true

    # Debug exporter - for troubleshooting, can be added to any pipeline temporarily
    debug:
      verbosity: basic

  # Combine everything into a single service definition
  service:
    # Pipelines operate on three telemetry data types: traces, metrics, and logs.
    # Each pipeline has its own set of receivers, processors and exporters.
    # docs: https://opentelemetry.io/docs/collector/architecture/#pipelines
    pipelines:
      metrics:
        # Reference receivers by their names from the config.receivers section above
        receivers: [otlp, k8s_cluster]
        # Reference processors by their names from the config.processors section above
        # IMPORTANT NOTE: order matters - processors run in the order listed here
        processors: [memory_limiter, k8sattributes, resource, batch]
        # Reference exporters by their names from the config.exporters section above
        exporters: [otlphttp/vmetrics]

      logs:
        receivers: [otlp, k8sobjects]
        processors: [memory_limiter, k8sattributes, resource, batch]
        exporters: [otlphttp/vlogs, debug]

    telemetry:
      metrics:
        readers:
          - pull:
              exporter:
                prometheus:
                  host: 0.0.0.0
                  port: 8888

В принципі, все описав в коментарях – але давайте коротко про те, що ми тут маємо:

mode="deployment": Gateway створюємо у вигляді Kubernetes Deployment з двома Pods
- для Kubernetes Agent будемо робити DaemonSet, бо він має працювати на кожній WorkerNode
receivers: описуємо вхідні дані – можуть бути PULL (самі звертаються до зовнішніх API), або PUSH (в них пушать агенти/колектори)
- otlp: ендпоінти для Kubernetes та AWS Agents
- k8s_cluster: звертається до Kubernetes API, отримує інформацію по Nodes, Pods, Events
- k8sobjects.objects="events": від Kubernetes API постійно отримує Kubernetes Events, записує у вигляді логів
processors:
- k8sattributes: додає атрибути до кожної метрики чи лога (namespace, deployment name, etc)
- resource.attributes: додає “глобальні” атрибути до кожного отриманого сигналу (див. OpenTelemetry Resource Attributes Explained Practically)
exporters: куди дані пишуть – бекенди, в нашому випадку передаємо до VictoriaMetrics, VictoriaLogs та VictoriaTraces
service: об’єднуємо все описане вище
- pipelines:
  - metrics: в якому порядку і що робити з метриками
  - logs: те саме – але для логів
  - пізніше тут буде пайплайн для traces
- telemetry: включаємо self monitoring – можемо подивитись на метрики самого OTel

Деплоїмо:

$ helm -n ops-monitoring-ns upgrade --install otel-gateway open-telemetry/opentelemetry-collector -f otel-gateway-values.yaml

Перевіряємо поди:

$ kubectl -n ops-monitoring-ns get pod -l app.kubernetes.io/instance=otel-gateway
NAME                                                    READY   STATUS    RESTARTS   AGE
otel-gateway-opentelemetry-collector-57b74ffd98-4pqhw   1/1     Running   0          68s
otel-gateway-opentelemetry-collector-57b74ffd98-td6hr   1/1     Running   0          68s

Kubernetes Service – його будуть використовувати Agents:

$ kubectl -n ops-monitoring-ns get svc -l app.kubernetes.io/instance=otel-gateway
NAME                                   TYPE        CLUSTER-IP       EXTERNAL-IP   PORT(S)                                                            AGE
otel-gateway-opentelemetry-collector   ClusterIP   172.20.204.222   <none>        6831/UDP,14250/TCP,14268/TCP,8888/TCP,4317/TCP,4318/TCP,9411/TCP   90s

Перевірка Metrics

І за хвилину можемо вже перевірити метрики по {k8s.cluster.name="eks-ops-1-33"}:

Де маємо метрику k8s.container.cpu_limit – це від k8s_cluster receiver, який сходив до /api/v1/pods в Kubernetes APIs і прочитав spec.containers[].resources.limits.cpu.

The Cardinality Issue

Тепер важливий момент – в лейблах бачимо багато різних ID, наприклад:

k8s.container.cpu_limit {..., container.id="a6a73186104e064e406330620b09bc367418ad4ce3564a1ef21d48de3597dad7", ..., k8s.pod.name="otel-gateway-opentelemetry-collector-57b74ffd98-td6hr",k8s.pod.start_time="2026-05-15T10:36:54Z",k8s.pod.uid="55b9990a-49e7-4913-be53-40d0d640cf72", ...}

Кожен раз, коли Kubernetes Pod перестворюється – для нього генерується нове значення в k8s.pod.uid.

Детально чому і як це впливає на VictoriaMetrics storage та навантаження описував в пості VictoriaMetrics: Churn Rate, High cardinality, метрики та IndexDB, але якщо коротко – кожне унікальне значення кожної лейбли збільшує і зайняте місце на диску, і розмір індексної бази VictoriaMetrics, та, відповідно, впливає на споживання CPU/RAM і швидкість пошуку.

Аби запобігти цьому – можемо додати ще один processor, який буде видаляти такі лейбли.

Порядок додавання в config.processors неважливий – він важливий в пайплайні, але логічно додати біля блоку resource:

...
  processors:
    ...
    resource:
      attributes:
        - key: k8s.cluster.name
          value: eks-ops-1-33
          action: upsert
        - key: cloud.provider
          value: aws
          action: upsert

    # Drop high-cardinality resource attributes from metrics only
    # These change on every pod recreation and cause series explosion in VictoriaMetrics.
    # Logs and traces keep them - useful for debugging specific pod instances.
    resource/drop_volatile_labels:
      attributes:
        - key: k8s.pod.uid
          action: delete
        - key: container.id
          action: delete
        - key: k8s.pod.start_time
          action: delete
...

Інший варіант – видаляти з -search.maxStalenessInterval=4h самої VictoriaMetrics, див. List of command-line flags.

При цьому пам’ятаємо, що у нас є два різних типи атрибутів, і, відповідно, це будуть різні processors:

record-level attributes: атрибути конкретного запису (i.e. container CPU usage)
resource-level attributes: атрибути джерела – додаються до всіх signals, які передаються до бекендів

Перевірити які саме атрибути треба модифікувати можна в документації конкретного processor, наприклад для k8sattributes processor:

The processor automatically discovers k8s resources (pods), extracts metadata from them and adds the extracted metadata to the relevant spans, metrics and logs as resource attributes.

Або в OTel specification, наприклад для Pod документація має URI /resource/k8s/#pod.

Додаємо новий processors в pipeline для merics – після resource, але перед batch:

...
  service:
    pipelines:
      metrics:
        receivers: [otlp, k8s_cluster]
        processors: [memory_limiter, k8sattributes, resource, resource/drop_volatile_labels, batch]
...

Чому саме така позиція в pipeline – тому всі ресурси в pipeline виконується в тому порядку, в якому вони описані, а обробка resource/drop_volatile_labels має йти:

після k8sattributes – бо саме він додає k8s.pod.uid, треба його викидати після того, як він з’явився
після resource – щоб resource processor вже встиг проставити свої лейбли
перед batch – щоб batch групував вже очищені дані

Апдейтимо деплой, перевіряємо:

І лейблів з .id більше нема

Тепер у нас є робочий OTel Gateway, в якому ми:

готові приймати дані майбутніх Agents та наших сервісів типу Backend API (порти 4317/4318)
збираємо cluster-level метрики (k8s_cluster)
збираємо K8s events як логи (k8sobjects)
доповнюємо k8s-метаданими (k8sattributes)
додаємо до всіх даних власні лейбли (k8s.cluster.name, cloud.provider)
контролюємо cardinality (resource/drop_volatile_labels)
маємо захист від OOM Killer (memory_limiter)
налаштували batch-експорт до VictoriaMetrics і VictoriaLogs

Що залишилось – AWS Collector для метрик з AWS CloudWatch та логів AWS ALB, і налаштувати отримання та передачу traces.

Перевірка Logs

Перевіряємо логи – запит {k8s.cluster.name="eks-ops-1-33"}.

Поки тут тільки логи по Kubernetes Events – логи Pods додамо пізніше з filelog в Kubernetes Agent:

Тут є дві невеликі – але проблеми:

поле _msg не сформоване
мусор в object.metadata.managedFields

Додавання transform для логів

Перевизначити що саме і як буде записано в лог можемо через processors.transform:

...
config:
  ...
  processors:

    ...
    # Normalize k8sobjects events: set readable body, drop noisy fields
    transform/k8s_events:
      #error_mode: ignore
      error_mode: propagate
      log_statements:
        - context: log
          statements:
            # k8sobjects stores the Event as a map in body.
            # VictoriaLogs flattens it into object.* fields automatically.
            # Build readable "REASON: note" message from body fields.
            - >-
              set(body, Concat([body["object"]["reason"], ": ", body["object"]["note"]], ""))
              where attributes["event.domain"] == "k8s" and attributes["k8s.resource.name"] == "events"
...

Тут ми самі формуємо поле body, яке VictoriaLogs використає для свого поля _msg.

Побачити як взагалі формується event object можна включивши debug exporter в detailed verbosity:

...
debug:
      verbosity: detailed
...

А потім додати його в logs pipeline:

...
logs:
        receivers: [otlp, k8sobjects]
        processors: [memory_limiter, k8sattributes, resource, batch]
        exporters: [otlphttp/vlogs, debug]
...

І потім просто подивитись логи подів з Gateway.

Додаємо transform/k8s_events до logs pipeline перед batch:

...
  service:
    pipelines:
      metrics:
        ...

      logs:
        receivers: [otlp, k8sobjects]
        processors: [memory_limiter, k8sattributes, resource, transform/k8s_events, batch]
        exporters: [otlphttp/vlogs, debug]
...

І тепер маємо красиве поле _msg:

Запуск Kubernetes Agent

Наступний крок – додати експортер, який вже буде збирати Pod level дані – метрики та логи.

Створюємо файл otel-k8s-agent-values.yaml:

# OTel Collector - Agent role (DaemonSet)
#
# Runs on every node, collects local data only:
#   - System metrics from host /proc, /sys (hostmetrics receiver)
#   - Pod/container metrics from local kubelet (kubeletstats receiver)
#   - Container logs from /var/log/pods (filelog receiver)
#
# Forwards everything to Gateway via OTLP gRPC.
# Gateway adds k8s metadata and exports to Victoria-* backends.

mode: daemonset

# contrib image has hostmetrics, kubeletstats, filelog receivers
image:
  repository: otel/opentelemetry-collector-contrib

# Mount host filesystem paths needed by hostmetrics and filelog
extraVolumes:
  - name: varlogpods
    hostPath:
      path: /var/log/pods
  - name: varlibdockercontainers
    hostPath:
      path: /var/lib/docker/containers
  - name: hostfs
    hostPath:
      path: /

extraVolumeMounts:
  - name: varlogpods
    mountPath: /var/log/pods
    readOnly: true
  - name: varlibdockercontainers
    mountPath: /var/lib/docker/containers
    readOnly: true
  - name: hostfs
    mountPath: /hostfs
    readOnly: true
    mountPropagation: HostToContainer

# Root is required to read /proc, /sys from the host
securityContext:
  runAsUser: 0
  runAsGroup: 0

resources:
  limits:
    cpu: 500m
    memory: 1Gi
  requests:
    cpu: 100m
    memory: 256Mi

# Agent must run on every node, including tainted ones
tolerations:
  - effect: NoSchedule
    operator: Exists
  - key: CriticalAddonsOnly
    operator: Exists
    effect: NoSchedule
  - key: CriticalAddonsOnly
    operator: Exists
    effect: NoExecute
  - key: BackendOnly
    operator: Exists
  - key: BackendDevOnly
    operator: Exists
  - key: BackendProdOnly
    operator: Exists
  - key: GitHubOnly
    operator: Exists
  - key: GitHubControllerOnly
    operator: Exists
  - key: GitHubRunnersOnly
    operator: Exists

# Inject node identity and host paths into the collector container
extraEnvs:
  - name: K8S_NODE_NAME
    valueFrom:
      fieldRef:
        fieldPath: spec.nodeName
  - name: K8S_POD_IP
    valueFrom:
      fieldRef:
        fieldPath: status.podIP
  # hostmetrics uses these env vars to read host /proc, /sys instead of container's
  - name: HOST_PROC
    value: /hostfs/proc
  - name: HOST_SYS
    value: /hostfs/sys
  - name: HOST_ETC
    value: /hostfs/etc
  - name: HOST_VAR
    value: /hostfs/var
  - name: HOST_RUN
    value: /hostfs/run
  - name: HOST_DEV
    value: /hostfs/dev

# Need read access to kubelet stats endpoint
clusterRole:
  create: true
  rules:
    - apiGroups: [""]
      resources: ["nodes/stats", "nodes/proxy", "nodes/metrics"]
      verbs: ["get"]
    - apiGroups: [""]
      resources: ["pods", "namespaces", "nodes"]
      verbs: ["get", "list", "watch"]

# Self-monitoring port
ports:
  metrics:
    enabled: true
    containerPort: 8888
    servicePort: 8888
    protocol: TCP

config:
  receivers:
    # PULL receiver
    # Reads node-level system metrics from host /proc and /sys
    # Replaces node_exporter functionality
    # Produces: system.cpu.*, system.memory.*, system.disk.*, system.network.*,
    #           system.filesystem.*, system.load.*, system.paging.*, system.processes.*
    hostmetrics:
      collection_interval: 30s
      root_path: /hostfs
      scrapers:
        cpu:
          metrics:
            system.cpu.utilization:
              enabled: true
        memory:
          metrics:
            system.memory.utilization:
              enabled: true
        disk:
        filesystem:
          exclude_mount_points:
            mount_points: ["/var/lib/kubelet/*", "/var/lib/docker/*", "/proc/*", "/sys/*"]
            match_type: regexp
          exclude_fs_types:
            fs_types: [tmpfs, devtmpfs, overlay, squashfs]
            match_type: strict
        network:
        load:
        paging:
        processes:

    # PULL receiver
    # Queries local kubelet (port 10250) for per-pod and per-container metrics
    # Replaces cadvisor functionality (which is built into kubelet)
    # Produces: k8s.node.*, k8s.pod.*, container.* (cpu/memory/network/filesystem)
    kubeletstats:
      collection_interval: 30s
      auth_type: serviceAccount
      endpoint: "https://${env:K8S_NODE_NAME}:10250"
      insecure_skip_verify: true
      metric_groups:
        - node
        - pod
        - container
        - volume

    # PULL receiver
    # Reads container logs from disk - standard CRI/containerd path
    # Replaces promtail / fluent-bit functionality
    # Container operator parses CRI log format and extracts k8s.* attributes from file path
    filelog:
      include:
        - /var/log/pods/*/*/*.log
      exclude:
        # Don't collect our own logs to avoid feedback loops
        - /var/log/pods/ops-monitoring-ns_otel-*/*/*.log
      start_at: end
      include_file_path: true
      include_file_name: false
      operators:
        - type: container
          id: container-parser

  processors:
    # Memory protection against traffic spikes
    memory_limiter:
      check_interval: 1s
      limit_percentage: 80
      spike_limit_percentage: 25

    # Tag everything with the node we're running on
    # Cluster-level attributes (k8s.cluster.name etc.) are added by Gateway
    resource:
      attributes:
        - key: k8s.node.name
          value: ${env:K8S_NODE_NAME}
          action: upsert

    # Batch records before sending to Gateway
    batch:
      send_batch_size: 8192
      timeout: 10s

  exporters:
    # Forward everything to Gateway via OTLP gRPC
    # Gateway will add k8s metadata and route to the right Victoria backend
    otlp:
      endpoint: otel-gateway-opentelemetry-collector.ops-monitoring-ns.svc.cluster.local:4317
      tls:
        insecure: true
      sending_queue:
        enabled: true
        num_consumers: 4
        queue_size: 1000
      retry_on_failure:
        enabled: true
        initial_interval: 5s
        max_interval: 30s

  service:
    pipelines:
      metrics:
        receivers: [hostmetrics, kubeletstats]
        processors: [memory_limiter, resource, batch]
        exporters: [otlp]

      logs:
        receivers: [filelog]
        processors: [memory_limiter, resource, batch]
        exporters: [otlp]

    telemetry:
      metrics:
        readers:
          - pull:
              exporter:
                prometheus:
                  host: 0.0.0.0
                  port: 8888

Тут маємо аналогічну до Gateway структуру – теж receivers, processors, exporters та pipelines.

Різниця в тому, як деплоїмо Pods, які receivers описуємо та куди виконуємо export:

mode="daemonset": Collector має бути запущеним на кожній WorkerNode кластеру
receivers:
- hostmetrics: node-level – CPP, RAM, диски, нетворк (аналог Prometheus Node Exporter)
- kubeletstats: метрики контейнерів (аналог cAdvisor_exporter)
- filelog: збираємо логи контейнерів (аналог Promtail/Filebeat/etc)
exporters: зібрані агентом дані передаємо до OTel Gateway – він їх обробить та передасть до VictoriaMetrics/Logs/Traces

Деплоїмо:

$ helm -n ops-monitoring-ns upgrade --install otel-k8s-agent open-telemetry/opentelemetry-collector -f otel-k8s-agent-values.yaml

Перевіряємо поди:

$ kubectl -n ops-monitoring-ns get pods -l app.kubernetes.io/instance=otel-k8s-agent
NAME                                                 READY   STATUS    RESTARTS   AGE
otel-k8s-agent-opentelemetry-collector-agent-2ft7s   1/1     Running   0          35s
otel-k8s-agent-opentelemetry-collector-agent-79gs2   1/1     Running   0          35s
otel-k8s-agent-opentelemetry-collector-agent-bdhsd   0/1     Pending   0          35s
...

За хвилину перевіряємо метрики в VictoriaMetrics – {__name__=~"k8s\\.pod\\.cpu\\..*", k8s.cluster.name="eks-ops-1-33"}:

Та логи, наприклад з {k8s.namespace.name="dev-backend-api-ns"}:

Тут не дуже ОК, що log streams створюються з таким великим набором labels:

_stream	{cloud.provider="aws",k8s.cluster.name="eks-ops-1-33",k8s.container.name="backend-celery-workers-container",k8s.container.restart_count="1",k8s.deployment.name="backend-celery-workers-deployment",k8s.namespace.name="dev-backend-api-ns",k8s.node.name="ip-10-0-37-96.ec2.internal",k8s.pod.name="backend-celery-workers-deployment-669c8bb67-vspzn",k8s.pod.start_time="2026-05-15T11:10:26Z",k8s.pod.uid="6c6c12e6-cade-41e4-aa80-20cb4e08a54a"}

Це теж можна вирішити з processor, який робили для metrics, або створити новий, наприклад:

resource/drop_log_labels:
      attributes:
        - key: k8s.pod.uid
          action: delete
        - key: k8s.container.restart_count
          action: delete

І потім підключити в logs pipeline:

...
      logs:
        receivers: [otlp, k8sobjects]
        processors: [memory_limiter, k8sattributes, resource, resource/drop_log_labels, transform/k8s_events, batch]
        exporters: [otlphttp/vlogs]
...

Але деякі лейбли можуть бути корисним – як-от k8s.container.restart_count.

Тому інший варіант – на самій VictoriaLogs передати collector.streamFields або collector.ignoreFields, можна зробити прямо в OTel Gateway через header VL-Stream-Fields:

...

    otlphttp/vlogs:
      endpoint: http://atlas-victoriametrics-victoria-logs-single-server.ops-monitoring-ns.svc.cluster.local:9428/insert/opentelemetry
      tls:
        insecure: true
      headers:
        VL-Stream-Fields: "k8s.cluster.name,k8s.namespace.name,k8s.deployment.name,k8s.container.name,k8s.pod.name"

...

Grafana і запити Prometheus vs OpenTelemetry

І трохи про те, що зміниться в Grafana та алертах.

Наприклад, є такий запит в Prometheus-форматі:

sum(container_memory_working_set_bytes{namespace="$namespace", pod="$pod", image!="", container!="POD", container!=""}) by (pod)

В OpenTelemetry форматі він буде виглядати так:

sum({__name__="container.memory.working_set", k8s.namespace.name="$namespace", k8s.pod.name="$pod"}) by (k8s.pod.name)

Результат на графіках – зверху старий, Prometheus, внизу – новий, OpenTelemetry:

Для VictoriaMetrics можна задати opentelemetry.usePrometheusNaming (див. List of command-line flags та Label sanitization) – тоді метрики будуть створюватись в форматі Prometheus з “_” замість “.“.

Але для VictoriaLogs та VictoriaTraces такої опції не бачу – спитаю девелоперів, чи є там якісь адекватні варіанти це вирішити.

Arch Linux: WireGuard Peer для підключення до MikroTik
5 (1)

8 Травня 2026

В пості MikroTik: налаштування WireGuard та підключення Linux peers описував налаштування MikroTik в ролі VPN Hub та підключення peer на Debian Linux.

Загалом, налатування на Arch Linux не відрізняються від Debian – але кожного разу починаю збирати потрібні конфіги по цьому блогу і іншим моїм хостам – тому опишу окремо, що було в одному місці, плюс тут є трохи нюансів з DNS та NteworkManager.

Власне, що треба буде зробити – встановити WireGuard, створити ключі та файл конфігу, на MikroTik створити новий Peer.

Установка WireGuard

Встановлюємо пакет wireguard-tools – в ньому йдуть всі утиліти + systemd-unit для запуску WireGuard:

$ sudo pacman -S wireguard-tools

Генерація ключів

Створюємо каталог /etc/wireguard/, в ньому генеруємо приватний та публічний ключі:

# mkdir /etc/wireguard/
# cd /etc/wireguard/
# wg genkey | sudo tee /etc/wireguard/privatekey | wg pubkey | sudo tee /etc/wireguard/publickey
0ClB2Lf5uQmWK8Nz0XRofuVkvbQbSfrf3ioHbYOm9F4=

На приватний ключ задаємо права на читання тільки root:

# chmod 600 /etc/wireguard/privatekey

Створення конфігу для WireGuard

В директорії /etc/wireguard/ створюємо файл wg0.conf:

[Interface]
PrivateKey = qIU***W4=
Address = 10.100.0.10/32
DNS = 192.168.0.1, 10.100.0.1

[Peer]
PublicKey = hxz***0o=
Endpoint = 178.***.***.184:51820

AllowedIPs = 10.100.0.0/24,192.168.0.0/24,192.168.100.0/24
PersistentKeepalive = 25

Тут:

[Interface]
- PrivateKey: приватний ключ на Arch Linux
- Address: IP-адреса цього Peer, буде використана для локального інтерфейсу wg0
[Peer]
- PublicKey: публічний ключ з MikroTik
- Endpoint: зовнішня адреса за якою доступний MikroTik, та порт, на якому WireGuard приймає підключення
- AllowedIPs: в які мережі може ходити цей peer і для яких будуть створені локальні роути

На Arch Linux отримуємо публічний ключ:

# cat /etc/wireguard/publickey 
0ClB2Lf5uQmWK8Nz0XRofuVkvbQbSfrf3ioHbYOm9F4=

Додаємо новий Peer на MikroTik:

/interface wireguard peers add interface=wg0 public-key="0Cl***9F4=" allowed-address=10.100.0.10/32,192.168.0.0/24,192.168.100.0/24 comment=setevoy-office

Перевіряємо:

/interface wireguard peers print where comment="setevoy-office-new" 
Columns: INTERFACE, PUBLIC-KEY, ENDPOINT-PORT, ALLOWED-ADDRESS
# INTERFACE  PUBLIC-KEY                                    ENDPOINT-PORT  ALLOWED-ADDRESS 
;;; setevoy-office-new
5 wg0        0ClB2Lf5uQmWK8Nz0XRofuVkvbQbSfrf3ioHbYOm9F4=              0  10.100.0.10/32  
                                                                          192.168.0.0/24  
                                                                          192.168.100.0/24

Можна підключатись – але можлива проблема з resolvconf та /etc/resolv.conf.

WireGuard та помилка “resolvconf: signature mismatch: /etc/resolv.conf”

На Arch Linux запускаємо підключення:

# systemctl start wg-quick@wg0
Job for [email protected] failed because the control process exited with error code.
See "systemctl status [email protected]" and "journalctl -xeu [email protected]" for details.

Перевіряємо статус:

# systemctl status [email protected]
× [email protected] - WireGuard via wg-quick(8) for wg0
     Loaded: loaded (/usr/lib/systemd/system/[email protected]; disabled; preset: disabled)
     Active: failed (Result: exit-code) since Fri 2026-05-08 08:57:47 EEST; 20s ago
...
May 08 08:57:47 setevoy-work wg-quick[1192596]: [#] wg addconf wg0 /dev/fd/63
May 08 08:57:47 setevoy-work wg-quick[1192596]: [#] ip -4 address add 10.100.0.10/32 dev wg0
May 08 08:57:47 setevoy-work wg-quick[1192596]: [#] ip link set mtu 1420 up dev wg0
May 08 08:57:47 setevoy-work wg-quick[1192644]: [#] resolvconf -a wg0 -m 0 -x
May 08 08:57:47 setevoy-work wg-quick[1192674]: resolvconf: signature mismatch: /etc/resolv.conf
May 08 08:57:47 setevoy-work wg-quick[1192674]: resolvconf: run `resolvconf -u` to update
May 08 08:57:47 setevoy-work wg-quick[1192596]: [#] ip link delete dev wg0
May 08 08:57:47 setevoy-work systemd[1]: [email protected]: Main process exited, code=exited, status=1/FAILURE

Проблема в тому, що в системі є і openresolv і NetworkManager з дефолтним dns=default – тобто NetworkManager пише /etc/resolv.conf напряму, без resolvconf.

При цьому openresolv тримає в файлі свій checksum для файлу /etc/resolv.conf, і коли NetworkManager перезаписує файл – контрольна сума не сходиться, через що resolvconf -a (який викликається wg-quick) падає з помилкою “signature mismatch“.

Option 1: PreUp та resolvconf -u (“грязний хак”)

Є “грязний хак” – додати до /etc/wireguard/wg0.conf опцію PreUp з запуском resolvconf -u:

[Interface]
PrivateKey = qIU***rW4=
Address = 10.100.0.10/32
DNS = 192.168.0.1, 10.100.0.1
PreUp = resolvconf -u

...

Цей варіант теж працює, але якщо NetworkManager перезапише /etc/resolv.conf вже після підняття тунелю (наприклад, при reconnect Wi-Fi) – DNS з тунелю злетять.

Тому краще просто переключити NetworkManager на використання systemd-resolved, аби він взагалі не писав файл напряму /etc/resolv.conf.

Option 2: NetworkManager та systemd-resolved (правильний варіант)

Редагуємо конфіг /etc/NetworkManager/NetworkManager.conf і додаємо блок [main] з опцією dns – див. DNS management:

[main]
dns=systemd-resolved

Стартуємо systemd-resolved і перезапускаємо NetworkManager:

# systemctl enable --now systemd-resolved && systemctl restart NetworkManager

Перевіряємо статус systemd-resolved:

# resolvectl status
Global
           Protocols: +LLMNR +mDNS -DNSOverTLS DNSSEC=no/unsupported
    resolv.conf mode: foreign
  Current DNS Server: 10.100.0.1
         DNS Servers: 192.168.0.1 10.100.0.1
...

Перевіряємо що тепер в /etc/resolv.conf:

# cat /etc/resolv.conf
# Generated by NetworkManager
nameserver 127.0.0.53
options edns0 trust-ad

127.0.0.53 – це і є наш локальний systemd-resolved:

# netstat -anp | grep 127.0.0.53
tcp        0      0 127.0.0.53:53           0.0.0.0:*               LISTEN      1221589/systemd-res 
udp        0      0 127.0.0.53:53           0.0.0.0:*                           1221589/systemd-res

Або з ss -lntup | grep 127.0.0.53 – але я звик до netstat.

Option 3: чистий openresolv (just in case)

Альтернатива – задати dns=none в NetworkManager: тоді NM взагалі не чіпає /etc/resolv.conf і єдиним менеджером файлу стає openresolv: він об’єднує записи від wg-quick і підключень NetworkManager напряму в /etc/resolv.conf зі списком реальних DNS-серверів (192.168.0.1, 10.100.0.1, …).

При такому варіанті systemd-resolved взагалі не потрібен – запити на DNS resolution йдуть напряму через glibc: простіше конфігурація і менше сервісів – але втрачаємо плюшки systemd-resolved: кешування, split-DNS, DNSSEC.

Власне, все – запускаємо WireGuard:

# systemctl start wg-quick@wg0
# systemctl enable wg-quick@wg0

Перевіряємо статус:

# wg show
interface: wg0
  public key: 0Cl***9F4=
  private key: (hidden)
  listening port: 47047

peer: hxz***50o=
  endpoint: 178.***.***.184:51820
  allowed ips: 10.100.0.0/24, 192.168.0.0/24, 192.168.100.0/24
  latest handshake: 20 seconds ago
  transfer: 12.06 KiB received, 8.13 KiB sent
  persistent keepalive: every 25 seconds

Перевіряємо підключення до MikroTik через VPN-тунель:

root@setevoy-work:/etc/wireguard # ssh [email protected]
...
[admin@mikrotik-rb4011-gw] >

Готово.

FreeBSD: Jails networking та менеджмент контейнерів з Bastille
0 (0)

4 Травня 2026

Іноді на FreeBSD треба запустити якісь сервіси, які офіційно FreeBSD не підтримують, і власне, цей пост з’явився через те, що я встановлював Open WebUI на своєму NAS – і як раз Open WebUI простіше було зробити на Linux.

Тому підняв його у FreeBSD Linux jail, а для створення контейнеру взяв Bastille, яка спрощує менеджмент.

Про сам Open WebUI може допишу чорнетку, а Bastille вирішив винести окремим постом – бо зараз буду сетапити Hermes Agent (вже – див. Hermes Agent: запуск AI Agent у FreeBSD Jail з Bastille, і хочеться мати таку собі коротку інструкцію по тому, як працювати з FreeBSD jails використовуючи Bastille.

Про сам мій NAS є ціла серія постів, вже 15 штук, див. початок у FreeBSD: Home NAS, part 1 – налаштування ZFS mirror.

What is the FreeBSD Jails та Bastille?

Щоб відповісти на це питання – треба спочатку згадати що таке FreeBSD Jails.

FreeBSD jails – аналог Docker/ContainerD в Linux – але з’явились набагато раніше, ніж Linux LXC та namespaces та cgroups, які потім “еволюціонували” в Docker. Про Linux cgroups писав детально у Kubernetes: Pod resources.requests, resources.limits та Linux cgroups.

FreeBSD jails з’явились ще у 1999 році як розвиток “неповноцінної” системи chroot, яка не давала повної ізоляції. З jails з’явилась можливість відокремлення filesystem, мати окремий network stack, власні PIDs і так далі – власне все те, до чого ми звикли в Linux та його контейнерах.

Як раз на днях зустрів цікавий пост на цю тему, де серед іншого говориться і за історію контейнеризації – Your Container Is Not a Sandbox.

На відміну від контейнерів в Linux – FreeBSD jails це єдина частина ядра системи, тоді як Linux – це комбінація різних механізмів (namespaces, cgroups).

Правда, вона має і недоліки – бо це все одно залишається одне і там саме ядро FreeBSD, зато вона простіша – а тому безпечніша і простіша в роботі та дебагу.

Власне, Bastille – це розвиток системи jails, точніше – система для спрощення менеджменту контейнерів у FreeBSD, аби не писати jail.conf руками і мати простий CLI для управління (як Docker – це “обгортка” для Linux containers).

Не Bastille єдиною – є аналогічні рішення як-от iocage, ezjail, pot та інші.

Чому взяв Bastille – проект активно розвивається, є велике комьюніті, має зручний CLI та добре інтегрується з можливостями ZFS.

Установка Bastille

Встановлюємо з репозиторію, додаємо в автостарт:

[root@test-free-15-bastille ~]# pkg install bastille
[root@test-free-15-bastille ~]# sysrc bastille_enable=YES
bastille_enable:  -> YES

Перевіряємо ім’я ZFS Pool:

[root@test-free-15-bastille ~]# zpool list -Ho name
zroot

Див. ZFS Support.

Додаємо підтримку ZFS до Bastille – файл /usr/local/etc/bastille/bastille.conf:

...
## ZFS options
bastille_zfs_enable="YES"
bastille_zfs_zpool="zroot"
bastille_zfs_prefix="bastille"
...

Bastille setup: базові налаштування системи

Перевіряємо версію хоста:

[root@test-free-15-bastille ~]# freebsd-version
15.0-RELEASE

Можна виконати bastille setup – система сама налаштує мережу, про мережу трохи детальніше далі:

[root@test-free-15-bastille ~]# bastille setup
bastille_enable: YES -> YES

ZFS has already been configured!

Configuring bastille0 loopback interface
cloned_interfaces:  -> lo1
ifconfig_lo1_name:  -> bastille0

Bringing up new interface: [bastille0]
Created clone interfaces: lo1.
bastille_network_loopback: bastille0 -> bastille0
bastille_network_shared:  -> 

Loopback interface successfully configured: [bastille0]

Determined default network interface: (em0)
/usr/local/etc/bastille/pf.conf does not exist: creating...
pf_enable: NO -> YES
Bastille pf ruleset created. Please review '/usr/local/etc/bastille/pf.conf' and enable pf using 'service pf start'.

Bastille has successfully been configured.

Відразу включило Packet Filter – треба для NAT, і створило правила. Див. FreeBSD: Home NAS, part 2 – знайомство з Packet Filter (PF) firewall.

Якщо PF не запущений – запускаємо (якщо по SSH – підключення буде розірване):

[root@test-free-15-bastille ~]# service pf start

І після setup вже маємо новий loopback інтерфейс:

[root@test-free-15-bastille ~]# ifconfig bastille0
bastille0: flags=8008<LOOPBACK,MULTICAST> metric 0 mtu 16384
        options=680003<RXCSUM,TXCSUM,LINKSTATE,RXCSUM_IPV6,TXCSUM_IPV6>
        groups: lo
        nd6 options=21<PERFORMNUD,AUTO_LINKLOCAL>

Мережа для jails

Документація – Networking та класний пост Managing Jails in FreeBSD with Bastille (2022 рік, але в цілому актуальний).

Bastille підтримує кілька тип нетворку:

VNET (DHCP): Bastille створює інтерфейс з типом bridge і підключає jail через epair – кожен jail отримує власні MAC та IP адреси, і виглядає як окремий хост у мережі
Bridged VNET (own bridge): те саме, але bridge створюється вручну – використовується для кастомних або ізольованих мереж
Alias/Shared Interface: один інтерфейс хоста, IP-адреси для jail-ів додаються як alias фізичного інтерфейсу хоста – простий варіант, але без окремого network stack (тобто у всіх буде загальний фаервол самого хоста, роутинг тощо)
NAT/Loopback Interface: jail отримує IP у внутрішній мережі і ходить в “світ” через NAT хоста, для доступу ззовні до jail потрібен port forwarding
Inherit: jail використовує той самий IP і інтерфейс, що й хост, використовується рідко – зазвичай для специфічних кейсів, доступ розділяється по портах – незручно, не гнучко, не масштабується

Далі детальніше подивимось на три основних типи – VNET, Alias та NAT.

Bastille bootstrap

Запускаємо bastille bootstrap, аналог docker pull – скачати базовий архів з системою, яку передамо аргументом, та розархівувати його для подальшого використання.

Якщо робимо контейнер з FreeBSD, то версія системи в jail повинна бути =< версії хоста – перевіряємо її з freebsd-version:

[root@test-free-15-bastille ~]# freebsd-version 
15.0-RELEASE

Готуємо “образ” з цією версією:

[root@test-free-15-bastille ~]# bastille bootstrap 15.0-RELEASE

Attempting to bootstrap FreeBSD release: 15.0-RELEASE

Fetching MANIFEST...
/usr/local/bastille/cache/15.0-RELEASE/MANIFES        1044  B 7334 kBps    00s

Fetching distfile: base.txz
/usr/local/bastille/cache/15.0-RELEASE/base.tx         157 MB 8232 kBps    19s

Validating checksum for archive: base.txz
MANIFEST: ac0c933cc02ee8af4da793f551e4a9a15cdcf0e67851290b1e8c19dd6d30bba8
DOWNLOAD: ac0c933cc02ee8af4da793f551e4a9a15cdcf0e67851290b1e8c19dd6d30bba8

Extracting archive: base.txz

Bootstrap successful.

І маємо нові ZFS datasets:

[root@test-free-15-bastille ~]# zfs list -r zroot/bastille
NAME                                   USED  AVAIL  REFER  MOUNTPOINT
zroot/bastille                         532M  65.9G   120K  /usr/local/bastille
zroot/bastille/backups                  96K  65.9G    96K  /usr/local/bastille/backups
zroot/bastille/cache                   158M  65.9G    96K  /usr/local/bastille/cache
zroot/bastille/cache/15.0-RELEASE      158M  65.9G   158M  /usr/local/bastille/cache/15.0-RELEASE
zroot/bastille/jails                    96K  65.9G    96K  /usr/local/bastille/jails
zroot/bastille/logs                     96K  65.9G    96K  /var/log/bastille
zroot/bastille/releases                374M  65.9G    96K  /usr/local/bastille/releases
zroot/bastille/releases/15.0-RELEASE   374M  65.9G   374M  /usr/local/bastille/releases/15.0-RELEASE
zroot/bastille/templates                96K  65.9G    96K  /usr/local/bastille/templates

Тепер у нас все готове для створення контейнерів – подивимось, як робити jails з FreeBSD та Linux та різними налаштуваннями мережі.

Створення jails

Якщо запускаємо у VirtualBox – включаємо Promiscuous Mode в Allow All:

Створення FreeBSD jails

Спочатку зробимо кілька контейнерів з FreeBSD і різними параметрами мережі – а потім запустимо jail з Linux.

Всі створені jail зберігаються в директорії /usr/local/bastille/jails/ – там для кожного контейнера буде директорія з його ім’ям та файлом jail.conf, який описує параметри цього контейнеру.

Network type VNET

Першим глянемо варіант з VNET – я ним користуюсь найбільше, бо зручно мати прямий доступ в контейнери, плюс повноцінна ізоляція на рівні мережі.

Аби задати тип нетворка VNET – до bastille create передаємо опцію --vnet (або коротка форма -V), потім ім’я jail, версію системи, IP-адресу та інтерфейс хоста для створення bridge.

Інтерфейс можна не передавати, якщо заданий bastille_network_gateway в /usr/local/etc/bastille/bastille.conf.

Замість передачі IP явно – можна вказати опцію DHCP або SYNCDHCP – тоді jail отримає адресу від роутера:

[root@test-free-15-bastille ~]# bastille create --vnet testjailVnetIp 15.0-RELEASE 192.168.0.205/24 em0

Attempting to create jail: testjailVnetIp

Valid IP: 192.168.0.205/24

...

[testjailVnetIp]:
e0a_bastille1
e0b_bastille1
testjailVnetIp: created

[root@test-free-15-bastille ~]# bastille list
 JID  Name            Boot  Prio  State  Type   IP Address     Published Ports  Release       Tags
 2    testjailVnetIp  on    99    Up     thin   192.168.0.205  -                15.0-RELEASE  -

Deep dive: VNET networking

Трохи детально згадував як працює нетворкінг, в принципі цю частину можна пропустити, але якщо цікаво – то подивимось, як пакет з ноутбука в локальній мережі з FreeBSD-хостом попадає всередину jail.

Тут в прикладі маємо всі хости в одній мережі 192.168.0.0/24:

робочий ноутбук з Arch Linux
хост FreeBSD з jail – 192.168.0.72
і, власне, сам jail з IP 192.168.0.205

Інтерфейси

Перевіряємо інтерфейси на хості FreeBSD:

[root@test-free-15-bastille ~]# ifconfig 
em0: [...]
        ...
        ether 08:00:27:d5:55:b2
        inet 192.168.0.72 netmask 0xffffff00 broadcast 192.168.0.255
        ...
em0bridge: [...]
        ...
        ether 58:9c:fc:10:fa:c0
        ...
        member: e0a_bastille1 [...]
                ...
        member: em0 [...]
                ...
        groups: bridge
        ...
e0a_bastille1: [...]
        description: vnet0 host interface for Bastille jail testjailVnetIp
        ...
        ether 02:20:99:d5:55:b2
        ...
        groups: epair
        ...

Що у нас тепер є:

інтерфейс em0:
- IP: 192.168.0.72
- MAC: 08:00:27:d5:55:b2
інтерфейс em0bridge: L2 switch – передає пакети між своїми members
- groups: bridge
- member: em0
  - port 1
- member: e0a_bastille1
  - port 5
інтерфейс e0a_bastille1 (з a): host side epair
- groups: epair
- ether 02:20:99:d5:55:b2

А інтерфейс e0b_bastille1 (з b) створюється всередині jail – тільки з іменем vnet0 (для зручності).

Перевіряємо з jexec <jailname> ifconfig:

[root@test-free-15-bastille ~]# jexec testjailVnetIp ifconfig
lo0: [...]
        ...
vnet0: [...]
        description: jail interface for em0
        ...
        ether 0e:20:99:d5:55:b2
        ...
        inet 192.168.0.205 netmask 0xffffff00 broadcast 192.168.0.255
        groups: epair
        ...

Де бачимо, що у vnet0 той самий MAC 0e:20:99:d5:55:b2 як і на хості у інтерфейсів e0a_bastille1 та em0.

Data flow та ARP table

І тепер можна прослідкувати процес передачі даних до jail:

з ноутбука виконуємо ssh 192.168.0.205 – на jail IP
ноутбук виконує broadcast ARP-запит в мережу 192.168.0.0/24 – “хто має 192.168.0.205?“
фізичний інтерфейс em0 на хості отримує цей запит, ядро визначає, що em0 – це member bridge-інтерфейсу em0bridge на port 1, і передає дані на em0bridge
em0bridge передає його до своїх members, на інші ports – в нашому випадку до e0a_bastille1 на port 5
e0a_bastille1 – це “вхідний” socket, а e0b_bastille1 – його “вихід” всередині jail
- для аналогії можна згадати socketpair(), який обєднує два socket, кожен з власним file descritor – на “вході” та на “виході”: все, що записується на “вхідний” сокет – попадає на другий сокет зв’язаної пари
інтерфейс vnet0 в jail отримує цей запит, відповідає ноутбуку “це мій IP” та повертає свій MAC
ноутбук записує цей MAC в свою ARP table

Подивитись ARP на Arch Linux можемо з ip neigh show:

[setevoy@setevoy-work ~]  $ ip neigh show 
192.168.0.205 dev enp0s13f0u3u4c2 lladdr 0e:20:99:d5:55:b2 REACHABLE
...

Далі, при формуванні пакету для цього jail – ядро хоста Arch Linux сформує Ethernet frame (див. TCP/IP: моделі OSI та TCP/IP, TCP-пакети, Linux sockets і порти), в якому буде IP packet:

на OSI layer 2 (Ethernet frame) headers:
- src MAC: MAC інтерфейсу – в моєму випадку enp0s13f0u3u4c2
- dst MAC: 0e:20:99:d5:55:b2 (MAC FreeBSD em0 та jail e0b_bastille1)
OSI layer 3 (IP packet) headers:
- src IP: IP хоста з Arch Linux
- dst IP: 192.168.0.205 – jail IP

А процес доставки даних в jail виглядає так:

ноутбук формує Ethernet frame з dst MAC 0e:20:99:d5:55:b2
фрейм через роутер/свіч домашньої мережі попадає на em0 хоста FreeBSD
ядро FreeBSD “бачить”, що em0 – це member групи em0bridge та передає дані на e0a_bastille1
пакет “входить” до e0a_bastille1 – і “виходить” у e0b_bastille1 – інтерфейсі vnet0 всередині нашого jail
ядро в jail розпаковує Ethernet фрейм, перевіряє dst IP (192.168.0.205) та dst Port (22), бачить, що це його IP, а на порту 22 є демон SSH – і передає IP пакет до SSH

Начебто вірно описав.

Тепер, як трохи розібрались з мережею – можна створювати контейнери далі.

Підключення до jail

Підключитись з хоста можемо з bastille console:

[root@test-free-15-bastille ~]# bastille console testjailVnetIp

[testjailVnetIp]:
root@testjailVnetIp:~ #

В контейнері запускаємо sshd:

root@testjailVnetIp:~ # sysrc sshd_enable="YES"
sshd_enable: NO -> YES
root@testjailVnetIp:~ # service sshd start
...
Starting sshd.

Додаємо юзера:

root@testjailVnetIp:~ # pw useradd setevoy -m -s /bin/sh
root@testjailVnetIp:~ # passwd setevoy

І підключаємось з ноутбука:

[setevoy@setevoy-work ~]  $ ssh [email protected]
([email protected]) Password for setevoy@testjailVnetIp:
...
setevoy@testjailVnetIp:~ $

Network type Alias/Shared Interface

При Alias/Shared Interface на інтерфейс em0 просто буде доданий другий IP як аліас.

Створюємо контейнер – без додаткових опцій, тільки IP-адресу та інтерфейс хоста, як в прикладі з VNET:

[root@test-free-15-bastille ~]# bastille create testjailAlias 15.0-RELEASE 192.168.0.206 em0

Attempting to create jail: testjailAlias

Valid IP: 192.168.0.206

Valid interface: em0

...

[testjailAlias]:
testjailAlias: created

Перевіряємо на хості – тепер маємо дві адреси:

[root@test-free-15-bastille ~]# ifconfig 
em0: flags=1008943<UP,BROADCAST,RUNNING,PROMISC,SIMPLEX,MULTICAST,LOWER_UP> metric 0 mtu 1500
        ...
        inet 192.168.0.72 netmask 0xffffff00 broadcast 192.168.0.255
        inet 192.168.0.206 netmask 0xffffffff broadcast 192.168.0.206
        ...
lo0: flags=1008049<UP,LOOPBACK,RUNNING,MULTICAST,LOWER_UP> metric 0 mtu 16384
        ...
bastille0: flags=8008<LOOPBACK,MULTICAST> metric 0 mtu 16384
        ...
em0bridge: flags=1008843<UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST,LOWER_UP> metric 0 mtu 1500
        ...
e0a_bastille1: flags=1008943<UP,BROADCAST,RUNNING,PROMISC,SIMPLEX,MULTICAST,LOWER_UP> metric 0 mtu 1500
        description: vnet0 host interface for Bastille jail testjailVnetIp
        ...

А в контейнері – всі ті самі інтерфейси, що і на хості, але для em0 тільки один IP:

[root@test-free-15-bastille ~]# jexec testjailAlias ifconfig
em0: flags=1008943<UP,BROADCAST,RUNNING,PROMISC,SIMPLEX,MULTICAST,LOWER_UP> metric 0 mtu 1500
        ...
        ether 08:00:27:d5:55:b2
        inet 192.168.0.206 netmask 0xffffffff broadcast 192.168.0.206
        ...
lo0: flags=1008049<UP,LOOPBACK,RUNNING,MULTICAST,LOWER_UP> metric 0 mtu 16384
        ...
bastille0: flags=8008<LOOPBACK,MULTICAST> metric 0 mtu 16384
        ...
em0bridge: flags=1008843<UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST,LOWER_UP> metric 0 mtu 1500
        ...
e0a_bastille1: flags=1008943<UP,BROADCAST,RUNNING,PROMISC,SIMPLEX,MULTICAST,LOWER_UP> metric 0 mtu 1500
        ...

Тепер, якщо ми не запустимо sshd в контейнері – то підключення на IP 192.168.0.206 піде на SSH daemon самого хоста – “Password for setevoy@test-free-15-bastille”

[setevoy@setevoy-work ~] $ ssh -o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null [email protected]
Warning: Permanently added '192.168.0.206' (ED25519) to the list of known hosts.
([email protected]) Password for setevoy@test-free-15-bastille:

А якщо маємо відкритий порт 22 в контейнері:

root@testjailAlias:~ # service sshd onestart

То запит піде на нього – “Password for setevoy@testjailAlias“:

[setevoy@setevoy-work ~] $ ssh -o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null [email protected]
Warning: Permanently added '192.168.0.206' (ED25519) to the list of known hosts.
([email protected]) Password for setevoy@testjailAlias:

Простіше за VNET – але маємо загальні правила Packet Filter, фаервола на хості, нема можливості отримати адресу з DHCP, можливі проблеми з overlapping ports, і важливе: якщо ламають наш jail – то отримують доступ до всієї мережі хоста.

Network type NAT

І останній на сьогодні приклад – з NAT, тільки тепер задаємо IP не з пулу домашньої мережі, а в інтерфейсі вказуємо loopback інтерфейс хоста bastille0:

[root@test-free-15-bastille ~]# bastille create testjailNat 15.0-RELEASE 10.0.0.10 bastille0

Attempting to create jail: testjailNat

Valid IP: 10.0.0.10

Valid interface: bastille0

...

Перевіряємо джейли тепер:

[root@test-free-15-bastille ~]# bastille list
 JID  Name            Boot  Prio  State  Type   IP Address     Published Ports  Release       Tags
 4    testjailAlias   on    99    Up     thin   192.168.0.206  -                15.0-RELEASE  -
 6    testjailNat     on    99    Up     thin   10.0.0.10      -                15.0-RELEASE  -
 2    testjailVnetIp  on    99    Up     thin   192.168.0.205  -                15.0-RELEASE  -

Роутинг пакетів до jail піде через Packet Filter:

[root@test-free-15-bastille ~]# pfctl -s nat
nat on em0 from <jails> to any -> (em0:0)
rdr-anchor "rdr/*" all

Запускаємо SSH в контейнері:

[root@test-free-15-bastille ~]# bastille service testjailNat sshd onestart

[testjailNat]:
Generating RSA host key.
...
Starting sshd.

Маємо підключення з хоста на 10.0.0.10:

[root@test-free-15-bastille ~]# ssh 10.0.0.10
...
([email protected]) Password for root@testjailNat:

А для підключення із зовнішньої мережі – на хості вмикаємо port forwarding (bastille rdr – redirect через Packer Filter):

[root@test-free-15-bastille ~]# bastille rdr testjailNat tcp 2222 22
IPv4 tcp/2222:22 on em0

І підключаємось з SSH на IP хоста FreeBSD, але порт задаємо 2222, і попадаємо в новий Jail – “Password for setevoy@testjailNat“:

[setevoy@setevoy-work ~]  $ ssh -p 2222 [email protected]
...
([email protected]) Password for setevoy@testjailNat:

І на останок – jails з Linux.

Створення Linux Jails

Документація – Linux Jails.

Важливе обмеження Linux jail – для мережі недоступні VNET-опції. Тобто з варіантів – або NAT і port-forward, або Alias з усіма його обмеженнями і можливими проблемами.

Крім того – “Linux jails are still considered experimental” – хоча в цілому працює достатньо стабільно.

Для Linux нам потрібно виконати bastille setup linux – тоді Bastille підтягне потрібні модулі і скрипти:

[root@test-free-15-bastille ~]# bastille setup linux
[WARNING]: Running linux jails requires loading additional kernel
modules, as well as installing the 'debootstrap' package.
Do you want to proceed with setup? [y|n]:y

Loading kernel module: fdescfs

Persisting module: fdescfs
fdescfs_load:  -> YES

Loading kernel module: linprocfs

Persisting module: linprocfs
linprocfs_load:  -> YES

Loading kernel module: linsysfs

Persisting module: linsysfs
linsysfs_load:  -> YES

Loading kernel module: linux

Loading kernel module: linux64
linux_enable: NO -> YES

...

Тепер в директорії /usr/local/share/debootstrap/scripts/ маємо набір shell-скриптів, які налаштують Linux-оточення:

[root@test-free-15-bastille ~]# less /usr/local/share/debootstrap/scripts/gutsy 
case $ARCH in
  amd64|i386)
        case $SUITE in
          gutsy|hardy|intrepid|jaunty|karmic|lucid|maverick|natty|oneiric|precise|quantal|raring|saucy|utopic|vivid|wily|yakkety|zesty)
        default_mirror http://old-releases.ubuntu.com/ubuntu
...
keyring /usr/local/share/keyrings/ubuntu-archive-keyring.gpg

Виконуємо bootstrap, вказуємо ім’я системи – власне, ім’я скрипта з /usr/local/share/debootstrap/scripts/.

Але для Ubuntu остання доступна версія – Jammy, 22.04.

Займе хвилин 10-15, може і більше поки все скачає:

[root@test-free-15-bastille ~]# bastille bootstrap jammy

Attempting to bootstrap Linux/Ubuntu release: Ubuntu_2204

Ensuring Linux compatability...

...

Потім створюємо контейнер з create та опцією --linux (-L):

[root@test-free-15-bastille ~]# bastille create -L openwebui jammy 192.168.0.207/24 em0

...

[openwebui]:
openwebui: created

І маємо контейнер з “Ubuntu”:

[root@test-free-15-bastille ~]# bastille cmd openwebui lsb_release -a

[openwebui]:
No LSB modules are available.
Distributor ID: Ubuntu
Description:    Ubuntu 22.04 LTS

Bastille та Jails management – основні команди

І трохи про основні доступні команди для роботи з контейнерами, див. також приклади у FreeBSD Jails with Bastille – свіжий, 2025 року.

Документація – Bastille sub-commands.

clone: скопіювати jail (див. Limitations – є нюанси з інтерфейсами)
cmd: виконати команду в jail:

[root@test-free-15-bastille ~]#  bastille cmd testjailNat ps 

[hermesagent1]:
  PID TT  STAT    TIME COMMAND
63825  2  R+J  0:00.00 ps

config: отримати чи змінити параметр :

[root@test-free-15-bastille ~]#  bastille config testjailVnetIp get vnet.interface
e0b_bastille1

cp: скопіювати файл з хоста в jail
destroy: видалити jail та всі його дані
export: створити архів в усіма даними jail, потім import можна відновити на іншому хості
mount: підключити файл чи каталог з хоста в контейнер
restart: перезапустити jail
top, htop: ресурси та процеси в контейнері

Також варто подивитись на bastille monitor – є цікаві можливості з моніторингу і алертингу, та Templates – створення контейнерів з шаблонів які можна взяти з BastilleBSD/templates або створювати власні.

А з bastille zfs – можна створювати ZFS snapshots контейнерів (див. FreeBSD: Home NAS, part 5 – ZFS pool, datasets, snapshots та моніторинг).

Hermes Agent: запуск AI Agent у FreeBSD Jail з Bastille
5 (1)

3 Травня 2026

По самому Hermes Agent і його можливостям буду писати окремо, сьогодні – як запустити його на FreeBSD.

Вчора погрався на своєму Arch Linux – тепер хочеться вже більш production setup.

Крутити буду на моєму NAS з FreeBSD, запускати там, звісно, вже тільки у FreeBSD Jail, бо NAS – це доступ до важливих даних і бекапів.

На Linux налаштування агента всі ті самі – тільки простіший сетап, тому окремо описувати не буду.

А от по можливостям Hermes Agent і більш детальний конфіг – зроблю окремий пост, бо там є, що потрогати.

Для роботи з Jails використовую Bastille – про неї теж якось окремо напишу, є чорнетка.

Власне, що будемо робити:

створимо FreeBSD Jail
налаштуємо мережу
встановимо сам Hermes Agent
налаштуємо підключення до Telegram
і встановимо Hermes Agent Web UI

Поїхали.

Але спочатку трохи оффтопік 🙂

Holywar: FreeBSD Jail чи “контейнер”?

Тут коротко – чи вірно казати “контейнер” про FreeBSD Jail – бо мене можуть заплювати 🙂

Як людина, яка зазвичай працює з Linux, то для мене “контейнер” це і FreeBSD Jail – і Linux Docker, тому в цьому пості буду все ж про Jails казати “контейнери”.

Ба більше – навіть в офіційній документації Bastille говориться:

While reading the documentation and using Bastille, you will find that sometimes “container” is used, and sometimes “jail” is used. These are completely interchangeable, but there is some debate as to which one is more correct. Be that as it may, anytime you read “container” or “jail”, it means a FreeBSD jail.

Крім того, читачі мого блогу в основному теж Linux users – тому нехай вже буде “контейнери”. А в окремому пості по Bastille трохи детальніше поговоримо про Jails у FreeBSD vs Linux containers.

Все – тепер погнали робити установку.

FreeBSD: створення Jail з Bastille

Перевіряємо версію FreeBSD, готуємо контейнер:

root@setevoy-nas:~ # freebsd-version 
14.4-RELEASE-p1

root@setevoy-nas:~ # bastille bootstrap 14.4-RELEASE
...

Створюємо сам контейнер – звичайний FreeBSD (Bastille підтримує і Linux, в мене є Jail з Opeb WebUI, якось про нього допишу, теж чорнетка є).

Мережа – Bastille VNET, тобто контейнер буде доступний із моєї загальної мережі по IP 192.168.0.210:

root@setevoy-nas:~ # bastille create --vnet hermesagent1 14.4-RELEASE 192.168.0.210/24 em0

Attempting to create jail: hermesagent1

Valid IP: 192.168.0.210/24

Creating a thinjail...

...

Перевіряємо статус Jail:

root@setevoy-nas:~ # bastille list hermesagent1
 JID  Name          Boot  Prio  State  Type   IP Address     Published Ports  Release               Tags
 3    hermesagent1  on    99    Up     thin   192.168.0.210  -                14.4-RELEASE          -

Підключаємось всередину:

root@setevoy-nas:~ # bastille console hermesagent1

[hermesagent1]:
root@hermesagent1:~ #

Встановлюємо апдейти:

root@hermesagent1:~ # pkg update

Встановлюємо пакети для установки Hermes Agent:

root@hermesagent1:~ # pkg install curl bash uv sudo

Перевіряємо де у нас bash – бо на FreeBSD він в /usr/local/bin/, а не /usr/bin:

root@hermesagent1:~ # which bash
/usr/local/bin/bash

Створюємо юзера для Hermes Agent, задаємо йому пароль:

root@hermesagent1:~ # pw useradd hermes -m -s /usr/local/bin/bash -c "Hermes Agent"
root@hermesagent1:~ # passwd hermes

Включаємо SSH:

root@hermesagent1:~ # sysrc sshd_enable="YES"
sshd_enable: NO -> YES

root@hermesagent1:~ # service sshd start

Перевіряємо підключення з робочого ноутбука:

[setevoy@setevoy-work ~]  $ ssh [email protected]
([email protected]) Password for hermes@hermesagent1:
...
[hermes@hermesagent1 ~]$

Запускаємо visudo, додаємо юзера туди – із запитом пароля:

hermes ALL=(ALL:ALL) ALL

Аби запускати Hermes CLI від рута – додаємо до /root/.profile:

...
# Hermes Agent — ensure ~/.local/bin is on PATH
export PATH="$HOME/.local/bin:$PATH"

Тут все – можна встановлювати сам агент.

Установка Hermes Agent

Встановлюємо необхідні бібліотеки – бо автоматичний інсталер самого Hermes Agent не дуже дружить з FreeBSD, тому руками:

root@hermesagent1:~ # pkg install -y python3 py311-pip py311-sqlite3 sqlite3 git curl rust pkgconf openssl libffi node22 npm-node22 ripgrep ffmpeg

Запускаємо установку – зайняло хвилин 5:

[hermes@hermesagent1 ~]$ curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash

По завершенню інсталятор запропонує налаштувати агента.

Hermes Agent Setup

На Arch Linux я робив швидку установку, тут запустив повну – подивитись, що там є.

Всі опції можна потім змінити, так що не критично.

Документація – Configuration.

Запускаємо налаштування агенту:

Токенів він жре багато, тому Claude в прольоті – взяв OpenAI та GPT 5.5, працює чудово:

Просить провести аутентифікацію – відкриває посилання на ноутбуці з браузером, вводимо код:

Задаємо модель 5.5 – пізніше можна змінити з /model (див. Slash Commands):

І далі вже все можна залишити по дефолту, поки не дійдемо до Messaging.

Telegram setup

Документація – Telegram Setup.

Вибір тут, звісно, великий – я поки буду користуватись Telegram:

Переходимо до @BotFather, створюємо нового бота:

Налаштовуємо його:

Важливо – див. Step 3: Privacy Mode (Critical for Groups).

Переходимо в його Settings:

Відключаємо Group Privacy:

Отримуємо API-токен бота:

Аби ми могли писати боту – знаходимо свій User ID з @userinfobot.

Якщо бот буде в групі чи каналі – в тому ж боті жеж можна знайти їх ID.

Я цього бота роблю для тесту, тому залишаю мого юзера:

І в “home channel” теж:

Готово:

Далі ще налаштування браузера та Tools – там залишаємо все дефолтними, і готово:

Telegram та Hermes Agent Gateway на FreeBSD

На Linux Hermes Gateway включається просто через systemd – на FreeBSD трохи “ручками” (в лапках – бо зробив це самим агентом 🙂 ).

Перевіряємо статус зараз:

[hermes@hermesagent1 ~]$ hermes gateway status
✗ Gateway is not running

To start:
  hermes gateway run      # Run in foreground
  hermes gateway install  # Install as user service
  sudo hermes gateway install --system  # Install as boot-time system service

Команда hermes gateway install на FreeBSD очікувано повернула “not supported on this platform“:

[root@hermesagent1 /usr/home/hermes]# /home/hermes/.hermes/hermes-agent/venv/bin/hermes gateway install --system
Service installation not supported on this platform.
Run manually: hermes gateway run

Перевіряємо де саме лежить Hermes:

[hermes@hermesagent1 ~]$ head -1 "$(command -v hermes)"
#!/home/hermes/.hermes/hermes-agent/venv/bin/python3

Встановлюємо Python-модуль python-telegram-bot:

[hermes@hermesagent1 ~]$ /home/hermes/.hermes/hermes-agent/venv/bin/python3 -m pip install python-telegram-bot
Collecting python-telegram-bot
  Downloading python_telegram_bot-22.7-py3-none-any.whl.metadata (17 kB)
...

Пробуємо запустити руками:

hermes@hermesagent1 ~]$ hermes gateway run
┌─────────────────────────────────────────────────────────┐
│           ⚕ Hermes Gateway Starting...                 │
├─────────────────────────────────────────────────────────┤
│  Messaging platforms + cron scheduler                    │
│  Press Ctrl+C to stop                                   │
└─────────────────────────────────────────────────────────┘

...

І пишемо боту в Telegram:

Hermes Agent Gateway autostart на FreeBSD

Ну і давайте спробуємо – чи справиться агент з задачею “я лінивий інженер, сдєлай мені харашо” – нехай сам скаже, як його гейтвей додати в автостарт на FreeBSD:

Окей.

Але я настільки лінивий, що не хочу займатись copy-paste – нехай робить все сам.

Ми в Jail – тому це безпечно:

Для створення rc.d скрипта йому потрібен root – питає пароль, бо sudo у нас тут парольний:

Скрипт готовий:

Сам скрипт, який він написав – /usr/local/etc/rc.d/hermes_gateway:

#!/bin/sh

# PROVIDE: hermes_gateway
# REQUIRE: LOGIN NETWORKING
# KEYWORD: shutdown

. /etc/rc.subr

name="hermes_gateway"
rcvar="hermes_gateway_enable"

load_rc_config "$name"

: ${hermes_gateway_enable:="NO"}
: ${hermes_gateway_user:="hermes"}
: ${hermes_gateway_home:="/home/hermes"}
: ${hermes_gateway_command:="/home/hermes/.local/bin/hermes"}
: ${hermes_gateway_log:="/var/log/hermes_gateway.log"}

pidfile="/var/run/${name}.pid"
command="/usr/sbin/daemon"
command_args="-f -p ${pidfile} -u ${hermes_gateway_user} -o ${hermes_gateway_log} /usr/bin/env HOME=${hermes_gateway_home} ${hermes_gateway_command} gateway run"

start_cmd="${name}_start"
stop_cmd="${name}_stop"
status_cmd="${name}_status"

hermes_gateway_start()
{
    if [ ! -x "${hermes_gateway_command}" ]; then
        echo "Hermes executable not found or not executable: ${hermes_gateway_command}"
        return 1
    fi

    touch "${hermes_gateway_log}"
    chown "${hermes_gateway_user}" "${hermes_gateway_log}" 2>/dev/null || true

    echo "Starting Hermes gateway."
    ${command} ${command_args}
}

hermes_gateway_stop()
{
    echo "Stopping Hermes gateway."
    if [ -f "${pidfile}" ]; then
        kill "$(cat ${pidfile})" 2>/dev/null || true
        rm -f "${pidfile}"
    else
        pkill -u "${hermes_gateway_user}" -f "${hermes_gateway_command} gateway run" 2>/dev/null || true
    fi
}

hermes_gateway_status()
{
    if [ -f "${pidfile}" ] && kill -0 "$(cat ${pidfile})" 2>/dev/null; then
        echo "Hermes gateway is running as pid $(cat ${pidfile})."
        return 0
    fi

    if pgrep -u "${hermes_gateway_user}" -f "${hermes_gateway_command} gateway run" >/dev/null 2>&1; then
        echo "Hermes gateway is running, but pidfile is missing/stale."
        return 0
    fi

    echo "Hermes gateway is not running."
    return 1
}

run_rc_command "$1"

Перевіряємо, що в /etc/rc.conf все додано:

root@hermesagent1:~ # cat /etc/rc.conf | grep hermes
hermes_gateway_enable="YES"
hermes_gateway_user="hermes"
hermes_gateway_home="/home/hermes"
hermes_gateway_command="/home/hermes/.local/bin/hermes"
hermes_gateway_log="/var/log/hermes_gateway.log"

Зупиняємо “hermes gateway run“, яку запускали руками вище, і пробуємо запустити вже через сервіс:

[hermes@hermesagent1 ~]$ sudo service hermes_gateway start
Starting Hermes gateway.
[hermes@hermesagent1 ~]$ sudo service hermes_gateway status
Hermes gateway is running as pid 60901.

Hermes Agent та Web UI

Нагуглив кілька рішень, собі поки взяв nesquena/hermes-webui, але ще можна глянути на EKKOLearnAI/hermes-web-ui.

Клонуємо репозиторій:

[hermes@hermesagent1 ~]$ git clone https://github.com/nesquena/hermes-webui.git hermes-webui
[hermes@hermesagent1 ~]$ cd hermes-webui/

Аби мати доступ до WebUI з мережі – задаємо $HERMES_WEBUI_HOST:

[hermes@hermesagent1 ~/hermes-webui]$ export HERMES_WEBUI_HOST=0.0.0.0

Запускаємо сервіс:

[hermes@hermesagent1 ~/hermes-webui]$ python3 bootstrap.py 
[bootstrap] Starting Hermes Web UI on http://0.0.0.0:8787
[bootstrap] Web UI is ready: http://0.0.0.0:8787
[bootstrap] Log file: /home/hermes/.hermes/webui/bootstrap-8787.log

Пробуємо в браузері:

В Telegram просимо створити якесь нагадування:

І бачимо його в Tasks:

Власне – на цьому і все.

Але ще приклад того, що можна робити з агентом.

Hermes Agent Use Case example: створення документації в DokuWiki

Попросив пройтись по всім моїм мережам і знайти хости – запустив nmap, все просканував, зібрав в табличку:

Потім я створив для агента окремого юзера в моєму локальному DokuWiki, включив XML-RPC у файлі /usr/local/www/dokuwiki/conf/local.php:

$conf['remote'] = 1;
$conf['remoteuser'] = 'hermes-agent';

Попросив агента – і Hermes створив мені сторінку з документацією по всім моїм хостам:

Перевіряв роботу з VictoriaMetrics – чудово додає метрики навіть без VictoriaMetrics Skills (див. Claude Code: створення Kubernetes debugging AI Agent для VictoriaMetrics), тому можна буде зробити автоматизацію типу “Alermanger webhook > Hermes > investigate > send result to Telegram”.

Короче – система цікава, класна – можна буде робити цікаві штуки.

Claude Code: створення Kubernetes debugging AI Agent для VictoriaMetrics
5 (5)

30 Квітня 2026

Поки пишеться серія постів по налаштуванню і використанню Claude Code – запишу приклад створення власного AI Agent для VictoriaMetrics та Kubernetes і “загортання” його в Claude Code Plugin та створення власного Claude Code Markeplace, де будуть жити подібні плагіни для девелоперів на моєму проекті.

Загальна ідея: мати агента, якого девелопери можуть підключити собі до Claude Code (а у нас 95% проекту користуються ним), і з яким зможуть запитати “якого біса впав той Kubernetes Pod”

І не тільки девелопери – я, коли тестив цього агента, відкрив для себе причину постійних рестартів Grafana – тому агент буде корисний і мені самому.

Є, звісно, проекти типу kubectl-ai або навіть robusta.dev – але ми побудуємо власного агента з маркетплейсом і скілами.

Що будемо робити:

агент буде використовувати офіційні скіли від VictoriaMetrics – для самої VictoriaMetrics, VictoriaLogs та Alertmanager
напишемо власний SKILL.md, в кому буде описаний flow перевірки стану Kubernetes Pods – цей скіл буде включений в плагін і потім його можна буде використовувати з новими агентами
для зручного підключення агента з усіма його скілами запакуємо весь проект в плагін для Claude Code, який буде зберігатись в проектному GitHub

Сам агент, описаний тут, більше PoC в плані його інструкцій, і по ходу діла буде тюнитись і допилюватись – але загальна конструкція створення маркеплейсу, побудові агента і плагіну для Claude Code залишиться такою, як показано в цьому пості.

Загальна структура і план

Ключові концепти про які варто знати наперед:

Marketplace: це git-репозиторій з одним або кількома плагінами, який девелопер додає до свого інстансу Claude Code одною командою.
Plugin: можемо “запакувати” всі Agents, Skills, Commands, MCP servers в єдиний пакет, який теж встановлюється до Claude Code одною командою
Agent: субагент Claude Code з власним system prompt і permissions, викликається з основної сесії через Agent tool – працює в ізольованому контексті, виконує задачу, повертає результат до головного “оркестратора”, в ролі якого в нашому випадку буде Claude Code девелопера (чи мій)
Skill: “інструкція”, яку агент читає при потребі і яка описує деталі виконання задачі

В результаті в репозиторії atlas-claude-plugins отримаємо таку структуру каталогів і файлів:

$ tree -a -I .git atlas-claude-plugins/
atlas-claude-plugins/
├── .claude
│   └── settings.json
├── .claude-plugin
│   └── marketplace.json
├── .gitignore
├── CLAUDE.md
├── README.md
├── plugins
│   └── k8s-tools
│       ├── .claude-plugin
│       │   └── plugin.json
│       ├── agents
│       │   └── k8s-pod-debugger.md
│       └── skills
│           └── k8s-troubleshooting-flow
│               └── SKILL.md
└── scripts
    └── bootstrap.sh

MCP vs Skills: чому скіли

Перша версія агента була з MCP. Насправді взагалі ця ідея з’явилась як раз під час написання чорнетки поста про Claude Code та підключення MCP – там описана робота з MCP на прикладі офіційних MCP від VictoriaMetrics (див. mcp-victoriametrics) та Kubernetes.

І тому, коли почав робити вже цього агента, то спочатку додав MCP, але потім стало питання – як девелоперам їх встановлювати? Тоді згадав, що у команди VictoriaMetrics є і набір готових skills: то, може, просто взяти їх – а не тягнути якісь бінарніки? І нехай собі Claude Code через Bash tool використовує curl та робить запити напряму до API.

Бо насправді – в чому різниця між MCP та Skill?

MCP (Model Context Protocol) – дає типізовані tools з чітко визначеними командами: наприклад, для VictoriaMetrics є офіційний mcp-victoriametrics сервер, в якому є Tools типу query(query: string, time: timestamp). Це виглядає круто – бо є детермінізм, визначеність, чітка структура – агент не може викликати функцію з неправильними параметрами, схема валідується.

Але! При використанні MCP функції – наприклад, query, функція приймає аргумент string – і агент все одно сам пише MetricsQL запит. Тобто, MCP визначає тільки як виконати запит – але не саму структуру запиту, і запит все одно LLM будує сама.

Власне, те саме і з kubectl – чи ми використовуємо MCP сервер для нього, чи ми робимо Bash(kubectl get pod …) – результат однаковий: агент/LLM все одно самі визначають запит і фільтри.

Зато в скілах ми можемо описати інше – “Щоб перевірити логи Pod-у в нашому кластері, використовуй такий pattern: _stream:{namespace=’X’}“. Це знання для агенту, яке MCP не передає.

Плюс є практичний момент:

використання офіційного marketplace VictoriaMetrics зі скілами victoriametrics-query, victorialogs-query, alertmanager-query – вони підтримуються командою VictoriaMetrics, оновлюються при змінах в MetricsQL/LogsQL
не треба тягнути зайві бінарні файли в систему юзера (девелопера) – простіше підключення та налаштування (хоча bootstrap.sh все одно треба додати, да і скіли VictoriaMetrics підключити)

Тому вирішив робити чисто “Bash + curl + власний скіл з нашим контекстом + офіційні VictoriaMetrics скіли” – без MCP взагалі.

Окремо момент з Kubernetes MCP та Skills: тут сама логіка – всі LLM чудово знають синтаксис kubectl, тому великого сенсу в додаванні MCP не бачу.

Можна було б додати якийсь готовий скіл, як це зроблено для VictoriaMetrics, наприклад LukasNiessen/kubernetes-skill – але цей скіл більше про те, як деплоїти – а ми будемо робити read-only агента, який буде дебажити, а не деплоїти – зовсім інший use case. Тому якісь деталі по нашому конкретному сетапу (типу namespace convention) можна просто додати в SKILL.md самого плагіну – а LLM вже сама розбереться як зробити kubectl get events.

Поїхали.

Створення Marketplace

Почнемо з бази – маркетплейсу, де буде цей агент та, в майбутньому, інші, і в ньому ж створимо вже структуру для плагіну.

Документація – Create and distribute a plugin marketplace.

У нас буде:

Marketplace: це сам GitHub репозиторій atlas-claude-plugins
- Plugin: k8s-tools
  - Agent: k8s-pod-debugger
  - Skill: k8s-troubleshooting-flow

Marketplace: файл .claude-plugin/marketplace.json

В корні репозиторію створюємо каталог .claude-plugin/, в ньому файл marketplace.json – він описує сам маркетплейс та плагіни в ньому:

{
    "name": "atlas-claude-plugins",
    "owner": {
      "name": "Org Engineering",
      "url": "https://github.com/Org-Engineering"
    },
    "metadata": {
      "description": "Org DevOps team Claude Code plugins for Kubernetes operations and debugging",
      "version": "0.1.0"
    },
    "plugins": [
      {
        "name": "k8s-tools",
        "source": "./plugins/k8s-tools",
        "description": "Kubernetes operations toolkit - read-only debugging agents and skills with VictoriaLogs, VictoriaMetrics, and Alertmanager integration",
        "version": "0.1.0",
        "category": "devops",
        "tags": ["kubernetes", "debugging", "observability", "victoriametrics", "victorialogs", "alertmanager"]
      }
    ]
  }

Тут:

name: "atlas-claude-plugins": задає ім’я, з яким marketplace буде встановлюватись до Claude Code з командою /plugin marketplace add your-org/atlas-claude-plugins
version: задається як на рівні marketplace (збільшуємо, коли міняється список плагінів) – так і на рівні кожного плагіну (збільшуємо, коли міняється сам плагін)
plugins[].source: масив, в якому описується список плагінів цього маркетплейсу, для кожного плагіну задаємо відносний шлях в репозиторії – з префіксом ./

Плагін: файл plugins/k8s-tools/.claude-plugin/plugin.json

Далі описуємо сам плагін – каталог plugins/k8s-tools/, як задано в plugins[].source файлу marketplace.json вище.

В plugins/k8s-tools/ створюємо каталог .claude-plugin/, а в ньому файл plugin.json:

{
    "name": "k8s-tools",
    "version": "0.1.0",
    "description": "Kubernetes operations toolkit - read-only debugging agents and skills for VictoriaLogs, VictoriaMetrics, and Alertmanager",
    "author": {
      "name": "Org Engineering",
      "url": "https://github.com/Org-Engineering"
    }
  }

Тут визначаємо що взагалі за плагін та його версію. Версія має співпадати з plugins[].version в marketplace.json.

Файл .claude/settings.json

Це файл який дає одну дуже приємну фічу для Claude Code – extraKnownMarketplaces: коли девелопер клонує репо і відкриває його в Claude Code – той автоматично пропонує встановити marketplace. Без “ручного читання” README.md, без ручного запуску команд.

Він не являє собою обов’язкову частину Claude Code Marketplace – це просто фішка, якою ми спростимо собі і девелоперам життя при запуску Claude Code.

Крім того, ми тут додаємо і наш власний маркетплейс – і маркетплейс від VictoriaMetrics: одним “yes” девелопер встановить обидва:

{
    "extraKnownMarketplaces": {
      "atlas-claude-plugins": {
        "source": {
          "source": "github",
          "repo": "Org-Engineering/atlas-claude-plugins"
        }
      },
      "victoriametrics-tools": {
        "source": {
          "source": "github",
          "repo": "VictoriaMetrics/skills"
        }
      }
    }
  }

Файл .gitignore

Відразу визначаємо дані, які нам в репозиторії не треба – бо всякі .claude/sessions/ це вже локальні дані девелопера, вони в репозиторії не потрібні. Аналогічно з файлами whatever.local.json – це локальні overwrides, які я чи девелопер може додати чисто для себе, в плагіні їх ігноруємо. Див. Available scopes, і про них буду писати окремо вже в постах по самому Claude Code:

# OS
.DS_Store
Thumbs.db

# Editors
.vscode/
.idea/
*.swp
*~

# Claude Code per-user state and overrides (never share)
.claude/local/
.claude/conversations/
.claude/sessions/
.claude/cache/
.claude/settings.local.json
.claude/*.local.json

# Local env files
.env
.env.local

Тепер маємо таку структуру:

$ tree -a -I '.git'
.claude
└── settings.json
.claude-plugin
└── marketplace.json
plugins
└── k8s-tools
    ├── .claude-plugin
    │   └── plugin.json

Тут:

.claude: конфіг для інстансу Claude Code на робочих машинках
.claude-plugin: метадані самого маркеплейсу
plugins/k8s-tools/.claude-plugin: метадані плагіну k8s-tools

Переходимо до самого агента.

Створення AI Agent

Давайте ще раз визначимо – що таке “AI Agent” взагалі: це окрема “сутність”, яку Claude Code може запустити для виконання якоїсь конкретної задачі.

У агента окремий system prompt, окремий контекст – його задача “зробити щось”, і повернути результат до головного інстансу Claude Code. Таким чином ми не забиваємо зайвими даними контекст самого Claude Code – він отримує тільки ті дані, які йому треба для виконання основної задачі.

Крім того, наприклад, окремому агенту можна задати іншу, більш дешеву модель – тоді при задачах типу парсінгу логів економимо гроші, бо логів багато – токенів жре багато. Дешева моделька вибирає тільки основні патерни, дані – і повертає їх до самого Claude Code, а та вже з дорогою моделлю типу Opus 4.7 (остання на сьогодні) виконує детальний аналіз.

Profit!

Файл plugins/k8s-tools/agents/k8s-pod-debugger.md

Для агенту нам треба створити файл, який буде описувати метадані агента та задавати його system prompt.

Файл розбитий на дві основні частини:

YAML frontmatter: блок на початку файла markdown, де між двома “---” задаємо ім’я, Description, Tools, Permissions
System Prompt: а вже в body файлу – описуємо агенту що і як він має робити, тут жеж можемо додати якісь деталі по конкретно нашому Kubernetes-кластеру чи зв’язкам workloads – як їх дебажити

Ім’я файлу k8s-pod-debugger.md має співпадати з полем name в frontmatter – інакше Claude Code не звʼяже їх.

Frontmatter: поля Name та Description

На початку файлу визначаємо ім’я, задаємо опис агента – це загальні метадані агента.

Тут зміст частинами, потім весь файл.

Опис використовується тільки Claude Code – не людиною, девелопером:

---
name: k8s-pod-debugger
description: Use this agent to investigate Kubernetes Pod, Namespace, or Workload issues. Performs read-only diagnostics across resource state, events, logs, metrics, and alerts. Invoke when user asks to debug a Pod, check why a Pod is failing (CrashLoopBackOff, OOMKilled, Pending, ImagePullBackOff), investigate problems in a Namespace, or troubleshoot a Deployment/StatefulSet/DaemonSet/Job that is not behaving correctly.

...

Frontmatter: поля Permissions та Tools

Далі визначаємо які Claude Code Tools агент може використовувати – а що йому явно заборонено.

У нас read-only agent, ніяких kubectl delete pod він робити не повинен – тому явно це визначаємо:

tools:
  - Bash
  - Read
  - Grep
allowed-tools:
  - Bash(kubectl get *)
  - Bash(kubectl describe *)
  - Bash(kubectl logs *)
  ...
  - Bash(curl --silent --get *)
  - Bash(jq *)
  - Bash(cat ~/.config/atlas/env)
deny-tools:
  - Bash(kubectl delete *)
  - Bash(kubectl apply *)
  - Bash(kubectl exec *)
  ...
  - Bash(*curl* -X *)
  - Bash(*curl* --request *)
  - Bash(*curl* -d *)
  ...
  - Bash(rm *)
  - Bash(mv *)
---

Permissions, deny-tools та Least Privilege Principle

Тут трохи зупинюсь на деталях deny-tools, бо важлива частина.

Використовуємо принцип least privilege – мінімально потрібні для роботи агента доступи.

Наприклад, curl без обмежень може видалити time series в VictoriaMetrics через POST на admin endpoint

$ curl -X POST https://victoriametrics.internal/api/v1/admin/tsdb/delete_series?match[]={namespace=”prod”}

Тому ріжемо їх, дозволяємо тільки GET.

Для bash – блокуємо різні pipe-операції – виконати curl … | bash агент не зможе.

Блокуємо різні redirect output – >, >> – не даємо писати в файли через bash.

Виконання команд rm, mv, cp – все це теж в denied.

Те саме для kubectl – явно забороняємо дії типу kubectl delete чи kubectl exec.

Body: Agent’s System Promt

І головна частина файлу – System Promt агента: що і як він має виконувати при дебагу:

...

# Kubernetes Pod Debugger

You are a read-only Kubernetes troubleshooting agent. Your job is to investigate issues with Pods, Namespaces, and Workloads (Deployments, StatefulSets, DaemonSets, Jobs) and report findings clearly. You have access to the cluster via kubectl, and to observability data via VictoriaLogs, VictoriaMetrics, and Alertmanager.

You are NOT responsible for Node issues, networking deep-dives (Service/Ingress connectivity), or Storage (PV/PVC) troubleshooting. If the user asks about those, advise that a different agent is needed and stop.

## Your boundaries

You are strictly read-only. You investigate, observe, and report. You do not modify anything in the cluster or any external system. The user's permissions enforce this, but you must also respect this boundary in your reasoning - never propose write actions as part of your investigation.
...

## Available tools and data sources

**kubectl** - read-only commands only (`get`, `describe`, `logs`, `top`, `events`).

**Observability via VictoriaMetrics skills.** This plugin relies on the official VictoriaMetrics `query` plugin from the `victoriametrics-tools` marketplace, which provides:
- `victoriametrics-query` skill - for metrics queries (PromQL/MetricsQL)
- `victorialogs-query` skill - for log searches (LogsQL)
- `alertmanager-query` skill - for active and silenced alerts
...

## Our environment specifics

This is essential context for query construction. Always apply these when invoking VM skills:

**VictoriaMetrics labels** (standard prometheus-operator stack):
- `cluster` - REQUIRED in all queries (e.g. `kube_pod_status_phase{cluster="prod-1",namespace="..."}`)
...

**VictoriaLogs streams** (promtail-based collection):
- Stream label: only `namespace` is indexed at stream level
...

## How to investigate

The investigation flow depends on the entry point. Identify which type of request you got and follow the matching flow.

### Entry point A: Single Pod

Triggered by requests like "debug pod X", "why is X failing", "what's wrong with X in namespace Y".

1. **Establish context**
   - `kubectl config current-context` (also use as `CLUSTER` for metrics)
   - If Namespace not specified, get current default: `kubectl config view --minify -o jsonpath='{..namespace}'`
   - Verify Pod exists: `kubectl get pod <name> -n <ns>`

2. **Check Pod state**
   - `kubectl get pod <name> -n <ns> -o wide` - status, Node, IP, restart count
   - `kubectl describe pod <name> -n <ns>` - full event history, conditions, container statuses, last termination reason
   - For multi-container Pods, identify all containers: `kubectl get pod <name> -n <ns> -o jsonpath='{.spec.containers[*].name}'`
...

## How to report findings

Structure your final report in clear sections. Be concrete - include actual values, error messages, timestamps. Avoid filler.

Use this template, adapted to the entry point:

- **Subject** - what you investigated (Pod name / Namespace / Workload kind+name)
...
- **Recommended actions** - read-only or human-driven next steps (you cannot execute writes)

For Namespace overview reports, structure findings as a prioritized list of issues, with a brief sub-report per top issue.

## Important rules

- **Never invent data.** If a command fails or returns nothing, report that explicitly. Do not fabricate values.
- **Cite your evidence.** Every claim in your conclusion must reference a specific kubectl output, log line, metric value, or alert
...
- **Out of scope:** Node issues, networking (Service/Ingress connectivity), Storage (PV/PVC). If the request is purely about these, say so and stop - a different agent should handle them.

..

Тут:

Kubernetes Pod Debugger: описуємо агенту – хто він такий і що робить взагалі
Your boundaries: ще раз вказуємо, що він read-only
Available tools and data sources: які утиліти і як він має використовувати – вказуємо, що є окремі скіли від VictoriaMetrics, аби він їх підключав
Our environment specifics: деталі, специфічні до нашого конкретного сетапу, labels в метриках чи streams в логах
How to investigate: описуємо процес пошуку проблем – як підключитись до Kubernetes, перевірити стан Kubernetes Pod, пов’язані events, etc
How to report findings: описуємо формат, в якому агент має повернути результати
Important rules: і трохи причісуємо поведінку – “не вигадуй, якщо щось пішло не так“, не лізти в зайві дані, і так далі

Окремо агенту явно вказуємо, що у нас є Skill k8s-troubleshooting-flow, в якому описані деталі виконання запитів – про нього далі.

Весь файл k8s-pod-debugger.md

В результаті маємо такий зміст:

---
name: k8s-pod-debugger
description: Use this agent to investigate Kubernetes Pod, Namespace, or Workload issues. Performs read-only diagnostics across resource state, events, logs, metrics, and alerts. Invoke when user asks to debug a Pod, check why a Pod is failing (CrashLoopBackOff, OOMKilled, Pending, ImagePullBackOff), investigate problems in a Namespace, or troubleshoot a Deployment/StatefulSet/DaemonSet/Job that is not behaving correctly.
tools:
  - Bash
  - Read
  - Grep
allowed-tools:
  - Bash(kubectl get *)
  - Bash(kubectl describe *)
  - Bash(kubectl logs *)
  - Bash(kubectl top *)
  - Bash(kubectl events *)
  - Bash(kubectl version)
  - Bash(kubectl config view *)
  - Bash(kubectl config current-context)
  - Bash(kubectl auth can-i *)
  - Bash(curl -s -G *)
  - Bash(curl -sG *)
  - Bash(curl --silent --get *)
  - Bash(jq *)
  - Bash(source ~/.config/atlas/env)
  - Bash(cat ~/.config/atlas/env)
deny-tools:
  - Bash(kubectl delete *)
  - Bash(kubectl apply *)
  - Bash(kubectl exec *)
  - Bash(kubectl edit *)
  - Bash(kubectl patch *)
  - Bash(kubectl scale *)
  - Bash(kubectl rollout *)
  - Bash(kubectl cp *)
  - Bash(kubectl port-forward *)
  - Bash(kubectl create *)
  - Bash(kubectl replace *)
  - Bash(kubectl annotate *)
  - Bash(kubectl label *)
  - Bash(kubectl drain *)
  - Bash(kubectl cordon *)
  - Bash(kubectl uncordon *)
  - Bash(kubectl taint *)
  - Bash(*curl* -X *)
  - Bash(*curl* --request *)
  - Bash(*curl* -d *)
  - Bash(*curl* --data*)
  - Bash(*curl* --upload-file *)
  - Bash(*curl* -T *)
  - Bash(*curl* -o *)
  - Bash(*curl* --output *)
  - Bash(*|*sh*)
  - Bash(*|*bash*)
  - Bash(*>*)
  - Bash(*>>*)
  - Bash(rm *)
  - Bash(mv *)
  - Bash(cp *)
  - Bash(chmod *)
  - Bash(chown *)
---

# Kubernetes Pod Debugger

You are a read-only Kubernetes troubleshooting agent. Your job is to investigate issues with Pods, Namespaces, and Workloads (Deployments, StatefulSets, DaemonSets, Jobs) and report findings clearly. You have access to the cluster via kubectl, and to observability data via VictoriaLogs, VictoriaMetrics, and Alertmanager.

You are NOT responsible for Node issues, networking deep-dives (Service/Ingress connectivity), or Storage (PV/PVC) troubleshooting. If the user asks about those, advise that a different agent is needed and stop.

## Your boundaries

You are strictly read-only. You investigate, observe, and report. You do not modify anything in the cluster or any external system. The user's permissions enforce this, but you must also respect this boundary in your reasoning - never propose write actions as part of your investigation.

For HTTP requests, use only `curl -sG` or `curl --silent --get`. Never use `-X`, `-d`, `--data`, or any non-GET method. If you find a problem that needs a fix, describe it as a recommendation in your final report - do not attempt to execute it.

## Available tools and data sources

**kubectl** - read-only commands only (`get`, `describe`, `logs`, `top`, `events`).

**Local skill: `k8s-troubleshooting-flow`** - this plugin includes a skill with our environment-specific knowledge: VictoriaLogs stream label schema, VictoriaMetrics label conventions (including the required `cluster` label), MetricsQL/LogsQL query templates for common Pod failure modes, and correlation patterns linking kubectl observations to metrics/logs/alerts. **Read this skill at the start of any non-trivial investigation** - it tells you which queries to construct for the situation at hand.

**External skills via VictoriaMetrics `query` plugin** - this plugin relies on the official `victoriametrics-tools` marketplace, which provides:
- `victoriametrics-query` skill - executes metrics queries (PromQL/MetricsQL) via curl
- `victorialogs-query` skill - executes log searches (LogsQL) via curl
- `alertmanager-query` skill - queries active and silenced alerts via curl

These skills handle curl mechanics, pagination, and result parsing. The flow is: read `k8s-troubleshooting-flow` to learn WHAT to query, then invoke the appropriate VM skill to actually run the query.

**Environment variables** - the VM skills require these to be set in the user's shell:
- `VM_METRICS_URL` - VictoriaMetrics endpoint
- `VM_LOGS_URL` - VictoriaLogs endpoint
- `VM_ALERTMANAGER_URL` - Alertmanager endpoint

These are configured by the bootstrap script (`scripts/bootstrap.sh` in the atlas-claude-plugins repo) and stored in `~/.config/atlas/env`. If commands fail because vars are missing, instruct the user to run the bootstrap script.

## How to investigate

The investigation flow depends on the entry point. Identify which type of request you got and follow the matching flow.

Before starting any flow, **read the `k8s-troubleshooting-flow` skill** to refresh your memory on:
- Our VictoriaLogs stream schema (so you build correct LogsQL)
- Our VictoriaMetrics label conventions (so you build correct MetricsQL with required `cluster` label)
- The correlation patterns matching the failure mode you're investigating

### Entry point A: Single Pod

Triggered by requests like "debug pod X", "why is X failing", "what's wrong with X in namespace Y".

1. **Establish context**
   - `kubectl config current-context`
   - If Namespace not specified, get current default: `kubectl config view --minify -o jsonpath='{..namespace}'`
   - Verify Pod exists: `kubectl get pod <name> -n <ns>`

2. **Check Pod state**
   - `kubectl get pod <name> -n <ns> -o wide` - status, Node, IP, restart count
   - `kubectl describe pod <name> -n <ns>` - full event history, conditions, container statuses, last termination reason
   - For multi-container Pods, identify all containers: `kubectl get pod <name> -n <ns> -o jsonpath='{.spec.containers[*].name}'`

   Pay attention to:
   - `Status`, `Reason`, `Message` fields
   - Container `State` and `Last State` (with reason: `CrashLoopBackOff`, `OOMKilled`, `Error`, `ImagePullBackOff`)
   - `Events` section - especially Warning events
   - Resource requests and limits vs actual usage

3. **Identify failure mode and consult skill** - based on the kubectl output above, identify which failure mode this matches (CrashLoopBackOff, OOMKilled, ImagePullBackOff, Pending, Ready=False but Running). Open the `k8s-troubleshooting-flow` skill and follow the correlation pattern matching that mode - it tells you exactly which metrics, logs, and alerts to check next.

4. **Check related events**
   - `kubectl events -n <ns> --for=pod/<name>` (newer kubectl versions)
   - Fallback: `kubectl get events -n <ns> --field-selector involvedObject.name=<name>`

5. **Check logs (recent, from kubectl)**
   - Current container: `kubectl logs <name> -n <ns> --tail=200`
   - Previous container if restarted: `kubectl logs <name> -n <ns> --previous --tail=200`
   - For multi-container Pods, iterate per container with `-c <container>`

6. **Check metrics** - use `victoriametrics-query` skill with MetricsQL templates from `k8s-troubleshooting-flow`. Always include the `cluster` label as documented in the skill.

7. **Check deeper logs (longer time window)** - use `victorialogs-query` skill with LogsQL stream patterns from `k8s-troubleshooting-flow`. Default time window: last 1 hour. Expand if not enough.

8. **Check related alerts** - use `alertmanager-query` skill. Filter by matching `namespace` and `pod` labels. Include both firing and recently resolved (last 1 hour) to catch flapping issues.

### Entry point B: Namespace overview

Triggered by requests like "what's wrong in namespace X", "check namespace X", "is anything broken in X".

1. **Establish context** - confirm cluster context, verify Namespace exists.

2. **Find unhealthy resources**
   - `kubectl get pods -n <ns>` - look for any non-Running, non-Completed Pods
   - `kubectl get pods -n <ns> --field-selector=status.phase!=Running,status.phase!=Succeeded`
   - `kubectl get deployments,statefulsets,daemonsets -n <ns>` - check ready/available counts mismatch
   - `kubectl get events -n <ns> --sort-by='.lastTimestamp' | tail -50` - recent Warning events

3. **Triage** - rank issues by severity:
   - Pods stuck in CrashLoopBackOff, ImagePullBackOff, Error - highest priority
   - Pods Pending - check if scheduling, image pull, or resource issue
   - Workloads with replicas mismatch (e.g. Deployment wants 3, has 2 ready)
   - Recent Warning events (OOM, FailedMount, FailedScheduling)

4. **Deep-dive on top issues** - for each priority Pod/Workload, switch to entry point A or C respectively. Limit to top 3-5 issues to keep report manageable. Use `k8s-troubleshooting-flow` correlation patterns for each.

5. **Check Namespace-level alerts** - use `alertmanager-query` skill, filter by `namespace="..."` label.

### Entry point C: Workload (Deployment / StatefulSet / DaemonSet / Job)

Triggered by requests like "why is deployment X not updating", "statefulset Y has issues", "job Z keeps failing".

1. **Establish context** - confirm cluster context, Namespace.

2. **Check Workload state**
   - `kubectl get <kind>/<name> -n <ns> -o wide`
   - `kubectl describe <kind>/<name> -n <ns>` - replicas, conditions, events, rollout status
   - For Deployments: `kubectl rollout history deployment/<name> -n <ns>` (read-only)
   - For Jobs: check `.status.conditions` and `.status.failed`/`.status.succeeded`

3. **Check Pods owned by Workload**
   - `kubectl get pods -n <ns> -l <workload-selector>` (selector from describe output)
   - Identify Pods in bad states - then for each, follow entry point A flow (including consulting `k8s-troubleshooting-flow` per failure mode)

4. **Check ReplicaSet/ControllerRevision history** for Deployments and StatefulSets - sometimes the issue is the new revision is broken.

5. **Check Workload-level metrics and alerts** - MetricsQL templates for Workload state are in the `k8s-troubleshooting-flow` skill (Deployment/StatefulSet/DaemonSet/Job replica metrics).

## How to report findings

Structure your final report in clear sections. Be concrete - include actual values, error messages, timestamps. Avoid filler.

Use this template, adapted to the entry point:

- **Subject** - what you investigated (Pod name / Namespace / Workload kind+name)
- **Status** - one-line summary: healthy / failing / partially failing / pending / etc
- **Key Findings** - bulleted list of specific observations with data
- **Events** - recent significant events with timestamps
- **Logs** - relevant log excerpts with line numbers/timestamps
- **Metrics** - resource usage observations, anomalies
- **Alerts** - firing alerts related to the subject, or "none"
- **Conclusion** - likely root cause based on evidence above
- **Recommended actions** - read-only or human-driven next steps (you cannot execute writes)

For Namespace overview reports, structure findings as a prioritized list of issues, with a brief sub-report per top issue.

## Important rules

- **Never invent data.** If a command fails or returns nothing, report that explicitly. Do not fabricate values.
- **Cite your evidence.** Every claim in your conclusion must reference a specific kubectl output, log line, metric value, or alert.
- **Stay focused.** Investigate what was asked. Do not wander into unrelated cluster issues.
- **Time-box log scans.** Default to last 200 lines or last 1 hour. Expand only if initial scan is insufficient.
- **Limit Namespace deep-dives.** When investigating a Namespace, do not deep-dive every problem - pick top 3-5 by severity.
- **Always consult `k8s-troubleshooting-flow` for query construction.** Do not invent LogsQL stream filters or MetricsQL label selectors from memory - the skill has the correct schema for our environment.
- **Always include `cluster` label** in MetricsQL queries against our VictoriaMetrics - all metrics are labeled with it (see skill for details).
- **Respect read-only boundary.** If you find a problem that needs a fix (e.g. wrong env var, missing Secret, bad image tag, wrong replica count), describe the fix as a recommendation. Do not attempt to apply it.
- **Out of scope:** Node issues, networking (Service/Ingress connectivity), Storage (PV/PVC). If the request is purely about these, say so and stop - a different agent should handle them.

Тепер в плагіні у нас така структура:

$ tree -a plugins/
plugins/
└── k8s-tools
    ├── .claude-plugin
    │   └── plugin.json
    ├── agents
    │   └── k8s-pod-debugger.md

Skill: k8s-troubleshooting-flow

Файл агента plugins/k8s-tools/agents/k8s-pod-debugger.md описує самого агента – що і як він має робити, які утиліти йому доступні.

На додачу до нього – створимо в плагіні окремий Skill, який описує деталі виконання запитів до VictoriaLogs, приклади запитів MetricsQL до VictoriaMetrics, які проблеми з Kubenretes Pods і які перевіряти.

Чому Skill окремо від System Prompt?

Тут кілька важливих моментів, які треба мати на увазі:

розділення абстракцій: System Prompt описує агенту “хто ти“, а Skill описує “як робити X в нашому кластері“
економія контексту: System Prompt додається до кожного запиту до LLM, а Skill читається при потребі – не витрачаємо токени і ліміти.
- тобто, коли агенту треба дізнатись “що робити, якщо Pod в стані CrashLoopBackOff” – він автоматично підгрузить Skill і отримає відповідні інструкції – а не буде кожного разу додавати всі деталі до кожного запиту
re-use з іншими агентами: ми додаємо скіл в корінь плагіну – то потім можемо його використовувати для інших агентів, а не дублювати
оновлення скілу: простіше додавати якісь нові деталі в одному місці, а не переписувати в 100500 файлах різних агентів

Файл plugins/k8s-tools/skills/k8s-troubleshooting-flow/SKILL.md

Весь скіл виглядає так:

---
name: k8s-troubleshooting-flow
description: Use when investigating Kubernetes Pod, Workload, or Namespace issues and you need to correlate kubectl observations with metrics (VictoriaMetrics), logs (VictoriaLogs), or alerts (Alertmanager). Provides query templates for common Pod failure modes (CrashLoopBackOff, OOMKilled, Pending, ImagePullBackOff), our specific stream label schema for VictoriaLogs (promtail-based), and standard MetricsQL patterns for kube-state-metrics and cAdvisor.
---

# Kubernetes Troubleshooting Flow

This skill provides query templates and correlation patterns for debugging Kubernetes workloads using our observability stack.

## Our environment

**VictoriaLogs** - log collection via promtail. Stream labels (indexed):
- `namespace` - the only stream-level label

Other useful fields available after stream filter (NOT indexed, but searchable):
- `pod` - Pod name
- `container` - container name within Pod
- `app` - app label from Pod
- `node_name`, `hostname` - Node where Pod runs
- `stream` - `stdout` or `stderr`

**VictoriaMetrics** - prometheus-operator stack. All metrics labeled with:
- `cluster` - cluster identifier (REQUIRED in queries)
- `namespace`, `pod`, `container` - standard k8s labels
- `job`, `instance`, `service`, `endpoint` - infra labels

**Alertmanager** - standard, queried via `alertmanager-query` skill.

## Query template patterns

### LogsQL (via victorialogs-query skill)

Always start with stream filter, then narrow by fields:

    _stream:{namespace="<NS>"} pod:"<POD>"

Common patterns:

- All logs for a Pod (last hour):
  `_stream:{namespace="<NS>"} pod:"<POD>"`

- Errors only:
  `_stream:{namespace="<NS>"} pod:"<POD>" (level:error OR error OR exception OR fatal OR panic)`

- Specific container in multi-container Pod:
  `_stream:{namespace="<NS>"} pod:"<POD>" container:"<CONTAINER>"`

- Errors across whole Namespace:
  `_stream:{namespace="<NS>"} (level:error OR error OR exception OR fatal)`

- Logs from specific Node (e.g. Node-level issues):
  `_stream:{namespace="<NS>"} node_name:"<NODE>"`

### MetricsQL (via victoriametrics-query skill)

Always include `cluster="<CLUSTER>"`. The user will tell you the cluster name, or you can ask if it's not clear.

**Pod state and lifecycle:**

- Current phase: `kube_pod_status_phase{cluster="<C>",namespace="<NS>",pod="<POD>"}`
- Restart count: `kube_pod_container_status_restarts_total{cluster="<C>",namespace="<NS>",pod="<POD>"}`
- Restart rate (last hour): `rate(kube_pod_container_status_restarts_total{cluster="<C>",namespace="<NS>",pod="<POD>"}[1h])`
- Last termination reason: `kube_pod_container_status_last_terminated_reason{cluster="<C>",namespace="<NS>",pod="<POD>"}`
- Ready status: `kube_pod_status_ready{cluster="<C>",namespace="<NS>",pod="<POD>"}`

**Memory (cAdvisor):**

- Working set (current): `container_memory_working_set_bytes{cluster="<C>",namespace="<NS>",pod="<POD>",container!=""}`
- vs limit: `container_memory_working_set_bytes{cluster="<C>",namespace="<NS>",pod="<POD>",container!=""} / container_spec_memory_limit_bytes{cluster="<C>",namespace="<NS>",pod="<POD>",container!=""}`
- OOM kills: `kube_pod_container_status_terminated_reason{cluster="<C>",namespace="<NS>",pod="<POD>",reason="OOMKilled"}`

**CPU (cAdvisor):**

- Usage rate: `rate(container_cpu_usage_seconds_total{cluster="<C>",namespace="<NS>",pod="<POD>",container!=""}[5m])`
- Throttling rate: `rate(container_cpu_cfs_throttled_periods_total{cluster="<C>",namespace="<NS>",pod="<POD>",container!=""}[5m]) / rate(container_cpu_cfs_periods_total{cluster="<C>",namespace="<NS>",pod="<POD>",container!=""}[5m])`
- Throttling > 0 means resource pressure

**Workload state (Deployment / StatefulSet / DaemonSet):**

- Deployment: desired vs available
  - `kube_deployment_spec_replicas{cluster="<C>",namespace="<NS>",deployment="<NAME>"}`
  - `kube_deployment_status_replicas_available{cluster="<C>",namespace="<NS>",deployment="<NAME>"}`
- StatefulSet: `kube_statefulset_status_replicas_ready{cluster="<C>",namespace="<NS>",statefulset="<NAME>"}`
- DaemonSet: `kube_daemonset_status_number_unavailable{cluster="<C>",namespace="<NS>",daemonset="<NAME>"}`
- Job: `kube_job_status_failed{cluster="<C>",namespace="<NS>",job_name="<NAME>"}`

**Namespace-wide health:**

- Failing Pods count: `count(kube_pod_status_phase{cluster="<C>",namespace="<NS>",phase=~"Failed|Pending|Unknown"})`
- Pods with restarts in last hour: `count(increase(kube_pod_container_status_restarts_total{cluster="<C>",namespace="<NS>"}[1h]) > 0)`

### Alertmanager (via alertmanager-query skill)

- Alerts for a Pod: filter by `pod="<POD>"` label
- Alerts for a Namespace: filter by `namespace="<NS>"` label
- Include `state=active` for currently firing
- Include recently resolved (last 1h) to catch flapping issues

## Correlation patterns by failure mode

For each Pod failure mode, this is what to look for and where:

### CrashLoopBackOff

**Signal in kubectl:**
- `kubectl describe pod` - container State `Waiting` with reason `CrashLoopBackOff`, Last State `Terminated` with exit code

**What to check:**
1. Last termination reason and exit code (kubectl describe)
2. Previous container logs: `kubectl logs <pod> --previous`
3. Restart count metric - is it climbing?
4. Time between restarts - constant (looks like the app starts then fails) or growing (BackOff is increasing)?
5. Logs in VictoriaLogs around restart timestamps - look for stack traces, init errors, missing config

**Common root causes:**
- Application bug on startup (check logs)
- Missing/wrong config (env var, ConfigMap, Secret)
- Failing readiness/liveness probe (check probe config in describe)
- Out of memory (cross-check with OOMKilled metric and memory metrics)

### OOMKilled

**Signal in kubectl:**
- `kubectl describe pod` - Last State `Terminated`, Reason `OOMKilled`, exit code 137

**What to check:**
1. `kube_pod_container_status_terminated_reason{...,reason="OOMKilled"}` - confirm in metrics
2. Memory usage trend leading up to kill: `container_memory_working_set_bytes{...}` over last 6h
3. Memory limit: `container_spec_memory_limit_bytes{...}`
4. Was it gradual leak or sudden spike?
5. Logs right before the kill (last 5 min before termination timestamp)

**Common root causes:**
- Memory leak in application
- Limit set too low for actual workload
- Sudden traffic spike causing memory allocation

### ImagePullBackOff / ErrImagePull

**Signal in kubectl:**
- `kubectl describe pod` - Events show `Failed to pull image`, `ErrImagePull`, `ImagePullBackOff`

**What to check:**
1. Exact image reference in Pod spec
2. Pull error message in events (auth, not found, network)
3. Check imagePullSecrets configured on Pod or ServiceAccount

**Common root causes:**
- Wrong image tag (typo, doesn't exist)
- Registry auth failure (missing/expired pull secret)
- Network issue from Node to registry
- Rate limiting (Docker Hub anonymous pulls)

### Pending

**Signal in kubectl:**
- `kubectl get pod` shows status `Pending` for >30s

**What to check:**
1. `kubectl describe pod` Events - scheduler messages
2. Common scheduler errors:
   - `0/N nodes are available: insufficient cpu/memory` - resource pressure
   - `node(s) didn't match Pod's node affinity/selector` - scheduling rules issue
   - `node(s) had untolerated taint` - taints/tolerations issue
   - `error getting PVC` - storage issue (out of scope, mention it)
3. Node resource availability: `kube_node_status_allocatable{cluster="<C>"}` vs requests on Pending Pod

**Common root causes:**
- Cluster out of resources for requested CPU/memory
- Node selector/affinity doesn't match any Node
- Taints not tolerated
- Storage class not provisioning (refer to storage agent)

### Pod Ready=False but Running

**Signal in kubectl:**
- `kubectl get pod` - status Running but READY shows `0/1`

**What to check:**
1. Container statuses in describe - which probe failing (readiness vs liveness)
2. Probe configuration - endpoint, expected response
3. Logs of the probe target (often the app's `/health` endpoint)
4. Was this recent change? Check rollout history if Deployment

**Common root causes:**
- App takes longer to start than `initialDelaySeconds`
- Wrong probe endpoint or expected response
- Backend dependency unavailable (DB, cache) - app can't become ready

## Investigation discipline

Reminders for the investigating agent:

- **Time-box**: default to last 1h for logs, last 6h for metric trends. Expand only if data is insufficient.
- **Cite evidence**: every finding must reference a specific kubectl output, log line with timestamp, metric value, or alert.
- **Don't conflate symptoms with causes**: "Pod is OOMKilled" is a symptom. The cause is "memory leak in handler X" or "limit set 256Mi but workload needs 512Mi".
- **Stop when you have enough**: a clear root cause + supporting evidence is the goal. Don't keep digging if the answer is found.

Створення Bootstrap скрипту

Агенту для роботи потрібні декілька environment variables – як підключатись до ендпоінтів VictoriaMetrics, VictoriaLogs, Alertmanager.

У нас VictoriaMetrics та VictoriaLogs мають власні Ingress, які доступні через AWS Internal Application Load Balancer та доступні через VPN, тому при додаванні плагіну треба перевірити, що вони доступні.

Заодно перевіряємо наявність kubectl, jq, curl, etc.

Змінні оточення записуємо в файл ~/.config/atlas/env, який потім використовується при старті агенту і описаний в його System Prompt.

Скрипт cross-platform – бо у нас є і macOS юзери, і Linux.

#!/usr/bin/env bash
# Atlas Claude Plugins - bootstrap script
#
# Sets up the local environment needed for the k8s-tools plugin and
# VictoriaMetrics observability skills. Cross-platform (macOS / Linux).
#
# Usage:
#   ./scripts/bootstrap.sh             # interactive setup
#   ./scripts/bootstrap.sh --force     # overwrite existing env file without asking
#   ./scripts/bootstrap.sh --help      # show help

set -euo pipefail

# Defaults that can be overridden via env vars before invocation
DEFAULT_VM_METRICS_URL="${VM_METRICS_URL:-https://vmsingle.monitoring.1-33.ops.example.co}"
DEFAULT_VM_LOGS_URL="${VM_LOGS_URL:-https://vmlogs.monitoring.1-33.ops.example.co}"
DEFAULT_VM_ALERTMANAGER_URL="${VM_ALERTMANAGER_URL:-http://localhost:9093}"

ENV_DIR="${HOME}/.config/atlas"
ENV_FILE="${ENV_DIR}/env"

# Color output (disabled if not a TTY)
if [ -t 1 ]; then
  C_RED=$'\033[31m'
  C_GREEN=$'\033[32m'
  C_YELLOW=$'\033[33m'
  C_BLUE=$'\033[34m'
  C_BOLD=$'\033[1m'
  C_RESET=$'\033[0m'
else
  C_RED=""
  C_GREEN=""
  C_YELLOW=""
  C_BLUE=""
  C_BOLD=""
  C_RESET=""
fi

log_info()  { printf "%s[INFO]%s  %s\n"  "$C_BLUE"   "$C_RESET" "$*"; }
log_ok()    { printf "%s[OK]%s    %s\n"  "$C_GREEN"  "$C_RESET" "$*"; }
log_warn()  { printf "%s[WARN]%s  %s\n"  "$C_YELLOW" "$C_RESET" "$*"; }
log_error() { printf "%s[ERROR]%s %s\n"  "$C_RED"    "$C_RESET" "$*" >&2; }

usage() {
  cat <<EOF
Atlas Claude Plugins - bootstrap script

Sets up environment variables required by k8s-tools plugin and
VictoriaMetrics skills (victoriametrics-query, victorialogs-query, alertmanager-query).

Usage:
  $(basename "$0") [--force] [--help]

Options:
  --force    Overwrite existing env file (${ENV_FILE}) without prompting.
  --help     Show this help message.

Environment variables (used as defaults if set):
  VM_METRICS_URL       Default: ${DEFAULT_VM_METRICS_URL}
  VM_LOGS_URL          Default: ${DEFAULT_VM_LOGS_URL}
  VM_ALERTMANAGER_URL  Default: ${DEFAULT_VM_ALERTMANAGER_URL}

EOF
}

# Parse arguments
FORCE=0
for arg in "$@"; do
  case "$arg" in
    --force) FORCE=1 ;;
    --help|-h) usage; exit 0 ;;
    *) log_error "Unknown argument: $arg"; usage; exit 1 ;;
  esac
done

# OS detection
detect_os() {
  case "$(uname -s)" in
    Darwin) echo "macos" ;;
    Linux)  echo "linux" ;;
    *)      echo "unknown" ;;
  esac
}

OS="$(detect_os)"
log_info "Detected OS: ${OS}"

# Shell detection
detect_shell() {
  local shell_path="${SHELL:-}"
  if [ -n "$shell_path" ]; then
    basename "$shell_path"
  else
    echo "unknown"
  fi
}

USER_SHELL="$(detect_shell)"

shell_rc_file() {
  case "$USER_SHELL" in
    bash) echo "${HOME}/.bashrc" ;;
    zsh)  echo "${HOME}/.zshrc" ;;
    fish) echo "${HOME}/.config/fish/config.fish" ;;
    *)    echo "" ;;
  esac
}

# Dependency checks
install_hint() {
  local tool="$1"
  case "$OS" in
    macos)
      case "$tool" in
        kubectl) echo "  brew install kubectl" ;;
        curl)    echo "  curl is preinstalled on macOS, check your PATH" ;;
        jq)      echo "  brew install jq" ;;
        claude)  echo "  npm install -g @anthropic-ai/claude-code  (or https://claude.ai/download)" ;;
      esac
      ;;
    linux)
      case "$tool" in
        kubectl) echo "  https://kubernetes.io/docs/tasks/tools/install-kubectl-linux/" ;;
        curl)    echo "  sudo apt install curl  # or: sudo dnf install curl" ;;
        jq)      echo "  sudo apt install jq    # or: sudo dnf install jq" ;;
        claude)  echo "  npm install -g @anthropic-ai/claude-code  (or https://claude.ai/download)" ;;
      esac
      ;;
    *)
      echo "  (install ${tool} for your platform)"
      ;;
  esac
}

check_dep() {
  local cmd="$1"
  if command -v "$cmd" >/dev/null 2>&1; then
    log_ok "${cmd} found: $(command -v "$cmd")"
    return 0
  else
    log_error "${cmd} not found in PATH"
    printf "        Install hint:\n%s\n" "$(install_hint "$cmd")"
    return 1
  fi
}

log_info "Checking dependencies..."
DEPS_OK=1
for dep in kubectl curl jq claude; do
  check_dep "$dep" || DEPS_OK=0
done

if [ "$DEPS_OK" -eq 0 ]; then
  log_error "Some dependencies are missing. Install them and re-run this script."
  exit 1
fi

# Handle existing env file
if [ -f "$ENV_FILE" ] && [ "$FORCE" -eq 0 ]; then
  log_warn "Env file already exists: ${ENV_FILE}"
  log_warn "Current contents:"
  printf "%s---%s\n" "$C_BOLD" "$C_RESET"
  cat "$ENV_FILE"
  printf "%s---%s\n" "$C_BOLD" "$C_RESET"
  log_warn "Re-run with --force to overwrite, or edit the file manually."
  exit 0
fi

# Interactive prompts - prompt goes to stderr, value to stdout
# This way command substitution captures only the value, not the prompt
prompt_with_default() {
  local label="$1"
  local default="$2"
  local answer

  # Prompt to stderr (visible to user, not captured by $(...))
  printf "%s%s%s [%s]: " "$C_BOLD" "$label" "$C_RESET" "$default" >&2
  read -r answer
  if [ -z "$answer" ]; then
    echo "$default"
  else
    echo "$answer"
  fi
}

log_info "Configure observability endpoints (press Enter to accept default):"
echo

VM_METRICS_URL_VAL="$(prompt_with_default "VictoriaMetrics URL"  "$DEFAULT_VM_METRICS_URL")"
VM_LOGS_URL_VAL="$(prompt_with_default     "VictoriaLogs URL"    "$DEFAULT_VM_LOGS_URL")"
VM_ALERTMANAGER_URL_VAL="$(prompt_with_default "Alertmanager URL" "$DEFAULT_VM_ALERTMANAGER_URL")"
echo

# Connectivity check (non-fatal)
check_url() {
  local url="$1"
  local label="$2"
  if curl -sS -o /dev/null -w "%{http_code}" --max-time 3 "$url" 2>/dev/null | grep -qE '^[234]'; then
    log_ok "${label} reachable (${url})"
  else
    log_warn "${label} not reachable (${url}) - check VPN if this is an internal endpoint"
  fi
}

log_info "Checking connectivity..."
check_url "$VM_METRICS_URL_VAL"      "VictoriaMetrics"
check_url "$VM_LOGS_URL_VAL"         "VictoriaLogs"
check_url "$VM_ALERTMANAGER_URL_VAL" "Alertmanager"
echo

# Write env file
log_info "Writing ${ENV_FILE}..."
mkdir -p "$ENV_DIR"

cat > "$ENV_FILE" <<ENVEOF
# Atlas Claude Plugins - environment configuration
# Generated by scripts/bootstrap.sh on $(date -u +"%Y-%m-%dT%H:%M:%SZ")
#
# These variables are required by:
#   - victoriametrics-query skill (from victoriametrics-tools marketplace)
#   - victorialogs-query skill
#   - alertmanager-query skill
#
# Re-run scripts/bootstrap.sh --force to regenerate.

export VM_METRICS_URL="${VM_METRICS_URL_VAL}"
export VM_LOGS_URL="${VM_LOGS_URL_VAL}"
export VM_ALERTMANAGER_URL="${VM_ALERTMANAGER_URL_VAL}"
ENVEOF

chmod 600 "$ENV_FILE"
log_ok "Env file written (mode 600)"
echo

# Shell rc integration hint
RC_FILE="$(shell_rc_file)"
SOURCE_LINE='[ -f ~/.config/atlas/env ] && source ~/.config/atlas/env'

log_info "Next step: make these variables available in your shell."
echo

if [ -n "$RC_FILE" ]; then
  if [ -f "$RC_FILE" ] && grep -qF "$SOURCE_LINE" "$RC_FILE" 2>/dev/null; then
    log_ok "Source line already present in ${RC_FILE}"
  else
    cat <<HINTEOF
Add this line to ${C_BOLD}${RC_FILE}${C_RESET}:

  ${C_GREEN}${SOURCE_LINE}${C_RESET}

Or run this once:

  ${C_GREEN}echo '${SOURCE_LINE}' >> ${RC_FILE}${C_RESET}

Then reload your shell:

  ${C_GREEN}source ${RC_FILE}${C_RESET}

HINTEOF
  fi
else
  log_warn "Could not detect your shell rc file. Add this line manually to your shell config:"
  echo "  ${SOURCE_LINE}"
  echo
fi

# Next steps
cat <<NEXTEOF
${C_BOLD}=== Setup complete ===${C_RESET}

To use the plugin, start Claude Code:

  ${C_GREEN}claude${C_RESET}

Then inside Claude Code (first time only):

  ${C_GREEN}/plugin marketplace add Org-Engineering/atlas-claude-plugins${C_RESET}
  ${C_GREEN}/plugin marketplace add VictoriaMetrics/skills${C_RESET}
  ${C_GREEN}/plugin install k8s-tools@atlas-claude-plugins${C_RESET}
  ${C_GREEN}/plugin install query@victoriametrics-tools${C_RESET}

If you cloned this repo and opened it in Claude Code, the marketplaces
will be suggested automatically (via .claude/settings.json).

NEXTEOF

Що робить скрипт:

визначає операційну систему – macOS чи Linux, бо трохи відрізняються утиліти типу date та sed
перевіряє чи встановлені всі потрібні утиліти, якщо нема – пропонує команду для установки
перевіряємо наявність файлу ~/.config/atlas/env
запитує значення для змінних VM_METRICS_URL, VM_LOGS_URL, VM_ALERTMANAGER_URL, пропонує встановити дефолти – але можна перевизначити
- тут єдиний нюанс – конкретно в нашому випадку у VM_ALERTMANAGER_URL нема Ingress/ALB, тому підключення через localhost – потім зроблю нормально, бо раніше ним користувався виключно я і мені було OK робити kubectl port-forward
виконує підключення до VM_METRICS_URL – перевіряє, що VPN включений і ендпоінти доступні
записує змінні до ~/.config/atlas/env
визначає user shell (zsh, bash), показує юзеру як додати ~/.config/atlas/env до shell rc
і в кінці виводить команди “як додати маркетплейс та плагін“

Запускаємо, перевіряємо як все працює:

Тут як раз забув kubectl port-forward до Alertmanager – отримав “[WARN] Alertmanager not reachable“.

Перевірка Marketplace та Plugin

В принципі – на цьому етапі вже все готово.

Але перед тим, як додавати CLAUDE.md та REAME.md і пушити в репозиторій – протестуємо локально, як все працює.

Переходимо в тестову директорію, запускаємо Claude Code:

$ cd /tmp && mkdir -p test-plugin && cd test-plugin
$ claude

Підтверджуємо довіру директорії:

Додаємо маркетплейс:

/plugin marketplace add ~/Work/Org/atlas-claude-plugins

Перевіряємо, що він доданий:

Додаємо сам плагін:

/plugin install k8s-tools@atlas-claude-plugins

Вибираємо “Install for you (user scope)“.

Виконуємо /reload-plugins:

Перевіряємо в Installed:

Перевіряємо сам агент:

Спробуємо дебаг – знаходимо проблемний Pod:

$ kk get pod -A | grep -v Running
NAMESPACE                   NAME                                                              READY   STATUS        RESTARTS      AGE
ops-monitoring-ns           atlas-victoriametrics-grafana-5f8ff65758-tbwzb                    0/3     Completed     0             8d

Бачимо, що агент знайшов і прочитав скіл в ~/.local/share/claude-code/plugins/k8s-troubleshooting-flow/skill.md.

І результат дебагу:

Файл CLAUDE.md

CLAUDE.md – це файл який Claude Code автоматично підхоплює як контекст коли хтось працює з репозиторієм. Тобто коли я через пів року відкрию репозиторій в Claude Code, щоб додати новий плагін чи поправити існуючий – Claude відразу буде розуміти що це за проект

Важливо не плутати з README.md:

CLAUDE.md: для тих, хто додає/змінює плагіни в репо з Claude Code
README.md: для юзерів плагіну (девелоперів, які встановлюють і користуються агентом)

Що в CLAUDE.md:

структура репо з коментарями що для чого
правила і naming conventions – коментарі в коді англійською, read-only by default, Kubernetes ресурси з великої букви, env naming
як додати новий плагін в існуючий marketplace
правила версіонування
як тестувати локально перед push
як публікувати на GitHub

Весь зміст:

# atlas-claude-plugins

Claude Code plugins for Org DevOps - Kubernetes debugging and operations.

## Repo structure

```
.claude-plugin/marketplace.json    # marketplace manifest, lists all plugins
.claude/settings.json              # extraKnownMarketplaces (auto-suggest on clone)
plugins/<plugin-name>/             # one directory per plugin
  .claude-plugin/plugin.json       # plugin metadata
  agents/<agent-name>.md           # agent definitions (filename = name in frontmatter)
  skills/<skill-name>/SKILL.md     # skills (each in its own directory)
  commands/<command-name>.md       # slash commands (optional)
scripts/bootstrap.sh               # user setup (env vars, deps check)
```

## Conventions

- **Code comments in English** always, regardless of context language
- **Agents are read-only by default**: explicit `allowed-tools` whitelist + `deny-tools` blacklist for write operations (kubectl write verbs, curl POST/PUT/DELETE, file writes)
- **Kubernetes resources capitalized in prose**: Pod, Deployment, Namespace, Service, etc
- **Env vars follow VictoriaMetrics convention**: `VM_METRICS_URL`, `VM_LOGS_URL`, `VM_ALERTMANAGER_URL` (so VM skills work without aliasing)
- **User config lives in `~/.config/atlas/env`** - never in repo, never in shell rc directly

## Adding a new plugin

1. Create `plugins/<name>/.claude-plugin/plugin.json` with name, version, description
2. Add agent(s) in `plugins/<name>/agents/<agent>.md` - frontmatter `name` must match filename
3. Add skill(s) in `plugins/<name>/skills/<skill>/SKILL.md` - directory name must match skill `name`
4. Register in `.claude-plugin/marketplace.json` under `plugins[]` array
5. Bump marketplace `version` in `marketplace.json`

## Versioning

- Each plugin has independent semver in its `plugin.json`
- Marketplace `version` in `marketplace.json` bumps when plugin list changes (add/remove)
- Plugin patch version bumps for prompt/skill content changes
- Plugin minor version bumps for new capabilities (new tools, new entry points)
- Plugin major version bumps for breaking changes (renamed agent, removed permissions)

## Testing locally

```bash
# 1. Run bootstrap (sets up env file + checks deps)
./scripts/bootstrap.sh

# 2. Source env in current shell (or open new shell if added to rc)
source ~/.config/atlas/env

# 3. Start Claude in some unrelated directory (NOT this repo)
cd /tmp && mkdir -p test-claude && cd test-claude && claude

# 4. Inside Claude, add this repo as local marketplace
/plugin marketplace add /path/to/atlas-claude-plugins
/plugin install <plugin-name>@atlas-claude-plugins

# 5. Verify agent loaded
/agents
# should show: Plugin agents - <plugin>:<agent>

# 6. Test the agent with a real task
> Use <agent-name> to debug pod foo in namespace bar
```

After changes to plugin files: `/plugin marketplace update atlas-claude-plugins` reloads.

## Publishing

```bash
git add -A
git commit -m "..."
git push origin master
```

Users on the next `/plugin marketplace update` get the changes. Or, if they cloned the repo, `extraKnownMarketplaces` in `.claude/settings.json` auto-suggests the marketplace on first open.

## Dependencies

- Plugins use `kubectl` + `curl` directly (no MCP servers)
- VictoriaMetrics observability via `query` plugin from `VictoriaMetrics/skills` marketplace - listed as suggested in `.claude/settings.json`
- Agents must work with read-only kubectl perms - never assume write access

Файл README.md

І останній файл – чисто для девелоперів: що в репозиторії, як користуватись:

Власне – на цьому все.

Пушимо в репозиторій і перевіряємо ще раз.

Перевірка extraKnownMarketplaces

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

/plugin marketplace remove atlas-claude-plugins

Перевіряємо, що його нема:

Створюємо тестову директорію:

$ mkdir /tmp/test-extra && cd /tmp/test-extra

Клонуємо репозиторій, запускаємо в ньому Claude Code:

$ git clone [email protected]:Org-Engineering/atlas-claude-plugins.git

$ cd atlas-claude-plugins/

$ claude

Підтверджуємо довіру каталогу:

Перевіряємо маркеплейси – маємо там і наш atlas-claude-plugins, і victoriametrics-tools:

Додаємо плагіни з цих маркетплейсів:

/plugin install k8s-tools@atlas-claude-plugins
/plugin install query@victoriametrics-tools

Перевіряємо:

Готово.

Okta: інтеграція з Google Workspaces, частина 1 – Provisioning
5 (1)

27 Квітня 2026

Продовжуємо налаштування Okta для нашого проекту. В попередніх частинах зробили SSO для Grafana (див. Okta: налаштування Grafana SSO з OIDC та Role mapping) та AWS (див. AWS: налаштування Okta SSO з AWS IAM Identity Center), а тепер сама цікава частина: інтеграція Okta з Google Workspaces.

Що треба буде зробити:

налаштувати Users Provisioning: всіма юзерами хочеться керувати з Okta, тобто при створенні Okta User – автоматично створювати Google account, а при деактивації юзера в Okta – блокувати і його акаунт в Google
налаштувати SSO/SAML: юзери мають логінитись в Google сервіси тільки через Okta

В цій частині налаштуємо Provisioning, а в наступній – SSO.

В Okta будемо використовувати Google Workspace App.

Писав по цій темі ще у 2019 році в пості Okta: интеграция с G-Suite – provisioning, импорт и экспорт пользователей, і, в принципі, нічого окрім інтерфейсу Okta не змінилось.

Але все ж тому посту 7 (OMG!) років, до того ж зараз я роблю дві інтеграції, тому нехай буде свіженький матеріал, ну і цього разу вийшло більше детально.

Тут приклади на моєму власному акаунті Google Workspaces, але вже зроблено і на робочому проекті – в продакшені вже з місяць, політ нормальний.

Документація від Okta – Google Workspace.

Сподіваюсь таки буде час подивитись на Authentik – open-source self-hosted IdP, альтернатива Okta, але поки не дуже актуально, бо у нас вже є ліцензії на Okta, а Open Source версії нема багатьох готових інтеграцій. Хіба що, може, візьму його для свого Home NAS на FreeBSD та його сервісів.

SCIM та Users Provisioning

Кілька слів про SCIM – System for Cross-domain Identity Management.

Як і у випадку з Provisioning для AWS і його IAM Identity Center – керування юзерами з Okta в Google Workspace відбувається за протоколом SCIM.

SCIM був створений у 2011 році аби навести порядок в різних інтеграціях, версія SCIM 2.0 була опублікована у 2015 і тепер використовується майже всюди – див. RFC 7642-7644.

По факту, це REST API, який описує як мають відбуватись операції з юзерами та групами – create, read, update, delete, у RFC вище є приклади GET/POST/PATCH запитів:

$ GET /Users/2819c223-7f76-453a-919d-413861904646
Host: example.com
...
HTTP/1.1 200 OK
Content-Type: application/scim+json
Location:
  https://example.com/v2/Users/2819c223-7f76-453a-919d-413861904646
...
   {
     "schemas":["urn:ietf:params:scim:schemas:core:2.0:User"],
     ...
     "meta":{
       "resourceType":"User",
     ...
     "name":{
       "formatted":"Ms. Barbara J Jensen III",
       "familyName":"Jensen",
       "givenName":"Barbara"
     },
     ...
     "emails":[
       {
         "value":"[email protected]",
         "type":"work"
       }
     ]
   }
...

В Okta Google Workspace App “знає” які API-запити робити до Google аби створити юзера – а Okta знає що треба передати “на вхід” до Google Workspace.

Альтернативи – LDAP (колись писав про OpenLDAP), JIT provisioning (Just-in-Time) – коли маємо SSO з сервісом, і юзер перший раз логіниться – то в цьому сервісі створюється юзер.

Okta: додавання Google Workspaces App

Для налаштувань Google Workspaces App в Okta треба буде вказати Company Domain.

Важливо: після створення App поле “Your Google Apps company domain” просто через Edit вже змінити не можна – тому налаштуйте відразу, він треба буде для SSO.

Переходимо в адмінку Google Workspaces, там в Account > Domains, знаходимо Primary domain:

Він буде використовуватись в SSO та при створенні посилань на сервіси.

Тобто лінк на Gmail буде виглядати як https://mail.google.com/a/setevoy.kiev.ua.

Додаємо нову Application в Okta, в General Settings задаємо цей Company Domain:

В Sign-On поки нічого не міняємо – в другій частині налаштуємо SAML:

Тут все – можна робити Provisioning.

Налаштування Provisioning

Переходимо на вкладку Provisioning, клікаємо Configure API Integration:

Логінимось з адмін-акаунтом (з роллю Super Admin) нашого Google Workspace:

Тут опція Push Empty Values for Custom Fields – якщо в Okta User Profile є кастомні атрибути, але вони з пустими значеннями – то Okta не передає їх до Google.

Attribute Mappings є в Profile Editor:

Але там з Okta до Google заданий тільки один userName:

Опція Import Groups – чи переносити групи з https://admin.google.com/ac/groups до Okta як окремих юзерів. В моєму випадку, коли інтеграція буде тільки для менеджменту саме юзерів – то групи не потрібні.

Google Workspace Permissions для Okta

Натискаємо “Authentificate with Google Workspace”, вибираємо що Okta може робити в Google:

View user schemas on your domain, See info about users on your domain, View and manage the provisioning of users on your domain: включаємо, це основне, для чого робимо інтеграцію – робота з Google Users
View and manage the provisioning of groups on your domain, View and manage group subscriptions on your domain: якщо хочемо керувати Google Groups з Okta – включаємо
- тоді зможемо робити Group Push із Okta да Google: якщо маємо Okta Group як “my-Group“, то вона буде додана в Google як “[email protected]“
- коли додаємо Okta юзера до Okta Group – то він буде доданий і до Google Group
View and manage organization units on your domain: якщо маємо мапінг атрибута в Okta на поле Organization Unit (OU) і вмикаємо цей дозвіл – то Okta може керувати OU юзера в Google
Manage delegated admin roles: якщо використовуємо Manage roles on create and update (буде далі) – якщо ролями Google з Okta керувати не плануємо – можна пропустити
View and manage Google Workspace licenses: чи дозволяти керувати ліцензіями
Manage data access permissions: керування сесіями – деактивація юзера в Okta завершує всі його активні сесії в Google, включаємо

Є класний список всіх Google OAuth scope в таблиці Google Workspace (G Suite) Integration.

Після аутентифікації Okta ще не почне нічим керувати – всі юзери в Google залишаться без змін, бо сам Provisioning ще не налаштований.

Але в будь-якому випадку для Production варто створити окремого breaking glass юзера, який не інтегрований ні з SSO, ні з provisioning.

Включаємо всі дозволи:

Готово:

Імпорт юзерів з Google до Okta

Okta дозволяє виконати синхронізацію юзерів як з Okta до Google, так і навпаки:

якщо в Okta вже юзери, а Google акаунт новий або там вже є ті самі юзери – то цю частину можна пропустити
якщо вже маємо юзерів в Google Workspaces і налаштовуємо новий акаунт Okta – то можемо імпортувати юзерів з Google до Okta

Google to Okta: параметри імпорту

Спершу можна зайти в Provisioning > To Okta, і перевірити налаштування там.

В принципі, зараз тут залишаємо всі дефолтні параметри, але маємо на увазі, що тут можна змінити.

В General можемо додати запуск по крону та, якщо використовуємо власний, то змінити Okta username format.

З цікавого тут опція Update application username on: теж залишаємо дефолтне значення Create only, бо навіть якщо ми включимо її в Create and update, то це вплине тільки на SSO цього юзера – який username буде відправлятись в SAML assertion (див. What is: SAML – обзор, структура и трассировка запросов на примере Jenkins и Okta SAML SSO, 2019 рік), але в самому Google акаунт автоматично не перейменується:

Далі, опції в “User Creation & Matching”:

Imported user is an exact match if: як Okta порівнює юзерів із Google з власною базою – залишаємо по email
Allow partial matches: якщо email юзера в Google != в Okta, то Okta спробує пошукати по First Name / Last name, в Production краще відключити – можемо мати двох юзерів зі схожими іменами/фаміліями, Okta може їх спутати (хоча ми все одно далі будемо робити manual review)
Confirm matched users та Confirm new users: можна включити автоматичний approve для імпортованих юзерів, дефолтне значення off, і для production це правильно

І останні дві частини тут – “Profile & Lifecycle Sourcing” та “Import Safeguard”.

Allow Google Workspace to source Okta users визначає хто буде керувати профілями: якщо включити, то профілі редагуються в Google, для Okta вони стають read only – не треба.

Import Safeguard – дуже корисна штука: якщо ми маємо 50 юзерів Okta, яким підключена Google Workspaces, а потім при імпорті з Google (наприклад, якщо включити імпорт за розкладом) Okta отримала від Google не 50 акаунтів, а тільки 5 – то вона не буде виконувати Google Workspace App unassign всіх юзерів, а зупинить імпорт і потребує ручного підтвердження:

Google до Okta: запуск імпорту

Для імпорту із Google до Okta переходимо у, власне, Import, клікаємо Import now.

Опції Confirm matched users та Confirm new users, які бачили вище, зараз відключені, тому натискання Import now ще не запустить імпорт, а тільки отримає список юзерів від Google:

В моєму акаунті тільки три юзера:

І три акаунти Okta і побачила:

Клікаємо OK, і тепер маємо можливість вибрати кого саме ми будемо імпортувати з Google до Okta.

Merge та Create Okta Users

Я буду в Okta додавати тільки одного тестового юзера, [email protected] – справа відмічаємо його і внизу клікаємо Confirm Assignments:

З юзерами, у яких статус Partial user march є кілька варіантів – змержити юзера, створити нового, заматчити на іншого існуючого юзера, або взагалі ігнорувати – клікаємо на такий partial match, і вибираємо дію з drop-down списку:

Якщо залишимо Partial user match – то Okta User [email protected] буде прив’язаний до Google User [email protected], і, відповідно, якщо ми зробимо Okta Deactivate для [email protected] – то в Google юзер [email protected] стане Suspended.

Ще нюанс: якщо юзер вже Suspended в Google – то в списку на Import він не додається. Але якщо такий юзер в Okta вже є, і навіть якщо він Deactivated – то Okta його додасть в список.

Можна відразу активувати його, клікаємо Confirm:

І перевіряємо.

Переходимо в Directory > People, маємо там нового Okta User:

Якому вже підключена Google Workspace App:

Тепер зробимо навпаки – синхронізацію юзерів з Okta до Google.

Provisioning з Okta до Google

Основна задача: при створенні нового Okta User (точніше – під час Assign юзера до Google Workspace App) треба автоматично створювати нові акаунти в Google Workspace.

Аналогічно при деактивації юзера в Okta – треба блокувати його акаунт в Google.

Тобто весь менеджмент акаунтами Google буде виконуватись через Okta, і Okta буде нашим “source of truth” для юзерів і їхнього стану (active, deactivated/suspended).

Okta to Google: параметри Provisioning

Переходимо в Provisioning > To App, клікаємо Edit, включаємо всі опції (або тільки Create Users, якщо хочеться спокійно потестити на “production” Google акаунті).

З цікавого тут Sync Password – який пароль буде задано в новому Google акаунті. Можна згенерити рандомний, можна встановити такий жеж, як у Okta User.

Опція Update User Attributes визначає, чи буде Okta міняти атрибути: якщо включено, і у юзера в Okta Profile змінився First Name – це поле буде змінено і в Google. Якщо відключено – то атрибути передаються тільки під час create user в Google:

Use of Sync Password

Тут окреме питання по Sync Password:

якщо у нас вже є юзер в Google з власним паролем, якого ми вже імпортували і виконали Assign на Google Workspace App, то зараз, коли ми збережемо Okta to Google provisioning – в нього зміниться пароль, чи ні?
- я перевіряв на цьому, тестовому акаунті – і пароль не міняється, тобто існуючі Google Users продовжують логінитись, як і до налаштування інтеграції
- але в робочому акаунті проекті все ж не ризикнув включати

І однозначної відповіді не знайшов:

в документації від Google Okta user provisioning and single sign-on говорить цю опцію не включати (хоча там далі є SSO, можливо, через це)
в документації від Okta Configure Password Push Updates говориться включати
і навіть тех. підтримка спочатку сформулювала відповідь як “If you don’t use SSO, just the Provisioning features, then yes, the Sync Password feature would override the users password“

Але пізніше я таки добився чіткої відповіді:

The passwords will be overridden, but it’s not going to be immediately as you enable the feature.

The password sync is based on certain triggers which typically are unavoidable (as discussed in this article).

Adding the specifics here as well for convenience:

” In order to trigger the password sync for a user, one of these events must occur:

Resetting an Okta-sourced password.

Signing in to Okta with a password.

Delegated authentication sign-in to Okta. “

In addition to those, app assignment or re-assignment after you enable the sync password feature also triggers the override.

Therefore, it’s possible that some users will still use the original password if none of the above events happened.

Тобто рано чи пізно – але пароль для Google акаунту таки зміниться.

Можна просто залишити цю опцію вимкненою взагалі – але тоді маємо проблему chicken and eggs: як передати новому юзеру його пароль?

Наприклад, у нас на проекті Slack login через Google. Тому в Slack теж не скинеш якийсь тимчасовий пароль.

Ідеально – включати опцію Sync Okta Password:

Але це ідеально, якщо у вас буде SSO в Google через Okta.

У нас SSO поки що не буде, і мені зараз жим-жим робити це для десятків юзерів які вже є в Google і яких я вже імпортував до Okta.

Тому цю опцію не включав взагалі – будемо передавати пароль на папірці :trollface:

Okta to Google: перевірка створення акаунту

Зберігаємо налаштування, і для перевірки додаємо в Okta нового юзера – але тільки створення нового Okta User, без, власне assign до Google Workspace App в Okta, ще не створить Google Account:

Аби додати новий акаунт в Google – переходимо до Google Workspace Application > Assignments:

Підключаємо цього тестового юзера:

В опціях можна залишити все дефолтним, або відразу задати ролі в Google Workspace.

Опцію Manage roles on create and update залишаємо відключеною – ролями в Google краще керувати самим:

Зберігаємо і дивимось логи в Reports > System log (взагалі корисна штука, потім треба буде налаштувати моніторинг) – бачимо, що push to Google виконаний без помилок:

Перевіряємо юзерів в самому Google:

Я в Okta залишив дефолтну опцію “Sync a randomly generated password“, тому для перевірки резетаємо пароль:

І логінимось:

Все працює:

Okta User Deactivation та Google Account Suspend

І перевіримо, як працює синхронізація стану юзера:

коли ми виконаємо Unassign юзера в Okta від Google Workspaces App, або якщо робимо Okta User Deactivate – то в Google його акаунт перейде в стан Suspended
при видалені юзера з Okta – його акаунт в Google залишиться, але теж в стані Suspended, але тільки якщо в Provisioning > To App включена опція Deactivate Users (по дефолту включена)

Пробуємо – деактивуємо юзера в Okta:

Перевіряємо в Google:

Готово.

SSL/TLS: self-signed Certificate Authority для NGINX на FreeBSD
0 (0)

18 Квітня 2026

На домашньому NAS крутиться багато web-сервісів – Grafana, VictoriaMetrics, мій власний щоденник на WordPress і ще пів-десятка дрібниць.

Вся серія постів по FreeBSD та NAS починається тут – FreeBSD: Home NAS, part 1 – налаштування ZFS mirror, там станом на зараз 15 частин.

Окремо описаний NGINX+PHP, див. FreeBSD: налаштування FEMP – NGINX, PHP-FPM, MariaDB.

В цілому, хоча це все і доступне тільки в рамках VPN або домашньої мережі – але внутрішня параноя кричить, коли бачить HTTP замість HTTPS, а тому хочеться мати SSL/TLS і налаштувати NGINX з ним.

Купувати сертифікат для такого use case сенсу нема, Let’s Encrypt теж не підійде – бо доступу до NGINX з інтернету нема, а DNS challenge для домашньої зони .setevoy піднімати – то трохи геморою, бо TXT має бути для публічно доступної зони.

Тому просто зробимо свій Certificate Authority з блекджеком і дівчатами, а потім ним підпишемо власний wildcard self-signed сертифікат для NGINX.

Ну а заодно згадаємо як взагалі працюють CA та приватні та публічні сертифікати.

Домени для Home NAS

В мене є “домашня” top level domain зона .setevoy в якій живуть всі мої сервіси і яка включає в себе два внутрішні домени:

.aws.setevoy: ресурси в AWS – EC2 для самого блогу RTFM, окремий EC2 для NAT Gateway, і інстанс RDS
- зроблено окремою зоною, бо це виключно AWS-related ресурси
.net.setevoy: це вже ресурси в моїх локальних мережах – одна квартира під “офіс”, в якій більшість хостів (сам NAS, MikroTik, робочий ноутбук тощо), та домашня мережа – там тільки домашній ноутбук

Відповідно в домені .net.setevoy будуть адреси:

work.net.setevoy: робочий ноут
nas.net.setevoy: ThinkCentre з FreeBSD/NAS
gw.net.setevoy: MikroTik RB4011

А для веб-сервісів будуть адреси типу grafana.net.setevoy для Grafana, victoria.net.setevoy – для VictoriaMetircs, logs.net.setevoy для VictoriaLogs тощо.

Власне, що для цього всього треба зробити – це wildcard SSL-сертифікат, який потім буде використовуватись в NGINX.

Аби браузери не сварились на нього – створимо власний CA-сертифікат, який потім я додам на свої робочий та домашній ноутбуки, і з власним Certificate Authority підпишемо wildcard-сертифікат для веб-сервісів.

Чому wildcard не на сам .setevoy

Перша думка була “зроблю собі *.setevoy, і буде один сертифікат на все” – але так не вийде, бо wildcard на TLD заборонений і, наприклад, Chrome відкидає такий сертифікат з помилкою ERR_CERT_COMMON_NAME_INVALID.

Формально RFC 6125 – 6.4.3 каже тільки те, що wildcard має бути в найлівішому лейблі (*.example.com – ОК, bar.*.example.net – ні) – і цьому *.setevoy відповідає.

Крім того, RFC прямо нічого не каже про мінімум лейблів (рівнів домену) – це навіть описана проблема цього RFC.

Але на практиці TLS-клієнти додають своє правило, наприклад, GnuTLS документує це явно – див. gnutls_x509_crt_check_hostname2:

wildcards […] are only considered if the domain name consists of three components or more

Тобто *.setevoy (2 компоненти) – не валідно, *.net.setevoy (3 компоненти) – валідно.

Chrome (через BoringSSL) і Firefox (через NSS), судячи з помилки яку я отримав, поводяться так само – хоча я не копав, де саме це у них задокументовано.

Окремо є CA/Browser Forum Baseline Requirements, які забороняють публічним CA видавати такі сертифікати в принципі. Мій CA не публічний – але правила браузерів від цього не перестають діяти.

Тому веб-сервіси будуть в зоні .net.setevoy, а wildcard буде для *.net.setevoy.

SSL vs TLS

Їх часто плутають, та я і сам в блозі пишу то “SSL”, то “TLS”, то просто “SSL/TLS”.

Власне, в чому різниця:

SSL (Secure Sockets Layer):
- оригінальний протокол від Netscape, 90-ті роки, див. The Origins of Web Security and the Birth of Security Socket Layer (SSL) Protocol
- SSL 2.0, SSL 3.0 давно deprecated, див. Deprecated SSL/TLS Versions
TLS (Transport Layer Security):
- це фактично SSL 4.0, просто перейменований коли стандарт передали в IETF, див. History of SSL/TLS
- зараз актуальні TLS 1.2 і TLS 1.3

Тобто коли хтось каже “SSL сертифікат” або “налаштувати SSL” – мається на увазі TLS. Це як “ксерокс” замість “копіювальний апарат” – всі розуміють, але технічно неточно. В тексті далі буду казати “SSL/TLS” або просто “SSL” чи “TLS” – це все про одне й те саме.

Що таке Certificate Authority

Certificate Authority – це центр, який має право підписувати сертифікати, і якому довіряють клієнти (браузери, операційні системи).

Коли ми створюємо сертифікат через Let’s Encrypt – він підписується сертифікатом компанії Let’s Encrypt.

Коли через AWS Certificate Manager – то сертифікатом Amazon.

У випадку Cloudflare – issuer буде Google Trust Services:

$ openssl s_client -connect rtfm.co.ua:443 </dev/null 2>/dev/null | openssl x509 -noout -issuer -subject
issuer=C=US, O=Google Trust Services, CN=WE1
subject=CN=rtfm.co.ua

Тобто, сертифікат виданий issuer=Google Trust Services, підписаний Google Trust Services CA, а виданий сертифікат для subject=rtfm.co.ua.

Всі публічні Certificate Authority сертифікати йдуть “в комплекті” браузера або операційної системи.

Наприклад, в Google Chrome список доступний в chrome://settings/certificates > Chrome Root Store:

Linux та ca-certificates

В Arch Linux за CA-сертифікати відповідають кілька пакетів – ca-certificates-utils та ca-certificates-mozilla.

Хоча насправді тут доволі цікавий ланцюжок.

Наприклад, пакет curl має в залежностях мета-пакет

$ pacman -Qi curl
Name            : curl
...
Depends On      : ca-certificates
...

Пакет ca-certificates має в залежностях пакет ca-certificates-mozilla:

$ pacman -Qi ca-certificates
Name            : ca-certificates
...
Depends On      : ca-certificates-mozilla
...

А ca-certificates-mozilla тягне за собою пакет ca-certificates-utils:

$ pacman -Qi ca-certificates-mozilla
Name            : ca-certificates-mozilla
...
Depends On      : ca-certificates-utils>=20181109-3
...

Пакет ca-certificates-utils створює каталоги (/etc/ca-certificates/, /etc/ssl/certs/), додає man pages та встановлює утиліту /usr/bin/update-ca-trust.

Пакет ca-certificates-mozilla додає в систему файл /usr/share/ca-certificates/trust-source/mozilla.trust.p11-kit, який містить всі публічні CA-сертифікати.

Наприклад, вже згаданий вище “Organization=Google Trust Services” з “CommonName=GTS Root R1“:

$ cat /usr/share/ca-certificates/trust-source/mozilla.trust.p11-kit | grep -A 10 "Google Trust Services"
#        Issuer: C=US, O=Google Trust Services LLC, CN=GTS Root R1
#        Validity
#            Not Before: Jun 22 00:00:00 2016 GMT
#            Not After : Jun 22 00:00:00 2036 GMT
#        Subject: C=US, O=Google Trust Services LLC, CN=GTS Root R1
#        Subject Public Key Info:
#            Public Key Algorithm: rsaEncryption
#                Public-Key: (4096 bit)
#                Modulus:
#                    00:b6:11:02:8b:1e:e3:a1:77:9b:3b:dc:bf:94:3e:
#                    b7:95:a7:40:3c:a1:fd:82:f9:7d:32:06:82:71:f6:
#                    f6:8c:7f:fb:e8:db:bc:6a:2e:97:97:a3:8c:4b:f9:
#                    2b:f6:b1:f9:ce:84:1d:b1:f9:c5:97:de:ef:b9:f2:
#                    a3:e9:bc:12:89:5e:a7:aa:52:ab:f8:23:27:cb:a4:
#                    b1:9c:63:db:d7:99:7e:f0:0a:5e:eb:68:a6:f4:c6:
...

А update-ca-trust – це bash-скрипт, який викликає утиліту /usr/bin/trust і витягує сертифікати в каталог DEST=/etc/ca-certificates/extracted/cadir:

$ ll /etc/ca-certificates/extracted/cadir/ | grep GTS_Root_R1
-r--r--r-- 1 root root 1.9K Apr  3 14:57 GTS_Root_R1.pem

Та потім створює сімлінки в /etc/ssl/certs/.

$ ll /etc/ssl/certs/ | grep GTS_Root_R1
lrwxrwxrwx 1 root root   53 Apr  3 14:57 GTS_Root_R1.pem -> ../../ca-certificates/extracted/cadir/GTS_Root_R1.pem

Глянути наявні сертифікати можемо з trust list:

$ trust list | grep -B2 -A 2 "GTS Root R1"
pkcs11:id=%E4%AF%2B%26%71%1A%2B%48%27%85%2F%52%66%2C%EF%F0%89%13%71%3E;type=cert
    type: certificate
    label: GTS Root R1
    trust: anchor
    category: authority

Власне, що ми будемо робити: створимо власний root-key нашого Certificate Authority, ним підпишемо TLS-сертифікат для NGINX, а потім сертифікат нашого Certificate Authority додамо в trusted store на робочих машинах.

Файли CA, CSR, CRT, KEY

Тут хочу окремо зупинитись, бо насправді не так часто щось роблю руками з сертифікатами, і від кількості пов’язаних файлів можна потірятись.

Отже, у нас будуть дві пари ключ+сертифікат.

Пара 1 – наш Certificate Authority:

ca-private.key: приватний ключ CA
- використовується виключно для підпису інших сертифікатів, зберігається окремо від сертифікатів NGINX
ca-public.crt: публічний сертифікат CA
- підписується ca-private.key – власне – тому ця схема і є “self-signed” – ми самі собі підписуємо публічний сертифікат, який потім додаємо в trust store хостів

Пара 2 – для NGINX:

wildcard.net.setevoy.key: приватний ключ NGINX
- лежить на сервері і нікому не передається
- під час TLS handshake NGINX ним підписує challenge від клієнта, чим доводить що володіє ключем (сам ключ по мережі не йде)
wildcard.net.setevoy.crt: фінальний публічний сертифікат веб-сервера, підписаний нашим CA
- це CSR + підпис від ca-private.key
- саме цей файл NGINX і віддає браузеру

Окремо будемо створювати файл Certificate Signing Request (CSR) – wildcard.net.setevoy.csr і який буде використовуватися для створення підпису публічного сертифікату wildcard.net.setevoy.crt.

Процес валідації сертифікатів

Тепер розберемо як саме CA використовується для перевірки сертифіката від NGINX.

Тут приклади на вже готових файлах.

У нас буде файл wildcard.net.setevoy.crt, який NGINX передає клієнту під час підключення і який підписаний ca-private.key – приватним ключем CA.

Клієнт має у своєму trust store публічний сертифікат CA – ca-public.crt, використовуючи який він має впевнитись, що wildcard.net.setevoy.crt був підписаний саме ca-private.key.

Файл wildcard.net.setevoy.crt містить в собі набір полів:

# openssl x509 -in wildcard.net.setevoy.crt -noout -text
Certificate:
    Data:
        ...
        Signature Algorithm: sha256WithRSAEncryption
        Issuer: C = UA, ST = Kyiv, O = Setevoy Home NAS, CN = Setevoy CA
        Validity
            Not Before: Apr 18 11:35:59 2026 GMT
            Not After : Jul 21 11:35:59 2028 GMT
        Subject: C = UA, ST = Kyiv, O = Setevoy Home NAS, CN = *.net.setevoy
        Subject Public Key Info:
            Public Key Algorithm: rsaEncryption
                Public-Key: (2048 bit)
                Modulus:
                    00:dd:c6:f7:e1:13:1c:dd:91:44:37:d5:75:09:ca:
                    fb:16:a5:80:22:23:42:6e:6b:7c:1f:08:dd:25:f3:
                    7f:bd:05:13:74:79:76:de:d7:2b:f8:4c:bd:4c:a5:
                    ...
    Signature Algorithm: sha256WithRSAEncryption
    Signature Value:
        3d:24:95:55:cd:fb:c6:af:35:59:bc:dd:f6:05:fb:da:c9:51:
        f1:37:38:79:f0:e8:62:4a:5c:bc:f3:da:4b:45:8c:39:75:f4:
        3c:e5:3f:73:89:e6:8a:93:79:52:d7:8e:08:b0:50:02:ce:e9:
        18:63:4d:cd:ef:be:fa:78:f2:ed:01:db:77:e8:30:d7:b6:27:
        ...

Для підписання цього сертифіката CA бере хеш (SHA-256) від усієї секції Data (subject, issuer, public key, validity, SAN, …), шифрує цей хеш своїм приватним ключем ca-private.key і прикріплює результат до сертифіката як поле “Signature Value“.

Коли клієнт отримує wildcard.net.setevoy.crt від NGINX – він перевіряє значення issuer, бачить там “Setevoy CA“, і шукає у своєму trust store сертифікат CA з таким subject – це буде наш ca-public.crt.

Тепер у клієнта є wildcard.net.setevoy.crt з Signature Value, і є ca-public.crt, після чого:

клієнт бере секцію Data з сертифіката і сам обчислює її SHA-256 хеш – назвемо цей хеш “H1“
бере значення Signature Value і розшифровує його публічним ключем CA (який лежить всередині ca-public.crt) – це буде хеш “H2“

Якщо хеши співпадають – то підпис дійсно був зроблений парним приватним ключем до публічного ключа CA, ca-private.key.

“H1” та “H2” тут – чисто умовні позначення, аби простіше було розібратись з тим, що будемо робити нижче.

Demo: перевірка підпису сертифікату

Виглядає класно в теорії – але давайте глянемо на практиці, як цей механізм працює.

Створимо файл data.txt – це буде наш умовний блок Data із сертифікату wildcard.net.setevoy.crt:

$ echo "Hello, this is our Data block" > data.txt

Створимо приватний ключ – це наш умовний ca-private.key, приватний ключ CA:

$ openssl genrsa -out demo.key 2048

З ca-private.key ми будемо підписувати хеш від data.txt.

Отримуємо з demo.key публічну частину – це буде наш умовний ca-public.crt, публічний сертифікат CA:

$ openssl rsa -in demo.key -pubout -out demo.pub

З ca-public.crt ми повинні мати змогу перевірити підпис від ca-private.key та отримати оригінальні дані.

А тепер сама цікава частина.

Отримуємо хеш даних в data.txt – це буде наш умовний “H1“:

$ openssl dgst -sha256 data.txt
SHA2-256(data.txt)= 959af28af72380bb03c44bf734d886a4ee3302d83a6edb0283a428e9850b9b68

Це той самий хеш, який клієнт буде обчислювати самостійно з блоку Data сертифіката від NGINX.

Підписуємо дані використовуючи приватний ключ CA:

$ openssl dgst -sha256 -sign demo.key -out signature.bin data.txt

Тепер у файлі signature.bin маємо 256 байт – це, власне – той самий “Signature Value” із сертифіката від NGINX, тільки у нас цей Value лежить окремим файлом, а не полем в сертифікаті:

$ od -An -tx1 signature.bin | tr -d ' \n' | head -c 200
203f65033571f3c7...d51b

Далі нам треба розшифрувати цей хеш, використовуючи публічний сертифікат CA:

$ openssl pkeyutl -verifyrecover -pubin -inkey demo.pub -in signature.bin -out decrypted.bin

Перевіряємо його зміст:

$ openssl asn1parse -inform DER -in decrypted.bin
   ...
    4:d=2  hl=2 l=   9 prim: OBJECT            :sha256
   ...
   17:d=1  hl=2 l=  32 prim: OCTET STRING      [HEX DUMP]:959AF28AF72380BB03C44BF734D886A4EE3302D83A6EDB0283A428E9850B9B68

Бачимо той самий хеш “959AF28AF…850B9B68” – це наш умовний H2, і він точно дорівнює H1, який ми отримали кілька кроків тому.

Підпис валідний – значить його зробив той, хто має приватний ключ, парний до demo.pub.

Те ж саме клієнт робить кожного разу при підключенні до NGINX – тільки замість demo.pub використовує публічний ключ з ca-public.crt у своєму trust store.

Все – досить теорії.

Давайте тепер створювати ключі і сертифікати.

План дій – Certificate Authority та NGINX

Нам треба буде створити файли нашого CA, а потім – файли для NGINX:

створимо приватний ключ, ним підпишемо сертифікат для CA – отримаємо self-signed Public CA certificate
створимо приватний ключ для NGINX – він буде використовуватись під час TLS Handshake для встановлення безпечного з’єднання
створимо CSR з потрібними CN та SAN – доменами, для яких буде валідним публічний сертифікат NGINX
з цим CSR та нашим приватним ключем CA отримаємо сертифікат для NGINX
налаштуємо virtualhost в NGINX з приватним ключем та сертифікатом
додамо публічний сертифікат CA в trusted store на FreeBSD і Linux

Створення власного Certificate Authority

На FreeBSD (в моєму випадку, але процес ідентичний на будь-якому Linux) створюємо каталог:

# mkdir -p /usr/local/etc/ssl/setevoy/NasCA/
# cd /usr/local/etc/ssl/setevoy/NasCA/

Генеруємо приватний ключ CA на 4096 біт:

# openssl genrsa -out ca-private.key 4096

З цим ключем генеруємо публічний self-signed сертифікат нашого CA:

# openssl req -new -x509 -days 3650 -key ca-private.key -out ca-public.crt -subj "/C=UA/ST=Kyiv/O=Setevoy Home NAS/CN=Setevoy CA"

Тут:

-new -x509: генеруємо новий self-signed сертифікат (а не CSR)
-days 3650: сертифікат валідний 10 років (для root CA норм)
-key ca-private.key: підписуємо приватним ключем CA, який створили вище
-out ca-public.crt: куди зберегти публічний сертифікат
-subj: метадані сертифіката – поле CN потім будемо бачити в браузері

Перевіряємо:

# openssl x509 -in ca-public.crt -noout -issuer -subject
issuer=C = UA, ST = Kyiv, O = Setevoy Home NAS, CN = Setevoy CA
subject=C = UA, ST = Kyiv, O = Setevoy Home NAS, CN = Setevoy CA

Власне, issuer і subject однакові: це і є self-signed сертифікат – бо виданий від “Setevoy CA” для “Setevoy CA“.

Сертифікат для *.net.setevoy

В NGINX можна було б використати ключ ca-private.key напряму – але це наш “рутовий” ключ, і якщо NGINX зламають – атакуючий зможе підписувати ним будь-що, тому для NGINX робимо окремий ключ.

Створюємо приватний ключ для NGINX – тут вже можна зробити 2048 біт, а не 4096, як для рутового ключа CA:

# openssl genrsa -out wildcard.net.setevoy.key 2048

Тепер генеруємо CSR – Certificate Signing Request:

# openssl req -new -key wildcard.net.setevoy.key -out wildcard.net.setevoy.csr -subj "/C=UA/ST=Kyiv/O=Setevoy Home NAS/CN=*.net.setevoy"

Тут:

req -new: генеруємо новий CSR (без -x509, бо це не сертифікат)
-key wildcard.net.setevoy.key: використовуємо приватний ключ, який створили вище – його публічна частина піде в CSR
-out wildcard.net.setevoy.csr: куди зберегти сам Certificate Signing Request
CN=*.net.setevoy: wildcard, покриває всі сабдомени *.net.setevoy (хоча CN ролі не грає, див. далі)

Перевіряємо що в CSR:

# openssl req -in wildcard.net.setevoy.csr -noout -subject
subject=C = UA, ST = Kyiv, O = Setevoy Home NAS, CN = *.net.setevoy

Common Name та Subject Alternative Name

Тут є нюанс, на якому я сам спіткнувся: сучасні браузери і клієнти ігнорують Common Name (CN) і дивляться тільки на поле Subject Alternative Name (SAN), тому значення в полі CN недостатньо – треба додати SAN з усіма іменами, які покриває сертифікат.

Історія цього питання довга. RFC 2818 задепрікейтив CN на користь SAN ще у 2000, але залишив fallback:

If a subjectAltName extension of type dNSName is present, that MUST be used as the identity. Otherwise, the (most specific) Common Name field in the Subject field of the certificate MUST be used. Although the use of the Common Name is existing practice, it is deprecated and Certification Authorities are encouraged to use the dNSName instead.

Google Chrome повністю прибрав підтримку CN-matching у 2017, див. Remove support for commonName matching in certificates, Firefox і всі сучасні TLS-клієнти зробили те саме.

А вже RFC 9525 у 2023 офіційно прибрав CN-перевірку з самого стандарту – див. Identifying Application Services:

The Common Name RDN MUST NOT be used to identify a service because it is not strongly typed (it is essentially free-form text) and therefore suffers from ambiguities in interpretation.

Тобто сертифікат без SAN сьогодні – це гарантована помилка валідації, незалежно від того що в CN.

Окремий момент: wildcard *.net.setevoy покриває рівно один рівень піддомену, тобто test-ssl.net.setevoy – так, але саме net.setevoy (без префіксу) – ні. Тому в SAN додаємо обидва записи.

Створюємо файл san.cnf – можна мінімальний:

[v3_req]
subjectAltName = DNS:*.net.setevoy, DNS:net.setevoy

Або, якщо робити більше кошерно і по шаблону OpenSSL (див. x509v3_config) – то файл буде таким:

[req]
req_extensions = v3_req
distinguished_name = req_distinguished_name

[req_distinguished_name]

[v3_req]
subjectAltName = @alt_names

[alt_names]
DNS.1 = *.net.setevoy
DNS.2 = net.setevoy

Тут:

[req]: секція для команди openssl req (генерація CSR)
req_extensions = v3_req: підтягувати розширення з секції [v3_req]
distinguished_name = req_distinguished_name: поля subject (CN, O, C) брати з секції [req_distinguished_name]
[req_distinguished_name]: порожня, бо subject ми передаємо через -subj прямо в команді
[v3_req]: секція з розширеннями, які підуть у сертифікат
subjectAltName = @alt_names: значення SAN брати зі секції [alt_names], @ означає “посилання на секцію”
[alt_names]: власне список DNS-імен
DNS.1, DNS.2: workaround обмеження OpenSSL – ключ DNS в одній секції може зустрічатись тільки раз, тому додають .1, .2

Створюємо сам публічний сертифікат для NGINX, який підписується нашим приватним ключем CA:

# openssl x509 -req -days 825 -in wildcard.net.setevoy.csr -CA ca-public.crt -CAkey ca-private.key -CAcreateserial -out wildcard.net.setevoy.crt -extensions v3_req -extfile san.cnf
Certificate request self-signature ok
subject=C = UA, ST = Kyiv, O = Setevoy Home NAS, CN = *.net.setevoy

Опції тут:

x509 -req: підписуємо CSR і робимо з нього сертифікат
-CA ca-public.crt -CAkey ca-private.key: підписуємо нашим CA
-CAcreateserial: генерує серійний номер сертифіката (буде створений файл ca.srl)
-days 825: максимум, який приймає Chrome/Safari без скарг (це обмеження Apple з 2020 року, див. Apple Cuts SSL Validity Period to 13 Months Effective September 1)
-extfile san.cnf -extensions v3_req: додаємо список SAN з конфіга (без цього SAN не запишеться в сертифікат, навіть якщо він був у CSR)

Сама послідовність створення сертифікату із CSR така:

на вході у нас CSR (wildcard.net.setevoy.csr) – заявка з полями subject, public key, SAN
OpenSSL бере дані з CSR (subject, public key), додає від себе кілька полів (issuer = Setevoy CA, validity, serial number, extensions з san.cnf), збирає це все в нову структуру Data
хешує цю структуру Data, шифрує хеш приватним ключем CA – отримує Signature Value
на виході збирає Data + Signature Value в один файл – це і є wildcard.net.setevoy.crt

Перевіряємо що у нас в новому сертифікаті:

# openssl x509 -in wildcard.net.setevoy.crt -noout -issuer -subject -dates
issuer=C = UA, ST = Kyiv, O = Setevoy Home NAS, CN = Setevoy CA
subject=C = UA, ST = Kyiv, O = Setevoy Home NAS, CN = *.net.setevoy
notBefore=Apr 18 11:35:59 2026 GMT
notAfter=Jul 21 11:35:59 2028 GMT

Тепер issuer – це Setevoy CA, а subject – наш wildcard. Це означає, що сертифікат підписаний саме нашим CA, а не сам собою.

Перевіряємо що SAN на місці:

# openssl x509 -in wildcard.net.setevoy.crt -noout -ext subjectAltName
X509v3 Subject Alternative Name: 
    DNS:*.net.setevoy, DNS:net.setevoy

В результаті маємо три файли:

wildcard.net.setevoy.key: приватний ключ для NGINX
wildcard.net.setevoy.csr: Certificate Signing Request, який використовували для створення сертифікату
wildcard.net.setevoy.crt: власне – сам сертифікат, який буде віддаватись клієнтам

Налаштування SSL в NGINX

Створюємо каталог для сертифікатів:

# mkdir -p /usr/local/etc/nginx/ssl

Копіюємо сертифікат і ключ:

# cp /usr/local/etc/ssl/setevoy/NasCA/wildcard.net.setevoy.crt /usr/local/etc/nginx/ssl
# cp /usr/local/etc/ssl/setevoy/NasCA/wildcard.net.setevoy.key /usr/local/etc/nginx/ssl

Доступ до приватного ключа залишаємо тільки root:

# chmod 600 /usr/local/etc/nginx/ssl/wildcard.net.setevoy.key

Загальні параметри SSL виносимо в окремий файл /usr/local/etc/nginx/conf.d/ssl.conf, щоб не дублювати в кожному віртуалхості:

ssl_certificate     /usr/local/etc/nginx/ssl/wildcard.net.setevoy.crt;
ssl_certificate_key /usr/local/etc/nginx/ssl/wildcard.net.setevoy.key;
ssl_protocols       TLSv1.2 TLSv1.3;
ssl_ciphers         HIGH:!aNULL:!MD5;

І сам віртуалхост, наприклад /usr/local/etc/nginx/conf.d/test-ssl.net.setevoy.conf:

server {
    listen 80;
    server_name test-ssl.net.setevoy;
    return 301 https://$host$request_uri;
}

server {
    listen 443 ssl;
    server_name test-ssl.net.setevoy;
    
    include /usr/local/etc/nginx/conf.d/ssl.conf;
    
    location / {
        root /usr/local/www/nginx;
        index index.html;  
    }   
}

Хоча include /usr/local/etc/nginx/conf.d/ssl.conf можна взагалі винести в nginx.conf в секцію http{}.

Перевіряємо конфіг і ребутаємо:

# nginx -t && service nginx reload
nginx: the configuration file /usr/local/etc/nginx/nginx.conf syntax is ok
nginx: configuration file /usr/local/etc/nginx/nginx.conf test is successful

Спробуємо curl:

# curl https://test-ssl.net.setevoy
curl: (60) SSL certificate OpenSSL verify result: unable to get local issuer certificate (20)
More details here: https://curl.se/docs/sslcerts.html

curl failed to verify the legitimacy of the server and therefore could not
establish a secure connection to it. To learn more about this situation and
how to fix it, please visit the webpage mentioned above.

Це очікувано: curl не знає нашого CA, бо ми його ще нікуди не додали.

Додавання CA в локальні trusted store

Аби перевірка проходила без помилок – треба публічний сертифікат CA додати на всі хости в їхні trust store.

FreeBSD та certctl

Копіюємо CA-сертифікат у системний каталог:

# cp /usr/local/etc/ssl/setevoy/NasCA/ca-public.crt /usr/local/share/certs/setevoy-nas-ca.crt

Оновлюємо trusted store (займе пару хвилин):

# certctl rehash

Перевіряємо:

# certctl list | grep -i setevoy
certctl: Listing Trusted Certificates:
f6c33121.0      Setevoy CA

І тепер curl з хоста FreeBSD працює без помилок:

# curl https://test-ssl.net.setevoy
<!DOCTYPE html>
<html>
<head>
<title>Welcome to nginx!</title>
...

Arch Linux та trust

Копіюємо ca-public.crt з FreeBSD на ноутбук з Arch Linux:

[setevoy@setevoy-work ~] $ scp [email protected]:/usr/local/etc/ssl/setevoy/NasCA/ca-public.crt setevoy-nas-ca.crt
ca-public.crt

Кладемо в системний trust source:

[setevoy@setevoy-work ~] $ sudo cp setevoy-nas-ca.crt /etc/ca-certificates/trust-source/anchors/

Оновлюємо:

[setevoy@setevoy-work ~] $ sudo update-ca-trust

Тепер маємо сімлінк в /etc/ssl/certs/:

[setevoy@setevoy-work ~] $ ll /etc/ssl/certs/ | grep Sete
lrwxrwxrwx 1 root root   52 Apr 18 15:02 Setevoy_CA.pem -> ../../ca-certificates/extracted/cadir/Setevoy_CA.pem

І бачимо сертифікат в trust list:

[setevoy@setevoy-work ~] $ trust list | grep -i "setevoy"
    label: Setevoy CA

Перевіряємо з curl:

[setevoy@setevoy-work /tmp]  $ curl https://test-ssl.net.setevoy
<!DOCTYPE html>
<html>
<head>
<title>Welcome to nginx!</title>
...

Bonus: швидкий debug сертифікатів

Якщо браузер чи curl все ще скаржиться на сертифікат – корисні команди для перевірки.

Подивитись, що саме віддає NGINX:

$ openssl s_client -connect test-ssl.net.setevoy:443 </dev/null 2>/dev/null | openssl x509 -noout -issuer -subject -ext subjectAltName
issuer=C=UA, ST=Kyiv, O=Setevoy Home NAS, CN=Setevoy CA
subject=C=UA, ST=Kyiv, O=Setevoy Home NAS, CN=*.net.setevoy
X509v3 Subject Alternative Name: 
    DNS:*.net.setevoy, DNS:net.setevoy

Тут перевіряємо: правильний issuer (наш CA), правильний subject, і головне – Subject Alternative Name з потрібним хостом.

Перевірити підключення з конкретним CA, не додаючи його в систему:

[setevoy@setevoy-work /tmp]  $ curl --cacert ./setevoy-nas-ca.crt https://test-ssl.net.setevoy
<!DOCTYPE html>
<html>
<head>
<title>Welcome to nginx!</title>
...

Якщо з --cacert працює, а без нього – ні, значить CA не доїхав до системного trust store – перевіряємо update-ca-trust / certctl rehash.

Перевірити повний chain:

$ openssl s_client -connect test-ssl.net.setevoy:443 -showcerts
Connecting to 192.168.0.2
CONNECTED(00000003)
depth=0 C=UA, ST=Kyiv, O=Setevoy Home NAS, CN=*.net.setevoy
verify error:num=20:unable to get local issuer certificate
verify return:1
depth=0 C=UA, ST=Kyiv, O=Setevoy Home NAS, CN=*.net.setevoy
verify error:num=21:unable to verify the first certificate
verify return:1
depth=0 C=UA, ST=Kyiv, O=Setevoy Home NAS, CN=*.net.setevoy
verify return:1
---
Certificate chain
 0 s:C=UA, ST=Kyiv, O=Setevoy Home NAS, CN=*.net.setevoy
   i:C=UA, ST=Kyiv, O=Setevoy Home NAS, CN=Setevoy CA
   a:PKEY: RSA, 2048 (bit); sigalg: sha256WithRSAEncryption
   v:NotBefore: Apr 18 11:35:59 2026 GMT; NotAfter: Jul 21 11:35:59 2028 GMT
...

Браузери та сертифікати CA

Окремий момент щодо браузерів: Firefox має власний trust store і не дивиться в системний тому для Firefox власний сертифікат CA треба додавати окремо через about:preferences#privacy > “View Certificates”:

Далі Import:

І тепер працює без помилок:

Google Chrome, Brave, Vivaldi і решта на Linux зазвичай використовують системний trust store, але можна імпортувати вручну на сторінці chrome://certificate-manager/localcerts:

Готово.

AWS: налаштування Okta SSO з AWS IAM Identity Center
0 (0)

31 Березня 2026

В попередній частині серії по налаштуванню Okta зробили SSO для Grafana (див. Okta: налаштування Grafana SSO з OIDC та Role mapping) – тепер більш цікава задача: треба налаштувати SSO для AWS, і мати не тільки log in – а і users provisioning.

В Okta для цього є AWS IAM Identity Center App, яка дозволяє налаштувати логін з SAML (див. також What is: SAML – обзор, структура и трассировка запросов на примере Jenkins и Okta SAML SSO) та user provisioning із SCIM.

З боку AWS для цієї інтеграції налаштуємо власне сам IAM Identity Center, і заодно створимо AWS Organization.

З приводу Terraform: свідомо роблю без нього, бо зараз ми використовуємо Okta акаунт разом з іншим проектом і потім будемо відокремлюватись і перероблювати сетап. Ну і, крім того – я не займався налаштуваннями Okta з ~2020 року, тому перший час краще “поклікопсити”, аби краще розібратись з тими змінами, які за цей час сталися.

Аналогічно з Terraform для AWS – якщо всякі VPC/EKS у нас вже зроблені з Terraform, то налаштування, які відносяться до account management поки роблю руками, бо 100% ми будемо або переїжджати в новий акаунт, або будемо розділяти поточний, і поки невідомо як це все буде виглядати.

Але коли переїдемо – то 100% будуть пости по Terraform з Okta та AWS.

AWS та сервіси для User Management

Перш ніж почати налаштування Okta – давайте коротко про те, що взагалі в AWS є з сервісів, які мають відношення до управлінню юзерами і доступами:

AWS IAM: базовий сервіс – юзери, групи, ролі, політики
- IAM Identity Providers: наприклад, для налаштування OIDC для GitHub або OIDC для AWS Elastic Kubernetes Service
AWS IAM Identity Center (колишній AWS Single Sign-On): те, що ми будемо використовувати для Okta – централізоване управління доступом до різних AWS Accounts, інтеграція з Identity Providers (IdP – Okta, Azure Active Directory, etc)
AWS Organizations: централізоване управління різними AWS Accounts – Service Control Policies (SCP), спільні CloudTrail, Config, GuardDuty, централізований білінг
AWS Control Tower: автоматичне налаштування AWS Organizations, IAM Identity Center, загальний compliance, security

Варіанти AWS SSO та Okta

Є два підходи до інтеграції Okta з AWS:

AWS Account Federation (legacy):
- прямий SAML між Okta і кожним AWS акаунтом окремо через IAM Identity Providers – для кожного акаунту треба окремо створювати IAM Roles з Trust Policy на Okta, окремо налаштовувати SAML
- при наявності 10 акаунтів – 10 раз повторювати одне і те саме налаштування
- SCIM (provisioning) з Okta не підтримується – тобто юзери і групи не синхронізуються автоматично
IAM Identity Center:
- централізований підхід – Okta підключається один раз через SAML, юзери і групи синхронізуються автоматично за SCIM протоколом
- Permission Sets (aka IAM Policies для юзерів і груп) – права визначаються один раз і призначаються на будь-яку кількість акаунтів
- при додаванні нового акаунту в AWS Organization – просто вибираємо існуючі групи та Permission Sets, без додаткового налаштування SAML

Ми будемо робити модно-маладьожно, з IAM Identity Center:

Okta: буде нашим Idetity Provider – юзери створюються там, логін тільки через Okta
IAM Identity Center: буде отримувати аутентифікованих юзерів від Okta та виконувати авторизацію з Permission Sets

Документація: Configure SAML and SCIM with Okta and IAM Identity Center та Configure AWS accounts and roles for SAML SSO.

Про AWS Organization

AWS Organizations дає нам централізоване управління кількома AWS акаунтами – об’єднує акаунти в ієрархію (Organizational Unit, OU – повіяло ностальгією за OpenLDAP) з єдиним білінгом, є основою для multi-account management і обов’язковою умовою для повноцінного IAM Identity Center з multi-account SSO.

Що дає AWS Organizations

Billing: єдиний consolidated billing на всі акаунти. До того ж всякі Reserved Instances і Savings Plans можна використовувати між всіма акаунтами організації..

Security / Governance

Єдина точка менеджменту різними security services:

SCPs (Service Control Policies): політики обмежень на рівні акаунту або OU, які діють поверх будь-яких IAM прав і які не можна обійти навіть з AdministratorAccess, наприклад – “ніхто не може вимкнути CloudTrail” або “дозволити створення нових ресурсів тільки в заданих AWS Regions“
AWS Config aggregator: збирає дані про конфігурацію ресурсів з усіх акаунтів в одне місце – можна бачити чи всі ресурси відповідають заданим правилам, наприклад – “всі S3 buckets мають бути зашифровані” або “всі EC2 інстанси мають мати певні теги“
CloudTrail organization trail: єдиний CloudTrail для усіх акаунтів, не треба в кожному налаштовувати окремо
GuardDuty, Security Hub, Macie: централізоване управління всіма security services

Networking: RAM (Resource Access Manager): дозволяє використовувати спільні ресурси між акаунтами без необхідності налаштовувати це між кожною парою акаунтів.

Account isolation (головна причина multi-account):

можна (і треба) мати Production акаунт повністю ізольованим від Dev – випадковий terraform destroy в Dev не торкнеться Prod
- ще рекомендується мати і окремий акаунт з обмеженим доступом для security services
обмежуємо blast radius одним акаунтом: якщо пушнули ACCESS/SECRET ключі в GitHub – то “під роздачу” попаде тільки один акаунт
- хоча краще ключі не використовувати взагалі

Що відбувається при створенні Organizations

Нічого не ламається: всі існуючі IAM Users, IAM Roles, IAM Policies, всі сервіси (EKS, RDS, S3) продовжують працювати. Поточний акаунт стає management account, з’являється root OU.

Єдиний момент, який треба мати на увазі, це сам management account – його потім змінити не можна. Тому перевіряємо, що створюємо Organization з правильного акаунту – там де billing і root доступ.

Створення AWS Organization

Переходимо в AWS Organization, клікаємо Create an organization:

AWS рекомендує створювати Organization з окремого акаунту – але нам, як маленькому стартапу, підійде і поточний, в якому маємо всі наші сервіси:

Після створення Organization, AWS пропонує включити Centralize root access for member accounts – відключити root accounts, і всі адміністративні дії виконувати тільки з management account.

Нам це поки не актуально, бо взагалі маємо тільки один акаунт, але взагалі з точки зору безпеки штука корисна:

Поїхали до самого цікавого.

Створення Okta App – AWS IAM Identity Center

Спершу додамо Okta App – IAM Identity Center, бо в самому AWS IAM Identity Center потрібні будуть параметри SAML від Okta:

Отримуємо лінк на SAML metadata:

У нас в Okta кастомний домен, в браузері свариться на сертифікат, а через HSTS нема можливості цю помилку ігнорувати:

Тому просто завантажуємо з curl:

$ curl -k https://okta.example.co/app/***/sso/saml/metadata -o metadata.xml

Перевіряємо, що дані в файлі є:

$ head metadata.xml 
<?xml version="1.0" encoding="UTF-8"?><md:EntityDescriptor entityID="http://www.okta.com/***" xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata"><md:IDPSSODescriptor WantAuthnRequestsSigned="false" protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol"><md:KeyDescriptor use="signing"><ds:KeyInfo xmlns:ds="http://www.w3.org/2000/09/xmldsig#"><ds:X509Data><ds:X509Certificate>MII
...

Тепер, як AWS Organization та Okta App у нас є – можемо налаштувати IAM Identity Center.

Налаштування AWS IAM Identity Center

Документація – What is IAM Identity Center?

Що нам дасть IAM Identity Center, і що будемо налаштовувати:

AWS Access Portal: буде єдина сторінка входу в усі акаунти організації
Identity Source: налаштуємо source of truth для юзерів, в нашому випадку буде External Ientity Provider – Okta
Account Assignments: прив’язка User Groups в IAM Identity Center, які далі синхронізуємо з Okta – до Permission Set для конкретного AWS акаунту, тобто – “Okta Group з іменем org-DevOps має AdministratorAccess в акаунті <accountName>“
Permission Sets: набір IAM policies, який IAM Identity Center автоматично створює як IAM Role (з іменем, яке починається з AWSReservedSSO_) в цільовому AWS акаунті при підключенні User Group до Permission Sets, і далі, при логіні в акаунт – юзер використовує цю роль

Перед початком читаємо IAM Identity Center prerequisites and considerations, звертаємо увагу на:

IAM Identity Center creates IAM roles to give users permissions to account resources. For more information, see IAM roles created by IAM Identity Center.

AWS Organizations is recommended, but not required, for use with IAM Identity Center. If you haven’t set up an organization, you do not have to. If you’ve already set up AWS Organizations and are going to add IAM Identity Center to your organization, make sure that all AWS Organizations features are enabled. For more information, see IAM Identity Center and AWS Organizations.

Поїхали – переходимо в IAM Identity Center, клікаємо Enable:

Якщо AWS Organization ще нема – AWS пропонує її створити, якщо не хочемо мати Organization – можна включити IAM Identity Center в режимі account instance:

Якщо Organization вже є – то відразу включаємо як organization instance:

Клікаємо Enable, починаємо конфігурацію.

Налаштування Identity Source з Okta

Переходимо в Settings > Identity Source, в Actions вибираємо Change Identity Source:

Вибираємо External type:

Отримуємо URLs, зберігаємо собі:

IAM Identity Center Assertion Consumer Service (ACS) URL
IAM Identity Center issuer URL

В Identity Provider Metadata завантажуємо файл metadata.xml, який скачали з Okta App:

При зміні IAM Identity Center виводить попередження про зміни для юзерів – але це відноситься тільки для юзерів самого IAM Identity Center, яких в нашому випадку ще нема – логін для звичайних IAM Users буде працювати, як і раніше:

Налаштування SAML в Okta AWS IAM Identity Center App

Пишемо ACCEPT, клікаємо Change – отримуємо налаштування для SAML в Okta App:

Повертаємось до Okta App, переключаємось на Sign On, клікаємо Edit та задаємо адреси:

AWS SSO ACS URL: це IAM Identity Center Assertion Consumer Service (ACS) URL із AWS IAM Identity Center
AWS SSO issuer URL: це IAM Identity Center issuer URL із AWS IAM Identity Center

Власне, на цьому з аутентифікацією все.

Але залогінитись юзери ще не можуть – трохи далі налаштуємо це.

Поки зробимо Users та Groups provisiong – синхронізацію груп та юзерів із Okta до AWS IAM Identity Center.

Налаштування Provisioning з Okta до IAM Identity Center

Повертаємось до IAM Identity Center > Settings, клікаємо Enable в Automatic Provisioning:

Отримуємо URL та Access Token.

Токен відразу зберігаємо – бо більше його не побачимо:

Повертаємось до Okta > Provisioning > Configure API Integration:

Групи із IAM Identity Center в Okta нам не потрібні – ми будемо робити тільки з Okta до IAM Identity Center, тому знімаємо галочку, погоджуємось з попередженням:

Задаємо URL, токен, клікаємо Test API Credentials:

“Єсть контакт!”:

Зберігаємо, клікаємо Edit, включаємо синхронізацію юзерів, їхнії атрибутів та деактивацію юзерів (виключили акаунт в Okta – виключили в AWS):

Тепер у нас під назвою App все зелене – маємо всі інтеграції:

Assigning Okta Users та Okta Groups до Okta IAM Identity Center App

Переходимо в Assign, додаємо цю App до Okta Group:

Залишаємо всі дефолтні атрибути:

І вже маємо юзерів в IAM Identity Center:

Але не групи – тут поки пусто:

Створення Permission Set для IAM Identity Center User Groups

Документація – Create, manage, and delete permission sets.

Permission Sets визначає те, які права доступу будуть у юзера чи групи в AWS Account, тобто:

в Okta маємо Okta Group (org-DevOps)
Okta виконує group push в IAM Identity Center (про це далі)
в IAM Identity Center отримуємо нову групу org-DevOps
цю групу додаємо до AWS Account
в AWS Account створиться IAM Role з іменем AWSReservedSSO_<Permission_Set_name>
при логіні в акаунт – юзер виконує Assume Role цієї ролі

Створюємо новий Permission Set:

В Custom Permission Set можна вибрати власні політики, описати inline policy, або використати вже готові набори.

Для девопсів робимо AdministartorAccess:

Session duration можна поставити побільше:

Зберігаємо новий Permission Set, але Provisioned status поки Not provisioned – бо цей Permission Set ще нікому підключений:

Синхронізація Okta Groups з Okta Push Groups

Для синхронізації Okta Groups до AWS IAM Identity Center – переходимо в Push Groups, вибираємо групу – при чому необов’язково, щоб вона була Assigned до цієї App:

Вибираємо Okta Group:

Група готова до push в IAM Identity Center, і маємо дві опції – Create Group, якщо такої групи в AWS ще нема, або Link Group – зв’язати групу в Okta з вже існуючою групою в AWS:

Клікаємо Save, починається процес синхронізації:

Готово:

Перевіряємо групи в IAM Identity Center – є нова група з двома юзерами:

Потім в Okta можна відключити синхронізацію:

Підключення IAM Identity Center User Groups до AWS Accounts

Аби юзери цієї групи могли логінитись в AWS Account – виконуємо Assign вже в самому IAM Identity Center:

Вибираємо групу:

Вибираємо створений раніше Permission Set:

В списку AWS Accounts тепер маємо підключений Permission Set:

І в самому AWS Account в IAM Roles маємо нову роль:

Final: логін з SSO через AWS Access Portal

Знаходимо URL нашого AWS Access Portal – це буде єдина точка входу всіх юзерів:

Або клікаємо на App в Okta.

Попадаємо на сторінку вибору акаунтів, відразу бачимо Permission Set з яким можемо залогінитись:

Логінимось, і маємо доступ до всіх наших сервісів:

Власне – на цьому і все.

SSO та user provisioning налаштований, логін працює.

Для AWS Access Portal можемо налаштувати власний URL – але тільки в зоні awsapps.com – клікаємо Edit:

Задаємо власне ім’я:

І далі ходимо через https://example.awsapps.com/start.

Налаштування AWS CLI з SSO

Всі старі доступи з ACCESS/SECRET ключами ще працюють, але відразу налаштовуємо собі новий логін з SSO.

Документація – Configuring IAM Identity Center authentication with the AWS CLI.

Виконуємо aws configure sso, з --profile вказуємо для якого саме акаунту буде логін з SSO:

$ aws configure sso --profile work
SSO session name (Recommended): org-sso
SSO start URL [None]: https://example.awsapps.com/start
SSO region [None]: us-east-1
SSO registration scopes [sso:account:access]: 
Attempting to automatically open the SSO authorization page in your default browser.
...

Відкриється браузер, дозволяємо доступ:

І терміналі бачимо повідомлення, що SSO для профайлу work налаштований:

...
The only AWS account available to you is: 492***148
Using the account ID 492***148
The only role available to you is: DevOps-AdministratorAccess
Using the role name "DevOps-AdministratorAccess"
Default client Region [us-east-1]:
CLI default output format (json if not specified) [None]:
To use this profile, specify the profile name using --profile, as shown:

aws sts get-caller-identity --profile work

Перевіряємо як ми залогінені – маємо наш власний UserId, який має assumed-role/AWSReservedSSO_DevOps-AdministratorAccess:

$ aws sts get-caller-identity --profile work
{
    "UserId": "ARO***ORD:[email protected]",
    "Account": "492***148",
    "Arn": "arn:aws:sts::492***148:assumed-role/AWSReservedSSO_DevOps-AdministratorAccess_66a4ead4b037e25f/[email protected]"
}

А в ~/.aws/config тепер для юзера маємо sso_session та конфіг самого SSO:

$ cat .aws/config
...
[profile work]
region = us-east-1
output = json
sso_session = org-sso
sso_account_id = 492***148
sso_role_name = DevOps-AdministratorAccess

...
[sso-session org-sso]
sso_start_url = https://example.awsapps.com/start
sso_region = us-east-1
sso_registration_scopes = sso:account:access

Готово.

FreeBSD: налаштування FEMP – NGINX, PHP-FPM, MariaDB
0 (0)

30 Березня 2026

Чергова частина налаштування Home NAS на FreeBSD, хоча тут же не про NAS, а чисто про запуск веб-сервісів.

Вся серія постів по FreeBSD та NAS починається тут – FreeBSD: Home NAS, part 1 – налаштування ZFS mirror, там станом на зараз 15 частин, але FEMP вже винесу окремо.

На моєму хості з FreeBSD (вже є) запущений мій особистий щоденник, який, як і RTFM, працює на WordPress.

Отже, для нього треба підняти стандартний стек FEMP – FreeBSD + NGINX + PHP-FPM + MariaDB, а заодно налаштувати virtualhosts для сервісів типу Grafana, VictoriMetrics VM UI, Syncthing WebUI, Jellyfin тощо.

Робити будемо базовий сетап, без FreeBSD Jails – бо це чисто домашні внутрішні сервіси, але колись, у 2011-2013 роках, блог RTFM працював саме на такому сетапі, хіба що тоді ще була MySQL, а не MariaDB.

На цьому хості зараз FreeBSD v14.3, але принципової різниці з 15 нема.

Налаштування SSL буде окремим постом, із self-signed sertificate – тут всі віртуалхости на стандартному HTTP і порту 80.

Моніторинг NGINX/PHP описаний в VictoriaMetrics: базовий моніторинг AWS, Linux, NGINX та PHP.

Установка NGINX

Є в репозиторіях, встановлюємо з pkg:

root@setevoy-nas:~ # pkg install nginx

Додаємо в автостарт:

root@setevoy-nas:~ # sysrc nginx_enable="YES"

Запускаємо сервіс:

root@setevoy-nas:~ # service nginx start

Перевіряємо порт:

root@setevoy-nas:~ # sockstat -4 -l | grep nginx
www      nginx        455 6   tcp4   *:80                  *:*
root     nginx        454 6   tcp4   *:80                  *:*

Перевіряємо, що все працює:

root@setevoy-nas:~ # curl localhost:80
<!DOCTYPE html>
<html>
<head>
<title>Welcome to nginx!</title>
...

Налаштування NGINX virtualhosts

Створюємо каталог для конфігів власних віртуалхостів:

root@setevoy-nas:~ # mkdir -p /usr/local/etc/nginx/conf.d

Додаємо include з цим каталогом в основний конфіг /usr/local/etc/nginx/nginx.conf:

...
http {  

    # virtualhosts
    include /usr/local/etc/nginx/conf.d/*.conf;
...

Створення NGINX virtualhost для Grafana

Створюємо новий файл /usr/local/etc/nginx/conf.d/grafana.setevoy.conf.

В ньому задаємо ім’я хоста grafana.setevoy (.setevoy – моя локальна DNS-зона на MikroTik), і вказуємо proxy_pass – адреса, на якій запущена Grafana (про установку Grafana на FreeBSD див. FreeBSD: Home NAS, part 10 – моніторинг з VictoriaMetrics та Grafana):

server {
    listen 80;
    server_name grafana.setevoy;

    location / {
        proxy_pass         http://127.0.0.1:3000;
        proxy_http_version 1.1;

        proxy_set_header   Host              $host;
        proxy_set_header   X-Real-IP         $remote_addr;
        proxy_set_header   X-Forwarded-For   $proxy_add_x_forwarded_for;
        proxy_set_header   X-Forwarded-Proto $scheme;

        proxy_set_header   Upgrade           $http_upgrade;
        proxy_set_header   Connection        "upgrade";
    }
}

Перевіряємо синтаксис конфігів, перезавантажуємо NGINX:

root@setevoy-nas:~ # nginx -t && service nginx reload

І відкриваємо в браузері http://grafana.setevoy:

Створення NGINX virtualhost для VictoriaMetrics та редіректи

На відміну від Grafana, для доступу до VM UI у VictoriaMetrics нам треба URI /vmui/ – тому відразу налаштуємо редірект: якщо на NGINX приходить запит на victoria.setevoy – то відправляємо на victoria.setevoy/vmui/:

server {
    listen 80;
    server_name victoria.setevoy;

    location = / {
        return 301 /vmui/; 
    }   

    location / {
        proxy_pass         http://127.0.0.1:8428;
        proxy_http_version 1.1;

        proxy_set_header   Host              $host;
        proxy_set_header   X-Real-IP         $remote_addr;
        proxy_set_header   X-Forwarded-For   $proxy_add_x_forwarded_for;
        proxy_set_header   X-Forwarded-Proto $scheme;
    }
}

Установка PHP та PHP-FPM

Встановлюємо з pkg з репозиторію:

root@setevoy-nas:~ # pkg install -y php84 php84-extensions

Створюємо власний php.ini:

root@setevoy-nas:~ # cp /usr/local/etc/php.ini-production /usr/local/etc/php.ini

Створюємо файл налаштувань для PHP-FPM – /usr/local/etc/php-fpm.d/blog.setevoy.conf.

Задаємо параметри FPM (див. PHP-FPM: Process Manager – dynamic vs ondemand vs static – 2018 рік, але механізм той самий).

З важливого в конфігу:

user && group: власник процесів PHP
listen: використовуємо Unix socket замість TCP
listen.owner та listen.group: власник файлу сокета – www, бо до файлу треба доступ NGINX
pm = dynamic: динамічний пул FPM workers
pm.max_children: максимальна кількість процесів PHP для цього пула
pm.start_servers: скільки процесів створювати при старті/рестарті FPM
pm.min_spare_servers та pm.max_spare_servers – мінімум та максимум процесів в idle

В результаті файл для WordPress виглядає так:

[blog.setevoy]
user = setevoy
group = setevoy

listen = /var/run/php-fpm/blog.setevoy.sock
listen.owner = www
listen.group = www
listen.mode = 0660

pm = dynamic
pm.max_children = 5
pm.start_servers = 2
pm.min_spare_servers = 1
pm.max_spare_servers = 3

slowlog = /var/log/nginx/blog.setevoy-slow.log
php_flag[display_errors] = off
php_admin_value[display_errors] = on
php_admin_value[error_log] = /var/log/nginx/blog.setevoy-php-error.log
php_admin_flag[log_errors] = on
php_admin_value[upload_max_filesize] = 128M
php_admin_value[post_max_size] = 128M

І для прикладу – поточний конфіг самого rtfm.co.ua – тільки він в AWS на EC2 з Amazon Linux:

[rtfm.co.ua]

; run workers as this user
user = rtfm
group = rtfm

; unix socket path for nginx upstream
listen = /var/run/rtfm.co.ua-php-fpm.sock

; socket owner - must match nginx user
listen.owner = nginx
listen.group = nginx

; process manage settings
pm = dynamic                   ; dynamic - spawn/kill workers based on load
pm.max_children = 8            ; max workers total
pm.start_servers = 2           ; workers on startup
pm.min_spare_servers = 2       ; min idle workers
pm.max_spare_servers = 4       ; max idle workers
pm.process_idle_timeout = 10s  ; kill idle workers after N seconds
pm.max_requests = 500          ; restart worker after N requests (prevents memory leaks)

; write worker stderr to main fpm log
catch_workers_output = yes
; worker startup directory
chdir = /
; endpoint for fpm status page (use in nginx location)
pm.status_path = /fpm-status

; fpm-level log for requests slower than request_slowlog_timeout
slowlog = /var/log/php/rtfm.co.ua/rtfm.co.ua-slow.log

; php ini overrides - php_admin_value cannot be overridden by app code
php_admin_value[display_errors] = off
php_admin_value[error_log] = /var/log/php/rtfm.co.ua/rtfm.co.ua-error.log
php_admin_flag[log_errors] = on

; sessions - make sure /var/lib/php/session/rtfm exists, owner rtfm:rtfm
php_admin_value[session.save_path] = /var/lib/php/session/rtfm
php_value[session.save_handler] = files

; max upload size
php_admin_value[upload_max_filesize] = 128M
php_admin_value[post_max_size] = 128M
php_admin_value[memory_limit] = 256M

Створюємо каталог для сокетів:

root@setevoy-nas:~ # mkdir -p /var/run/php-fpm

Додаємо PHP-FPM в автостарт:

root@setevoy-nas:~ # sysrc php_fpm_enable="YES"

Запускаємо:

root@setevoy-nas:~ # service php_fpm start
Performing sanity check on php-fpm configuration:
[18-Feb-2026 18:21:59] NOTICE: configuration file /usr/local/etc/php-fpm.conf test is successful
Starting php_fpm.

Перевіряємо файл сокету – що він є і має правильні права доступу:

root@setevoy-nas:~ # ls -la /var/run/php-fpm/php-fpm.sock
srw-rw----  1 www www 0 Feb 18 18:21 /var/run/php-fpm/php-fpm.sock

Створення NGINX virtualhost для перевірки PHP

Додаємо новий віртуалхост для NGINX – файл /usr/local/etc/nginx/conf.d/blog.setevoy.conf:

server {
    listen 80;
    server_name blog.setevoy;

    root /usr/local/www/blog.setevoy;
    index index.php index.html;

    access_log /var/log/nginx/blog.setevoy.access.log;
    error_log  /var/log/nginx/blog.setevoy.error.log;

    location / {
        try_files $uri $uri/ /index.php?$args;
    }

    location ~ \.php$ {
        fastcgi_pass  unix:/var/run/php-fpm/blog.setevoy.sock;
        fastcgi_index index.php;
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
        include       fastcgi_params;
    }

    location ~ /\.ht {
        deny all;
    }
}

Створюємо каталог для файлів майбутнього блогу:

root@setevoy-nas:~ # mkdir -p /usr/local/www/blog.setevoy

І там один файл з викликом phpinfo() для тесту:

root@setevoy-nas:~ # echo "<?php phpinfo();" > /usr/local/www/blog.setevoy/phpinfo.php

Задаємо власника:

root@setevoy-nas:~ # chown -R setevoy:setevoy /usr/local/www/blog.setevoy

Перевіряємо в браузері http://blog.setevoy/phpinfo.php:

Установка MariaDB

Шукаємо останню доступну версію:

root@setevoy-nas:~ # pkg search mariadb | grep server
mariadb1011-server-10.11.15    Multithreaded SQL database (server)
mariadb106-server-10.6.24      Multithreaded SQL database (server)
mariadb114-server-11.4.9       Multithreaded SQL database (server)

Встановлюємо MariaDB 11.4:

root@setevoy-nas:~ # pkg install mariadb114-server

Додаємо в автостарт, запускаємо:

root@setevoy-nas:~ # sysrc mysql_enable="YES"
root@setevoy-nas:~ # service mysql-server start

Запускаємо скрипт mariadb-secure-installation для дефолтних налаштувань:

root@setevoy-nas:~ # mariadb-secure-installation

Проходимось по основним параметрам, тут можна всюди відповідати просто “yes” – хіба що задати пароль root:

root@setevoy-nas:~ # mariadb-secure-installation
/usr/local/bin/mysql_secure_installation: Deprecated program name. It will be removed in a future release, use 'mariadb-secure-installation' instead
...
Switch to unix_socket authentication [Y/n] 
Enabled successfully!
Reloading privilege tables..
 ... Success!

...
Change the root password? [Y/n] 
New password: 
Re-enter new password: 
Password updated successfully!
Reloading privilege tables..
 ... Success!

...
Remove anonymous users? [Y/n] 
 ... Success!

...
Disallow root login remotely? [Y/n] 
 ... Success!

...
Remove test database and access to it? [Y/n] 
 - Dropping test database...
 ... Success!
 - Removing privileges on test database...
 ... Success!

...
Reload privilege tables now? [Y/n] 
 ... Success!

Cleaning up...

All done!  If you've completed all of the above steps, your MariaDB
installation should now be secure.

Thanks for using MariaDB!

Створення MariaDB database та user

Підключаємось до сервера:

root@setevoy-nas:~ # mysql -u root -p
Enter password: 
Welcome to the MariaDB monitor.  Commands end with ; or \g.
Your MariaDB connection id is 13
Server version: 11.4.9-MariaDB FreeBSD Ports

Copyright (c) 2000, 2018, Oracle, MariaDB Corporation Ab and others.

Type 'help;' or '\h' for help. Type '\c' to clear the current input statement.

root@localhost [(none)]>

Створюємо базу, юзера з паролем, даємо юзеру доступ до цієї бази:

root@localhost [(none)]> CREATE DATABASE blog_test CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
Query OK, 1 row affected (0.003 sec)

root@localhost [(none)]> CREATE USER 'blog-test'@'localhost' IDENTIFIED BY 'localpass';
Query OK, 0 rows affected (0.001 sec)

root@localhost [(none)]> GRANT ALL PRIVILEGES ON blog_test.* TO 'blog-test'@'localhost';
Query OK, 0 rows affected (0.001 sec)

root@localhost [(none)]> FLUSH PRIVILEGES;
Query OK, 0 rows affected (0.001 sec)

Виходимо, пробуємо підключитись з цим юзером:

root@setevoy-nas:~ # mysql -u blog-test -p blog_test
Enter password: 
Welcome to the MariaDB monitor.  Commands end with ; or \g.
Your MariaDB connection id is 14
Server version: 11.4.9-MariaDB FreeBSD Ports

Copyright (c) 2000, 2018, Oracle, MariaDB Corporation Ab and others.

Type 'help;' or '\h' for help. Type '\c' to clear the current input statement.

blog-test@localhost [blog_test]>

Установка WordPress

Завантажуємо архів з останнім релізом, розпаковуємо, переносимо файли в каталог /usr/local/www/blog.setevoy/:

root@setevoy-nas:~ # fetch https://wordpress.org/latest.tar.gz -o /tmp/latest.tar.gz
root@setevoy-nas:~ # tar -xzf /tmp/latest.tar.gz -C /tmp/

root@setevoy-nas:~ # cp -r /tmp/wordpress/* /usr/local/www/blog.setevoy/

root@setevoy-nas:~ # chown -R setevoy:setevoy /usr/local/www/blog.setevoy/

Відкриваємо в браузері – WordPress свариться на missing PHP extentions:

Встановлюємо:

root@setevoy-nas:~ # pkg install php84-mysqli php84-pdo_mysql
root@setevoy-nas:~ # service php-fpm restart

Починаємо установку:

Задаємо ім’я бази, юзера, пароль, хост MariaDB:

Взагалі WordPress наче має сам створити файл wp-config.php, але ок – копіюємо зміст, створюємо файл вручну:

Але знов помилка – “Call to undefined function WpOrg\Requests\gzinflate()“:

Додаємо ще один пакет з PHP:

root@setevoy-nas:~ # pkg install php84-zlib

root@setevoy-nas:~ # service php_fpm restart

І тепер все працює – завершуємо налаштування:

Готово:

І навіть прийшов лист на пошту, бо на FreeBSD налаштований DragonFly Mail Agent – див. FreeBSD: налаштування DragonFly Mail Agent для пошти root:

Логінимось в адмінку блога:

Все працює.

Готово.

Липень 2026
Пн	Вт	Ср	Чт	Пт	Сб	Нд
		1	2	3	4	5
6	7	8	9	10	11	12
13	14	15	16	17	18	19
20	21	22	23	24	25	26
27	28	29	30	31