Lynq
GitHub stars

API Reference ​

Lynq adds three Custom Resource Definitions to your cluster.

CRDAPI GroupPurpose
LynqHuboperator.lynq.sh/v1Database connection + sync configuration
LynqFormoperator.lynq.sh/v1Resource blueprint (what to create per active row)
LynqNodeoperator.lynq.sh/v1Instance for one row × one form; tracks reconciliation status

Naming convention: LynqNode CRs follow {uid}-{form-name}. A hub with 3 active rows and 2 forms creates 6 LynqNodes: acme-web-app, acme-worker, beta-web-app, beta-worker, corp-web-app, corp-worker.

Common Types ​

Duration ​

String with unit suffix. Pattern: ^\d+(s|m|h)$.

Examples: 30s, 1m, 2h

CreationPolicy ​

ValueBehavior
WhenNeeded (default)Create, then re-apply only when the rendered spec changes (annotation-based skip) or during periodic drift-correction
OnceCreate once; never update even if spec changes

DeletionPolicy ​

ValueBehavior
Delete (default)Set ownerReference → Kubernetes GC removes resource when LynqNode is deleted
RetainLabel-based tracking only (no ownerReference) → resource stays after LynqNode deletion

DeletionPolicy is evaluated at creation time. The tracking mechanism (ownerReference vs labels) is set when the resource is first created.

ConflictPolicy ​

ValueBehavior
Stuck (default)Stop reconciliation on SSA field-manager conflict; mark LynqNode Degraded
ForceApply with force=true; take ownership from other field managers

PatchStrategy ​

ValueBehavior
apply (default)Server-Side Apply (SSA) — field-manager-aware, preserves other controllers' fields
mergeStrategic merge patch — preserves unspecified fields
replaceFull replacement — removes fields not in the template

Labels Reference ​

On LynqNode CRs (set by hub controller) ​

LabelValue
lynq.sh/hubHub name
lynq.sh/uidRow UID

On managed resources (set by LynqNode controller) ​

LabelSet whenValue
lynq.sh/nodeCross-namespace, Retain policy, or Namespace resourcesLynqNode name
lynq.sh/node-namespacePaired with lynq.sh/nodeLynqNode namespace
lynq.sh/orphanedResource removed from template or LynqNode deleted (Retain)"true"

Annotations on managed resources ​

AnnotationValuePurpose
lynq.sh/deletion-policy"Delete" or "Retain"Stored at creation; used during orphan cleanup
lynq.sh/created-once"true"Marks resources created with creationPolicy: Once
lynq.sh/orphaned-atRFC3339 timestampWhen orphaned
lynq.sh/orphaned-reason"RemovedFromTemplate" or "LynqNodeDeleted"Why orphaned

kubectl Quick Reference ​

Listing resources ​

bash
kubectl get lynqhubs -n lynq-system
kubectl get lynqforms -n lynq-system
kubectl get lynqnodes -n lynq-system

# All namespaces
kubectl get lynqnodes -A

# Wide output (shows more columns)
kubectl get lynqnodes -A -o wide

Checking status ​

bash
# Hub sync status
kubectl get lynqhub <name> -o jsonpath='{.status}'

# Node readiness
kubectl get lynqnode <name> -o jsonpath='{.status.readyResources}/{.status.desiredResources}'

# Node conditions
kubectl get lynqnode <name> -o jsonpath='{range .status.conditions[*]}{.type}: {.status} ({.reason}){"\n"}{end}'

# Applied resources list
kubectl get lynqnode <name> -o jsonpath='{.status.appliedResources}'

Querying by labels ​

bash
# Resources managed by a specific node
kubectl get all -l lynq.sh/node=<lynqnode-name>

# Orphaned resources cluster-wide
kubectl get all -A -l lynq.sh/orphaned=true

# Nodes from a specific hub
kubectl get lynqnodes -l lynq.sh/hub=<hub-name>

Operations ​

bash
# Force reconciliation
kubectl annotate lynqnode <name> lynq.sh/force-reconcile=$(date +%s) --overwrite

# Describe (shows events)
kubectl describe lynqnode <name>

# Custom columns output
kubectl get lynqnodes -o custom-columns='NAME:.metadata.name,READY:.status.readyResources,DESIRED:.status.desiredResources,FAILED:.status.failedResources'

# JSON for scripting
kubectl get lynqnodes -o json | jq '.items[] | {name: .metadata.name, ready: .status.readyResources}'

See Also ​