Стадия жизненного цикла модуля: Preview
У модуля есть требования для установки

Конвертация существующих дашбордов из GrafanaDashboardDefinition

Для перехода со старого формата дашбордов (GrafanaDashboardDefinition) на новый (ObservabilityDashboard, ClusterObservabilityDashboard), необходимо вручную адаптировать манифесты. Обратите внимание на следующие отличия:

Старый формат Новый формат
spec.folder Поле отсутствует. Папка задаётся с помощью аннотации: observability.deckhouse.io/category
Название дашборда берется из поля Title дашборда Название задаётся с помощью аннотации: observability.deckhouse.io/title. Если аннотация отсутствует — используется поле title из JSON дашборда

Пример конвертации

Старый формат:

apiVersion: deckhouse.io/v1
kind: GrafanaDashboardDefinition
metadata:
  name: example-dashboard
spec:
  folder: "Apps"
  json: '{
    "title": "Example Dashboard",
    ...
  }'

Новый формат (ObservabilityDashboard):

apiVersion: observability.deckhouse.io/v1alpha1
kind: ObservabilityDashboard
metadata:
  name: example-dashboard
  namespace: my-namespace
  annotations:
    metadata.deckhouse.io/category: "Apps"
    metadata.deckhouse.io/title: "Example Dashboard"
spec:
  definition: |
    {
      "title": "Example Dashboard",
      ...
    }

Новый формат (ClusterObservabilityDashboard):

apiVersion: observability.deckhouse.io/v1alpha1
kind: ClusterObservabilityDashboard
metadata:
  name: example-dashboard
  annotations:
    metadata.deckhouse.io/category: "Apps"
    metadata.deckhouse.io/title: "Example Dashboard"
spec:
  definition: |
    {
      "title": "Example Dashboard",
      ...
    }

Как предоставить права на метрики и дашборды в конкретном пространстве имен

Для предоставления доступа к метрикам и дашбордам в конкретном пространстве имён необходимо создать ресурсы ClusterRole и RoleBinding, которые будут определять права пользователя. Доступ к метрикам и дашбордам предоставляется отдельно:

  • Метрики — проверяется наличие права get на ресурс metrics.observability.deckhouse.io.
  • Дашборды — проверяется наличие прав на ресурс observabilitydashboards.observability.deckhouse.io:
    • get — просмотр дашбордов;
    • create — создание, изменение и удаление дашбордов.

Пример ClusterRole и RoleBinding для доступа к метрикам и дашбордам только на чтение

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: observability-viewer
rules:
  - apiGroups: ["observability.deckhouse.io"]
    resources: ["metrics", "observabilitydashboards"]
    verbs: ["get", "list", "watch"]
---
apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
  name: bind-observability-viewer
  namespace: my-namespace
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: ClusterRole
  name: observability-viewer
subjects:
  - kind: User
    name: user@example.com
    apiGroup: rbac.authorization.k8s.io

Пример ClusterRole и RoleBinding для доступа к метрикам и дашбордам на чтение и редактирование

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: observability-editor
rules:
  - apiGroups: ["observability.deckhouse.io"]
    resources: ["metrics", "observabilitydashboards"]
    verbs: ["get", "list", "watch"]
  - apiGroups: ["observability.deckhouse.io"]
    resources: ["observabilitydashboards"]
    verbs: ["create", "update", "delete"]
---
apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
  name: bind-observability-editor
  namespace: my-namespace
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: ClusterRole
  name: observability-editor
subjects:
  - kind: User
    name: user@example.com
    apiGroup: rbac.authorization.k8s.io

Как предоставить доступ к системным метрикам и дашбордам

Для предоставления доступа к системным метрикам и дашбордам необходимо создать ClusterRole и ClusterRoleBinding, которые будут определять права пользователя. Доступ к метрикам и дашбордам предоставляется отдельно:

  • Метрики — проверяется наличие права get на ресурс clustermetrics.observability.deckhouse.io.
  • Дашборды — проверяется наличие прав на ресурс clusterobservabilitydashboards.observability.deckhouse.io:
    • get — просмотр дашбордов;
    • create — создание, изменение и удаление дашбордов.

