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

Эндпоинты, требующие аутентификации, должны вызываться с указанием заголовка 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.

Формат секции данных в результате запроса:

{
  "resultType": "matrix" | "vector" | "scalar" | "string",
  "result": <value>
}

<value> относится к данным результатов запроса, формат которых зависит от resultType. Смотри форматы результатов запросов выражений.

Пример:

Пример запроса для выполнения выражения up на время 2015-07-01T20:10:51.781Z:

$ curl -H "X-Auth-Token: <API-token>" \
  'https://api.dop.example.com/prometheus/api/v1/query?query=up&time=2015-07-01T20:10:51.781Z'

Ответ:

{
   "status" : "success",
   "data" : {
      "resultType" : "vector",
      "result" : [
         {
            "metric" : {
               "__name__" : "up",
               "job" : "prometheus",
               "instance" : "localhost:9090"
            },
            "value": [ 1435781451.781, "1" ]
         },
         {
            "metric" : {
               "__name__" : "up",
               "job" : "node",
               "instance" : "localhost:9100"
            },
            "value" : [ 1435781451.781, "0" ]
         }
      ]
   }
}
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 секунд:

$ curl -H "X-Auth-Token: <API-token>" \
  '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'

Ответ:

{
   "status" : "success",
   "data" : {
      "resultType" : "matrix",
      "result" : [
         {
            "metric" : {
               "__name__" : "up",
               "job" : "prometheus",
               "instance" : "localhost:9090"
            },
            "values" : [
               [ 1435781430.781, "1" ],
               [ 1435781445.781, "1" ],
               [ 1435781460.781, "1" ]
            ]
         },
         {
            "metric" : {
               "__name__" : "up",
               "job" : "node",
               "instance" : "localhost:9091"
            },
            "values" : [
               [ 1435781430.781, "0" ],
               [ 1435781445.781, "0" ],
               [ 1435781460.781, "1" ]
            ]
         }
      ]
   }
}

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, что означает отсутствие ограничения.

Пример:

$ curl -H "X-Auth-Token: <API-token>" \
    -g 'https://api.dop.example.com/prometheus/api/v1/series?' \
    --data-urlencode 'match[]=up' \
    --data-urlencode 'match[]=process_start_time_seconds{job="prometheus"}'

Ответ:

{
   "status" : "success",
   "data" : [
      { "__name__" : "up", "job" : "prometheus", "instance" : "localhost:9090" },
      { "__name__" : "up", "job" : "node", "instance" : "localhost:9091" },
      { "__name__" : "process_start_time_seconds", "job" : "prometheus", "instance" : "localhost:9090" }
   ]
}

Получение имен меток

Этот эндпоинт возвращает список имен меток:

GET /prometheus/api/v1/labels POST /prometheus/api/v1/labels

Требуется аутентификация…

Пример:

$ curl -H "X-Auth-Token: <API-token>" \
    'https://api.dop.example.com/prometheus/api/v1/labels'

Ответ:

{
    "status": "success",
    "data": [
        "__name__",
        "call",
        "code",
        "config",
        "dialer_name",
        "endpoint",
        "event",
        "goversion",
        "handler",
        "instance",
        "interval",
        "job",
        "le",
        "listener_name",
        "name",
        "quantile",
        "reason",
        "role",
        "scrape_job",
        "slice",
        "version"
    ]
}

Получение значений меток

Этот эндпоинт возвращает список значений для указанного имени метки:

GET /prometheus/api/v1/label/<label_name>/values

Требуется аутентификация…

Пример:

Пример запроса для значений метки job:

$ curl -H "X-Auth-Token: <API-token>" \
    https://api.dop.example.com/prometheus/api/v1/label/job/values

Ответ:

{
   "status" : "success",
   "data" : [
      "node",
      "prometheus"
   ]
}

Форматы результатов запросов выражений

Запросы выражений могут возвращать следующие значения в свойстве result секции данных. Шаблоны <sample_value> используются для представления числовых значений. Поскольку формат JSON не поддерживает специальные значения с плавающей точкой, такие как NaN, Inf и -Inf, образцы данных передаются как строковые значения в кавычках вместо чисел.

Ключи "histogram" и "histograms" появляются только в том случае, если в ответе присутствуют экспериментальные нативные гистограммы. Шаблон <histogram> поясняется ниже в отдельном разделе.

Range vectors

Range vectors возвращаются как результат типа matrix. Соответствующее свойство result имеет следующий формат:

[
  {
    "metric": { "<label_name>": "<label_value>", ... },
    "values": [ [ <unix_time>, "<sample_value>" ], ... ],
    "histograms": [ [ <unix_time>, <histogram> ], ... ]
  },
  ...
]

Каждая серия может включать ключ values, ключ histograms, или оба. Для каждого временного штампа будет только одна выборка — либо типа float, либо типа histogram.

Серии возвращаются отсортированными по метрикам. Функции, такие как sort и sort_by_label, не влияют на векторы диапазонов.

Instant vectors

Мгновенные векторы возвращаются как результат типа vector. Соответствующее свойство result имеет следующий формат:

[
  {
    "metric": { "<label_name>": "<label_value>", ... },
    "value": [ <unix_time>, "<sample_value>" ],
    "histogram": [ <unix_time>, <histogram> ]
  },
  ...
]

Каждая серия может содержать ключ value или ключ histogram, но не оба.

Серии не гарантируются в каком-либо определённом порядке, если не была использована функция, такая как sort или sort_by_label.

Scalars

Скалярные результаты возвращаются как результат типа scalar. Соответствующее свойство result имеет следующий формат:

[ <unix_time>, "<scalar_value>" ]

Строки

Строковые результаты возвращаются как результат типа string. Соответствующее свойство result имеет следующий формат:

