Аутентификация
Эндпоинты, требующие аутентификации, должны вызываться с указанием заголовка HTTP-запроса X-Auth-Token
, содержащего API-токен.
Метрики
Отправка метрик
Для отправки метрик поддерживается протокол: Prometheus Remote-Write.
Пример запроса:
POST /api/v1/push
Этот эндпоинт принимает HTTP POST-запрос. Данные запроса закодированы с использованием Protocol Buffers и сжаты с помощью Snappy.
Определение protobuf-сообщения можно найти в файле pkg/mimirpb/mimir.proto
. HTTP-запрос должен содержать заголовок X-Prometheus-Remote-Write-Version
с версией 0.1.0
.
Просмотр метрик
Общий формат
Instant queries метрик
Этот эндпоинт выполняет мгновенный запрос на указанную точку времени.
Пример запроса:
GET /prometheus/api/v1/query
POST /prometheus/api/v1/query
Параметры запроса в URL:
query=<string>
: строка выражения запроса Prometheus.time=<rfc3339 | unix_timestamp>
: отметка времени для выполнения запроса. Опционально.timeout=<duration>
: время ожидания выполнения запроса. Опционально. По умолчанию ограничено значением флага-query.timeout
.
Если параметр time
пропущен, используется текущее время сервера.
Вы можете закодировать параметры запроса непосредственно в теле запроса, используя метод POST
и заголовок Content-Type: application/x-www-form-urlencoded
.
Это полезно при указании больших запросов, которые могут превысить ограничение на длину URL.
Формат секции данных в результате запроса:
1{
2 "resultType": "matrix" | "vector" | "scalar" | "string",
3 "result": <value>
4}
<value>
относится к данным результатов запроса, формат которых зависит от resultType
. Смотри форматы результатов запросов выражений.
Пример:
Пример запроса для выполнения выражения up
на время 2015-07-01T20:10:51.781Z
:
1$ curl -H "X-Auth-Token: <API-token>" \
2 'https://api.dop.example.com/prometheus/api/v1/query?query=up&time=2015-07-01T20:10:51.781Z'
Ответ:
1{
2 "status" : "success",
3 "data" : {
4 "resultType" : "vector",
5 "result" : [
6 {
7 "metric" : {
8 "__name__" : "up",
9 "job" : "prometheus",
10 "instance" : "localhost:9090"
11 },
12 "value": [ 1435781451.781, "1" ]
13 },
14 {
15 "metric" : {
16 "__name__" : "up",
17 "job" : "node",
18 "instance" : "localhost:9100"
19 },
20 "value" : [ 1435781451.781, "0" ]
21 }
22 ]
23 }
24}
Range queries
Этот эндпоинт выполняет выражение запроса на диаграмму времени по диапазону:
GET /prometheus/api/v1/query_range
POST /prometheus/api/v1/query_range
Параметры URL:
query=<string>
: строка выражения Prometheus.start=<rfc3339 | unix_timestamp>
: начальная временная метка.end=<rfc3339 | unix_timestamp>
: конечная временная метка.step=<duration | float>
: шаг разрешения диаграммы (форматduration
или число секунд в формате float).timeout=<duration>
: время ожидания выполнения. Опционально.
Пример:
Пример запроса с выражением up
за 30-секундный диапазон с разрешением 15 секунд:
1$ curl -H "X-Auth-Token: <API-token>" \
2 'https://api.dop.example.com/prometheus/api/v1/query_range?query=up&start=2015-07-01T20:10:30.781Z&end=2015-07-01T20:11:00.781Z&step=15s'
Ответ:
1{
2 "status" : "success",
3 "data" : {
4 "resultType" : "matrix",
5 "result" : [
6 {
7 "metric" : {
8 "__name__" : "up",
9 "job" : "prometheus",
10 "instance" : "localhost:9090"
11 },
12 "values" : [
13 [ 1435781430.781, "1" ],
14 [ 1435781445.781, "1" ],
15 [ 1435781460.781, "1" ]
16 ]
17 },
18 {
19 "metric" : {
20 "__name__" : "up",
21 "job" : "node",
22 "instance" : "localhost:9091"
23 },
24 "values" : [
25 [ 1435781430.781, "0" ],
26 [ 1435781445.781, "0" ],
27 [ 1435781460.781, "1" ]
28 ]
29 }
30 ]
31 }
32}
Querying metadata
Deckhouse Observability Platform предоставляет несколько API для запроса метаданных о временных рядах и их метках.
Поиск ряда по набору меток
Эндпоинт возвращает список временных рядов, соответствующих определённому набору меток:
GET /prometheus/api/v1/series
POST /prometheus/api/v1/series
Параметры URL:
match[]=<series_selector>
: повторяющийся аргумент селектора, который выбирает возвращаемые ряды. Необходимо указать хотя бы один аргументmatch[]
.start=<rfc3339 | unix_timestamp>
: начальная временная метка.end=<rfc3339 | unix_timestamp>
: конечная временная метка.limit=<number>
: Максимальное количество возвращаемых рядов. По умолчанию 0, что означает отсутствие ограничения.
Пример:
1$ curl -H "X-Auth-Token: <API-token>" \
2 -g 'https://api.dop.example.com/prometheus/api/v1/series?' \
3 --data-urlencode 'match[]=up' \
4 --data-urlencode 'match[]=process_start_time_seconds{job="prometheus"}'
Ответ:
1{
2 "status" : "success",
3 "data" : [
4 { "__name__" : "up", "job" : "prometheus", "instance" : "localhost:9090" },
5 { "__name__" : "up", "job" : "node", "instance" : "localhost:9091" },
6 { "__name__" : "process_start_time_seconds", "job" : "prometheus", "instance" : "localhost:9090" }
7 ]
8}
Получение имен меток
Этот эндпоинт возвращает список имен меток:
GET /prometheus/api/v1/labels
POST /prometheus/api/v1/labels
Пример:
1$ curl -H "X-Auth-Token: <API-token>" \
2 'https://api.dop.example.com/prometheus/api/v1/labels'
Ответ:
1{
2 "status": "success",
3 "data": [
4 "__name__",
5 "call",
6 "code",
7 "config",
8 "dialer_name",
9 "endpoint",
10 "event",
11 "goversion",
12 "handler",
13 "instance",
14 "interval",
15 "job",
16 "le",
17 "listener_name",
18 "name",
19 "quantile",
20 "reason",
21 "role",
22 "scrape_job",
23 "slice",
24 "version"
25 ]
26}
Получение значений меток
Этот эндпоинт возвращает список значений для указанного имени метки:
GET /prometheus/api/v1/label/<label_name>/values
Пример:
Пример запроса для значений метки job
:
1$ curl -H "X-Auth-Token: <API-token>" \
2 https://api.dop.example.com/prometheus/api/v1/label/job/values
Ответ:
1{
2 "status" : "success",
3 "data" : [
4 "node",
5 "prometheus"
6 ]
7}
Форматы результатов запросов выражений
Запросы выражений могут возвращать следующие значения в свойстве result
секции данных.
Шаблоны <sample_value>
используются для представления числовых значений. Поскольку формат JSON не поддерживает специальные значения с плавающей точкой, такие как NaN
, Inf
и -Inf
, образцы данных передаются как строковые значения в кавычках вместо чисел.
Ключи "histogram"
и "histograms"
появляются только в том случае, если в ответе присутствуют экспериментальные нативные гистограммы.
Шаблон <histogram>
поясняется ниже в отдельном разделе.
Range vectors
Range vectors возвращаются как результат типа matrix
. Соответствующее свойство result
имеет следующий формат:
1[
2 {
3 "metric": { "<label_name>": "<label_value>", ... },
4 "values": [ [ <unix_time>, "<sample_value>" ], ... ],
5 "histograms": [ [ <unix_time>, <histogram> ], ... ]
6 },
7 ...
8]
Каждая серия может включать ключ values
, ключ histograms
, или оба.
Для каждого временного штампа будет только одна выборка — либо типа float
, либо типа histogram
.
Серии возвращаются отсортированными по метрикам. Функции, такие как sort
и sort_by_label
, не влияют на векторы диапазонов.
Instant vectors
Мгновенные векторы возвращаются как результат типа vector
. Соответствующее свойство result
имеет следующий формат:
1[
2 {
3 "metric": { "<label_name>": "<label_value>", ... },
4 "value": [ <unix_time>, "<sample_value>" ],
5 "histogram": [ <unix_time>, <histogram> ]
6 },
7 ...
8]
Каждая серия может содержать ключ value
или ключ histogram
, но не оба.
Серии не гарантируются в каком-либо определённом порядке, если не была использована функция, такая как sort
или sort_by_label
.
Scalars
Скалярные результаты возвращаются как результат типа scalar
. Соответствующее свойство result
имеет следующий формат:
1[ <unix_time>, "<scalar_value>" ]
Строки
Строковые результаты возвращаются как результат типа string
. Соответствующее свойство result
имеет следующий формат:
1[ <unix_time>, "<string_value>" ]
Логи
Отправка логов
POST /loki/api/v1/push
Этот эндпоинт используется для отправки логов в Deckhouse Observability Platform.
По умолчанию тело POST-запроса должно быть сжато с использованием Snappy Protocol Buffer
сообщением:
Эти POST-запросы требуют HTTP-заголовка Content-Type: application/x-protobuf
.
Альтернативно, если заголовок Content-Type
установлен на application/json
, можно отправить тело POST-запроса в формате JSON:
1{
2 "streams": [
3 {
4 "stream": {
5 "label": "value"
6 },
7 "values": [
8 [ "<Unix Timestamp в наносекундах>", "<лог строка>" ],
9 [ "<Unix Timestamp в наносекундах>", "<лог строка>" ]
10 ]
11 }
12 ]
13}
Можно установить заголовок запроса Content-Encoding: gzip
для отправки сжатого JSON.
Также можно присоединить структурированные метаданные к каждой строке логов, добавив JSON-объект в конец массива логов. Этот объект не должен содержать вложенные объекты, и должен содержать только строковые ключи и значения. Он должен быть указан сразу после строки лога:
Пример:
1"values": [
2 [ "<Unix Timestamp в наносекундах>", "<лог строка>", {"trace_id": "0242ac120002", "user_id": "superUser123"}]
3]
Примеры:
Пример команды cURL для отправки потока с меткой foo=bar2
и одной строкой лога "fizzbuzz"
с использованием кодировки JSON:
1curl -H "Content-Type: application/json" \
2 -H "X-Auth-Token: <API-token>" \
3 -s -X POST "https://api.dop.example.com/loki/api/v1/push" \
4 --data-raw '{"streams": [{ "stream": { "foo": "bar2" }, "values": [ [ "1570818238000000000", "fizzbuzz" ] ] }]}'
Просмотр логов
Instant queries логов
GET /loki/api/v1/query
Этот эндпоинт позволяет выполнять запросы логов для конкретного момента времени. Instant query используются только для запрашивания логов с метриками LogQL и вернут ошибку 400 (Bad Request) в случае использования запроса логов.
Параметры запроса в URL:
query
: Запрос LogQL. Запросы с некорректным синтаксисом LogQL вернут ошибку.limit
: Максимальное количество записей для возврата. По умолчанию — 100. Применяется только для запросов, которые возвращают лог-линии.time
: Время выполнения запроса в формате Unix Timestamp в наносекундах (или другом формате). По умолчанию — текущее время.direction
: Определяет порядок сортировки логов. Поддерживаемые значения:forward
илиbackward
. По умолчанию —backward
.
Формат ответа:
1{
2 "status": "success",
3 "data": {
4 "resultType": "vector" | "streams",
5 "result": [<vector value>] | [<stream value>],
6 "stats": [<statistics>]
7 }
8}
Где vector value
имеет формат:
1{
2 "metric": {
3 <label key-value pairs>
4 },
5 "value": [
6 <number: second Unix Timestamp>,
7 <string: value>
8 ]
9}
и stream value
имеет формат:
1{
2 "stream": {
3 <label key-value pairs>
4 },
5 "values": [
6 [
7 <string: nanosecond Unix Timestamp>,
8 <string: log line>
9 ],
10 ...
11 ]
12}
Элементы в массиве values
сортируются по времени.
Первый элемент — самый свежий при использовании direction=backward
.
Самый старый элемент — первый при использовании direction=forward
.
Пример:
1curl -G -s -H 'X-Auth-Token: <API-token>' "https://api.dop.example.com/loki/api/v1/query" \
2 --data-urlencode 'query=sum(rate({job="varlogs"}[10m])) by (level)' | jq
Ответ:
1{
2 "status": "success",
3 "data": {
4 "resultType": "vector",
5 "result": [
6 {
7 "metric": {},
8 "value": [
9 1588889221,
10 "1267.1266666666666"
11 ]
12 },
13 {
14 "metric": {
15 "level": "warn"
16 },
17 "value": [
18 1588889221,
19 "37.77166666666667"
20 ]
21 },
22 {
23 "metric": {
24 "level": "info"
25 },
26 "value": [
27 1588889221,
28 "37.69"
29 ]
30 }
31 ],
32 "stats": {
33 ...
34 }
35 }
36}
Range query
GET /loki/api/v1/query_range
Этот эндпоинт позволяет запрашивать логи в пределах определенного временного диапазона. Его применяют как к запросам логов, так и к метрическим запросам LogQL.
Параметры запроса в URL:
query
: Запрос LogQL для выполнения.limit
: Максимальное количество возвращаемых записей. По умолчанию равно 100. Применяется только к типам запросов, которые возвращают поток (строки логов).start
: Начальное время запроса в виде Unix Timestamp в наносекундах или другом поддерживаемом формате. По умолчанию — один час назад. Loki возвращает результаты с меткой времени больше или равной этому значению.end
: Конечное время запроса, также в виде Unix Timestamp в наносекундах или другом поддерживаемом формате. По умолчанию — текущее время. Loki возвращает результаты с меткой времени меньше этого значения.since
: Длительность, используемая для вычисления начала относительно конца. Если значениеend
находится в будущем, начальное время вычисляется как эта длительность до текущего момента. Любое заданное значение параметраstart
имеет приоритет надsince
.step
: Шаг разбивки запроса в формате длительности или вещественное число, представляющее количество секунд. Длительность подразумевает строки формата Prometheus, такие как [0-9]+[smhdwy]. Например,5m
означает длительность в 5 минут. По умолчанию — динамическое значение на основеstart
иend
. Применяется к запросам, которые возвращают ответ в виде матрицы.interval
: Возвращает записи не реже, чем указанный интервал, может быть задан в формате длительности или вещественного числа секунд. Работает только для запросов, возвращающих поток. Не путать с параметромstep
, смотрите объяснение ниже.direction
: Определяет порядок сортировки логов. Поддерживаемые значения —forward
(по возрастанию) илиbackward
(по убыванию). По умолчанию -backward
.
Формат ответа:
1{
2 "status": "success",
3 "data": {
4 "resultType": "matrix" | "streams",
5 "result": [<matrix value>] | [<stream value>],
6 "stats" : [<statistics>]
7 }
8}
Где <matrix value>
имеет формат:
1{
2 "metric": {
3 <label key-value pairs>
4 },
5 "values": [
6 [
7 <number: second Unix Timestamp>,
8 <string: value>
9 ],
10 ...
11 ]
12}
и <stream value>
имеет формат:
1{
2 "stream": {
3 <label key-value pairs>
4 },
5 "values": [
6 [
7 <string: nanosecond Unix Timestamp>,
8 <string: log line>
9 ],
10 ...
11 ]
12}
Элементы в массиве values
отсортированы по временной метке: если используется параметр direction=backward
, первой идет самая свежая запись, а если forward
— самой старой записью.
Примеры:
1curl -G -s -H 'X-Auth-Token: <API-token>' "https://api.dop.example.com/loki/api/v1/query_range" \
2 --data-urlencode 'query=sum(rate({job="varlogs"}[10m])) by (level)' \
3 --data-urlencode 'step=300' | jq
Ответ:
1{
2 "status": "success",
3 "data": {
4 "resultType": "matrix",
5 "result": [
6 {
7 "metric": {
8 "level": "info"
9 },
10 "values": [
11 [
12 1588889221,
13 "137.95"
14 ],
15 [
16 1588889221,
17 "467.115"
18 ],
19 [
20 1588889221,
21 "658.8516666666667"
22 ]
23 ]
24 },
25 {
26 "metric": {
27 "level": "warn"
28 },
29 "values": [
30 [
31 1588889221,
32 "137.27833333333334"
33 ],
34 [
35 1588889221,
36 "467.69"
37 ],
38 [
39 1588889221,
40 "660.6933333333334"
41 ]
42 ]
43 }
44 ],
45 "stats": {
46 ...
47 }
48 }
49}
Query labels
GET /loki/api/v1/labels
Этот эндпоинт возвращает список известных меток в пределах временного диапазона.
Параметры запроса в URL:
start
: Начальное время запроса как Unix Timestamp в наносекундах. По умолчанию — 6 часов назад.end
: Конечное время, так же в формате Unix Timestamp в наносекундах. По умолчанию — текущее время.since
: Длительность для вычисления начала относительно конца.query
: Селектор потока логов, выбирающий потоки для отображения меток. Пример:{app="myapp", environment="dev"}
Формат ответа:
1{
2 "status": "success",
3 "data": [
4 <label string>,
5 ...
6 ]
7}
Пример:
1curl -G -s -H"X-Auth-Token: <API-token>" "https://api.dop.example.com/loki/api/v1/labels" | jq
Ответ:
1{
2 "status": "success",
3 "data": [
4 "foo",
5 "bar",
6 "baz"
7 ]
8}
Query label values
GET /loki/api/v1/label/<name>/values
Этот эндпоинт возвращает список возможных значений метки <name>
в пределах временного диапазона.
Параметры запроса в URL:
start
: Начальное время.end
: Конечное время.since
: Длительность для вычисления начала относительно конца.query
: Селектор логов для выбора потоков и возвращения значений метки.
Пример:
1curl -G -s -H"X-Auth-Token: <API-token>" "https://api.dop.example.com/loki/api/v1/label/foo/values" | jq
Ответ:
1{
2 "status": "success",
3 "data": [
4 "cat",
5 "dog",
6 "axolotl"
7 ]
8}
Триггеры
Параметры триггеров
metadata.name
: имя триггера, должно быть уникальным (не использоваться др. триггером проекта или глобальным триггером), допускаются строчные латинские буквы и-
metadata.generation
: версия триггераmetadata.resourceVersion
: глобальная версия триггераmetadata.creationTimestamp
: дата / время создания триггераmetadata.annotations
: список аннотаций триггера в формате имя - значение. В данный момент поддерживается аннотация категории триггераmetadata.deckhouse.io/category
spec.alertMetadata.annotations
: произвольный список аннотаций триггера в формате имя - значение.spec.alertMetadata.additionalLabels
: произвольный список лейблов триггера в формате имя - значение.spec.delays.firing
: задержка перед срабатыванием триггера (1s, 1m и т.п.)spec.delays.resolving
: продолжительность срабатывания после завершения (1s, 1m и т.п.)spec.expression
: выражение триггера, должно быть корректным prometheus выражением.spec.thresholds
: массив порогов срабатывания, должен быть как минимум один.valueExpression
: значение или выражение порога срабатыванияoperator
: оператор, допустимые значения:Equal | GreaterThan | LessThan | LessThanOrEqual | GreaterThanOrEqual | NotEqual
severity
: уровень важности, допустимые значения:Critical | Info | Warning | Setup
Получение списка триггеров проекта
Этот эндпоинт возвращает список триггеров проекта (не включая глобальные триггеры).
GET /api/v1/observability.deckhouse.io/spaces/:space_name/projects/:project_name/alertingrules
Параметры адреса запроса в URL:
space_name
: имя рабочего пространства. Обязательноеproject_name
: имя проекта. Обязательное
Требуется аутентификация… У токена должны быть права “Управление через API” “Триггеры и производные метрики”
Пример запроса
1$ curl -H "X-Auth-Token: <API-token>" \
2 'https://api.dop.example.com/api/v1/observability.deckhouse.io/spaces/:space_name/projects/:project_name/alertingrules'
Пример ответа
1{
2 "apiVersion": "observability.deckhouse.io/v1alpha1",
3 "kind": "List",
4 "metadata":
5 {},
6 "items":
7 [
8 {
9 "apiVersion": "observability.deckhouse.io/v1alpha1",
10 "kind": "ObservabilityMetricsAlertingRule",
11 "metadata":
12 {
13 "creationTimestamp": "2024-12-11T10:38:23Z",
14 "generation": 1,
15 "annotations":
16 {
17 "metadata.deckhouse.io/category": "Main"
18 },
19 "name": "rule-name",
20 "resourceVersion": 1
21 },
22 "spec":
23 {
24 "alertMetadata":
25 {
26 "annotations":
27 {
28 "summary": "{{ $labels.instance }} pgbouncer '{{ $labels.conf }}' configuration incomplete"
29 },
30 "additionalLabels":
31 {
32 "additional_label": "value"
33 }
34 },
35 "delays":
36 {
37 "firing": "1m",
38 "resolving": "0s"
39 },
40 "expression": "job:request_latency_seconds:mean5m{job=\"myjob\"}",
41 "thresholds":
42 [
43 {
44 "valueExpression": "0.5",
45 "operator": "GreaterThan",
46 "severity": "Warning"
47 }
48 ]
49 }
50 }
51 ]
52}
Получение триггера
Этот эндпоинт возвращает триггер по имени.
GET /api/v1/observability.deckhouse.io/spaces/:space_name/projects/:project_name/alertingrules/:name
Параметры адреса запроса в URL:
space_name
: имя рабочего пространства. Обязательноеproject_name
: имя проекта. Обязательноеname
: имя тригера. Обязательное
Требуется аутентификация… У токена должны быть права “Управление через API” “Триггеры и производные метрики”
Пример запроса
1$ curl -H "X-Auth-Token: <API-token>" \
2 'https://api.dop.example.com/api/v1/observability.deckhouse.io/spaces/:space_name/projects/:project_name/alertingrules/:name'
Пример ответа
1{
2 "apiVersion": "observability.deckhouse.io/v1alpha1",
3 "kind": "ObservabilityMetricsAlertingRule",
4 "metadata":
5 {
6 "creationTimestamp": "2024-12-11T10:42:56Z",
7 "generation": 1,
8 "annotations":
9 {
10 "metadata.deckhouse.io/category": "Main"
11 },
12 "name": "test1",
13 "resourceVersion": 1
14 },
15 "spec":
16 {
17 "alertMetadata":
18 {
19 "annotations":
20 {
21 "summary": "{{ $labels.instance }} pgbouncer '{{ $labels.conf }}' configuration incomplete"
22 },
23 "additionalLabels":
24 {
25 "testlabel": "value"
26 }
27 },
28 "delays":
29 {
30 "firing": "1m",
31 "resolving": "0s"
32 },
33 "expression": "job:request_latency_seconds:mean5m{job=\"myjob\"}",
34 "thresholds":
35 [
36 {
37 "valueExpression": "0.5",
38 "operator": "GreaterThan",
39 "severity": "Warning"
40 }
41 ]
42 }
43}
Создание триггера
Этот эндпоинт создает новый триггер.
POST /api/v1/observability.deckhouse.io/spaces/:space_name/projects/:project_name/alertingrules/
Параметры адреса запроса в URL:
space_name
: имя рабочего пространства. Обязательноеproject_name
: имя проекта. Обязательное
Требуется аутентификация… У токена должны быть права “Управление через API” “Триггеры и производные метрики”
Пример запроса
1$ curl -X POST -H "Content-Type: application/json" -H "X-Auth-Token: <API-token>" \
2 'https://api.dop.example.com/api/v1/observability.deckhouse.io/spaces/:space_name/projects/:project_name/alertingrules/' -d \
3'
4{
5 "kind": "ObservabilityMetricsAlertingRule",
6 "metadata":
7 {
8 "annotations":
9 {
10 "metadata.deckhouse.io/category": "critical"
11 },
12 "name": "some-name"
13 },
14 "spec":
15 {
16 "alertMetadata":
17 {
18 "annotations":
19 {
20 "summary": "some description summary"
21 },
22 "additionalLabels":
23 {
24 "testlabel": "value"
25 }
26 },
27 "delays":
28 {
29 "firing": "1s",
30 "resolving": "1s"
31 },
32 "expression": "vector(10)",
33 "thresholds":
34 [
35 {
36 "valueExpression": "0.5",
37 "operator": "GreaterThan",
38 "severity": "critical"
39 }
40 ]
41 }
42}
43'
Пример ответа
1{
2 "apiVersion": "observability.deckhouse.io/v1alpha1",
3 "kind": "ObservabilityMetricsAlertingRule",
4 "metadata":
5 {
6 "creationTimestamp": "2024-12-11T10:48:11Z",
7 "generation": 1,
8 "annotations":
9 {
10 "metadata.deckhouse.io/category": "critical"
11 },
12 "name": "some-name",
13 "resourceVersion": 1
14 },
15 "spec":
16 {
17 "alertMetadata":
18 {
19 "annotations":
20 {
21 "summary": "some description summary"
22 },
23 "additionalLabels":
24 {
25 "testlabel": "value"
26 }
27 },
28 "delays":
29 {
30 "firing": "1s",
31 "resolving": "1s"
32 },
33 "expression": "vector(10)",
34 "thresholds":
35 [
36 {
37 "valueExpression": "0.5",
38 "operator": "GreaterThan",
39 "severity": "Critical"
40 }
41 ]
42 }
43}
Обновление триггера
Этот эндпоинт обновляет существующий триггер.
PUT api/v1/observability.deckhouse.io/spaces/:space_name/projects/:project_name/alertingrules/:name
Параметры адреса запроса в URL:
space_name
: имя рабочего пространства. Обязательноеproject_name
: имя проекта. Обязательноеname
: имя триггера
Требуется аутентификация… У токена должны быть права “Управление через API” “Триггеры и производные метрики”
Пример запроса
1$ curl -X PUT -H "Content-Type: application/json" -H "X-Auth-Token: <API-token>" \
2 'https://api.dop.example.com/api/v1/observability.deckhouse.io/spaces/:space_name/projects/:project_name/alertingrules/:name' -d \
3'
4{
5 "kind": "ObservabilityMetricsAlertingRule",
6 "metadata":
7 {
8 "annotations":
9 {
10 "metadata.deckhouse.io/category": "critical"
11 }
12 },
13 "spec":
14 {
15 "alertMetadata":
16 {
17 "annotations":
18 {
19 "summary": "{{ $labels.instance }} pgbouncer '{{ $labels.conf }}' configuration incomplete"
20 },
21 "additionalLabels":
22 {
23 "somelabel": "value"
24 }
25 },
26 "delays":
27 {
28 "firing": "2s",
29 "resolving": "3s"
30 },
31 "expression": "vector(10)",
32 "thresholds":
33 [
34 {
35 "valueExpression": "0.5",
36 "operator": "GreaterThan",
37 "severity": "critical"
38 }
39 ]
40 }
41}
42'
Пример ответа
1{
2 "apiVersion": "observability.deckhouse.io/v1alpha1",
3 "kind": "ObservabilityMetricsAlertingRule",
4 "metadata":
5 {
6 "creationTimestamp": "2024-12-13T06:16:03Z",
7 "generation": 1,
8 "annotations":
9 {
10 "metadata.deckhouse.io/category": "critical"
11 },
12 "name": "test1",
13 "resourceVersion": 1
14 },
15 "spec":
16 {
17 "alertMetadata":
18 {
19 "annotations":
20 {
21 "summary": "{{ $labels.instance }} pgbouncer '{{ $labels.conf }}' configuration incomplete"
22 },
23 "additionalLabels":
24 {
25 "somelabel": "value"
26 }
27 },
28 "delays":
29 {
30 "firing": "2s",
31 "resolving": "3s"
32 },
33 "expression": "vector(10)",
34 "thresholds":
35 [
36 {
37 "valueExpression": "0.5",
38 "operator": "GreaterThan",
39 "severity": "Critical"
40 }
41 ]
42 }
43}
Удаление триггера
Этот эндпоинт удаляет существующий триггер.
DELETE /api/v1/observability.deckhouse.io/spaces/:space_name/projects/:project_name/alertingrules/:name
Параметры адреса запроса в URL:
space_name
: имя рабочего пространства. Обязательноеproject_name
: имя проекта. Обязательноеname
: имя триггера
Требуется аутентификация… У токена должны быть права “Управление через API” “Триггеры и производные метрики”
Пример запроса
1$ curl -X DELETE -H "Content-Type: application/json" -H "X-Auth-Token: <API-token>" \
2 'https://api.dop.example.com/api/v1/observability.deckhouse.io/spaces/:space_name/projects/:project_name/alertingrules/:name'
Ошибки при создании или обновлении триггеров
В случае, если запрос на создание или обновление триггера содержит некорректные данные, ответ будет со статусом 4xx с указанием ошибки:
1{"error":"Validation failed: Name has already been taken"}
Производные метрики
Параметры производных метрик
metadata.name
: имя метрики, должно быть уникальным (не использоваться др. метрикой проекта или глобальной метрикой), допускаются строчные латинские буквы и-
metadata.generation
: версия метрикиmetadata.resourceVersion
: глобальная версия метрикиmetadata.creationTimestamp
: дата / время создания метрикиmetadata.annotations
: список аннотаций метрики в формате имя - значение. В данный момент поддерживается аннотация категории метрикиmetadata.deckhouse.io/category
spec.expression
: выражение метрики, должно быть корректным prometheus выражением.spec.alertMetadata.targetMetric
: параметры метрикиname
: имя метрики, допускаются строчные латинские буквы и:
, пример:some:metric
, должны быть уникальными.additionalLabels
: произвольный список лейблов метрики в формате имя - значение.
Получение списка производных метрик проекта
Этот эндпоинт возвращает список производных метрик проекта (не включая глобальные метрики).
GET /api/v1/observability.deckhouse.io/spaces/:space_name/projects/:project_name/recordingrules
Параметры адреса запроса в URL:
space_name
: имя рабочего пространства. Обязательноеproject_name
: имя проекта. Обязательное
Требуется аутентификация… У токена должны быть права “Управление через API” “Триггеры и производные метрики”
Пример запроса
1$ curl -H "X-Auth-Token: <API-token>" \
2 'https://api.dop.example.com/api/v1/observability.deckhouse.io/spaces/:space_name/projects/:project_name/recordingrules'
Пример ответа
1{
2 "apiVersion": "v1",
3 "kind": "List",
4 "metadata": {},
5 "items":
6 [
7 {
8 "apiVersion": "observability.deckhouse.io/v1alpha1",
9 "kind": "ObservabilityMetricsRecordingRule",
10 "spec":
11 {
12 "expression": "vector(10)",
13 "targetMetric":
14 {
15 "name": "test:vector",
16 "additionalLabels":
17 {
18 "test": "test",
19 "author": "test"
20 }
21 }
22 },
23 "metadata":
24 {
25 "creationTimestamp": "2024-12-13T06:24:30Z",
26 "generation": 1,
27 "annotations":
28 {
29 "metadata.deckhouse.io/category": "Main"
30 },
31 "name": "test-vector-1",
32 "resourceVersion": 1
33 }
34 }
35 ]
36}
Получение производной метрики
Этот эндпоинт возвращает производную метрику по имени.
GET /api/v1/observability.deckhouse.io/spaces/:space_name/projects/:project_name/recordingrules/:name
Параметры адреса запроса в URL:
space_name
: имя рабочего пространства. Обязательноеproject_name
: имя проекта. Обязательноеname
: имя производной метрики. Обязательное
Требуется аутентификация… У токена должны быть права “Управление через API” “Триггеры и производные метрики”
Пример запроса
1$ curl -H "X-Auth-Token: <API-token>" \
2 'https://api.dop.example.com/api/v1/observability.deckhouse.io/spaces/:space_name/projects/:project_name/recordingrules/:name'
Пример ответа
1{
2 "apiVersion": "observability.deckhouse.io/v1alpha1",
3 "kind": "ObservabilityMetricsRecordingRule",
4 "spec":
5 {
6 "expression": "vector(10)",
7 "targetMetric":
8 {
9 "name": "test:vector",
10 "additionalLabels":
11 {
12 "test": "test",
13 "author": "test"
14 }
15 }
16 },
17 "metadata":
18 {
19 "creationTimestamp": "2024-12-13T06:37:39Z",
20 "generation": 1,
21 "annotations":
22 {
23 "metadata.deckhouse.io/category": "Main"
24 },
25 "name": "test-vector-1",
26 "resourceVersion": 1
27 }
28}
Создание производной метрики
Этот эндпоинт создает новую производную метрику.
POST /api/v1/observability.deckhouse.io/spaces/:space_name/projects/:project_name/recordingrules
Параметры адреса запроса в URL:
space_name
: имя рабочего пространства. Обязательноеproject_name
: имя проекта. Обязательное
Требуется аутентификация… У токена должны быть права “Управление через API” “Триггеры и производные метрики”
Пример запроса
1$ curl -X POST -H "Content-Type: application/json" -H "X-Auth-Token: <API-token>" \
2 'https://api.dop.example.com/api/v1/observability.deckhouse.io/spaces/:space_name/projects/:project_name/recordingrules' -d \
3'
4{
5 "kind": "ObservabilityMetricsRecordingRule",
6 "metadata":
7 {
8 "annotations":
9 {
10 "metadata.deckhouse.io/category": "recording"
11 },
12 "name": "some-name"
13 },
14 "spec":
15 {
16 "targetMetric":
17 {
18 "name": "metric:rule:name",
19 "additionalLabels":
20 {
21 "testlabel": "value"
22 }
23 },
24 "expression": "vector(10)"
25 }
26}
27'
Пример ответа
1{
2 "apiVersion": "observability.deckhouse.io/v1alpha1",
3 "kind": "ObservabilityMetricsRecordingRule",
4 "spec":
5 {
6 "expression": "vector(10)",
7 "targetMetric":
8 {
9 "name": "metric:rule:name",
10 "additionalLabels":
11 {
12 "testlabel": "value"
13 }
14 }
15 },
16 "metadata":
17 {
18 "creationTimestamp": "2024-12-13T06:40:08Z",
19 "generation": 1,
20 "annotations":
21 {
22 "metadata.deckhouse.io/category": "recording"
23 },
24 "name": "some-name",
25 "resourceVersion": 1
26 }
27}
Обновление производной метрики
Этот эндпоинт обновляет существующую производную метрику.
PUT /api/v1/observability.deckhouse.io/spaces/:space_name/projects/:project_name/recordingrules/:name
Параметры адреса запроса в URL:
space_name
: имя рабочего пространства. Обязательноеproject_name
: имя проекта. Обязательноеname
: имя производной метрики
Требуется аутентификация… У токена должны быть права “Управление через API” “Триггеры и производные метрики”
Пример запроса
1$ curl -X PUT -H "Content-Type: application/json" -H "X-Auth-Token: <API-token>" \
2 'https://api.dop.example.com/api/v1/observability.deckhouse.io/spaces/:space_name/projects/:project_name/recordingrules/:name' -d \
3'
4{
5 "kind": "ObservabilityMetricsRecordingRule",
6 "metadata":
7 {
8 "annotations":
9 {
10 "metadata.deckhouse.io/category": "recording updated"
11 },
12 "name": "test-vector-1"
13 },
14 "spec":
15 {
16 "targetMetric":
17 {
18 "name": "metric:rule:name:updated",
19 "additionalLabels":
20 {
21 "testlabel": "value"
22 }
23 },
24 "expression": "vector(11)"
25 }
26}
27'
Пример ответа
1{
2 "apiVersion": "observability.deckhouse.io/v1alpha1",
3 "kind": "ObservabilityMetricsRecordingRule",
4 "spec":
5 {
6 "expression": "vector(11)",
7 "targetMetric":
8 {
9 "name": "metric:rule:name:updated",
10 "additionalLabels":
11 {
12 "testlabel": "value"
13 }
14 }
15 },
16 "metadata":
17 {
18 "creationTimestamp": "2024-12-13T06:42:35Z",
19 "generation": 1,
20 "annotations":
21 {
22 "metadata.deckhouse.io/category": "recording updated"
23 },
24 "name": "test-vector-1",
25 "resourceVersion": 1
26 }
27}
Удаление производной метрики
Этот эндпоинт удаляет существующую метрику.
DELETE /api/v1/observability.deckhouse.io/spaces/:space_name/projects/:project_name/recordingrules/:name
Параметры адреса запроса в URL:
space_name
: имя рабочего пространства. Обязательноеproject_name
: имя проекта. Обязательноеname
: имя метрики
Требуется аутентификация… У токена должны быть права “Управление через API” “Триггеры и производные метрики”
Пример запроса
1$ curl -X DELETE -H "Content-Type: application/json" -H "X-Auth-Token: <API-token>" \
2 'https://api.dop.example.com/api/v1/observability.deckhouse.io/spaces/:space_name/projects/:project_name/recordingrules/:name'
Ошибки при создании или обновлении метрик
В случае, если запрос на создание или обновление метрики содержит некорректные данные, ответ будет со статусом 4xx с указанием ошибки:
1{"error":"Validation failed: Name has already been taken"}
Дашборды
Параметры дашбордов
metadata.name
: имя дашборда, должно быть уникальным (не использоваться др. дашбордом проекта или глобальным дашбордом), допускаются строчные латинские буквы и-
metadata.generation
: версия дашбордаmetadata.resourceVersion
: глобальная версия дашбордаmetadata.creationTimestamp
: дата / время создания дашбордаmetadata.annotations
: список аннотаций дашборда в формате имя - значение. В данный момент поддерживаются аннотации:metadata.deckhouse.io/category
- категория дашбордаmetadata.deckhouse.io/title
- отображаемое название
spec.definition
: JSON описание дашборда
Получение списка дашбордов проекта
Этот эндпоинт возвращает список дашбордов проекта (не включая глобальные метрики).
GET /api/v1/observability.deckhouse.io/spaces/:space_name/projects/:project_name/observabilitydashboards
Параметры адреса запроса в URL:
space_name
: имя рабочего пространства. Обязательноеproject_name
: имя проекта. Обязательное
Требуется аутентификация… У токена должны быть права “Управление через API” “Дашборды”
Пример запроса
1$ curl -H "X-Auth-Token: <API-token>" \
2 'https://api.dop.example.com/api/v1/observability.deckhouse.io/spaces/:space_name/projects/:project_name/observabilitydashboards'
Пример ответа
1{
2 "apiVersion": "observability.deckhouse.io/v1alpha1",
3 "kind": "ObservabilityDashboardList",
4 "items":
5 [
6 {
7 "apiVersion": "observability.deckhouse.io/v1alpha1",
8 "kind": "ObservabilityDashboard",
9 "metadata":
10 {
11 "annotations":
12 {
13 "metadata.deckhouse.io/category": "Category-3",
14 "metadata.deckhouse.io/title": "dashboard-3"
15 },
16 "creationTimestamp": "2025-01-24T10:32:23Z",
17 "generation": 1,
18 "name": "dash-dash-board-3",
19 "namespace": "spicy-space-1",
20 "resourceVersion": 1
21 },
22 "spec":
23 {
24 "definition": "{\"id\":255,\"uid\":\"GrxobkC5leWtZmaE\",\"tags\":[\"test\",\"test1\"],\"title\":\"Dash-dash-board-3\"}"
25 }
26 }
27 ]
28}
Получение дашборда
Этот эндпоинт возвращает дашборд по имени.
GET /api/v1/observability.deckhouse.io/spaces/:space_name/projects/:project_name/observabilitydashboards/:name
Параметры адреса запроса в URL:
space_name
: имя рабочего пространства. Обязательноеproject_name
: имя проекта. Обязательноеname
: имя дашборда. Обязательное
Требуется аутентификация… У токена должны быть права “Управление через API” “Дашборды”
Пример запроса
1$ curl -H "X-Auth-Token: <API-token>" \
2 'https://api.dop.example.com/api/v1/observability.deckhouse.io/spaces/:space_name/projects/:project_name/observabilitydashboards/:name'
Пример ответа
1{
2 "apiVersion": "observability.deckhouse.io/v1alpha1",
3 "kind": "ObservabilityDashboard",
4 "metadata":
5 {
6 "annotations":
7 {
8 "metadata.deckhouse.io/category": "Category-1",
9 "metadata.deckhouse.io/title": "Dash-dash-board 1"
10 },
11 "creationTimestamp": "2025-01-24T10:38:57Z",
12 "generation": 1,
13 "name": "dash-dash-board-1",
14 "namespace": "spicy-space-1",
15 "resourceVersion": 1
16 },
17 "spec":
18 {
19 "definition": "{\"uid\":\"KttpW5ERbCrk6H8R\",\"tags\":[\"test\",\"test1\"],\"title\":\"Dash-dash-board-1\"}"
20 }
21}
Создание дашборда
Этот эндпоинт создает новую производную метрику.
POST /api/v1/observability.deckhouse.io/spaces/:space_name/projects/:project_name/observabilitydashboards
Параметры адреса запроса в URL:
space_name
: имя рабочего пространства. Обязательноеproject_name
: имя проекта. Обязательное
Требуется аутентификация… У токена должны быть права “Управление через API” “Дашборды”
Пример запроса
1$ curl -X POST -H "Content-Type: application/json" -H "X-Auth-Token: <API-token>" \
2 'https://api.dop.example.com/api/v1/observability.deckhouse.io/spaces/:space_name/projects/:project_name/observabilitydashboards' -d \
3'
4{
5 "kind": "ObservabilityDashboard",
6 "metadata":
7 {
8 "annotations":
9 {
10 "metadata.deckhouse.io/category": "category-name",
11 "metadata.deckhouse.io/title": "some name"
12 },
13 "name": "some-name"
14 },
15 "spec":
16 {
17 "definition": {...}
18 }
19}
20'
Пример ответа
1{
2 "apiVersion": "observability.deckhouse.io/v1alpha1",
3 "kind": "ObservabilityDashboard",
4 "metadata":
5 {
6 "annotations":
7 {
8 "metadata.deckhouse.io/category": "category-name",
9 "metadata.deckhouse.io/title": "some name"
10 },
11 "creationTimestamp": "2025-01-24T10:41:12Z",
12 "generation": 1,
13 "name": "some-name",
14 "namespace": "spicy-space-1",
15 "resourceVersion": 1
16 },
17 "spec":
18 {
19 "definition": "{\"uid\":\"czvSGOukIQTWEE19\",\"tags\":[\"test\"],\"title\":\"some name\"}"
20 }
21}
Обновление дашборда
Этот эндпоинт обновляет существующий дашборд.
PUT /api/v1/observability.deckhouse.io/spaces/:space_name/projects/:project_name/observabilitydashboards/:name
Параметры адреса запроса в URL:
space_name
: имя рабочего пространства. Обязательноеproject_name
: имя проекта. Обязательноеname
: имя дашборда
Требуется аутентификация… У токена должны быть права “Управление через API” “Дашборды”
Пример запроса
1$ curl -X PUT -H "Content-Type: application/json" -H "X-Auth-Token: <API-token>" \
2 'https://api.dop.example.com/api/v1/observability.deckhouse.io/spaces/:space_name/projects/:project_name/observabilitydashboards/:name' -d \
3'
4{
5 "kind": "ObservabilityDashboard",
6 "metadata":
7 {
8 "annotations":
9 {
10 "metadata.deckhouse.io/category": "new-category"
11 }
12 },
13 "spec":
14 {
15 "definition": {...}
16 }
17}
18'
Пример ответа
1{
2 "apiVersion": "observability.deckhouse.io/v1alpha1",
3 "kind": "ObservabilityDashboard",
4 "metadata":
5 {
6 "annotations":
7 {
8 "metadata.deckhouse.io/category": "new-category",
9 "metadata.deckhouse.io/title": "Dash-dash-board-1"
10 },
11 "creationTimestamp": "2025-01-24T10:45:15Z",
12 "generation": 1,
13 "name": "dash-dash-board-1",
14 "namespace": "spicy-space-1",
15 "resourceVersion": 1
16 },
17 "spec":
18 {
19 "definition": "{\"uid\":\"yS1Qy46y6x01bFJI\",\"tags\":[\"test\",\"another-test\"],\"title\":\"Dash-dash-board-1\"}"
20 }
21}
Удаление дашборда
Этот эндпоинт удаляет существующий дашборд.
DELETE /api/v1/observability.deckhouse.io/spaces/:space_name/projects/:project_name/observabilitydashboards/:name
Параметры адреса запроса в URL:
space_name
: имя рабочего пространства. Обязательноеproject_name
: имя проекта. Обязательноеname
: имя дашборда
Требуется аутентификация… У токена должны быть права “Управление через API” “Дашборды”
Пример запроса
1$ curl -X DELETE -H "Content-Type: application/json" -H "X-Auth-Token: <API-token>" \
2 'https://api.dop.example.com/api/v1/observability.deckhouse.io/spaces/:space_name/projects/:project_name/observabilitydashboards/:name'
Ошибки при создании или обновлении дашбордов
В случае, если запрос на создание или обновление дашборда содержит некорректные данные, ответ будет со статусом 4xx с указанием ошибки:
1{"error":"Validation failed: Name has already been taken"}
Рабочие пространства
Параметры рабочего пространства
metadata.name
: имя рабочего пространства, должно быть уникальным, допускаются строчные латинские буквы и-
metadata.generation
: версия рабочего пространстваmetadata.resourceVersion
: глобальная версия рабочего пространстваmetadata.creationTimestamp
: дата / время создания рабочего пространства
Получение списка рабочих пространств
Этот эндпоинт возвращает список рабочих пространств.
GET /api/v1/observability.deckhouse.io/spaces
Требуется аутентификация… У токена должны быть права “Управление через API” “Рабочие пространства”
Пример запроса
1$ curl -H "X-Auth-Token: <API-token>" \
2 'https://api.dop.example.com/api/v1/observability.deckhouse.io/spaces'
Пример ответа
1{
2 "apiVersion": "observability.deckhouse.io/v1alpha1",
3 "kind": "ObservabilitySpacesList",
4 "metadata": {},
5 "items":
6 [
7 {
8 "apiVersion": "observability.deckhouse.io/v1alpha1",
9 "kind": "ObservabilitySpace",
10 "metadata":
11 {
12 "creationTimestamp": "2025-03-14T06:07:50Z",
13 "generation": 1,
14 "name": "example-space",
15 "resourceVersion": 1
16 },
17 "spec":
18 {}
19 }
20 ]
21}
Получение рабочего пространства
Этот эндпоинт возвращает рабочее пространство по имени.
GET /api/v1/observability.deckhouse.io/spaces/:name
Параметры адреса запроса в URL:
name
: имя рабочего пространства. Обязательное
Требуется аутентификация… У токена должны быть права “Управление через API” “Рабочие пространства”
Пример запроса
1$ curl -H "X-Auth-Token: <API-token>" \
2 'https://api.dop.example.com/api/v1/observability.deckhouse.io/spaces/:name'
Пример ответа
1{
2 "apiVersion": "observability.deckhouse.io/v1alpha1",
3 "kind": "ObservabilitySpace",
4 "metadata":
5 {
6 "creationTimestamp": "2025-03-14T06:07:50Z",
7 "generation": 1,
8 "name": "example-space",
9 "resourceVersion": 1
10 },
11 "spec":
12 {}
13}
Создание рабочего пространства
Этот эндпоинт создает новое рабочее пространство.
POST /api/v1/observability.deckhouse.io/spaces
Требуется аутентификация… У токена должны быть права “Управление через API” “Рабочие пространства”
Пример запроса
1$ curl -X POST -H "Content-Type: application/json" -H "X-Auth-Token: <API-token>" \
2 'https://api.dop.example.com/api/v1/observability.deckhouse.io/spaces' -d \
3'
4{
5 "kind": "ObservabilitySpace",
6 "metadata":
7 {
8 "name": "some-name"
9 }
10}
11'
Пример ответа
1{
2 "apiVersion": "observability.deckhouse.io/v1alpha1",
3 "kind": "ObservabilitySpace",
4 "metadata":
5 {
6 "creationTimestamp": "2025-03-14T06:07:50Z",
7 "generation": 1,
8 "name": "some-name",
9 "resourceVersion": 1
10 },
11 "spec":
12 {}
13}
Удаление рабочего пространства
Этот эндпоинт удаляет существующее рабочее пространство.
DELETE /api/v1/observability.deckhouse.io/spaces/:name
Параметры адреса запроса в URL:
name
: имя рабочего пространства
Требуется аутентификация… У токена должны быть права “Управление через API” “Рабочие пространства”
Пример запроса
1$ curl -X DELETE -H "Content-Type: application/json" -H "X-Auth-Token: <API-token>" \
2 'https://api.dop.example.com/api/v1/observability.deckhouse.io/spaces/:name'
Ошибки при создании рабочих пространств
В случае, если запрос на создание рабочего пространства содержит некорректные данные, ответ будет со статусом 4xx с указанием ошибки:
1{"error":"Validation failed: Space name has already been taken"}
Проекты
Параметры проекта
metadata.name
: имя проекта, должно быть уникальным в рамках рабочего пространства, допускаются строчные латинские буквы и-
metadata.generation
: версия проектаmetadata.resourceVersion
: глобальная версия проектаmetadata.creationTimestamp
: дата / время создания проектаspec.description
: описание проектаspec.auto-monitoring
: флаг, используется ли автомониторинг в указанном проекте или нет.
Получение списка проектов рабочего пространства
Этот эндпоинт возвращает список проектов рабочего пространства.
GET /api/v1/observability.deckhouse.io/spaces/:space_name/projects
Параметры адреса запроса в URL:
space_name
: имя рабочего пространства. Обязательное
Требуется аутентификация… У токена должны быть права “Управление через API” “Проекты”
Пример запроса
1$ curl -H "X-Auth-Token: <API-token>" \
2 'https://api.dop.example.com/api/v1/observability.deckhouse.io/spaces/:space_name/projects/'
Пример ответа
1{
2 "apiVersion": "observability.deckhouse.io/v1alpha1",
3 "kind": "ObservabilityProjectsList",
4 "metadata": {},
5 "items":
6 [
7 {
8 "apiVersion": "observability.deckhouse.io/v1alpha1",
9 "kind": "ObservabilityProject",
10 "metadata":
11 {
12 "creationTimestamp": "2025-03-14T06:06:41Z",
13 "generation": 1,
14 "name": "some-project",
15 "resourceVersion": 1
16 },
17 "spec":
18 {
19 "description": "project description",
20 "auto-monitoring": true
21 }
22 }
23 ]
24}
Получение проекта
Этот эндпоинт возвращает проект по имени.
GET /api/v1/observability.deckhouse.io/spaces/:space_name/projects/:name
Параметры адреса запроса в URL:
space_name
: имя рабочего пространства. Обязательноеname
: имя проекта. Обязательное
Требуется аутентификация… У токена должны быть права “Управление через API” “Проекты”
Пример запроса
1$ curl -H "X-Auth-Token: <API-token>" \
2 'https://api.dop.example.com/api/v1/observability.deckhouse.io/spaces/:space_name/projects/:name'
Пример ответа
1{
2 "apiVersion": "observability.deckhouse.io/v1alpha1",
3 "kind": "ObservabilityProject",
4 "metadata":
5 {
6 "creationTimestamp": "2025-03-14T06:06:41Z",
7 "generation": 1,
8 "name": "some-project",
9 "resourceVersion": 1
10 },
11 "spec":
12 {
13 "description": "project description",
14 "auto-monitoring": true
15 }
16}
Создание проекта
Этот эндпоинт создает новый проект.
POST /api/v1/observability.deckhouse.io/spaces/:space_name/projects
Параметры адреса запроса в URL:
space_name
: имя рабочего пространства. Обязательное
Требуется аутентификация… У токена должны быть права “Управление через API” “Проекты”
Пример запроса
1$ curl -X POST -H "Content-Type: application/json" -H "X-Auth-Token: <API-token>" \
2 'https://api.dop.example.com/api/v1/observability.deckhouse.io/spaces/:space_name/projects' -d \
3'
4{
5 "kind": "ObservabilityProject",
6 "metadata":
7 {
8 "name": "some-name"
9 },
10 "spec":
11 {
12 "description": "project description",
13 "auto-monitoring": true
14 }
15}
16'
Пример ответа
1{
2 "apiVersion": "observability.deckhouse.io/v1alpha1",
3 "kind": "ObservabilityProject",
4 "metadata":
5 {
6 "creationTimestamp": "2025-03-14T06:06:41Z",
7 "generation": 1,
8 "name": "some-project",
9 "resourceVersion": 1
10 },
11 "spec":
12 {
13 "description": "project description",
14 "auto-monitoring": true
15 }
16}
Обновление проекта
Этот эндпоинт обновляет существующий проект.
PUT /api/v1/observability.deckhouse.io/spaces/:space_name/projects/:name
Параметры адреса запроса в URL:
space_name
: имя рабочего пространства. Обязательноеname
: имя проекта. Обязательное
Требуется аутентификация… У токена должны быть права “Управление через API” “Проекты”
Пример запроса
1$ curl -X PUT -H "Content-Type: application/json" -H "X-Auth-Token: <API-token>" \
2 'https://api.dop.example.com/api/v1/observability.deckhouse.io/spaces/:space_name/projects/:name' -d \
3'
4{
5 "kind": "ObservabilityProject",
6 "spec":
7 {
8 "description": "updated description",
9 "auto-monitoring": false
10 }
11}
12'
Пример ответа
1{
2 "apiVersion": "observability.deckhouse.io/v1alpha1",
3 "kind": "ObservabilityProject",
4 "metadata":
5 {
6 "creationTimestamp": "2025-03-14T06:06:41Z",
7 "generation": 1,
8 "name": "some-project",
9 "resourceVersion": 1
10 },
11 "spec":
12 {
13 "description": "updated description",
14 "auto-monitoring": false
15 }
16}
Удаление проекта
Этот эндпоинт удаляет существующий проект.
DELETE /api/v1/observability.deckhouse.io/spaces/:space_name/projects/:name
Параметры адреса запроса в URL:
space_name
: имя рабочего пространства. Обязательноеname
: имя проекта. Обязательное
Требуется аутентификация… У токена должны быть права “Управление через API” “Проекты”
Пример запроса
1$ curl -X DELETE -H "Content-Type: application/json" -H "X-Auth-Token: <API-token>" \
2 'https://api.dop.example.com/api/v1/observability.deckhouse.io/spaces/:space_name/projects/:name'
Ошибки при создании или обновлении проекта
В случае, если запрос на создание или обновление проекта содержит некорректные данные, ответ будет со статусом 4xx с указанием ошибки:
1{"error":"Validation failed: Project name has already been taken"}
Каналы уведомлений
Параметры канала уведомлений
metadata.name
: имя канала уведомлений, должно быть уникальным в рамках проекта, допускаются строчные латинские буквы и-
metadata.generation
: версия канала уведомленийmetadata.resourceVersion
: глобальная версия канала уведомленийmetadata.creationTimestamp
: дата / время создания канала уведомленийspec.type
: тип канала уведомлений, допустимые значения: Email, Telegram, Webhook, Slack
Параметры Email канала уведомлений
spec.email.from
: email, с которого будут отправляться сообщенияspec.email.smtp.address
: адрес почтового сервераspec.email.smtp.auth.username
: пользователь для авторизации на почтовом сервереspec.email.smtp.auth.password
: пароль для авторизации на почтовом сервереspec.email.stmp.requireTLS
: флаг, указывает, требуется ли TLS при отправке сообщений. Допустимые значения: true / falsespec.email.template
: шаблон сообщения. Возвращается в ответах, не изменяется с помощью API
Параметры Telegram канала уведомлений
spec.telegram.apiUrl
: URL API телеграмма, по умолчанию используется стандартный https://api.telegram.orgspec.telegram.apiToken
: Авторизационный токен для канала телеграммspec.telegram.template
: шаблон сообщения. Возвращается в ответах, не изменяется с помощью API
Параметры Slack канала уведомлений
spec.slack.apiURL
: Slack URL для отправки уведомленийspec.slack.template
: шаблон сообщения. Возвращается в ответах, не изменяется с помощью API
Параметры Webhook канала уведомлений
spec.webhook.url
: URL для отправки сообщений
Получение списка каналов проекта
Этот эндпоинт возвращает список каналов уведомлений проекта и общедоступных каналов уведомлений. Для общедоступных каналов возвращаются только название и тип, без параметров канала.
GET /api/v1/observability.deckhouse.io/spaces/:space_name/projects/:project_name/observabilitynotificationchannels
Параметры адреса запроса в URL:
space_name
: имя рабочего пространства. Обязательноеproject_name
: имя проекта
Требуется аутентификация… У токена должны быть права “Управление через API” “Каналы уведомлений”
Пример запроса
1$ curl -H "X-Auth-Token: <API-token>" \
2 'https://api.dop.example.com/api/v1/observability.deckhouse.io/spaces/:space_name/projects/:project_name/observabilitynotificationchannels'
Пример ответа
1{
2 "apiVersion": "observability.deckhouse.io/v1alpha1",
3 "kind": "ObservabilityNotificationChannelsList",
4 "metadata": {},
5 "items": [
6 {
7 "apiVersion": "observability.deckhouse.io/v1alpha1",
8 "kind": "ObservabilityNotificationChannel",
9 "metadata": {
10 "name": "example-channel",
11 "creationTimestamp": "2025-03-19T06:12:20Z",
12 "generation": 1,
13 "resourceVersion": "1"
14 },
15 "spec": {
16 "type": "Email",
17 "email": {
18 "from": "no-reply@email.com",
19 "smtp": {
20 "address": "smtp.example.server.com:555",
21 "auth": {
22 "username": "username",
23 "password": "password"
24 },
25 "requireTLS": true
26 },
27 "template": "..."
28 }
29 }
30 },
31 ]
32}
Получение канала уведомлений
Этот эндпоинт возвращает канал уведомлений проекта по имени.
GET /api/v1/observability.deckhouse.io/spaces/:space_name/projects/:project_name/observabilitynotificationchannels/:name
Параметры адреса запроса в URL:
space_name
: имя рабочего пространства. Обязательноеproject_name
: имя проектаname
: имя канала. Обязательное
Требуется аутентификация… У токена должны быть права “Управление через API” “Каналы уведомлений”
Пример запроса
1$ curl -H "X-Auth-Token: <API-token>" \
2 'https://api.dop.example.com/api/v1/observability.deckhouse.io/spaces/:space_name/projects/:project_name/observabilitynotificationchannels/:name'
Пример ответа
1{
2 "apiVersion": "observability.deckhouse.io/v1alpha1",
3 "kind": "ObservabilityNotificationChannel",
4 "metadata": {
5 "name": "example-channel",
6 "creationTimestamp": "2025-03-19T06:12:20Z",
7 "generation": 1,
8 "resourceVersion": "1"
9 },
10 "spec": {
11 "type": "Email",
12 "email": {
13 "from": "no-reply@email.com",
14 "smtp": {
15 "address": "smtp.example.server.com:555",
16 "auth": {
17 "username": "username",
18 "password": "password"
19 },
20 "requireTLS": true
21 },
22 "template": "..."
23 }
24 }
25}
Создание канала уведомлений
Этот эндпоинт создает новый канал уведомлений проекта.
POST /api/v1/observability.deckhouse.io/spaces/:space_name/projects/:project_name/observabilitynotificationchannels
Параметры адреса запроса в URL:
space_name
: имя рабочего пространства. Обязательноеproject_name
: имя проекта
Требуется аутентификация… У токена должны быть права “Управление через API” “Каналы уведомлений”
Пример запроса
1$ curl -X POST -H "Content-Type: application/json" -H "X-Auth-Token: <API-token>" \
2 'https://api.dop.example.com/api/v1/observability.deckhouse.io/spaces/:space_name/projects/:project_name/observabilitynotificationchannels' -d \
3'
4{
5 "kind": "ObservabilityNotificationChannel",
6 "metadata":
7 {
8 "name": "new-channel"
9 },
10 "spec":
11 {
12 "type": "Email",
13 "email":
14 {
15 "from": "from@email.com",
16 "smtp":
17 {
18 "address": "smtp.example.com:444",
19 "auth":
20 {
21 "username": "username",
22 "password": "password"
23 },
24 "requireTLS": true
25 }
26 }
27 }
28}
29'
Пример ответа
1{
2 "apiVersion": "observability.deckhouse.io/v1alpha1",
3 "kind": "ObservabilityNotificationChannel",
4 "metadata":
5 {
6 "name": "new-channel",
7 "creationTimestamp": "2025-03-28T05:04:45Z",
8 "generation": 1,
9 "resourceVersion": "1"
10 },
11 "spec":
12 {
13 "type": "Email",
14 "email":
15 {
16 "from": "from@email.com",
17 "smtp":
18 {
19 "address": "smtp.example.com:444",
20 "auth":
21 {
22 "username": "username",
23 "password": "password"
24 },
25 "requireTLS": true
26 },
27 "template": null
28 }
29 }
30}
Обновление канала уведомлений
Этот эндпоинт обновляет канал уведомлений проекта
PUT /api/v1/observability.deckhouse.io/spaces/:space_name/projects/:project_name/observabilitynotificationchannels/:name
Параметры адреса запроса в URL:
space_name
: имя рабочего пространства. Обязательноеproject_name
: имя проектаname
: имя канала. Обязательное
Требуется аутентификация… У токена должны быть права “Управление через API” “Каналы уведомлений”
Пример запроса
1$ curl -X PUT -H "Content-Type: application/json" -H "X-Auth-Token: <API-token>" \
2 'https://api.dop.example.com/api/v1/observability.deckhouse.io/spaces/:space_name/projects/:project_name/observabilitynotificationchannels/:name' -d \
3'
4{
5 "kind": "ObservabilityNotificationChannel",
6 "metadata":
7 {
8 "name": "some-channel-1"
9 },
10 "spec":
11 {
12 "type": "Email",
13 "email":
14 {
15 "from": "from2@email.com",
16 "smtp":
17 {
18 "address": "smtp.example.com:444",
19 "auth":
20 {
21 "username": "username",
22 "password": "password"
23 },
24 "requireTLS": true
25 }
26 }
27 }
28}
29'
Пример ответа
1{
2 "apiVersion": "observability.deckhouse.io/v1alpha1",
3 "kind": "ObservabilityNotificationChannel",
4 "metadata":
5 {
6 "name": "some-channel-1",
7 "creationTimestamp": "2025-03-28T05:08:42Z",
8 "generation": 1,
9 "resourceVersion": "1"
10 },
11 "spec":
12 {
13 "type": "Email",
14 "email":
15 {
16 "from": "from2@email.com",
17 "smtp":
18 {
19 "address": "smtp.example.com:444",
20 "auth":
21 {
22 "username": "username",
23 "password": "password"
24 },
25 "requireTLS": true
26 },
27 "template": null
28 }
29 }
30}
Удаление канала уведомлений
Этот эндпоинт удаляет существующий канал уведомлений проекта.
DELETE /api/v1/observability.deckhouse.io/spaces/:space_name/projects/:project_name/observabilitynotificationchannels/:name
Параметры адреса запроса в URL:
space_name
: имя рабочего пространства. Обязательноеproject_name
: имя проектаname
: имя канала. Обязательное
Требуется аутентификация… У токена должны быть права “Управление через API” “Каналы уведомлений”
Пример запроса
1$ curl -X DELETE -H "Content-Type: application/json" -H "X-Auth-Token: <API-token>" \
2 'https://api.dop.example.com/api/v1/observability.deckhouse.io/spaces/:space_name/projects/:project_name/observabilitynotificationchannels/:name'
Ошибки при создании или обновлении канала уведомлений
В случае, если запрос на создание или обновление канала содержит некорректные данные, ответ будет со статусом 4xx с указанием ошибки:
1{"error":"Validation failed: Name has already been taken"}
Правила уведомлений
Параметры правил уведомлений
metadata.name
: имя канала уведомлений, должно быть уникальным в рамках проекта, допускаются строчные латинские буквы и-
metadata.generation
: версия канала уведомленийmetadata.resourceVersion
: глобальная версия канала уведомленийmetadata.creationTimestamp
: дата / время создания канала уведомленийspec.alert.selector.matchExpressions.items
: массив селекторов уведомлений, описан нижеspec.notification.channel.name
: имя канала уведомленийspec.notification.parameters
: параметры уведомления, зависят от типа канала, описаны нижеspec.notification.repeatInterval
: интервал повторного уведомления, строкове значение вида ’30s’, ‘5m’, ‘1h’ (допустимы секунды, минуты и часы)
Селектор уведомлений
key
: наименование лейблаoperator
: строковое обозначение оператора, допустимые значения Equal, NotEqual, Regex, NotRegexvalue
: строковое значение лейбла для сравнения оператором
Параметры Email канала уведомлений
spec.notification.parameters.emails
: массив адресов email, на которые отправляется данное уведомление
Параметры Telegram канала уведомлений
spec.notification.parameters.chatIds
: массив идентификаторов чатов, на которые отправляются уведомления
Параметры Slack канала уведомлений
spec.notification.parameters.channels
: массив названий каналов Slack, в которые отправляется уведомление
Параметры Webhook канала уведомлений
Правила уведомлений для webhook-каналов не используют параметры.
Получение списка правил уведомления канала
Этот эндпоинт возвращает список правил уведомлений канала уведомлений рабочего пространства.
GET /api/v1/observability.deckhouse.io/spaces/:space_name/projects/:project_name/observabilitynotificationpolicies
Параметры адреса запроса в URL:
space_name
: имя рабочего пространства. Обязательноеproject_name
: имя проекта
Требуется аутентификация… У токена должны быть права “Управление через API” “Правила уведомлений”
Пример запроса
1$ curl -H "X-Auth-Token: <API-token>" \
2 'https://api.dop.example.com/api/v1/observability.deckhouse.io/spaces/:space_name/projects/:project_name/observabilitynotificationpolicies'
Пример ответа
1{
2 "apiVersion": "observability.deckhouse.io/v1alpha1",
3 "kind": "ObservabilityNotificationPoliciesList",
4 "metadata": {},
5 "items":
6 [
7 {
8 "apiVersion": "observability.deckhouse.io/v1alpha1",
9 "kind": "ObservabilityNotificationPolicy",
10 "metadata": {
11 "name": "test-rule",
12 "creationTimestamp": "2025-03-28T06:42:47Z",
13 "generation": 1,
14 "resourceVersion": "1"
15 },
16 "spec": {
17 "alert": {
18 "selector": {
19 "matchExpressions": {
20 "items":
21 [
22 {
23 "key": "severity",
24 "operator": "Equal",
25 "value": "critical"
26 }
27 ]
28 }
29 }
30 },
31 "notification":
32 {
33 "channel":
34 {
35 "kind": "ObservabilityNotificationChannel",
36 "name": "some-channel-1",
37 "parameters": { "emails": ["test@email.com"] }
38 },
39 "repeatInterval": "30s"
40 }
41 }
42 }
43 ]
44}
Получение правила уведомлений
Этот эндпоинт возвращает правило канала уведомлений проекта по имени.
GET /api/v1/observability.deckhouse.io/spaces/:space_name/projects/:project_name/observabilitynotificationpolicies/:name
Параметры адреса запроса в URL:
space_name
: имя рабочего пространства. Обязательноеproject_name
: имя проектаname
: имя канала. Обязательное
Требуется аутентификация… У токена должны быть права “Управление через API” “Правила уведомлений”
Пример запроса
1$ curl -H "X-Auth-Token: <API-token>" \
2 'https://api.dop.example.com/api/v1/observability.deckhouse.io/spaces/:space_name/projects/:project_name/observabilitynotificationpolicies/:name'
Пример ответа
1{
2 "apiVersion": "observability.deckhouse.io/v1alpha1",
3 "kind": "ObservabilityNotificationPolicy",
4 "metadata": {
5 "name": "test-rule",
6 "creationTimestamp": "2025-03-28T07:00:54Z",
7 "generation": 1,
8 "resourceVersion": "1"
9 },
10 "spec": {
11 "alert": {
12 "selector": {
13 "matchExpressions": {
14 "items": [
15 {
16 "key": "severity",
17 "operator": "Equal",
18 "value": "critical"
19 }
20 ]
21 }
22 }
23 },
24 "notification": {
25 "channel": {
26 "kind": "ObservabilityNotificationChannel",
27 "name": "some-giper-channel-1",
28 "parameters": {
29 "emails": ["test@email.com"]
30 }
31 },
32 "repeatInterval": "30s"
33 }
34 }
35}
Создание правила уведомлений
Этот эндпоинт создает новое правило канала уведомлений проекта.
POST /api/v1/observability.deckhouse.io/spaces/:space_name/projects/:project_name/observabilitynotificationpolicies
Параметры адреса запроса в URL:
space_name
: имя рабочего пространства. Обязательноеproject_name
: имя проекта
Требуется аутентификация… У токена должны быть права “Управление через API” “Правила уведомлений”
Пример запроса
1$ curl -X POST -H "Content-Type: application/json" -H "X-Auth-Token: <API-token>" \
2 'https://api.dop.example.com/api/v1/observability.deckhouse.io/spaces/:space_name/projects/:project_name/observabilitynotificationchannels/:notification_channel_name/observabilitynotificationpolicies' -d \
3'
4{
5 "kind": "ObservabilityNotificationPolicy",
6 "metadata": {
7 "name": "test-rule"
8 },
9 "spec": {
10 "alert": {
11 "selector": {
12 "matchExpressions": {
13 "items": [
14 {
15 "key": "severity",
16 "operator": "Equal",
17 "value": "critical"
18 }
19 ]
20 }
21 }
22 },
23 "notification": {
24 "channel": {
25 "kind": "ObservabilityNotificationChannel",
26 "name": "some-giper-channel-1",
27 "parameters": {
28 "emails": [
29 "first@email.com",
30 "second@email.com"
31 ]
32 }
33 },
34 "repeatInterval": "45s"
35 }
36 }
37}
38'
Пример ответа
1{
2 "apiVersion": "observability.deckhouse.io/v1alpha1",
3 "kind": "ObservabilityNotificationPolicy",
4 "metadata": {
5 "name": "test-rule",
6 "creationTimestamp": "2025-03-28T07:12:41Z",
7 "generation": 1,
8 "resourceVersion": "1"
9 },
10 "spec": {
11 "alert": {
12 "selector": {
13 "matchExpressions": {
14 "items": [
15 {
16 "key": "severity",
17 "operator": "Equal",
18 "value": "critical"
19 }
20 ]
21 }
22 }
23 },
24 "notification": {
25 "channel": {
26 "kind": "ObservabilityNotificationChannel",
27 "name": "some-giper-channel-1",
28 "parameters": {
29 "emails": [
30 "first@email.com",
31 "second@email.com"
32 ]
33 }
34 },
35 "repeatInterval": "45s"
36 }
37 }
38}
Обновление правила уведомлений
Этот эндпоинт обновляет правило канала уведомлений проекта
PUT /api/v1/observability.deckhouse.io/spaces/:space_name/projects/:project_name/observabilitynotificationpolicies/:name
Параметры адреса запроса в URL:
space_name
: имя рабочего пространства. Обязательноеproject_name
: имя проектаname
: имя канала. Обязательное
Требуется аутентификация… У токена должны быть права “Управление через API” “Правила уведомлений”
Пример запроса
1$ curl -X PUT -H "Content-Type: application/json" -H "X-Auth-Token: <API-token>" \
2 'https://api.dop.example.com/api/v1/observability.deckhouse.io/spaces/:space_name/projects/:project_name/observabilitynotificationpolicies/:name' -d \
3'
4{
5 "kind": "ObservabilityNotificationChannel",
6 "metadata": {
7 "name": "test-rule"
8 },
9 "spec": {
10 "alert": {
11 "selector": {
12 "matchExpressions": {
13 "items": [
14 {
15 "key": "severity",
16 "operator": "Equal",
17 "value": "warning"
18 }
19 ]
20 }
21 }
22 },
23 "notification": {
24 "channel": {
25 "kind": "ObservabilityNotificationChannel",
26 "name": "some-channel-1",
27 "parameters": {
28 "emails": [
29 "first@email.com",
30 "second@email.com"
31 ]
32 }
33 },
34 "repeatInterval": "46s"
35 }
36 }
37}
38'
Пример ответа
1{
2 "apiVersion": "observability.deckhouse.io/v1alpha1",
3 "kind": "ObservabilityNotificationPolicy",
4 "metadata": {
5 "name": "test-rule",
6 "creationTimestamp": "2025-03-28T07:16:02Z",
7 "generation": 1,
8 "resourceVersion": "1"
9 },
10 "spec": {
11 "alert": {
12 "selector": {
13 "matchExpressions": {
14 "items": [
15 {
16 "key": "severity",
17 "operator": "Equal",
18 "value": "warning"
19 }
20 ]
21 }
22 }
23 },
24 "notification": {
25 "channel": {
26 "kind": "ObservabilityNotificationChannel",
27 "name": "some-giper-channel-1",
28 "parameters": {
29 "emails": [
30 "first@email.com",
31 "second@email.com"
32 ]
33 }
34 },
35 "repeatInterval": "46s"
36 }
37 }
38}
Удаление правила уведомлений
Этот эндпоинт удаляет существующее правило канала уведомлений проекта.
DELETE /api/v1/observability.deckhouse.io/spaces/:space_name/projects/:project_name/observabilitynotificationpolicies/:name
Параметры адреса запроса в URL:
space_name
: имя рабочего пространства. Обязательноеproject_name
: имя проектаname
: имя канала. Обязательное
Требуется аутентификация… У токена должны быть права “Управление через API” “Правила уведомлений”
Пример запроса
1$ curl -X DELETE -H "Content-Type: application/json" -H "X-Auth-Token: <API-token>" \
2 'https://api.dop.example.com/api/v1/observability.deckhouse.io/spaces/:space_name/projects/:project_name/observabilitynotificationpolicies/:name'
Ошибки при создании или обновлении правила канала уведомлений
В случае, если запрос на создание или обновление канала содержит некорректные данные, ответ будет со статусом 4xx с указанием ошибки:
1{"error":"Validation failed: Name has already been taken"}
Пользователи
Параметры пользователя
metadata.external_id
: внешний идентификатор пользователя (oidc ID, например)metadata.generation
: версия пользователяmetadata.resourceVersion
: глобальная версия пользователяmetadata.creationTimestamp
: дата / время создания пользователяspec.email
: email пользователяspec.firstName
: имя пользователяspec.lastName
: фамилия пользователяspec.displayName
: полное имя
Получение списка пользователей
Этот эндпоинт возвращает список рабочих пространств.
GET /api/v1/observability.deckhouse.io/users
Требуется аутентификация… У токена должны быть права “Управление пользователями”, токен должен быть привязан к всей системе (глобальному скоупу)
Пример запроса
1$ curl -H "X-Auth-Token: <API-token>" \
2 'https://api.dop.example.com/api/v1/observability.deckhouse.io/users'
Пример ответа
1{
2 "apiVersion": "observability.deckhouse.io/v1alpha1",
3 "kind": "ObservabilityUsersList",
4 "metadata":
5 {},
6 "items":
7 [
8 {
9 "apiVersion": "observability.deckhouse.io/v1alpha1",
10 "kind": "ObservabilityUser",
11 "metadata":
12 {
13 "creationTimestamp": "2025-05-13T07:14:10Z",
14 "generation": 1,
15 "externalId": "1",
16 "resourceVersion": "1"
17 },
18 "spec":
19 {
20 "email": "mail1+memaybe@example.com",
21 "firstName": "Jason",
22 "lastName": "Bourne-1th",
23 "displayName": null
24 }
25 }
26 ]
27}
Получение пользователя
Этот эндпоинт возвращает пользователя по внешнему идентификатору.
GET https://api.dop.example.com/api/v1/observability.deckhouse.io/users/:external_id
Параметры адреса запроса в URL:
external_id
: Внешний идентификатор пользователя. Обязательное
Требуется аутентификация… У токена должны быть права “Управление пользователями”, токен должен быть привязан к всей системе (глобальному скоупу)
Пример запроса
1$ curl -H "X-Auth-Token: <API-token>" \
2 'https://api.dop.example.com/api/v1/observability.deckhouse.io/users/1'
Пример ответа
1{
2 "apiVersion": "observability.deckhouse.io/v1alpha1",
3 "kind": "ObservabilityUser",
4 "metadata":
5 {
6 "creationTimestamp": "2025-05-13T07:14:10Z",
7 "generation": 1,
8 "externalId": "1",
9 "resourceVersion": "1"
10 },
11 "spec":
12 {
13 "email": "mail1+memaybe@example.com",
14 "firstName": "Jason",
15 "lastName": "Bourne-1th",
16 "displayName": null
17 }
18}
Создание пользователя
Этот эндпоинт создает нового пользователя. Для отправки запросов на создание пользователя необходимо, чтобы было выключено получение ролей через OIDC.
POST https://api.dop.example.com/api/v1/observability.deckhouse.io/users
Требуется аутентификация… У токена должны быть права “Управление пользователями”, токен должен быть привязан к всей системе (глобальному скоупу)
Пример запроса
1$ curl -X POST -H "Content-Type: application/json" -H "X-Auth-Token: <API-token>" \
2 'https://api.dop.example.com/api/v1/observability.deckhouse.io/users' -d \
3'
4{
5 "kind": "ObservabilityUser",
6 "metadata":
7 {
8 "externalId": "1"
9 },
10 "spec":
11 {
12 "email": "some@email.com",
13 "firstName": "Ivan",
14 "lastName": "Ivanov",
15 "displayName": "Ivan Ivanov"
16 }
17}
18'
Пример ответа
1{
2 "apiVersion": "observability.deckhouse.io/v1alpha1",
3 "kind": "ObservabilityUser",
4 "metadata":
5 {
6 "creationTimestamp": "2025-05-16T12:43:48Z",
7 "generation": 1,
8 "externalId": "1",
9 "resourceVersion": "1"
10 },
11 "spec":
12 {
13 "email": "some@email.com",
14 "firstName": "Ivan",
15 "lastName": "Ivanov",
16 "displayName": "Ivan Ivanov"
17 }
18}
Редактирование пользователя
Этот эндпоинт обновляет существующего пользователя. Для отправки запросов на изменение пользователя необходимо, чтобы было выключено получение ролей через OIDC.
PUT /api/v1/observability.deckhouse.io/users/:external_id
external_id
: Внешний идентификатор пользователя. Обязательное
Требуется аутентификация… У токена должны быть права “Управление пользователями”, токен должен быть привязан к всей системе (глобальному скоупу)
Пример запроса
1$ curl -X PUT -H "Content-Type: application/json" -H "X-Auth-Token: <API-token>" \
2 'https://api.dop.example.com/api/v1/observability.deckhouse.io/users/1' -d \
3'
4{
5 "kind": "ObservabilityUser",
6 "metadata":
7 {
8 "externalId": "1"
9 },
10 "spec":
11 {
12 "email": "updated@email.com",
13 "firstName": "Ivan",
14 "lastName": "Ivanov",
15 "displayName": "Ivan Ivanov"
16 }
17}
18'
Пример ответа
1{
2 "apiVersion": "observability.deckhouse.io/v1alpha1",
3 "kind": "ObservabilityUser",
4 "metadata":
5 {
6 "creationTimestamp": "2025-05-16T12:49:06Z",
7 "generation": 1,
8 "externalId": "1",
9 "resourceVersion": "1"
10 },
11 "spec":
12 {
13 "email": "updated@email.com",
14 "firstName": "Ivan",
15 "lastName": "Ivanov",
16 "displayName": "Ivan Ivanov"
17 }
18}
Удаление пользователя
Этот эндпоинт удаляет существующего пользователя. Для отправки запросов на удаление пользователя необходимо, чтобы было выключено получение ролей через OIDC.
DELETE /api/v1/observability.deckhouse.io/users/:external_id
external_id
: Внешний идентификатор пользователя. Обязательное
Требуется аутентификация… У токена должны быть права “Управление пользователями”, токен должен быть привязан к всей системе (глобальному скоупу)
Пример запроса
1$ curl -X DELETE -H "Content-Type: application/json" -H "X-Auth-Token: <API-token>" \
2 'https://api.dop.example.com/api/v1/observability.deckhouse.io/users/1'
Ошибки при создании или обновлении пользователя
В случае, если запрос на создание или обновление пользователя содержит некорректные данные, ответ будет со статусом 4xx с указанием ошибки:
1{"error":"Validation failed: Email has already been taken"}
В случае, если включено получение ролей через OIDC, попытки изменить роли пользователя будут возвращать ошибку “OIDC user roles enabled”
Роли пользователя
Описание ролевой модели пользователей.
Параметры роли пользователя
metadata.generation
: версия пользователяmetadata.resourceVersion
: глобальная версия пользователяmetadata.creationTimestamp
: дата / время создания пользователяspec.scope
: тип объекта, к которому привязана роль пользователя (допустимые значения - GlobalScope, Space, Project)spec.role
: роль пользователя, допустимые значения - super_admin, admin, user, viewer, ro_super_adminspec.space
: рабочее пространство, к которому привязана роль пользователяspec.project
: проект, к которому привязана роль пользователя
Получение списка ролей пользователя
Этот эндпоинт возвращает список ролей пользователя.
GET /api/v1/observability.deckhouse.io/users/:external_id/memberships
Требуется аутентификация… У токена должны быть права “Управление пользователями”, токен должен быть привязан к всей системе (глобальному скоупу)
Пример запроса
1$ curl -H "X-Auth-Token: <API-token>" \
2 'https://api.dop.example.com/api/v1/observability.deckhouse.io/users/:external_id/memberships'
Пример ответа
1{
2 "apiVersion": "observability.deckhouse.io/v1alpha1",
3 "kind": "ObservabilityUserMembershipsList",
4 "metadata": {},
5 "items":
6 [
7 {
8 "apiVersion": "observability.deckhouse.io/v1alpha1",
9 "kind": "ObservabilityUserMembership",
10 "metadata":
11 {
12 "creationTimestamp": "2025-05-13T05:21:39Z",
13 "generation": 1,
14 "resourceVersion": 1
15 },
16 "spec":
17 {
18 "scope": "GlobalScope",
19 "role": "admin"
20 }
21 },
22 {
23 "apiVersion": "observability.deckhouse.io/v1alpha1",
24 "kind": "ObservabilityUserMembership",
25 "metadata":
26 {
27 "creationTimestamp": "2025-05-13T05:21:39Z",
28 "generation": 1,
29 "resourceVersion": 1
30 },
31 "spec":
32 {
33 "scope": "Space",
34 "role": "user",
35 "space": "spicy-space-1"
36 }
37 },
38 {
39 "apiVersion": "observability.deckhouse.io/v1alpha1",
40 "kind": "ObservabilityUserMembership",
41 "metadata":
42 {
43 "creationTimestamp": "2025-05-13T05:21:39Z",
44 "generation": 1,
45 "resourceVersion": 1
46 },
47 "spec":
48 {
49 "scope": "Project",
50 "role": "viewer",
51 "space": "spicy-space-1",
52 "project": "umbrella-project-1"
53 }
54 }
55 ]
56}
Обновление ролей пользователя
Этот эндпоинт обновляет роли пользователя. Для отправки запросов на обновление ролей необходимо, чтобы было выключено получение ролей через OIDC.
POST /api/v1/observability.deckhouse.io/users/:external_id/memberships
Параметры адреса запроса в URL:
external_id
: Внешний идентификатор пользователя. Обязательное
Требуется аутентификация… У токена должны быть права “Управление пользователями”, токен должен быть привязан к всей системе (глобальному скоупу)
Пример запроса
1$ curl -X POST -H "Content-Type: application/json" -H "X-Auth-Token: <API-token>" \
2 'https://api.dop.example.com/api/v1/users/1/memberships' -d \
3'
4{
5 "apiVersion": "observability.deckhouse.io/v1alpha1",
6 "kind": "ObservabilityUserMembershipsList",
7 "metadata": {},
8 "items":
9 [
10 {
11 "spec":
12 {
13 "scope": "GlobalScope",
14 "role": "admin"
15 }
16 },
17 {
18 "spec":
19 {
20 "scope": "Space",
21 "role": "user",
22 "space": "spicy-space-1"
23 }
24 },
25 {
26 "spec":
27 {
28 "scope": "Project",
29 "role": "viewer",
30 "space": "spicy-space-1",
31 "project": "umbrella-project-1"
32 }
33 }
34 ]
35}
36'
Пример ответа
1{
2 "apiVersion": "observability.deckhouse.io/v1alpha1",
3 "kind": "ObservabilityUserMembershipsList",
4 "metadata": {},
5 "items":
6 [
7 {
8 "spec":
9 {
10 "scope": "GlobalScope",
11 "role": "admin"
12 }
13 },
14 {
15 "spec":
16 {
17 "scope": "Space",
18 "role": "user",
19 "space": "spicy-space-1"
20 }
21 },
22 {
23 "spec":
24 {
25 "scope": "Project",
26 "role": "viewer",
27 "space": "spicy-space-1",
28 "project": "umbrella-project-1"
29 }
30 }
31 ]
32}
Ошибки при создании или обновлении ролей пользователей
В случае, если запрос на обновление ролей пользователя содержит некорректные данные, ответ будет со статусом 4xx с указанием ошибки:
1{"error":"Validation failed: Memberships is invalid"}
В случае, если включено получение ролей через OIDC, попытки изменить роли пользователя будут возвращать ошибку “OIDC user roles enabled”