Policies Guide

Lynq provides fine-grained control over resource lifecycle through four policy types. This guide explains each policy and when to use them.

Policy Types Overview

Policy	Controls	Default	Options
CreationPolicy	When resources are created	`WhenNeeded`	`Once`, `WhenNeeded`
DeletionPolicy	What happens on delete	`Delete`	`Delete`, `Retain`
ConflictPolicy	Ownership conflict handling	`Stuck`	`Stuck`, `Force`
PatchStrategy	How resources are updated	`apply`	`apply`, `merge`, `replace`

Practical Examples

See Policy Combinations Examples for detailed real-world scenarios with diagrams and step-by-step explanations.

Field-Level Control (v1.1.4+)

For fine-grained control over specific fields while using WhenNeeded, see Field-Level Ignore Control. This allows you to selectively ignore certain fields during reconciliation (e.g., HPA-managed replicas).

CreationPolicy

Controls when a resource is created or re-applied.

CreationPolicy Flow Visualizer

Delete or recreate resources to see how changes cascade through the system. Watch how finalizers ensure proper cleanup order. Use "Make Drift" to see how WhenNeeded (Watch) and Once (Static) resources behave differently.

🗄️

Database

External Data Source

Always Active

acme-corpacme.com✓ active

📋

LynqHub

Syncs every 30s

Active

📄

LynqForm

Template (v1)

Active

🏢

LynqNode

acme-corp (v1)

Active

⚙️

Cluster Resources

Kubernetes Objects

Deploymentacme-apiv1

👁️WatchActive

Serviceacme-svcv1

👁️WatchActive

Ingressacme-ingv1

👁️WatchActive

Jobacme-init-jobv1

🔒StaticRetainActive

👁️Watch Continuously syncs with LynqNode changes (CreationPolicy=WhenNeeded)

🔒Static No sync after creation (CreationPolicy=Once)

Event Log0

`WhenNeeded` (Default)

Resource is created and updated whenever the spec changes.

yaml

deployments:
  - id: app
    creationPolicy: WhenNeeded  # Default
    nameTemplate: "{{ .uid }}-app"
    spec:
      # ... deployment spec

Behavior:

✅ Creates resource if it doesn't exist
✅ Updates resource when spec changes
✅ Re-applies if manually deleted
✅ Maintains desired state continuously

Use when:

Resources should stay synchronized with templates
You want drift correction
Resource state should match database

Example: Application deployments, services, configmaps

Alternative: Use ignoreFields

If you need to update most fields but ignore specific ones (e.g., replicas controlled by HPA), consider using creationPolicy: WhenNeeded with ignoreFields instead of using Once. This provides more flexibility while still allowing selective field updates. See Field-Level Ignore Control for details.

`Once`

Resource is created only once and never updated, even if spec changes.

yaml

jobs:
  - id: init-job
    creationPolicy: Once
    nameTemplate: "{{ .uid }}-init"
    spec:
      apiVersion: batch/v1
      kind: Job
      spec:
        template:
          spec:
            containers:
            - name: init
              image: busybox
              command: ["sh", "-c", "echo Initializing node {{ .uid }}"]
            restartPolicy: Never

Behavior:

✅ Creates resource on first reconciliation
❌ Never updates resource, even if template changes
✅ Skips if resource already exists with lynq.sh/created-once annotation
✅ Re-creates if manually deleted

Use when:

One-time initialization tasks
Security resources that shouldn't change
Database migrations
Initial setup jobs

Example: Init Jobs, security configurations, bootstrap scripts

Annotation Added:

yaml

metadata:
  annotations:
    lynq.sh/created-once: "true"

DeletionPolicy

Controls what happens to resources when a LynqNode CR is deleted.

DeletionPolicy Flow Visualizer

Remove resources from LynqForm template or delete LynqNode to see how DeletionPolicy controls cleanup behavior. Compare Delete (automatic removal) vs Retain (keeps in cluster with orphan markers).

📄

LynqForm

Template Definition

📦Deployment🗑️Delete

💾PVC🔒Retain

Active

🏢

LynqNode

acme-corp

Active

⚙️

Cluster Resources

Kubernetes Objects

Deploymentacme-api

🗑️DeleteownerRefActive

PVCacme-data

🔒RetainlabelsActive

🗑️Delete Automatic cleanup via ownerReference (Kubernetes garbage collector)

🔒Retain Stays in cluster with orphan markers (label-based tracking, no ownerReference)

Event Log0

`Delete` (Default)

Resources are deleted when the Node is deleted via ownerReference.

yaml

deployments:
  - id: app
    deletionPolicy: Delete  # Default
    nameTemplate: "{{ .uid }}-app"
    spec:
      # ... deployment spec