[ <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:

{
  "streams": [
    {
      "stream": {
        "label": "value"
      },
      "values": [
          [ "<Unix Timestamp в наносекундах>", "<лог строка>" ],
          [ "<Unix Timestamp в наносекундах>", "<лог строка>" ]
      ]
    }
  ]
}

Можно установить заголовок запроса Content-Encoding: gzip для отправки сжатого JSON.

Также можно присоединить структурированные метаданные к каждой строке логов, добавив JSON-объект в конец массива логов. Этот объект не должен содержать вложенные объекты, и должен содержать только строковые ключи и значения. Он должен быть указан сразу после строки лога:

Пример:

"values": [
    [ "<Unix Timestamp в наносекундах>", "<лог строка>", {"trace_id": "0242ac120002", "user_id": "superUser123"}]
]

Примеры:

Пример команды cURL для отправки потока с меткой foo=bar2 и одной строкой лога "fizzbuzz" с использованием кодировки JSON:

curl -H "Content-Type: application/json" \
  -H "X-Auth-Token: <API-token>" \
  -s -X POST "https://api.dop.example.com/loki/api/v1/push" \
  --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.

Формат ответа:

{
  "status": "success",
  "data": {
    "resultType": "vector" | "streams",
    "result": [<vector value>] | [<stream value>],
    "stats": [<statistics>]
  }
}

Где vector value имеет формат:

{
  "metric": {
    <label key-value pairs>
  },
  "value": [
    <number: second Unix Timestamp>,
    <string: value>
  ]
}

и stream value имеет формат:

{
  "stream": {
    <label key-value pairs>
  },
  "values": [
    [
      <string: nanosecond Unix Timestamp>,
      <string: log line>
    ],
    ...
  ]
}

Элементы в массиве values сортируются по времени. Первый элемент — самый свежий при использовании direction=backward. Самый старый элемент — первый при использовании direction=forward.

Пример:

curl -G -s -H 'X-Auth-Token: <API-token>'  "https://api.dop.example.com/loki/api/v1/query" \
  --data-urlencode 'query=sum(rate({job="varlogs"}[10m])) by (level)' | jq

Ответ:

{
  "status": "success",
  "data": {
    "resultType": "vector",
    "result": [
      {
        "metric": {},
        "value": [
          1588889221,
          "1267.1266666666666"
        ]
      },
      {
        "metric": {
          "level": "warn"
        },
        "value": [
          1588889221,
          "37.77166666666667"
        ]
      },
      {
        "metric": {
          "level": "info"
        },
        "value": [
          1588889221,
          "37.69"
        ]
      }
    ],
    "stats": {
      ...
    }
  }
}

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.

Формат ответа:

{
  "status": "success",
  "data": {
    "resultType": "matrix" | "streams",
    "result": [<matrix value>] | [<stream value>],
    "stats" : [<statistics>]
  }
}

Где <matrix value> имеет формат:

{
  "metric": {
    <label key-value pairs>
  },
  "values": [
    [
      <number: second Unix Timestamp>,
      <string: value>
    ],
    ...
  ]
}

и <stream value> имеет формат:

{
  "stream": {
    <label key-value pairs>
  },
  "values": [
    [
      <string: nanosecond Unix Timestamp>,
      <string: log line>
    ],
    ...
  ]
}

Элементы в массиве values отсортированы по временной метке: если используется параметр direction=backward, первой идет самая свежая запись, а если forward — самой старой записью.

Примеры:

curl -G -s -H 'X-Auth-Token: <API-token>' "https://api.dop.example.com/loki/api/v1/query_range" \
  --data-urlencode 'query=sum(rate({job="varlogs"}[10m])) by (level)' \
  --data-urlencode 'step=300' | jq

Ответ:

{
  "status": "success",
  "data": {
    "resultType": "matrix",
    "result": [
      {
       "metric": {
          "level": "info"
        },
        "values": [
          [
            1588889221,
            "137.95"
          ],
          [
            1588889221,
            "467.115"
          ],
          [
            1588889221,
            "658.8516666666667"
          ]
        ]
      },
      {
        "metric": {
          "level": "warn"
        },
        "values": [
          [
            1588889221,
            "137.27833333333334"
          ],
          [
            1588889221,
            "467.69"
          ],
          [
            1588889221,
            "660.6933333333334"
          ]
        ]
      }
    ],
    "stats": {
      ...
    }
  }
}

Query labels

GET /loki/api/v1/labels

Требуется аутентификация…

Этот эндпоинт возвращает список известных меток в пределах временного диапазона.

Параметры запроса в URL:

  • start: Начальное время запроса как Unix Timestamp в наносекундах. По умолчанию — 6 часов назад.
  • end: Конечное время, так же в формате Unix Timestamp в наносекундах. По умолчанию — текущее время.
  • since: Длительность для вычисления начала относительно конца.
  • query: Селектор потока логов, выбирающий потоки для отображения меток. Пример: {app="myapp", environment="dev"}

Формат ответа:

{
  "status": "success",
  "data": [
    <label string>,
    ...
  ]
}

Пример:

curl -G -s -H"X-Auth-Token: <API-token>"  "https://api.dop.example.com/loki/api/v1/labels" | jq

Ответ:

{
  "status": "success",
  "data": [
    "foo",
    "bar",
    "baz"
  ]
}

Query label values

GET /loki/api/v1/label/<name>/values

Требуется аутентификация…

Этот эндпоинт возвращает список возможных значений метки <name> в пределах временного диапазона.

Параметры запроса в URL:

  • start: Начальное время.
  • end: Конечное время.
  • since: Длительность для вычисления начала относительно конца.
  • query: Селектор логов для выбора потоков и возвращения значений метки.

Пример:

curl -G -s -H"X-Auth-Token: <API-token>"  "https://api.dop.example.com/loki/api/v1/label/foo/values" | jq

Ответ:

{
  "status": "success",
  "data": [
    "cat",
    "dog",
    "axolotl"
  ]
}

Триггеры

Параметры триггеров

  • 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” “Триггеры и производные метрики”

Пример запроса

$ curl -H "X-Auth-Token: <API-token>" \
  'https://api.dop.example.com/api/v1/observability.deckhouse.io/spaces/:space_name/projects/:project_name/alertingrules'

Пример ответа

{
    "apiVersion": "observability.deckhouse.io/v1alpha1",
    "kind": "List",
    "metadata":
    {},
    "items":
    [
        {
            "apiVersion": "observability.deckhouse.io/v1alpha1",
            "kind": "ObservabilityMetricsAlertingRule",
            "metadata":
            {
                "creationTimestamp": "2024-12-11T10:38:23Z",
                "generation": 1,
                "annotations":
                {
                    "metadata.deckhouse.io/category": "Main"
                },
                "name": "rule-name",
                "resourceVersion": 1
            },
            "spec":
            {
                "alertMetadata":
                {
                    "annotations":
                    {
                        "summary": "{{ $labels.instance }} pgbouncer '{{ $labels.conf }}' configuration incomplete"
                    },
                    "additionalLabels":
                    {
                        "additional_label": "value"
                    }
                },
                "delays":
                {
                    "firing": "1m",
                    "resolving": "0s"
                },
                "expression": "job:request_latency_seconds:mean5m{job=\"myjob\"}",
                "thresholds":
                [
                    {
                        "valueExpression": "0.5",
                        "operator": "GreaterThan",
                        "severity": "Warning"
                    }
                ]
            }
        }
    ]
}

Получение триггера

Этот эндпоинт возвращает триггер по имени.

GET /api/v1/observability.deckhouse.io/spaces/:space_name/projects/:project_name/alertingrules/:name

Параметры адреса запроса в URL:

  • space_name: имя рабочего пространства. Обязательное
  • project_name: имя проекта. Обязательное
  • name: имя тригера. Обязательное

Требуется аутентификация… У токена должны быть права “Управление через API” “Триггеры и производные метрики”

Пример запроса

$ curl -H "X-Auth-Token: <API-token>" \
  'https://api.dop.example.com/api/v1/observability.deckhouse.io/spaces/:space_name/projects/:project_name/alertingrules/:name'

Пример ответа

{
    "apiVersion": "observability.deckhouse.io/v1alpha1",
    "kind": "ObservabilityMetricsAlertingRule",
    "metadata":
    {
        "creationTimestamp": "2024-12-11T10:42:56Z",
        "generation": 1,
        "annotations":
        {
            "metadata.deckhouse.io/category": "Main"
        },
        "name": "test1",
        "resourceVersion": 1
    },
    "spec":
    {
        "alertMetadata":
        {
            "annotations":
            {
                "summary": "{{ $labels.instance }} pgbouncer '{{ $labels.conf }}' configuration incomplete"
            },
            "additionalLabels":
            {
                "testlabel": "value"
            }
        },
        "delays":
        {
            "firing": "1m",
            "resolving": "0s"
        },
        "expression": "job:request_latency_seconds:mean5m{job=\"myjob\"}",
        "thresholds":
        [
            {
                "valueExpression": "0.5",
                "operator": "GreaterThan",
                "severity": "Warning"
            }
        ]
    }
}

Создание триггера

Этот эндпоинт создает новый триггер.

POST /api/v1/observability.deckhouse.io/spaces/:space_name/projects/:project_name/alertingrules/

Параметры адреса запроса в URL:

  • space_name: имя рабочего пространства. Обязательное
  • project_name: имя проекта. Обязательное

Требуется аутентификация… У токена должны быть права “Управление через API” “Триггеры и производные метрики”

Пример запроса

$ curl -X POST -H "Content-Type: application/json" -H "X-Auth-Token: <API-token>" \
  'https://api.dop.example.com/api/v1/observability.deckhouse.io/spaces/:space_name/projects/:project_name/alertingrules/' -d \
'
{
    "kind": "ObservabilityMetricsAlertingRule",
    "metadata":
    {
        "annotations":
        {
            "metadata.deckhouse.io/category": "critical"
        },
        "name": "some-name"
    },
    "spec":
    {
        "alertMetadata":
        {
            "annotations":
            {
                "summary": "some description summary"
            },
            "additionalLabels":
            {
                "testlabel": "value"
            }
        },
        "delays":
        {
            "firing": "1s",
            "resolving": "1s"
        },
        "expression": "vector(10)",
        "thresholds":
        [
            {
                "valueExpression": "0.5",
                "operator": "GreaterThan",
                "severity": "critical"
            }
        ]
    }
}
'

Пример ответа

{
    "apiVersion": "observability.deckhouse.io/v1alpha1",
    "kind": "ObservabilityMetricsAlertingRule",
    "metadata":
    {
        "creationTimestamp": "2024-12-11T10:48:11Z",
        "generation": 1,
        "annotations":
        {
            "metadata.deckhouse.io/category": "critical"
        },
        "name": "some-name",
        "resourceVersion": 1
    },
    "spec":
    {
        "alertMetadata":
        {
            "annotations":
            {
                "summary": "some description summary"
            },
            "additionalLabels":
            {
                "testlabel": "value"
            }
        },
        "delays":
        {
            "firing": "1s",
            "resolving": "1s"
        },
        "expression": "vector(10)",
        "thresholds":
        [
            {
                "valueExpression": "0.5",
                "operator": "GreaterThan",
                "severity": "Critical"
            }
        ]
    }
}

Обновление триггера

Этот эндпоинт обновляет существующий триггер.

PUT api/v1/observability.deckhouse.io/spaces/:space_name/projects/:project_name/alertingrules/:name

Параметры адреса запроса в URL:

  • space_name: имя рабочего пространства. Обязательное
  • project_name: имя проекта. Обязательное
  • name: имя триггера

Требуется аутентификация… У токена должны быть права “Управление через API” “Триггеры и производные метрики”

Пример запроса

$ curl -X PUT -H "Content-Type: application/json" -H "X-Auth-Token: <API-token>" \
  'https://api.dop.example.com/api/v1/observability.deckhouse.io/spaces/:space_name/projects/:project_name/alertingrules/:name' -d \
'
{
    "kind": "ObservabilityMetricsAlertingRule",
    "metadata":
    {
        "annotations":
        {
            "metadata.deckhouse.io/category": "critical"
        }
    },
    "spec":
    {
        "alertMetadata":
        {
            "annotations":
            {
                "summary": "{{ $labels.instance }} pgbouncer '{{ $labels.conf }}' configuration incomplete"
            },
            "additionalLabels":
            {
                "somelabel": "value"
            }
        },
        "delays":
        {
            "firing": "2s",
            "resolving": "3s"
        },
        "expression": "vector(10)",
        "thresholds":
        [
            {
                "valueExpression": "0.5",
                "operator": "GreaterThan",
                "severity": "critical"
            }
        ]
    }
}
'

Пример ответа

{
    "apiVersion": "observability.deckhouse.io/v1alpha1",
    "kind": "ObservabilityMetricsAlertingRule",
    "metadata":
    {
        "creationTimestamp": "2024-12-13T06:16:03Z",
        "generation": 1,
        "annotations":
        {
            "metadata.deckhouse.io/category": "critical"
        },
        "name": "test1",
        "resourceVersion": 1
    },
    "spec":
    {
        "alertMetadata":
        {
            "annotations":
            {
                "summary": "{{ $labels.instance }} pgbouncer '{{ $labels.conf }}' configuration incomplete"
            },
            "additionalLabels":
            {
                "somelabel": "value"
            }
        },
        "delays":
        {
            "firing": "2s",
            "resolving": "3s"
        },
        "expression": "vector(10)",
        "thresholds":
        [
            {
                "valueExpression": "0.5",
                "operator": "GreaterThan",
                "severity": "Critical"
            }
        ]
    }
}

Удаление триггера

Этот эндпоинт удаляет существующий триггер.

DELETE /api/v1/observability.deckhouse.io/spaces/:space_name/projects/:project_name/alertingrules/:name

Параметры адреса запроса в URL:

  • space_name: имя рабочего пространства. Обязательное
  • project_name: имя проекта. Обязательное
  • name: имя триггера

Требуется аутентификация… У токена должны быть права “Управление через API” “Триггеры и производные метрики”

Пример запроса

$ curl -X DELETE -H "Content-Type: application/json" -H "X-Auth-Token: <API-token>" \
  'https://api.dop.example.com/api/v1/observability.deckhouse.io/spaces/:space_name/projects/:project_name/alertingrules/:name'

Ошибки при создании или обновлении триггеров

В случае, если запрос на создание или обновление триггера содержит некорректные данные, ответ будет со статусом 4xx с указанием ошибки:

{"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” “Триггеры и производные метрики”

Пример запроса

$ curl -H "X-Auth-Token: <API-token>" \
  'https://api.dop.example.com/api/v1/observability.deckhouse.io/spaces/:space_name/projects/:project_name/recordingrules'

Пример ответа

{
    "apiVersion": "v1",
    "kind": "List",
    "metadata": {},
    "items":
    [
        {
            "apiVersion": "observability.deckhouse.io/v1alpha1",
            "kind": "ObservabilityMetricsRecordingRule",
            "spec":
            {
                "expression": "vector(10)",
                "targetMetric":
                {
                    "name": "test:vector",
                    "additionalLabels":
                    {
                        "test": "test",
                        "author": "test"
                    }
                }
            },
            "metadata":
            {
                "creationTimestamp": "2024-12-13T06:24:30Z",
                "generation": 1,
                "annotations":
                {
                    "metadata.deckhouse.io/category": "Main"
                },
                "name": "test-vector-1",
                "resourceVersion": 1
            }
        }
    ]
}

Получение производной метрики

Этот эндпоинт возвращает производную метрику по имени.

GET /api/v1/observability.deckhouse.io/spaces/:space_name/projects/:project_name/recordingrules/:name

Параметры адреса запроса в URL:

  • space_name: имя рабочего пространства. Обязательное
  • project_name: имя проекта. Обязательное
  • name: имя производной метрики. Обязательное

Требуется аутентификация… У токена должны быть права “Управление через API” “Триггеры и производные метрики”

Пример запроса

$ curl -H "X-Auth-Token: <API-token>" \
  'https://api.dop.example.com/api/v1/observability.deckhouse.io/spaces/:space_name/projects/:project_name/recordingrules/:name'

Пример ответа

{
    "apiVersion": "observability.deckhouse.io/v1alpha1",
    "kind": "ObservabilityMetricsRecordingRule",
    "spec":
    {
        "expression": "vector(10)",
        "targetMetric":
        {
            "name": "test:vector",
            "additionalLabels":
            {
                "test": "test",
                "author": "test"
            }
        }
    },
    "metadata":
    {
        "creationTimestamp": "2024-12-13T06:37:39Z",
        "generation": 1,
        "annotations":
        {
            "metadata.deckhouse.io/category": "Main"
        },
        "name": "test-vector-1",
        "resourceVersion": 1
    }
}

Создание производной метрики

Этот эндпоинт создает новую производную метрику.

POST /api/v1/observability.deckhouse.io/spaces/:space_name/projects/:project_name/recordingrules

Параметры адреса запроса в URL:

  • space_name: имя рабочего пространства. Обязательное
  • project_name: имя проекта. Обязательное

Требуется аутентификация… У токена должны быть права “Управление через API” “Триггеры и производные метрики”

Пример запроса

$ curl -X POST -H "Content-Type: application/json" -H "X-Auth-Token: <API-token>" \
  'https://api.dop.example.com/api/v1/observability.deckhouse.io/spaces/:space_name/projects/:project_name/recordingrules' -d \
'
{
    "kind": "ObservabilityMetricsRecordingRule",
    "metadata":
    {
        "annotations":
        {
            "metadata.deckhouse.io/category": "recording"
        },
        "name": "some-name"
    },
    "spec":
    {
        "targetMetric":
        {
            "name": "metric:rule:name",
            "additionalLabels":
            {
                "testlabel": "value"
            }
        },
        "expression": "vector(10)"
    }
}
'

Пример ответа

{
    "apiVersion": "observability.deckhouse.io/v1alpha1",
    "kind": "ObservabilityMetricsRecordingRule",
    "spec":
    {
        "expression": "vector(10)",
        "targetMetric":
        {
            "name": "metric:rule:name",
            "additionalLabels":
            {
                "testlabel": "value"
            }
        }
    },
    "metadata":
    {
        "creationTimestamp": "2024-12-13T06:40:08Z",
        "generation": 1,
        "annotations":
        {
            "metadata.deckhouse.io/category": "recording"
        },
        "name": "some-name",
        "resourceVersion": 1
    }
}

Обновление производной метрики

Этот эндпоинт обновляет существующую производную метрику.

PUT /api/v1/observability.deckhouse.io/spaces/:space_name/projects/:project_name/recordingrules/:name

Параметры адреса запроса в URL:

  • space_name: имя рабочего пространства. Обязательное
  • project_name: имя проекта. Обязательное
  • name: имя производной метрики

Требуется аутентификация… У токена должны быть права “Управление через API” “Триггеры и производные метрики”

Пример запроса

$ curl -X PUT -H "Content-Type: application/json" -H "X-Auth-Token: <API-token>" \
  'https://api.dop.example.com/api/v1/observability.deckhouse.io/spaces/:space_name/projects/:project_name/recordingrules/:name' -d \
'
{
    "kind": "ObservabilityMetricsRecordingRule",
    "metadata":
    {
        "annotations":
        {
            "metadata.deckhouse.io/category": "recording updated"
        },
        "name": "test-vector-1"
    },
    "spec":
    {
        "targetMetric":
        {
            "name": "metric:rule:name:updated",
            "additionalLabels":
            {
                "testlabel": "value"
            }
        },
        "expression": "vector(11)"
    }
}
'

Пример ответа

{
    "apiVersion": "observability.deckhouse.io/v1alpha1",
    "kind": "ObservabilityMetricsRecordingRule",
    "spec":
    {
        "expression": "vector(11)",
        "targetMetric":
        {
            "name": "metric:rule:name:updated",
            "additionalLabels":
            {
                "testlabel": "value"
            }
        }
    },
    "metadata":
    {
        "creationTimestamp": "2024-12-13T06:42:35Z",
        "generation": 1,
        "annotations":
        {
            "metadata.deckhouse.io/category": "recording updated"
        },
        "name": "test-vector-1",
        "resourceVersion": 1
    }
}

Удаление производной метрики

Этот эндпоинт удаляет существующую метрику.

DELETE /api/v1/observability.deckhouse.io/spaces/:space_name/projects/:project_name/recordingrules/:name

Параметры адреса запроса в URL:

  • space_name: имя рабочего пространства. Обязательное
  • project_name: имя проекта. Обязательное
  • name: имя метрики

Требуется аутентификация… У токена должны быть права “Управление через API” “Триггеры и производные метрики”

Пример запроса

$ curl -X DELETE -H "Content-Type: application/json" -H "X-Auth-Token: <API-token>" \
  'https://api.dop.example.com/api/v1/observability.deckhouse.io/spaces/:space_name/projects/:project_name/recordingrules/:name'

Ошибки при создании или обновлении метрик

В случае, если запрос на создание или обновление метрики содержит некорректные данные, ответ будет со статусом 4xx с указанием ошибки:

{"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” “Дашборды”

Пример запроса

$ curl -H "X-Auth-Token: <API-token>" \
  'https://api.dop.example.com/api/v1/observability.deckhouse.io/spaces/:space_name/projects/:project_name/observabilitydashboards'

Пример ответа

{
    "apiVersion": "observability.deckhouse.io/v1alpha1",
    "kind": "ObservabilityDashboardList",
    "items":
    [
        {
            "apiVersion": "observability.deckhouse.io/v1alpha1",
            "kind": "ObservabilityDashboard",
            "metadata":
            {
                "annotations":
                {
                    "metadata.deckhouse.io/category": "Category-3",
                    "metadata.deckhouse.io/title": "dashboard-3"
                },
                "creationTimestamp": "2025-01-24T10:32:23Z",
                "generation": 1,
                "name": "dash-dash-board-3",
                "namespace": "spicy-space-1",
                "resourceVersion": 1
            },
            "spec":
            {
                "definition": "{\"id\":255,\"uid\":\"GrxobkC5leWtZmaE\",\"tags\":[\"test\",\"test1\"],\"title\":\"Dash-dash-board-3\"}"
            }
        }
    ]
}

Получение дашборда

Этот эндпоинт возвращает дашборд по имени.

GET /api/v1/observability.deckhouse.io/spaces/:space_name/projects/:project_name/observabilitydashboards/:name

Параметры адреса запроса в URL:

  • space_name: имя рабочего пространства. Обязательное
  • project_name: имя проекта. Обязательное
  • name: имя дашборда. Обязательное

Требуется аутентификация… У токена должны быть права “Управление через API” “Дашборды”

Пример запроса

$ curl -H "X-Auth-Token: <API-token>" \
  'https://api.dop.example.com/api/v1/observability.deckhouse.io/spaces/:space_name/projects/:project_name/observabilitydashboards/:name'

Пример ответа

{
    "apiVersion": "observability.deckhouse.io/v1alpha1",
    "kind": "ObservabilityDashboard",
    "metadata":
    {
        "annotations":
        {
            "metadata.deckhouse.io/category": "Category-1",
            "metadata.deckhouse.io/title": "Dash-dash-board 1"
        },
        "creationTimestamp": "2025-01-24T10:38:57Z",
        "generation": 1,
        "name": "dash-dash-board-1",
        "namespace": "spicy-space-1",
        "resourceVersion": 1
    },
    "spec":
    {
        "definition": "{\"uid\":\"KttpW5ERbCrk6H8R\",\"tags\":[\"test\",\"test1\"],\"title\":\"Dash-dash-board-1\"}"
    }
}

Создание дашборда

Этот эндпоинт создает новую производную метрику.

POST /api/v1/observability.deckhouse.io/spaces/:space_name/projects/:project_name/observabilitydashboards

Параметры адреса запроса в URL:

  • space_name: имя рабочего пространства. Обязательное
  • project_name: имя проекта. Обязательное

Требуется аутентификация… У токена должны быть права “Управление через API” “Дашборды”

Пример запроса

$ curl -X POST -H "Content-Type: application/json" -H "X-Auth-Token: <API-token>" \
  'https://api.dop.example.com/api/v1/observability.deckhouse.io/spaces/:space_name/projects/:project_name/observabilitydashboards' -d \
'
{
    "kind": "ObservabilityDashboard",
    "metadata":
    {
        "annotations":
        {
            "metadata.deckhouse.io/category": "category-name",
            "metadata.deckhouse.io/title": "some name"
        },
        "name": "some-name"
    },
    "spec":
    {
        "definition": {...}
    }
}
'

Пример ответа

{
    "apiVersion": "observability.deckhouse.io/v1alpha1",
    "kind": "ObservabilityDashboard",
    "metadata":
    {
        "annotations":
        {
            "metadata.deckhouse.io/category": "category-name",
            "metadata.deckhouse.io/title": "some name"
        },
        "creationTimestamp": "2025-01-24T10:41:12Z",
        "generation": 1,
        "name": "some-name",
        "namespace": "spicy-space-1",
        "resourceVersion": 1
    },
    "spec":
    {
        "definition": "{\"uid\":\"czvSGOukIQTWEE19\",\"tags\":[\"test\"],\"title\":\"some name\"}"
    }
}

Обновление дашборда

Этот эндпоинт обновляет существующий дашборд.

PUT /api/v1/observability.deckhouse.io/spaces/:space_name/projects/:project_name/observabilitydashboards/:name

Параметры адреса запроса в URL:

  • space_name: имя рабочего пространства. Обязательное
  • project_name: имя проекта. Обязательное
  • name: имя дашборда

Требуется аутентификация… У токена должны быть права “Управление через API” “Дашборды”

Пример запроса

$ curl -X PUT -H "Content-Type: application/json" -H "X-Auth-Token: <API-token>" \
  'https://api.dop.example.com/api/v1/observability.deckhouse.io/spaces/:space_name/projects/:project_name/observabilitydashboards/:name' -d \
'
{
    "kind": "ObservabilityDashboard",
    "metadata":
    {
        "annotations":
        {
            "metadata.deckhouse.io/category": "new-category"
        }
    },
    "spec":
    {
        "definition": {...}
    }
}
'

Пример ответа

{
    "apiVersion": "observability.deckhouse.io/v1alpha1",
    "kind": "ObservabilityDashboard",
    "metadata":
    {
        "annotations":
        {
            "metadata.deckhouse.io/category": "new-category",
            "metadata.deckhouse.io/title": "Dash-dash-board-1"
        },
        "creationTimestamp": "2025-01-24T10:45:15Z",
        "generation": 1,
        "name": "dash-dash-board-1",
        "namespace": "spicy-space-1",
        "resourceVersion": 1
    },
    "spec":
    {
        "definition": "{\"uid\":\"yS1Qy46y6x01bFJI\",\"tags\":[\"test\",\"another-test\"],\"title\":\"Dash-dash-board-1\"}"
    }
}

Удаление дашборда

Этот эндпоинт удаляет существующий дашборд.

DELETE /api/v1/observability.deckhouse.io/spaces/:space_name/projects/:project_name/observabilitydashboards/:name

Параметры адреса запроса в URL:

  • space_name: имя рабочего пространства. Обязательное
  • project_name: имя проекта. Обязательное
  • name: имя дашборда

Требуется аутентификация… У токена должны быть права “Управление через API” “Дашборды”

Пример запроса

$ curl -X DELETE -H "Content-Type: application/json" -H "X-Auth-Token: <API-token>" \
  'https://api.dop.example.com/api/v1/observability.deckhouse.io/spaces/:space_name/projects/:project_name/observabilitydashboards/:name'

Ошибки при создании или обновлении дашбордов

В случае, если запрос на создание или обновление дашборда содержит некорректные данные, ответ будет со статусом 4xx с указанием ошибки:

{"error":"Validation failed: Name has already been taken"}

Рабочие пространства

Параметры рабочего пространства

  • metadata.name: имя рабочего пространства, должно быть уникальным, допускаются строчные латинские буквы и -
  • metadata.generation: версия рабочего пространства
  • metadata.resourceVersion: глобальная версия рабочего пространства
  • metadata.creationTimestamp: дата / время создания рабочего пространства

Получение списка рабочих пространств

Этот эндпоинт возвращает список рабочих пространств. GET /api/v1/observability.deckhouse.io/spaces

Требуется аутентификация… У токена должны быть права “Управление через API” “Рабочие пространства”

Пример запроса

$ curl -H "X-Auth-Token: <API-token>" \
  'https://api.dop.example.com/api/v1/observability.deckhouse.io/spaces'

Пример ответа

{
    "apiVersion": "observability.deckhouse.io/v1alpha1",
    "kind": "ObservabilitySpacesList",
    "metadata": {},
    "items":
    [
        {
            "apiVersion": "observability.deckhouse.io/v1alpha1",
            "kind": "ObservabilitySpace",
            "metadata":
            {
                "creationTimestamp": "2025-03-14T06:07:50Z",
                "generation": 1,
                "name": "example-space",
                "resourceVersion": 1
            },
            "spec":
            {}
        }
    ]
}

Получение рабочего пространства

Этот эндпоинт возвращает рабочее пространство по имени.

GET /api/v1/observability.deckhouse.io/spaces/:name

Параметры адреса запроса в URL:

  • name: имя рабочего пространства. Обязательное

Требуется аутентификация… У токена должны быть права “Управление через API” “Рабочие пространства”

Пример запроса

$ curl -H "X-Auth-Token: <API-token>" \
  'https://api.dop.example.com/api/v1/observability.deckhouse.io/spaces/:name'

Пример ответа

{
  "apiVersion": "observability.deckhouse.io/v1alpha1",
  "kind": "ObservabilitySpace",
  "metadata":
  {
      "creationTimestamp": "2025-03-14T06:07:50Z",
      "generation": 1,
      "name": "example-space",
      "resourceVersion": 1
  },
  "spec":
  {}
}

Создание рабочего пространства

Этот эндпоинт создает новое рабочее пространство.

POST /api/v1/observability.deckhouse.io/spaces

Требуется аутентификация… У токена должны быть права “Управление через API” “Рабочие пространства”

Пример запроса

$ curl -X POST -H "Content-Type: application/json" -H "X-Auth-Token: <API-token>" \
  'https://api.dop.example.com/api/v1/observability.deckhouse.io/spaces' -d \
'
{
    "kind": "ObservabilitySpace",
    "metadata":
    {
        "name": "some-name"
    }
}
'

Пример ответа

{
  "apiVersion": "observability.deckhouse.io/v1alpha1",
  "kind": "ObservabilitySpace",
  "metadata":
  {
      "creationTimestamp": "2025-03-14T06:07:50Z",
      "generation": 1,
      "name": "some-name",
      "resourceVersion": 1
  },
  "spec":
  {}
}

Удаление рабочего пространства

Этот эндпоинт удаляет существующее рабочее пространство.

DELETE /api/v1/observability.deckhouse.io/spaces/:name

Параметры адреса запроса в URL:

  • name: имя рабочего пространства

Требуется аутентификация… У токена должны быть права “Управление через API” “Рабочие пространства”

Пример запроса

$ curl -X DELETE -H "Content-Type: application/json" -H "X-Auth-Token: <API-token>" \
  'https://api.dop.example.com/api/v1/observability.deckhouse.io/spaces/:name'

Ошибки при создании рабочих пространств

В случае, если запрос на создание рабочего пространства содержит некорректные данные, ответ будет со статусом 4xx с указанием ошибки:

{"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” “Проекты”

Пример запроса

$ curl -H "X-Auth-Token: <API-token>" \
  'https://api.dop.example.com/api/v1/observability.deckhouse.io/spaces/:space_name/projects/'

Пример ответа

{
    "apiVersion": "observability.deckhouse.io/v1alpha1",
    "kind": "ObservabilityProjectsList",
    "metadata": {},
    "items":
    [
        {
            "apiVersion": "observability.deckhouse.io/v1alpha1",
            "kind": "ObservabilityProject",
            "metadata":
            {
                "creationTimestamp": "2025-03-14T06:06:41Z",
                "generation": 1,
                "name": "some-project",
                "resourceVersion": 1
            },
            "spec":
            {
                "description": "project description",
                "auto-monitoring": true
            }
        }
    ]
}

Получение проекта

Этот эндпоинт возвращает проект по имени.

GET /api/v1/observability.deckhouse.io/spaces/:space_name/projects/:name

Параметры адреса запроса в URL:

  • space_name: имя рабочего пространства. Обязательное
  • name: имя проекта. Обязательное

Требуется аутентификация… У токена должны быть права “Управление через API” “Проекты”

Пример запроса

$ curl -H "X-Auth-Token: <API-token>" \
  'https://api.dop.example.com/api/v1/observability.deckhouse.io/spaces/:space_name/projects/:name'

Пример ответа

{
  "apiVersion": "observability.deckhouse.io/v1alpha1",
  "kind": "ObservabilityProject",
  "metadata":
  {
      "creationTimestamp": "2025-03-14T06:06:41Z",
      "generation": 1,
      "name": "some-project",
      "resourceVersion": 1
  },
  "spec":
  {
      "description": "project description",
      "auto-monitoring": true
  }
}

Создание проекта

Этот эндпоинт создает новый проект.

POST /api/v1/observability.deckhouse.io/spaces/:space_name/projects

Параметры адреса запроса в URL:

  • space_name: имя рабочего пространства. Обязательное

Требуется аутентификация… У токена должны быть права “Управление через API” “Проекты”

Пример запроса

$ curl -X POST -H "Content-Type: application/json" -H "X-Auth-Token: <API-token>" \
  'https://api.dop.example.com/api/v1/observability.deckhouse.io/spaces/:space_name/projects' -d \
'
{
    "kind": "ObservabilityProject",
    "metadata":
    {
      "name": "some-name"
    },
    "spec":
    {
      "description": "project description",
      "auto-monitoring": true
    }
}
'

Пример ответа

{
  "apiVersion": "observability.deckhouse.io/v1alpha1",
  "kind": "ObservabilityProject",
  "metadata":
  {
      "creationTimestamp": "2025-03-14T06:06:41Z",
      "generation": 1,
      "name": "some-project",
      "resourceVersion": 1
  },
  "spec":
  {
      "description": "project description",
      "auto-monitoring": true
  }
}

Обновление проекта

Этот эндпоинт обновляет существующий проект.

PUT /api/v1/observability.deckhouse.io/spaces/:space_name/projects/:name

Параметры адреса запроса в URL:

  • space_name: имя рабочего пространства. Обязательное
  • name: имя проекта. Обязательное

Требуется аутентификация… У токена должны быть права “Управление через API” “Проекты”

Пример запроса

$ curl -X PUT -H "Content-Type: application/json" -H "X-Auth-Token: <API-token>" \
  'https://api.dop.example.com/api/v1/observability.deckhouse.io/spaces/:space_name/projects/:name' -d \
'
{
    "kind": "ObservabilityProject",
    "spec":
    {
        "description": "updated description",
        "auto-monitoring": false
    }
}
'

Пример ответа

{
  "apiVersion": "observability.deckhouse.io/v1alpha1",
  "kind": "ObservabilityProject",
  "metadata":
  {
      "creationTimestamp": "2025-03-14T06:06:41Z",
      "generation": 1,
      "name": "some-project",
      "resourceVersion": 1
  },
  "spec":
  {
      "description": "updated description",
      "auto-monitoring": false
  }
}

Удаление проекта

Этот эндпоинт удаляет существующий проект.

DELETE /api/v1/observability.deckhouse.io/spaces/:space_name/projects/:name

Параметры адреса запроса в URL:

  • space_name: имя рабочего пространства. Обязательное
  • name: имя проекта. Обязательное

Требуется аутентификация… У токена должны быть права “Управление через API” “Проекты”

Пример запроса

$ curl -X DELETE -H "Content-Type: application/json" -H "X-Auth-Token: <API-token>" \
  'https://api.dop.example.com/api/v1/observability.deckhouse.io/spaces/:space_name/projects/:name'

Ошибки при создании или обновлении проекта

В случае, если запрос на создание или обновление проекта содержит некорректные данные, ответ будет со статусом 4xx с указанием ошибки:

{"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” “Каналы уведомлений”

Пример запроса

$ curl -H "X-Auth-Token: <API-token>" \
  'https://api.dop.example.com/api/v1/observability.deckhouse.io/spaces/:space_name/projects/:project_name/observabilitynotificationchannels'

Пример ответа

{
  "apiVersion": "observability.deckhouse.io/v1alpha1",
  "kind": "ObservabilityNotificationChannelsList",
  "metadata": {},
  "items": [
    {
      "apiVersion": "observability.deckhouse.io/v1alpha1",
      "kind": "ObservabilityNotificationChannel",
      "metadata": {
        "name": "example-channel",
        "creationTimestamp": "2025-03-19T06:12:20Z",
        "generation": 1,
        "resourceVersion": "1"
      },
      "spec": {
        "type": "Email",
        "email": {
          "from": "no-reply@email.com",
          "smtp": {
            "address": "smtp.example.server.com:555",
            "auth": {
              "username": "username",
              "password": "password"
            },
            "requireTLS": true
          },
          "template": "..."
        }
      }
    },
  ]
}

Получение канала уведомлений

Этот эндпоинт возвращает канал уведомлений проекта по имени.

GET /api/v1/observability.deckhouse.io/spaces/:space_name/projects/:project_name/observabilitynotificationchannels/:name

Параметры адреса запроса в URL:

  • space_name: имя рабочего пространства. Обязательное
  • project_name: имя проекта
  • name: имя канала. Обязательное

Требуется аутентификация… У токена должны быть права “Управление через API” “Каналы уведомлений”

Пример запроса

$ curl -H "X-Auth-Token: <API-token>" \
  'https://api.dop.example.com/api/v1/observability.deckhouse.io/spaces/:space_name/projects/:project_name/observabilitynotificationchannels/:name'

Пример ответа

{
  "apiVersion": "observability.deckhouse.io/v1alpha1",
  "kind": "ObservabilityNotificationChannel",
  "metadata": {
    "name": "example-channel",
    "creationTimestamp": "2025-03-19T06:12:20Z",
    "generation": 1,
    "resourceVersion": "1"
  },
  "spec": {
    "type": "Email",
    "email": {
      "from": "no-reply@email.com",
      "smtp": {
        "address": "smtp.example.server.com:555",
        "auth": {
          "username": "username",
          "password": "password"
        },
        "requireTLS": true
      },
      "template": "..."
    }
  }
}

Создание канала уведомлений

Этот эндпоинт создает новый канал уведомлений проекта.

POST /api/v1/observability.deckhouse.io/spaces/:space_name/projects/:project_name/observabilitynotificationchannels

Параметры адреса запроса в URL:

  • space_name: имя рабочего пространства. Обязательное
  • project_name: имя проекта

Требуется аутентификация… У токена должны быть права “Управление через API” “Каналы уведомлений”

Пример запроса

$ curl -X POST -H "Content-Type: application/json" -H "X-Auth-Token: <API-token>" \
  'https://api.dop.example.com/api/v1/observability.deckhouse.io/spaces/:space_name/projects/:project_name/observabilitynotificationchannels' -d \
'
{
  "kind": "ObservabilityNotificationChannel",
  "metadata":
  {
      "name": "new-channel"
  },
  "spec":
  {
      "type": "Email",
      "email":
      {
          "from": "from@email.com",
          "smtp":
          {
              "address": "smtp.example.com:444",
              "auth":
              {
                  "username": "username",
                  "password": "password"
              },
              "requireTLS": true
          }
      }
  }
}
'

Пример ответа

{
  "apiVersion": "observability.deckhouse.io/v1alpha1",
  "kind": "ObservabilityNotificationChannel",
  "metadata":
  {
      "name": "new-channel",
      "creationTimestamp": "2025-03-28T05:04:45Z",
      "generation": 1,
      "resourceVersion": "1"
  },
  "spec":
  {
      "type": "Email",
      "email":
      {
          "from": "from@email.com",
          "smtp":
          {
              "address": "smtp.example.com:444",
              "auth":
              {
                  "username": "username",
                  "password": "password"
              },
              "requireTLS": true
          },
          "template": null
      }
  }
}

Обновление канала уведомлений

Этот эндпоинт обновляет канал уведомлений проекта

PUT /api/v1/observability.deckhouse.io/spaces/:space_name/projects/:project_name/observabilitynotificationchannels/:name

Параметры адреса запроса в URL:

  • space_name: имя рабочего пространства. Обязательное
  • project_name: имя проекта
  • name: имя канала. Обязательное

Требуется аутентификация… У токена должны быть права “Управление через API” “Каналы уведомлений”

Пример запроса

$ curl -X PUT -H "Content-Type: application/json" -H "X-Auth-Token: <API-token>" \
  'https://api.dop.example.com/api/v1/observability.deckhouse.io/spaces/:space_name/projects/:project_name/observabilitynotificationchannels/:name' -d \
'
{
  "kind": "ObservabilityNotificationChannel",
  "metadata":
  {
      "name": "some-channel-1"
  },
  "spec":
  {
      "type": "Email",
      "email":
      {
          "from": "from2@email.com",
          "smtp":
          {
              "address": "smtp.example.com:444",
              "auth":
              {
                  "username": "username",
                  "password": "password"
              },
              "requireTLS": true
          }
      }
  }
}
'

Пример ответа

{
  "apiVersion": "observability.deckhouse.io/v1alpha1",
  "kind": "ObservabilityNotificationChannel",
  "metadata":
  {
      "name": "some-channel-1",
      "creationTimestamp": "2025-03-28T05:08:42Z",
      "generation": 1,
      "resourceVersion": "1"
  },
  "spec":
  {
      "type": "Email",
      "email":
      {
          "from": "from2@email.com",
          "smtp":
          {
              "address": "smtp.example.com:444",
              "auth":
              {
                  "username": "username",
                  "password": "password"
              },
              "requireTLS": true
          },
          "template": null
      }
  }
}

Удаление канала уведомлений

Этот эндпоинт удаляет существующий канал уведомлений проекта.

DELETE /api/v1/observability.deckhouse.io/spaces/:space_name/projects/:project_name/observabilitynotificationchannels/:name

Параметры адреса запроса в URL:

  • space_name: имя рабочего пространства. Обязательное
  • project_name: имя проекта
  • name: имя канала. Обязательное

Требуется аутентификация… У токена должны быть права “Управление через API” “Каналы уведомлений”

Пример запроса

$ curl -X DELETE -H "Content-Type: application/json" -H "X-Auth-Token: <API-token>" \
  'https://api.dop.example.com/api/v1/observability.deckhouse.io/spaces/:space_name/projects/:project_name/observabilitynotificationchannels/:name'

Ошибки при создании или обновлении канала уведомлений

В случае, если запрос на создание или обновление канала содержит некорректные данные, ответ будет со статусом 4xx с указанием ошибки:

{"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” “Правила уведомлений”

Пример запроса

$ curl -H "X-Auth-Token: <API-token>" \
  'https://api.dop.example.com/api/v1/observability.deckhouse.io/spaces/:space_name/projects/:project_name/observabilitynotificationpolicies'

Пример ответа

{
  "apiVersion": "observability.deckhouse.io/v1alpha1",
  "kind": "ObservabilityNotificationPoliciesList",
  "metadata": {},
  "items":
  [
    {
      "apiVersion": "observability.deckhouse.io/v1alpha1",
      "kind": "ObservabilityNotificationPolicy",
      "metadata": {
        "name": "test-rule",
        "creationTimestamp": "2025-03-28T06:42:47Z",
        "generation": 1,
        "resourceVersion": "1"
      },
      "spec": {
        "alert": {
          "selector": {
            "matchExpressions": {
              "items":
              [
                {
                  "key": "severity",
                  "operator": "Equal",
                  "value": "critical"
                }
              ]
            }
          }
        },
        "notification":
        {
          "channel":
          {
            "kind": "ObservabilityNotificationChannel",
            "name": "some-channel-1",
            "parameters": { "emails": ["test@email.com"] }
          },
          "repeatInterval": "30s"
        }
      }
    }
  ]
}

Получение правила уведомлений

Этот эндпоинт возвращает правило канала уведомлений проекта по имени.

GET /api/v1/observability.deckhouse.io/spaces/:space_name/projects/:project_name/observabilitynotificationpolicies/:name

Параметры адреса запроса в URL:

  • space_name: имя рабочего пространства. Обязательное
  • project_name: имя проекта
  • name: имя канала. Обязательное

Требуется аутентификация… У токена должны быть права “Управление через API” “Правила уведомлений”

Пример запроса

$ curl -H "X-Auth-Token: <API-token>" \
  'https://api.dop.example.com/api/v1/observability.deckhouse.io/spaces/:space_name/projects/:project_name/observabilitynotificationpolicies/:name'

Пример ответа

{
  "apiVersion": "observability.deckhouse.io/v1alpha1",
  "kind": "ObservabilityNotificationPolicy",
  "metadata": {
    "name": "test-rule",
    "creationTimestamp": "2025-03-28T07:00:54Z",
    "generation": 1,
    "resourceVersion": "1"
  },
  "spec": {
    "alert": {
      "selector": {
        "matchExpressions": {
          "items": [
            {
              "key": "severity",
              "operator": "Equal",
              "value": "critical"
            }
          ]
        }
      }
    },
    "notification": {
      "channel": {
        "kind": "ObservabilityNotificationChannel",
        "name": "some-giper-channel-1",
        "parameters": {
          "emails": ["test@email.com"]
        }
      },
      "repeatInterval": "30s"
    }
  }
}

Создание правила уведомлений

Этот эндпоинт создает новое правило канала уведомлений проекта.

POST /api/v1/observability.deckhouse.io/spaces/:space_name/projects/:project_name/observabilitynotificationpolicies

Параметры адреса запроса в URL:

  • space_name: имя рабочего пространства. Обязательное
  • project_name: имя проекта

Требуется аутентификация… У токена должны быть права “Управление через API” “Правила уведомлений”

Пример запроса

$ curl -X POST -H "Content-Type: application/json" -H "X-Auth-Token: <API-token>" \
  'https://api.dop.example.com/api/v1/observability.deckhouse.io/spaces/:space_name/projects/:project_name/observabilitynotificationchannels/:notification_channel_name/observabilitynotificationpolicies' -d \
'
{
  "kind": "ObservabilityNotificationPolicy",
  "metadata": {
    "name": "test-rule"
  },
  "spec": {
    "alert": {
      "selector": {
        "matchExpressions": {
          "items": [
            {
              "key": "severity",
              "operator": "Equal",
              "value": "critical"
            }
          ]
        }
      }
    },
    "notification": {
      "channel": {
        "kind": "ObservabilityNotificationChannel",
        "name": "some-giper-channel-1",
        "parameters": {
          "emails": [
            "first@email.com",
            "second@email.com"
          ]
        }
      },
      "repeatInterval": "45s"
    }
  }
}
'

Пример ответа

{
  "apiVersion": "observability.deckhouse.io/v1alpha1",
  "kind": "ObservabilityNotificationPolicy",
  "metadata": {
    "name": "test-rule",
    "creationTimestamp": "2025-03-28T07:12:41Z",
    "generation": 1,
    "resourceVersion": "1"
  },
  "spec": {
    "alert": {
      "selector": {
        "matchExpressions": {
          "items": [
            {
              "key": "severity",
              "operator": "Equal",
              "value": "critical"
            }
          ]
        }
      }
    },
    "notification": {
      "channel": {
        "kind": "ObservabilityNotificationChannel",
        "name": "some-giper-channel-1",
        "parameters": {
          "emails": [
            "first@email.com",
            "second@email.com"
          ]
        }
      },
      "repeatInterval": "45s"
    }
  }
}

Обновление правила уведомлений

Этот эндпоинт обновляет правило канала уведомлений проекта

PUT /api/v1/observability.deckhouse.io/spaces/:space_name/projects/:project_name/observabilitynotificationpolicies/:name

Параметры адреса запроса в URL:

  • space_name: имя рабочего пространства. Обязательное
  • project_name: имя проекта
  • name: имя канала. Обязательное

Требуется аутентификация… У токена должны быть права “Управление через API” “Правила уведомлений”

Пример запроса

$ curl -X PUT -H "Content-Type: application/json" -H "X-Auth-Token: <API-token>" \
  'https://api.dop.example.com/api/v1/observability.deckhouse.io/spaces/:space_name/projects/:project_name/observabilitynotificationpolicies/:name' -d \
'
{
  "kind": "ObservabilityNotificationChannel",
  "metadata": {
    "name": "test-rule"
  },
  "spec": {
    "alert": {
      "selector": {
        "matchExpressions": {
          "items": [
            {
              "key": "severity",
              "operator": "Equal",
              "value": "warning"
            }
          ]
        }
      }
    },
    "notification": {
      "channel": {
        "kind": "ObservabilityNotificationChannel",
        "name": "some-channel-1",
        "parameters": {
          "emails": [
            "first@email.com",
            "second@email.com"
          ]
        }
      },
      "repeatInterval": "46s"
    }
  }
}
'

Пример ответа

{
  "apiVersion": "observability.deckhouse.io/v1alpha1",
  "kind": "ObservabilityNotificationPolicy",
  "metadata": {
    "name": "test-rule",
    "creationTimestamp": "2025-03-28T07:16:02Z",
    "generation": 1,
    "resourceVersion": "1"
  },
  "spec": {
    "alert": {
      "selector": {
        "matchExpressions": {
          "items": [
            {
              "key": "severity",
              "operator": "Equal",
              "value": "warning"
            }
          ]
        }
      }
    },
    "notification": {
      "channel": {
        "kind": "ObservabilityNotificationChannel",
        "name": "some-giper-channel-1",
        "parameters": {
          "emails": [
            "first@email.com",
            "second@email.com"
          ]
        }
      },
      "repeatInterval": "46s"
    }
  }
}

Удаление правила уведомлений

Этот эндпоинт удаляет существующее правило канала уведомлений проекта.

DELETE /api/v1/observability.deckhouse.io/spaces/:space_name/projects/:project_name/observabilitynotificationpolicies/:name

Параметры адреса запроса в URL:

  • space_name: имя рабочего пространства. Обязательное
  • project_name: имя проекта
  • name: имя канала. Обязательное

Требуется аутентификация… У токена должны быть права “Управление через API” “Правила уведомлений”

Пример запроса

$ curl -X DELETE -H "Content-Type: application/json" -H "X-Auth-Token: <API-token>" \
  'https://api.dop.example.com/api/v1/observability.deckhouse.io/spaces/:space_name/projects/:project_name/observabilitynotificationpolicies/:name'

Ошибки при создании или обновлении правила канала уведомлений

В случае, если запрос на создание или обновление канала содержит некорректные данные, ответ будет со статусом 4xx с указанием ошибки:

{"error":"Validation failed: Name has already been taken"}