Пример ClusterRole и ClusterRoleBinding для просмотра системных метрик и дашбордов

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: observability-cluster-viewer
rules:
  - apiGroups: ["observability.deckhouse.io"]
    resources: ["clustermetrics", "clusterobservabilitydashboards"]
    verbs: ["get", "list", "watch"]
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: bind-observability-cluster-viewer
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: ClusterRole
  name: observability-cluster-viewer
subjects:
  - kind: User
    name: user@example.com
    apiGroup: rbac.authorization.k8s.io

Пример ClusterRole и ClusterRoleBinding для доступа к метрикам и дашбордам на чтение и редактирование

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: observability-cluster-editor
rules:
  - apiGroups: ["observability.deckhouse.io"]
    resources: ["clustermetrics", "clusterobservabilitydashboards"]
    verbs: ["get", "list", "watch"]
  - apiGroups: ["observability.deckhouse.io"]
    resources: ["clusterobservabilitydashboards"]
    verbs: ["create", "update", "delete"]
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: bind-observability-cluster-editor
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: ClusterRole
  name: observability-cluster-editor
subjects:
  - kind: User
    name: user@example.com
    apiGroup: rbac.authorization.k8s.io

Как предоставить полный доступ ко всем метрикам и дашбордам

Для предоставления полного доступа ко всем метрикам и дашбордам в Deckhouse необходимо создать роль ClusterRole, которая будет включать все необходимые права, и используйте ClusterRoleBinding для назначения этой роли.

Пример ClusterRole

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: observability-admin
rules:
  - apiGroups: ["observability.deckhouse.io"]
    resources:
      - metrics
      - clustermetrics
      - observabilitydashboards
      - clusterobservabilitydashboards
      - clusterobservabilitypropagateddashboards
    verbs: ["get", "list", "watch", "create", "update", "delete"]
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: bind-observability-admin
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: ClusterRole
  name: observability-admin
subjects:
  - kind: User
    name: user@example.com
    apiGroup: rbac.authorization.k8s.io

Можно использовать готовую роль cluster-admin, однако её следует применять с осторожностью, так как она предоставляет полный доступ ко всем ресурсам кластера.

Как выдать доступ при использовании RBAC 2.0

Если включена экспериментальная ролевая модель, права назначаются через ресурсы UserRole и ClusterUserRole.

Пример доступа к метрикам и дашбордам в конкретном пространстве имён

Для предоставления пользователю доступа к пространству имён myapp с возможностью просмотра метрик и дашбордов, можно использовать следующий манифест:

apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
  name: myapp-developer
  namespace: myapp
subjects:
  - kind: User
    name: user@example.com
    apiGroup: rbac.authorization.k8s.io
roleRef:
  kind: ClusterRole
  name: d8:use:role:user
  apiGroup: rbac.authorization.k8s.io

Данный пример предоставляет права не только для доступа к дашбордам и метрикам. Описание данной роли можно найти в документации модуля user-authz.

Как предоставить внешний доступ для чтения метрик проекта

Для предоставления внешнего доступа к метрикам проекта необходимо выполнить следующие шаги:

  1. Разрешите внешний доступ к метрикам. Для этого включите параметр spec.settings.externalMetricsAccess в настройках модуля observability.

  2. Создайте ServiceAccount для авторизации запросов:

    apiVersion: v1
kind: ServiceAccount
metadata:
  name: metrics-access
  namespace: my-namespace
---
apiVersion: v1
kind: Secret
metadata:
  name: metrics-access
  annotations:
    kubernetes.io/service-account.name: metrics-access
type: kubernetes.io/service-account-token

  3. Предоставьте права на чтение метрик созданному ServiceAccount с помощью ресурсов Role и RoleBinding.

    apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
  namespace: my-namespace
  name: metrics-access
