Аутентификация

Эндпоинты, требующие аутентификации, должны вызываться с указанием заголовка 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 / false
  • spec.email.template: шаблон сообщения. Возвращается в ответах, не изменяется с помощью API

Параметры Telegram канала уведомлений

  • spec.telegram.apiUrl: URL API телеграмма, по умолчанию используется стандартный https://api.telegram.org
  • spec.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, NotRegex
  • value: строковое значение лейбла для сравнения оператором

Параметры 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_admin
  • spec.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”