Labels & Conventions

The unified polycrate_* label schema used across the Polycrate API, CLI and Kubernetes resources since API 0.15.0, including the migration from *.polycrate.io/* keys, standard label keys, filtering in logs and metrics, and the finalizer naming convention.

Labels & Conventions

Overview

Since Polycrate API 0.15.0, the entire Polycrate platform uses a unified label schema with the prefix polycrate_. These labels are used consistently on Kubernetes objects (Pods, Secrets, PVs, Services, …), in the Polycrate API and in metrics/logs. They enable:

  • Mapping of Kubernetes objects to Polycrate entities (Organization, Workspace, K8sApp, Host, Block)
  • Filtering in logs and metrics (Log Explorer, dashboards)
  • Discovery by the Polycrate Operator

Migration from *.polycrate.io/* to polycrate_*

Earlier Polycrate versions used FQDN-style label keys such as:

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

As of Polycrate API 0.15.0 / CLI 0.35.0 these are replaced by flat, underscore-separated keys:

polycrate_organization: my-org
polycrate_workspace: production
polycrate_app_kind: postgres

Why?

  • Consistency between API, CLI and Kubernetes resources
  • Simpler filters in VictoriaMetrics / VictoriaLogs / Grafana (no dots/slashes in the key)
  • Single source of truth: label keys are defined as a StrEnum in the Polycrate API and are automatically generated via OpenAPI as typed Go constants in the CLI → API and CLI can never diverge
  • Validity for Kubernetes finalizers: polycrate.io/<resource>-<purpose> (e.g. polycrate.io/s3bucket-cleanup) satisfies the K8s finalizer FQDN requirement

Transitional behavior

Component Behavior
Polycrate Operator (CLI 0.35.0+) Reads both old and new labels, writes only new ones
Log Explorer (API 0.15.0+) Uses exclusively the new polycrate_* keys
Existing objects Are migrated to the new labels on the next sync/reconcile
Customer-side manifests Should be switched to polycrate_*

The operator still supports the old keys so that existing objects do not break. A "grace period" of one minor version is planned; a concrete deprecation version will be announced in due time.

Standard label keys

Key Content Example value
polycrate_organization Organization 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 (for Ansible logs) deploy

The complete, always up-to-date list can be found in the OpenAPI spec of the Polycrate API (enum PolycrateLabelKeys).

How do I use the labels?

Labeling your own K8sApp manifests

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
    ...

The operator recognizes these labels, assigns the object to your organization/workspace/K8sApp and displays it correctly in the Polycrate dashboard.

Filtering in Log Explorer / Grafana

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: always preferred, since metrics/logs are sampled per pod
  • Namespace labels as a fallback (for all pods in a namespace)
  • The operator automatically propagates labels to dependent objects via discovery controllers (e.g. pods of a Helm release)

Finalizer convention

Polycrate Kubernetes finalizers follow the FQDN convention:

polycrate.io/<resource>-<purpose>

Examples:

  • polycrate.io/s3bucket-cleanup – prevents deletion of an S3Bucket CR before clean deprovisioning
  • polycrate.io/endpoint-sync – holds an Endpoint CR until the API sync

The three-generation migration (see Release CLI 0.35.1) automatically cleans up old, invalidly named finalizers.

See also