rules:
  - apiGroups: ["observability.deckhouse.io"]
    resources: ["metrics"]
    verbs: ["get", "watch", "list"]
  - apiGroups: [""]
    resources: ["namespaces"]
    verbs: ["get", "watch", "list"]
---
apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
  name: metrics-access
  namespace: my-namespace
subjects:
  - kind: ServiceAccount
    name: metrics-access
    namespace: my-namespace
roleRef:
  kind: Role
  name: metrics-access
  apiGroup: rbac.authorization.k8s.io

  4. Получите авторизационный токен для доступа к метрикам. При создании ServiceAccount был создан секрет с токеном. Токен хранится в виде Base64-строки. Чтобы извлечь его и раскодировать, выполните следующую команду:

    d8 k -n my-namespace get secret metrics-access -ojsonpath='{ .data.token }' | base64 -d

    Этот токен потребуется на следующем шаге для настройки источника данных (data source) в Grafana.

  5. Настройте доступ к метрикам во внешней Grafana. Добавьте источник данных (data source) Prometheus со следующими параметрами:

    • Name — произвольное имя источника данных.
    • URL — адрес внешнего эндпоинта для доступа к метрикам в формате https://observability.%publicDomainTemplate%/<prefix>, где:
      • %publicDomainTemplate% — шаблон DNS-имен вашего кластера, заданный в глобальных настройках Deckhouse Kubernetes Platform.
      • <prefix> — один из префиксов для доступа к Prometheus:
        • /metrics/main — для метрик основного Prometheus.
        • /metrics/longterm — для метрик Prometheus Longterm.
    • HTTP Headers — дополнительные HTTP-заголовки для авторизации:
      • Header: Authorization.
      • Value: Bearer <TOKEN_VALUE>, где <TOKEN_VALUE> — это токен, полученный из секрета на предыдущем шаге.

Как предоставить внешний доступ для записи метрик

Для предоставления внешнего доступа для записи метрик необходимо выполнить следующие шаги:

  1. Разрешить внешний доступ к метрикам, для этого необходимо включить параметр spec.settings.externalMetricsAccess, в настройках модуля observability.

  2. Для авторизации запросов, создать сервис аккаунт:

    apiVersion: v1
kind: ServiceAccount
metadata:
  name: metrics-access
  namespace: my-namespace
---
apiVersion: v1
kind: Secret
metadata:
  name: metrics-access
  namespace: my-namespace
  annotations:
    kubernetes.io/service-account.name: metrics-access
type: kubernetes.io/service-account-token

  3. Предоставить права на запись метрик для созданного сервис аккаунта с помощью Role и RoleBinding. Пример манифеста:

    apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
  namespace: my-namespace
  name: metrics-access
rules:
  - apiGroups: ["observability.deckhouse.io"]
    resources: ["metrics"]
    verbs: ["create"]
  - apiGroups: [""]
    resources: ["namespaces"]
    verbs: ["get", "watch", "list"]
---
apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
  name: metrics-access
  namespace: my-namespace
subjects:
  - kind: ServiceAccount
    name: metrics-access
    namespace: my-namespace
roleRef:
  kind: Role
  name: metrics-access
  apiGroup: rbac.authorization.k8s.io

  4. Получить авторизационный токен. При создании ServiceAccount был создан Secret, содержащий авторизационный токен. Токены в секретах содержатся в base64. Этот токен можно использовать для доступа к метрикам. Получить токен и раскодировать его можно с помощью команды:

    kubectl -n my-namespace get secret metrics-access -ojsonpath='{ .data.token }' | base64 -d

  5. Для записи метрик необходимо отправлять запросы по протоколам Prometheus Remote-Write V1 или V2.

    • URL: https://observability.%publicDomainTemplate%/api/v1/write. Подробнее про publicDomainTemplate.
    • HTTP Headers:
      • Header: Authorization
      • Value: Bearer <TOKEN_VALUE>, где токен это токен полученный из Secret-а metrics-access на предыдущем шаге.