Behavior:

✅ Removes resource from cluster automatically
✅ Uses ownerReference for garbage collection
✅ No orphaned resources

Use when:

Resources are node-specific and should be removed
You want complete cleanup
Resources have no value after node deletion

Example: Deployments, Services, ConfigMaps, Secrets

`Retain`

Resources are kept in the cluster and never have ownerReference set (use label-based tracking instead).

yaml

persistentVolumeClaims:
  - id: data-pvc
    deletionPolicy: Retain
    nameTemplate: "{{ .uid }}-data"
    spec:
      apiVersion: v1
      kind: PersistentVolumeClaim
      spec:
        accessModes: ["ReadWriteOnce"]
        resources:
          requests:
            storage: 10Gi

Behavior:

✅ No ownerReference (label-based tracking only)
✅ Resource stays in cluster even when Node is deleted
✅ Orphan labels added on deletion for identification
❌ No automatic cleanup by Kubernetes garbage collector
⚠️ Manual deletion required

Why no ownerReference?

Setting ownerReference would cause Kubernetes garbage collector to automatically delete the resource when the LynqNode CR is deleted, regardless of DeletionPolicy. The operator evaluates DeletionPolicy at resource creation time and uses label-based tracking (lynq.sh/node, lynq.sh/node-namespace) instead of ownerReference for Retain resources.

Use when:

Data must survive node deletion
Resources are expensive to recreate
Regulatory/compliance requirements
Debugging or forensics needed

Example: PersistentVolumeClaims, backup resources, audit logs

Orphan Markers:

When resources are retained (DeletionPolicy=Retain), they are automatically marked for easy identification:

yaml

metadata:
  labels:
    lynq.sh/orphaned: "true"  # Label for selector queries
  annotations:
    lynq.sh/orphaned-at: "2025-01-15T10:30:00Z"  # RFC3339 timestamp
    lynq.sh/orphaned-reason: "RemovedFromTemplate"  # or "LynqNodeDeleted"

Finding orphaned resources:

bash

# Find all orphaned resources
kubectl get all -A -l lynq.sh/orphaned=true

# Find resources orphaned due to template changes
kubectl get all -A -l lynq.sh/orphaned=true \
  -o jsonpath='{range .items[?(@.metadata.annotations.k8s-lynq\.org/orphaned-reason=="RemovedFromTemplate")]}{.kind}/{.metadata.name}{"\n"}{end}'

# Find resources orphaned due to node deletion
kubectl get all -A -l lynq.sh/orphaned=true \
  -o jsonpath='{range .items[?(@.metadata.annotations.k8s-lynq\.org/orphaned-reason=="LynqNodeDeleted")]}{.kind}/{.metadata.name}{"\n"}{end}'

Orphan Resource Cleanup

Dynamic Template Evolution

DeletionPolicy applies not only when a LynqNode CR is deleted, but also when resources are removed from the LynqForm.

How it works:

The operator tracks all applied resources in status.appliedResources with keys in format kind/namespace/name@id. During each reconciliation:

Detect Orphans: Compares current template resources with previously applied resources
Respect Policy: Applies the resource's deletionPolicy setting
Update Status: Tracks the new set of applied resources

Orphan Lifecycle - Re-adoption:

If you re-add a previously removed resource to the template, the operator automatically:

Removes all orphan markers (label + annotations)
Re-applies tracking labels or ownerReferences based on current DeletionPolicy
Resumes full management of the resource

This means you can safely experiment with template changes:

Remove a resource → It becomes orphaned (if Retain policy)
Re-add the same resource → It's cleanly re-adopted into management
No manual cleanup or label management needed!

Protecting LynqNodes from Cascade Deletion

Cascading deletions are immediate

Deleting a LynqHub or LynqForm cascades to all LynqNode CRs, which in turn deletes managed resources unless retention policies are set.

The Problem

Why This Works

With deletionPolicy: Retain:

At creation time: Resources are created with label-based tracking only (NO ownerReference)
Even if LynqHub/LynqForm is deleted → LynqNode CRs are deleted
When LynqNode CRs are deleted → Resources stay in cluster (no ownerReference = no automatic deletion)
Finalizer adds orphan labels for easy identification
Resources stay in the cluster because Kubernetes garbage collector never marks them for deletion

Key insight: DeletionPolicy is evaluated when creating resources, not when deleting them. This prevents the Kubernetes garbage collector from auto-deleting Retain resources.

When to Use This Strategy

✅ Use Retain when:

You need to delete/recreate LynqHub for migration
You're updating LynqForm with breaking changes
You're testing hub configuration changes
You have production LynqNodes that must not be interrupted
You're performing maintenance on operator components

❌ Don't use Retain when:

