Skip to main content

ADR: Management Policies for Resource Lifecycle Control

  • Status: Approved
  • Date: 2026-01-19
  • Updated: 2026-03-08
  • Decision Makers: Entigo RnD Team

Context​

Entigo Platform synchronizes resources between a control plane and workspace clusters. Resources can enter the platform from two directions:

  1. Top-down (full management): Resources defined in the control plane and provisioned to workspaces
  2. Bottom-up (observation): Resources created directly in the workspace (via GitOps, Helm, etc.) and mirrored to the control plane for visibility

The platform needs a mechanism to declare and enforce which direction applies to each resource, determining the source of truth and allowable operations.

Problem Statement​

Without explicit policy:

  • The platform cannot determine whether to overwrite a resource in the workspace or preserve it
  • Users have no way to indicate "this resource is managed elsewhere, just observe it"
  • Cloud resources could be accidentally deleted if the platform assumes full ownership of externally created resources

Decision​

Management Policy Label​

Use the label entigo.com/management-policy to instruct the platform on how to manage each resource.

ValueSource of TruthPlatform Behavior
full (default, implicit)Control PlaneFull lifecycle: create, update, delete
observedWorkspaceRead-only: mirror spec and status to control plane

Key design choice:

  • full is the default at the control plane level. The label does not need to be explicitly set for fully managed resources at the control plane. When a resource is synced to the workspace from the control plane, the full lable is set at workspace resources.
  • observed is the default at the workspace level. If the lable is not explicitly set to full, observed management policy is assumed and the resource status will be mirrored to the control plane.

The management policy is a Kubernetes-only concept — it is not propagated to cloud resource tags. See Cloud Resource Tagging ADR for the cloud tagging strategy.

Syncer Agent Responsibilities​

The Syncer agent is responsible for labeling resources when the label is not already set:

  • Full management: Set entigo.com/management-policy=full on the managed resource in the Workspace (making it explicit at the workspace level for other tools to see)
  • Observation: Set entigo.com/management-policy=observed on the resource in the Platform that originate from the workspace

Status Matrix​

Label in the Workspace takes precedence over a label set to a resource in the Platform.

Platform resource labelWorkspace resource labelBehaviourNotes
anymanagement-policy=fullfullWorkspace explicitly requests full management
anymanagement-policy=observedobserveWorkspace explicitly requests observe only
anyNo label (steady-state)observeAfter migration: unlabeled resources default to observe
management-policy=fullnone (doesn't exist)fullPlatform provisions resource with full management
no labelnone (doesn't exist)fullPlatform provisions resource with full management
management-policy=observednone (doesn't exist)orphanedPlatform expects resource but it doesn't exist; don't provision

Alternatives Considered​

Alternative 1: Boolean managed Flag​

Approach: A simple boolean label entigo.com/managed: true|false.

Pros:

  • Simpler — binary choice

Cons:

  • Does not express directionality (who is source of truth)
  • false is ambiguous — does it mean "ignore" or "observe"?

Rejected: We need to distinguish between "fully managed by the platform" and "observed but managed elsewhere."

Consequences​

Positive​

  1. Clear ownership — Each resource has an unambiguous source of truth
  2. Safe observation — Observed resources cannot be accidentally modified or deleted through the platform control plane
  3. Infralib upgrade path — Customers can upgrade form OSS Infralib environment to full Platform without having to redeploy

Negative​

  1. Migration complexity — Transitioning a resource from observed to full requires careful coordination (remove observed tag, ensure platform has the correct desired state)
  2. Orphaned state — If a resource is marked as observed at the platform level but doesn't exist in the workspace, it enters an orphaned state that requires manual resolution

References​