Core Concepts

Yamlr operates as the Kubernetes Configuration Resolution Plane. While traditional linters only inspect individual YAML files against static schemas, Yamlr evaluates the topological system integrity across your entire Kubernetes manifest graph.

Schema validations catch obvious syntax errors; relational misconfigurations are silent and account for the vast majority of Kubernetes deployment outages.

1. The ResourceGraph (Cross-Resource Topology)

Kubernetes resources depend on dynamic runtime bindings. Yamlr constructs an in-memory directed relational dependency graph before deployment:

• Service → Pod: Validates that spec.selector labels match real Pod template labels, preventing silent Ghost Services.
• Ingress → Service: Verifies that referenced backend Services exist, their namespaces align, and the target port matches an exposed Service port.
• ConfigMap / Secret → Pod: Verifies that required environment variables (valueFrom) and volume mounts exist.
• HPA → Deployment / StatefulSet: Verifies scale target references and ensures target metrics are valid.
• NetworkPolicy → Pod: Maps ingress/egress selector boundaries.
• PodDisruptionBudget → Pod: Validates disruption budgets against declared replica counts to prevent eviction deadlocks.

This cross-resource awareness enables precise blast radius calculation before changes reach the cluster.

2. Deterministic Risk Classification

Every diagnostic finding is categorized by impact and failure domain:

• Traffic Routing Faults: Dead service ports, misrouted Ingress hosts, unresolvable Gateway API routes.
• State & Dependency Failures: Missing Secrets, unmounted ConfigMaps, dangling PVC claims.
• API Version Drift: Deprecated APIs across Kubernetes versions 1.25 through 1.32.
• Security & Capability Violations: Privilege escalation, root execution, unconfined seccomp profiles.

3. Semantic DNA Integrity

To eliminate accidental drift or unintended mutations during automated healing:

• Yamlr computes a structural cryptographic fingerprint (Manifest DNA) of the Abstract Syntax Tree.
• Following remediation, Yamlr recalculates the DNA to verify that only the targeted misconfiguration was modified and that no unrelated semantic state changed.
• If any discrepancy is detected, the operation aborts immediately.

4. Concrete Syntax Tree (CST) Comment Preservation

Standard YAML serializers drop comments, shuffle key ordering, and destroy developer formatting.

Yamlr's native Concrete Syntax Tree (CST) engine:

• Preserves 100% of # comments and licensing headers.
• Maintains established indentation boundaries.
• Guarantees zero unnecessary diff churn in GitOps repositories.

5. Atomic Write-Ahead Log (WAL) Journaling

Before any byte is written to disk, Yamlr journals the exact file state to an atomic Write-Ahead Log in .yamlr/wal/.

• Reversible at any time via yamlr rollback [path].
• Safe for automated CI pipelines and pre-commit hooks.