You actually want to clean up all node resources
Testing in development environments
You have backup/restore procedures in place

Alternative: Update Instead of Delete

Instead of deleting and recreating, consider:

bash

# ❌ DON'T: Delete and recreate (causes cascade deletion)
kubectl delete lynqhub my-hub
kubectl apply -f updated-hub.yaml

# ✅ DO: Update in place
kubectl apply -f updated-hub.yaml

ConflictPolicy

Controls what happens when a resource already exists with a different owner or field manager.

ConflictPolicy Flow Visualizer

Trigger ownership conflicts to see how ConflictPolicy handles conflicts. Compare Stuck (safe halt) vs Force (SSA force takeover).

📄

LynqForm

Template Definition

🌐Service⚠️Stuck

📦Deployment⚡Force

Active

🏢

LynqNode

acme-corp

Healthy

⚙️

Cluster Resources

Kubernetes Objects

Serviceacme-svc

⚠️StuckActive

Deploymentacme-api

⚡ForceActive

⚠️Stuck Halts reconciliation on conflict, marks LynqNode as Degraded (safe but requires manual fix)

⚡Force Uses SSA force=true to take ownership (aggressive, keeps reconciliation healthy)

Event Log0

`Stuck` (Default)

Reconciliation stops if ownership conflict is detected.

yaml

services:
  - id: app-svc
    conflictPolicy: Stuck  # Default
    nameTemplate: "{{ .uid }}-app"
    spec:
      # ... service spec

Behavior:

✅ Fails safe - doesn't overwrite existing resources
❌ Stops reconciliation on conflict
📢 Emits ResourceConflict event
⚠️ Marks Node as Degraded

Use when:

Safety is paramount
You want to investigate conflicts manually
Resources might be managed by other controllers
Default case (most conservative)

Example: Any resource where safety > availability

`Force`

Attempts to take ownership using Server-Side Apply with force=true.

yaml

deployments:
  - id: app
    conflictPolicy: Force
    nameTemplate: "{{ .uid }}-app"
    spec:
      # ... deployment spec

Behavior:

✅ Takes ownership forcefully
⚠️ May overwrite other controllers' changes
✅ Reconciliation continues
📢 Emits events on success/failure

Use when:

Lynq should be the source of truth
Conflicts are expected and acceptable
You're migrating from another management system
Availability > safety

Example: Resources exclusively managed by Lynq

Warning: This can override changes from other controllers or users!

PatchStrategy

Controls how resources are updated.

`apply` (Default - Server-Side Apply)

Uses Kubernetes Server-Side Apply for declarative updates.

yaml

deployments:
  - id: app
    patchStrategy: apply  # Default
    nameTemplate: "{{ .uid }}-app"
    spec:
      # ... deployment spec

Behavior:

✅ Declarative updates
✅ Conflict detection
✅ Preserves fields managed by other controllers
✅ Field-level ownership tracking
✅ Most efficient

Use when:

Multiple controllers manage the same resource
You want Kubernetes-native updates
Default case (best practice)

Field Manager: lynq

`merge` (Strategic Merge Patch)

Uses strategic merge patch for updates.

yaml

services:
  - id: app-svc
    patchStrategy: merge
    nameTemplate: "{{ .uid }}-app"
    spec:
      # ... service spec

Behavior:

✅ Merges changes with existing resource
✅ Preserves unspecified fields
⚠️ Less precise conflict detection
✅ Works with older Kubernetes versions

Use when:

Partial updates needed
Compatibility with legacy systems
Strategic merge semantics preferred

`replace` (Full Replacement)

Completely replaces the resource.

yaml

configMaps:
  - id: config
    patchStrategy: replace
    nameTemplate: "{{ .uid }}-config"
    spec:
      # ... configmap spec

Behavior:

⚠️ Replaces entire resource
❌ Loses fields not in template
✅ Guarantees exact match
✅ Handles resourceVersion conflicts

Use when:

Exact resource state required
No other controllers manage the resource
Complete replacement is intentional

Warning: This removes any fields not in your template!

Default Values

If policies are not specified, these defaults apply:

yaml

resources:
  - id: example
    creationPolicy: WhenNeeded  # ✅ Default
    deletionPolicy: Delete      # ✅ Default
    conflictPolicy: Stuck       # ✅ Default
    patchStrategy: apply        # ✅ Default

Policy Decision Matrix

Recommended policy combinations by resource type:

Resource Type	CreationPolicy	DeletionPolicy	ConflictPolicy	PatchStrategy
Deployment	WhenNeeded	Delete	Stuck	apply
Service	WhenNeeded	Delete	Stuck	apply
ConfigMap	WhenNeeded	Delete	Stuck	apply
Secret	WhenNeeded	Delete	Force	apply
PVC	Once	Retain	Stuck	apply
Init Job	Once	Delete	Force	replace
Namespace	WhenNeeded	Retain	Force	apply
Ingress	WhenNeeded	Delete	Stuck	apply

