Единые требования к labels и annotations в инфраструктуре

Стандарты именования (Labels & Annotations)

Для обеспечения единообразия и возможности автоматизации (мониторинг, биллинг, логгирование), все ресурсы в кластере должны следовать единому стандарту меток.

Обязательные метки (`labels`)

Используются стандартные рекомендации Kubernetes (app.kubernetes.io/*):

app.kubernetes.io/name: Имя приложения (например, auth, besu-connector).
app.kubernetes.io/component: Роль компонента:
- microservice — логика приложения.
- database — хранилища (Postgres, Redis).
- message-broker — очередь сообщений (Kafka).
- dlt-node — узлы блокчейна (Besu).
app.kubernetes.io/part-of: Всегда maniton-platform.
app.kubernetes.io/managed-by: Инструмент деплоя (например, kustomize).

Аннотации (`annotations`)

Используются для интеграции с внешними системами:

prometheus.io/scrape: "true": Разрешить сбор метрик для этого пода.
prometheus.io/port: "3000": Порт, на котором сервис отдает метрики.
kubernetes.io/description: Краткое описание назначения ресурса на русском языке.

Пример манифеста

metadata:
  name: auth-service
  labels:
    app.kubernetes.io/name: auth
    app.kubernetes.io/component: microservice
    app.kubernetes.io/part-of: maniton-platform
  annotations:
    kubernetes.io/description: 'Сервис аутентификации и управления KYC'
    prometheus.io/scrape: 'true'

Дополнительные метки

Service Labels

metadata:
  name: auth-service
  labels:
    app.kubernetes.io/name: auth
    app.kubernetes.io/component: microservice
    app.kubernetes.io/part-of: maniton-platform
    app.kubernetes.io/version: '1.2.0'
    app.kubernetes.io/managed-by: kustomize
    maniton.io/environment: 'production'
    maniton.io/team: 'platform'

Deployment Labels

spec:
  template:
    metadata:
      labels:
        app.kubernetes.io/name: auth
        app.kubernetes.io/component: microservice
        app.kubernetes.io/part-of: maniton-platform
        app.kubernetes.io/version: '1.2.0'
        maniton.io/pod-template-hash: 'abc123'

Аннотации для мониторинга

Prometheus

annotations:
  prometheus.io/scrape: 'true'
  prometheus.io/port: '3001'
  prometheus.io/path: '/metrics'

Grafana

annotations:
  grafana.io/dashboard: 'auth-service'
  grafana.io/panel: 'requests'

Loki

annotations:
  loki.io/format: 'json'
  loki.io/labels: 'service=auth-service'

Метки для трассировки

OpenTelemetry

annotations:
  tracing.opentelemetry.io/instrument: 'true'
  tracing.opentelemetry.io/exporter: 'jaeger'
  tracing.opentelemetry.io/sampler: 'always_on'

Метки для безопасности

PodSecurity

metadata:
  annotations:
    pod-security.policy: 'restricted'
    pod-security.version: 'latest'

Network Policies

metadata:
  annotations:
    network-policy: 'default-deny-ingress'
    network-policy.version: 'v1'

Метки для биллинга

Cost Labels

metadata:
  labels:
    cost-center: 'platform'
    cost-environment: 'production'
    cost-team: 'platform'

Resource Labels

spec:
  template:
    metadata:
      labels:
        maniton.io/cpu-request: '500m'
        maniton.io/cpu-limit: '1000m'
        maniton.io/memory-request: '512Mi'
        maniton.io/memory-limit: '1Gi'

Метки для релиз

Version Labels

metadata:
  labels:
    app.kubernetes.io/version: '1.2.0'
    app.kubernetes.io/commit: 'abc123'
    app.kubernetes.io/build-date: '2024-01-28T00:00:00Z'

Метки для окружений

Environment Labels

metadata:
  labels:
    maniton.io/environment: 'production'
    maniton.io/cluster: 'moneyton'
    maniton.io/region: 'eu-central-1'

Метки для компонентов

Database Labels

metadata:
  name: postgres
  labels:
    app.kubernetes.io/name: postgres
    app.kubernetes.io/component: database
    app.kubernetes.io/part-of: maniton-platform
    app.kubernetes.io/managed-by: kustomize
    maniton.io/database-type: 'postgresql'
    maniton.io/database-version: '16'

Kafka Labels

metadata:
  name: kafka
  labels:
    app.kubernetes.io/name: kafka
    app.kubernetes.io/component: message-broker
    app.kubernetes.io/part-of: maniton-platform
    app.kubernetes.io/managed-by: kustomize
    maniton.io/message-broker-type: 'kafka'
    maniton.io/message-broker-version: '3.6'

Besu Labels

metadata:
  name: besu
  labels:
    app.kubernetes.io/name: besu
    app.kubernetes.io/component: dlt-node
    app.kubernetes.io/part-of: maniton-platform
    app.kubernetes.io/managed-by: kustomize
    maniton.io/dlt-type: 'besu'
    maniton.io/dlt-version: '23.10.0'
    maniton.io/consensus: 'qbft'

Метки для тестирования

Test Labels

metadata:
  labels:
    app.kubernetes.io/environment: 'test'
    app.kubernetes.io/test-type: 'integration'

Стандарты именования (K8s)