Как предоставить внешний доступ для чтения метрик кластера

Для предоставления внешнего доступа к метрикам кластера необходимо выполнить следующие шаги:

  1. Разрешите внешний доступ к метрикам. Для этого включите параметр spec.settings.externalMetricsAccess в настройках модуля observability.

  2. Создайте ServiceAccount для авторизации запросов:

    apiVersion: v1
kind: ServiceAccount
metadata:
  name: cluster-metrics-access
---
apiVersion: v1
kind: Secret
metadata:
  name: cluster-metrics-access
  annotations:
    kubernetes.io/service-account.name: cluster-metrics-access
type: kubernetes.io/service-account-token

  3. Предоставьте права на чтение метрик созданному ServiceAccount с помощью ресурсов ClusterRole и ClusterRoleBinding.

    apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: observability-cluster-metrics-viewer
rules:
  - apiGroups: ["observability.deckhouse.io"]
    resources: ["clustermetrics"]
    verbs: ["get", "list", "watch"]
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: bind-observability-cluster-metrics-viewer
subjects:
  - kind: ServiceAccount
    name: cluster-metrics-access
    namespace: default
roleRef:
  kind: ClusterRole
  name: observability-cluster-metrics-viewer
  apiGroup: rbac.authorization.k8s.io

  4. Получите авторизационный токен для доступа к метрикам. При создании ServiceAccount был создан секрет с токеном. Токен хранится в виде Base64-строки. Чтобы извлечь его и раскодировать, выполните следующую команду:

    d8 k -n my-namespace get secret cluster-metrics-access -ojsonpath='{ .data.token }' | base64 -d

    Этот токен потребуется на следующем шаге для настройки источника данных (data source) в Grafana.

  5. Настройте доступ к метрикам во внешней Grafana. Добавьте источник данных (data source) Prometheus со следующими параметрами:

    • Name — произвольное имя источника данных.
    • URL — адрес внешнего эндпоинта для доступа к метрикам в формате https://observability.%publicDomainTemplate%/<prefix>, где:
      • %publicDomainTemplate% — шаблон DNS-имен вашего кластера, заданный в глобальных настройках Deckhouse Kubernetes Platform.
      • <prefix> — один из префиксов для доступа к Prometheus:
        • /metrics/main — для метрик основного Prometheus.
        • /metrics/longterm — для метрик Prometheus Longterm.
    • HTTP Headers — дополнительные HTTP-заголовки для авторизации:
      • Header: Authorization.
      • Value: Bearer <TOKEN_VALUE>, где <TOKEN_VALUE> — это токен, полученный из секрета на предыдущем шаге.

Что такое DeadMansSwitch и PrometheusUnavailable алерты?

DeadMansSwitch

DeadMansSwitch — это особый алерт, который непрерывно срабатывает, пока Prometheus работает и пайплайн алертинга функционирует. По умолчанию он отправляется во все настроенные каналы уведомлений (если они не имеют фильтрации по лейблам в политиках уведомлений).

Алерт DeadMansSwitch скрыт из вывода kubectl get clusterobservabilityalerts (list/watch), чтобы не засорять список алертов. Однако его можно получить напрямую через kubectl get clusterobservabilityalert <name>.

DeadMansSwitch можно отключить через настройку deadMansSwitch.enabled в ModuleConfig observability. При отключении алерты DeadMansSwitch и PrometheusUnavailable не создаются.

PrometheusUnavailable

PrometheusUnavailable (ранее MissingDeadMansSwitch) — это алерт, который автоматически генерируется, если алерт DeadMansSwitch не поступал более 2 минут. Это означает, что весь пайплайн алертинга не функционирует — Prometheus может быть недоступен, нарушено соединение между Prometheus и alertmanager, или существует другая проблема, препятствующая отправке алертов.

PrometheusUnavailable — это кластерный алерт, отображаемый как в UI, так и в kubectl get clusterobservabilityalerts.