See Detailed Examples

For in-depth explanations with diagrams and scenarios, see Policy Combinations Examples.

Observability

Events

Policies trigger various events:

bash

# View Node events
kubectl describe lynqnode <lynqnode-name>

Conflict Events:

ResourceConflict: Resource conflict detected for default/acme-app (Kind: Deployment, Policy: Stuck)

Deletion Events:

LynqNodeDeleting: Deleting LynqNode 'acme-prod-template' (template: prod-template, uid: acme)
LynqNodeDeleted: Successfully deleted LynqNode 'acme-prod-template'

Metrics

promql

# Count apply attempts by policy
apply_attempts_total{kind="Deployment",result="success",conflict_policy="Stuck"}

# Track conflicts
lynqnode_conflicts_total{lynqnode="acme-web",conflict_policy="Stuck"}

# Failed reconciliations
lynqnode_reconcile_duration_seconds{result="error"}

See Monitoring Guide for complete metrics reference.

Troubleshooting

Conflict Stuck

Symptom: LynqNode shows Degraded condition

Cause: Resource exists with different owner

Solution:

Check who owns the resource:

bash

kubectl get <resource-type> <resource-name> -o yaml | grep -A5 managedFields

Either:
- Delete the conflicting resource
- Change to conflictPolicy: Force
- Use unique nameTemplate

Resource Not Updating

Symptom: Changes to template don't apply

Cause: creationPolicy: Once is set

Solution:

Change to creationPolicy: WhenNeeded, or
Delete the resource to force recreation, or
This is expected behavior for Once policy

Resource Not Deleted

Symptom: Resource remains after LynqNode deletion

Cause: deletionPolicy: Retain is set

Solution:

Manually delete: kubectl delete <resource-type> <resource-name>
This is expected behavior for Retain policy

Policies Guide

Policy Types Overview

CreationPolicy

CreationPolicy Flow Visualizer

`WhenNeeded` (Default)

`Once`

DeletionPolicy

DeletionPolicy Flow Visualizer

`Delete` (Default)

`Retain`

Orphan Resource Cleanup

Protecting LynqNodes from Cascade Deletion

The Problem

Recommended Solution: Use `Retain` DeletionPolicy

Why This Works

When to Use This Strategy

Alternative: Update Instead of Delete

ConflictPolicy

ConflictPolicy Flow Visualizer

`Stuck` (Default)

`Force`

PatchStrategy

`apply` (Default - Server-Side Apply)

`merge` (Strategic Merge Patch)

`replace` (Full Replacement)

Default Values

Policy Decision Matrix

Observability

Events

Metrics

Troubleshooting

Conflict Stuck

Resource Not Updating

Resource Not Deleted

See Also

Policies Guide ​

Policy Types Overview ​

CreationPolicy ​

CreationPolicy Flow Visualizer

WhenNeeded (Default) ​

Once ​

DeletionPolicy ​

DeletionPolicy Flow Visualizer

Delete (Default) ​

Retain ​

Orphan Resource Cleanup ​

Protecting LynqNodes from Cascade Deletion ​

The Problem ​

Recommended Solution: Use Retain DeletionPolicy ​

Why This Works ​

When to Use This Strategy ​

Alternative: Update Instead of Delete ​

ConflictPolicy ​

ConflictPolicy Flow Visualizer

Stuck (Default) ​

Force ​

PatchStrategy ​

apply (Default - Server-Side Apply) ​

merge (Strategic Merge Patch) ​

replace (Full Replacement) ​

Default Values ​

Policy Decision Matrix ​

Observability ​

Events ​

Metrics ​

Troubleshooting ​

Conflict Stuck ​

Resource Not Updating ​

Resource Not Deleted ​

See Also ​

Policies Guide

Policy Types Overview

CreationPolicy

`WhenNeeded` (Default)

`Once`

DeletionPolicy

`Delete` (Default)

`Retain`

Orphan Resource Cleanup

Protecting LynqNodes from Cascade Deletion

The Problem

Recommended Solution: Use `Retain` DeletionPolicy

Why This Works

When to Use This Strategy

Alternative: Update Instead of Delete

ConflictPolicy

`Stuck` (Default)

`Force`

PatchStrategy

`apply` (Default - Server-Side Apply)

`merge` (Strategic Merge Patch)

`replace` (Full Replacement)

Default Values

Policy Decision Matrix

Observability

Events

Metrics

Troubleshooting

Conflict Stuck

Resource Not Updating

Resource Not Deleted

See Also