Zum Inhalt

Labels & Konventionen

Überblick

Seit Polycrate API 0.15.0 verwendet die gesamte Polycrate-Plattform ein einheitliches Label-Schema mit dem Präfix polycrate_. Diese Labels werden auf Kubernetes-Objekten (Pods, Secrets, PVs, Services, …), in der Polycrate-API und in Metrics/Logs konsistent verwendet. Sie ermöglichen:

  • Zuordnung von Kubernetes-Objekten zu Polycrate-Entitäten (Organization, Workspace, K8sApp, Host, Block)
  • Filtern in Logs und Metrics (Log Explorer, Dashboards)
  • Discovery durch den Polycrate Operator

Migration von *.polycrate.io/* zu polycrate_*

Frühere Polycrate-Versionen verwendeten FQDN-artige Label-Keys wie:

organization.polycrate.io/name: my-org
workspace.polycrate.io/name: production
app.polycrate.io/kind: postgres

Ab Polycrate API 0.15.0 / CLI 0.35.0 werden diese durch flache, unterstrich-getrennte Keys ersetzt:

polycrate_organization: my-org
polycrate_workspace: production
polycrate_app_kind: postgres

Warum?

  • Konsistenz zwischen API, CLI und Kubernetes-Ressourcen
  • Einfachere Filter in VictoriaMetrics / VictoriaLogs / Grafana (keine Punkte/Slashes im Key)
  • Single Source of Truth: Label-Keys sind als StrEnum in der Polycrate-API definiert und werden via OpenAPI automatisch als typisierte Go-Konstanten im CLI generiert → API und CLI können nie divergieren
  • Validität für Kubernetes-Finalizer: polycrate.io/<resource>-<purpose> (z. B. polycrate.io/s3bucket-cleanup) erfüllt die K8s-Finalizer-FQDN-Anforderung

Übergangsverhalten

Komponente Verhalten
Polycrate Operator (CLI 0.35.0+) Liest sowohl alte als auch neue Labels, schreibt nur noch neue
Log Explorer (API 0.15.0+) Nutzt ausschließlich neue polycrate_* Keys
Bestehende Objekte Werden bei nächstem Sync/Reconcile auf die neuen Labels migriert
Kundenseitige Manifeste Sollten auf polycrate_* umgestellt werden

Der Operator unterstützt die alten Keys noch, damit Bestandsobjekte nicht brechen. Eine "Grace Period" von einer Minor-Version ist vorgesehen; eine konkrete Deprecation-Version wird rechtzeitig angekündigt.

Standard-Label-Keys

Key Inhalt Beispielwert
polycrate_organization Organisation-Slug ayedo
polycrate_workspace Workspace-Name production
polycrate_block Block-Name postgres
polycrate_block_version Block-Version 1.2.0
polycrate_app K8sApp-Name customer-portal
polycrate_app_kind K8sApp-Kind postgres, helm, generic
polycrate_host Host-Name node-01
polycrate_cluster K8sCluster-Name prod-fra1
polycrate_action Action-Name (bei Ansible-Logs) deploy

Die vollständige, stets aktuelle Liste finden Sie in der OpenAPI-Spec der Polycrate API (Enum PolycrateLabelKeys).

Wie verwende ich die Labels?

Eigene K8sApp-Manifeste labeln

apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-app
  labels:
    polycrate_organization: ayedo
    polycrate_workspace: production
    polycrate_app: my-app
    polycrate_app_kind: generic
spec:
  template:
    metadata:
      labels:
        polycrate_organization: ayedo
        polycrate_app: my-app
    ...

Der Operator erkennt diese Labels, ordnet das Objekt Ihrer Organisation/Ihrem Workspace/Ihrer K8sApp zu und zeigt es im Polycrate-Dashboard korrekt an.

In Log Explorer / Grafana filtern

Log Explorer (VictoriaLogs):

polycrate_organization:"ayedo" AND polycrate_app:"customer-portal"

Grafana / PromQL (VictoriaMetrics):

sum by (polycrate_app) (
  rate(http_requests_total{polycrate_workspace="production"}[5m])
)

Pod-Labels vs. Namespace-Labels

  • Pod-Labels: immer bevorzugt, da Metrics/Logs pro-Pod gesampelt werden
  • Namespace-Labels als Fallback (für alle Pods eines Namespaces)
  • Der Operator propagiert Labels über Discovery-Controller automatisch auf abhängige Objekte (z. B. Pods eines Helm-Release)

Finalizer-Konvention

Polycrate-Kubernetes-Finalizer folgen der FQDN-Konvention:

polycrate.io/<resource>-<purpose>

Beispiele:

  • polycrate.io/s3bucket-cleanup – verhindert Löschen eines S3Bucket-CR vor sauberer Deprovisionierung
  • polycrate.io/endpoint-sync – hält einen Endpoint-CR bis zum API-Sync

Die 3-Generationen-Migration (siehe Release CLI 0.35.1) räumt alte, ungültig benannte Finalizer automatisch auf.

Siehe auch