README
¶
pkg/labels
labels owns two things:
-
All label, annotation, and finalizer constants used by the Orkestra control plane — stable string identifiers shared across the runtime, CLI, generators, komposers, Gateway, and admission webhooks.
-
The
Manager— a stateless helper that applies the standard label invariants to any Kubernetes object based on Katalog configuration. Previously part of the reconciler, it lives here so the admission layer and any future consumer can use it without importing reconciler internals.
The package is dependency-free except for domain.Object and k8s.io/apimachinery. Safe to import from any layer.
What lives here
| File | Role |
|---|---|
labels.go |
All label keys, annotation keys, finalizer keys, selector helpers, and label set constructors |
manager.go |
Manager — applies managed, deletion-protection, and strict-mode-exempt labels to a domain.Object in memory |
Key constants
| Constant | Value | Purpose |
|---|---|---|
DeletionProtectionLabel |
orkestra.io/deletion-protection |
Marks resources the deletion-protection webhook blocks from being deleted |
StrictModeExemptKey |
orkestra.io/strict-mode-exempt |
Signals that a CRD has opted out of strict-mode; the strict-mode webhook allows label removal when present |
ManagedKey |
orkestra.orkspace.io/managed |
Identifies resources actively managed by Orkestra |
OrkestraOwner |
orkestra-owner |
Identifies the owning CR name |
AnnotationManagedBy |
orkestra.orkspace.io/managed-by |
Records which operator instance manages the resource |
AnnotationManagedSince |
orkestra.orkspace.io/managed-since |
Records when Orkestra first took ownership (write-once) |
FinalizerOrkestra |
orkestra.orkspace.io/finalizer |
Finalizer applied to CRs for cleanup hooks |
Quick usage
// Construct a Manager once per reconcile cycle
mgr := labels.NewManager(labels.Config{
DeletionProtectionEnabled: kat.IsDeletionProtectionEnabled(),
})
// Apply all label invariants in memory
mgr.EnsureManagedLabel(obj)
mgr.EnsureDeletionProtectionLabel(obj, shouldProtect)
mgr.EnsureStrictModeExemptLabel(obj, effectiveStrict)
// Caller persists to the API server
kube.PatchLabels(ctx, obj, gvr, serverLabels, obj.GetLabels())
Developer documentation
| I want to… | Go to |
|---|---|
| Understand every label and annotation constant and who uses them | 01 — Label reference |
| Understand how the Manager works and the two-phase protection removal | 02 — Manager |
Documentation
¶
Overview ¶
Package labels defines all label, annotation, and finalizer constants used by the Orkestra control plane. These identifiers form the contract between the runtime, admission webhooks, generators, CLI tooling, and developer-created workloads.
Nothing in this package performs logic — it only provides:
- stable label keys
- stable annotation keys
- stable finalizer keys
- helpers for constructing label sets
- selectors used by the admission webhooks
This package is intentionally dependency‑free and safe to import from any layer of the system (runtime, CLI, generators, komposers, motifs, etc.).
Package labels provides a stateless label and annotation manager for any Kubernetes object that implements the domain.Object interface.
Responsibilities ¶
The Manager answers one question per reconcile cycle: given the current Katalog configuration, what labels should this object carry? It then applies the answer in memory. The caller is responsible for persisting the result to the API server (e.g., via kube.PatchLabels).
What the Manager owns ¶
- Manager.EnsureManagedLabel — adds "orkestra.orkspace.io/managed: true" to identify Orkestra-owned resources.
- Manager.EnsureManagedAnnotations — adds "managed-by" and "managed-since" annotations for audit and ownership tracking.
- Manager.EnsureDeletionProtectionLabel — adds or removes the "orkestra.io/deletion-protection: true" label based on the CRD's effective protection setting.
- Manager.EnsureStrictModeExemptLabel — adds or removes the "orkestra.io/strict-mode-exempt: true" label based on whether the CRD has opted out of strict-mode enforcement.
What the Manager does not own ¶
The Manager performs no API calls and imports no Orkestra internal packages (katalog, reconciler, etc.). All configuration is passed at construction time via Config. This keeps the package safe to import from any layer.
Threading ¶
Manager is safe to construct per reconcile cycle (it holds no mutable state). Sharing a Manager across goroutines is also safe because all exported methods are pure transformations on the object they receive.
Index ¶
- Constants
- func DeletionProtectionSelector() *metav1.LabelSelector
- func OrkestraBaseLabels() map[string]string
- func OrkestraResourceLabels() map[string]string
- func OrkestraResourceSelector() *metav1.LabelSelector
- func WithDeletionProtection(m map[string]string) map[string]string
- type Config
- type Manager
- func (m *Manager) EnsureDeletionProtectionLabel(obj domain.Object, shouldHave bool) bool
- func (m *Manager) EnsureManagedAnnotations(obj domain.Object, operatorName string) bool
- func (m *Manager) EnsureManagedLabel(obj domain.Object) bool
- func (m *Manager) EnsureStrictModeExemptLabel(obj domain.Object, strictModeEnabled bool) bool
- func (m *Manager) GetDeletionProtectionLabel() string
- func (m *Manager) GetManagedByAnnotation() string
- func (m *Manager) GetManagedLabel() string
- func (m *Manager) GetManagedSinceAnnotation() string
- func (m *Manager) GetStrictModeExemptLabel() string
- func (m *Manager) IsDeletionProtectionEnabled() bool
- func (m *Manager) IsStandalone() bool
Constants ¶
const ( DeletionProtectionLabel = "orkestra.io/deletion-protection" // DeletionProtectionValue is the label value that enables protection. DeletionProtectionValue = "true" // StrictModeExemptKey is the label that exempts a resource from strict‑mode // enforcement. When present with value "true", the resource's deletion‑protection // label can be removed even if strictMode is enabled. StrictModeExemptKey = "orkestra.io/strict-mode-exempt" StrictModeExemptValue = "true" )
DeletionProtectionLabel marks resources that must not be deleted. Any object carrying:
orkestra.io/deletion-protection=true
will be matched by the deletion‑protection admission webhook. This protects both Orkestra control‑plane resources and developer‑opt‑in resources.
const ( ManagedKey = "orkestra.orkspace.io/managed" // ManagedValue is always "true". ManagedValue = "true" // OrkestraOwner identifies which CR owns a generated resource. Used by // reconcile loops to determine whether a resource should be updated or deleted. OrkestraOwner = "orkestra-owner" // LabelCreatedBy identifies the creator of a resource. LabelCreatedBy = "app.kubernetes.io/createdBy" // CreatedByOrkDoctor marks resources created by orkdoctor. These are excluded // from cleanup logic even if ownership matches. CreatedByOrkDoctor = "orkdoctor" // AnnotationManagedBy identifies which Orkestra operator instance manages a CR. AnnotationManagedBy = "orkestra.orkspace.io/managed-by" // AnnotationManagedSince records when Orkestra first took ownership of a CR. AnnotationManagedSince = "orkestra.orkspace.io/managed-since" // FinalizerOrkestra ensures cleanup runs before a CR is removed. FinalizerOrkestra = "orkestra.orkspace.io/finalizer" )
Managed marks resources that Orkestra actively manages.
Variables ¶
This section is empty.
Functions ¶
func DeletionProtectionSelector ¶ added in v0.4.1
func DeletionProtectionSelector() *metav1.LabelSelector
DeletionProtectionSelector returns a LabelSelector matching only the deletion‑protection label. Used when constructing webhook configurations.
func OrkestraBaseLabels ¶ added in v0.4.1
OrkestraBaseLabels returns a copy of the standard Orkestra control‑plane labels. Useful for generators and CLI commands that do not load Konfig.
func OrkestraResourceLabels ¶ added in v0.4.1
OrkestraResourceLabels returns the internal label map used for control‑plane resources. Callers must treat the returned map as read‑only.
func OrkestraResourceSelector ¶ added in v0.4.1
func OrkestraResourceSelector() *metav1.LabelSelector
OrkestraResourceSelector returns the selector for Orkestra control‑plane resources.
Types ¶
type Config ¶ added in v0.5.2
type Config struct {
// Standalone disables finalizer management. Set this when there is no
// runtime reconciler to process finalizers (e.g., gateway-only mode).
Standalone bool
// DeletionProtectionEnabled mirrors the global
// security.deletionProtection.enabled setting from the Katalog. When true,
// [Manager.EnsureDeletionProtectionLabel] may add the protection label.
DeletionProtectionEnabled bool
}
Config holds the configuration for a Manager.
type Manager ¶ added in v0.5.2
type Manager struct {
// contains filtered or unexported fields
}
Manager handles label and annotation mutations on domain objects. It is configuration-driven and stateless between calls.
func NewManager ¶ added in v0.5.2
NewManager constructs a Manager with the given configuration. All label and annotation key constants are resolved at construction time, so callers pay that cost once per reconcile cycle rather than per call.
func (*Manager) EnsureDeletionProtectionLabel ¶ added in v0.5.2
EnsureDeletionProtectionLabel reconciles the deletion-protection label on obj to match the desired state expressed by shouldHave.
- shouldHave = true → label is added: orkestra.io/deletion-protection = "true"
- shouldHave = false → label is removed: key is deleted from the label map
The typical caller logic for shouldHave is:
shouldHave = katalog.IsDeletionProtectionEnabled() && crd.ShouldProtectCRs()
Returns true if the label map was modified; false if it was already in the desired state. The caller must persist any change via kube.PatchLabels.
Note: removing this label while strict mode is active will be blocked by the strict-mode admission webhook. See [EnsureStrictModeExemptLabel] for how the reconciler handles the two-phase transition safely.
func (*Manager) EnsureManagedAnnotations ¶ added in v0.5.2
EnsureManagedAnnotations adds the standard Orkestra management annotations to obj if they are absent or empty.
Annotations applied:
- orkestra.orkspace.io/managed-by: <operatorName>
- orkestra.orkspace.io/managed-since: <UTC RFC 3339 timestamp>
Existing values are never overwritten — the managed-since timestamp records the first time Orkestra took ownership and must not drift on subsequent reconciles.
Returns true if any annotation was added; false if both were already present. The caller must persist any change via kube.PatchAnnotations.
func (*Manager) EnsureManagedLabel ¶ added in v0.5.2
EnsureManagedLabel adds the standard Orkestra ownership label to obj if it is missing or has the wrong value.
Label applied: orkestra.orkspace.io/managed = "true"
Returns true if the label was absent and has been added; false if it was already present with the correct value (no mutation occurred).
The caller must persist any change via kube.PatchLabels.
func (*Manager) EnsureStrictModeExemptLabel ¶ added in v0.5.3
EnsureStrictModeExemptLabel reconciles the strict-mode exemption label on obj to match the effective strict-mode state for this CRD.
- strictModeEnabled = true → label is removed: key is deleted from the label map
- strictModeEnabled = false → label is added: orkestra.io/strict-mode-exempt = "true"
The exemption label signals to the strict-mode admission webhook that this resource is allowed to have its deletion-protection label removed. It is added when a CRD declares strictMode: false in its per-CRD deletionProtection override, overriding the global strictMode setting.
Two-phase removal: when the reconciler is transitioning a resource from protected to unprotected (removing deletion-protection), it must keep the exemption label present in the same patch so the webhook allows the UPDATE. Once deletion-protection is gone the webhook objectSelector no longer matches and the exemption label can be removed freely on the next cycle. The GenericReconciler handles this automatically — callers of this method should not need to think about it.
Returns true if the label map was modified; false if it was already correct. The caller must persist any change via kube.PatchLabels.
Source Files