Configuration Guide

This document serves as the definitive reference for .yamlr.yaml, the configuration file that controls the behavior of the Yamlr Safety Engine.

What is `.yamlr.yaml`?

.yamlr.yaml is a project-level configuration file that lives at the root of your repository. It allows teams to codify their architectural standards, silence false positives, and enforce security guardrails universally across the codebase.

By committing this file to version control, you guarantee that every engineer on your team—as well as your CI/CD pipelines—validates Kubernetes manifests using the exact same rule thresholds, ignored paths, and target cluster versions.

If you don't have one yet, you can generate a best-practices template by running:

bash
yamlr init

1. Rules Configuration

Customize global health thresholds and specific analyzer rule ignores.

yaml
rules:
  # The minimum health score (0-100) required to pass a CI/CD scan.
  # If the score drops below this, 'yamlr scan' returns exit code 1.
  threshold: 70

  # List of Rule IDs to completely ignore during scanning.
  # Use 'yamlr rules' in the CLI to see all available IDs.
  ignore:
    - "rules/no-latest-tag"
    - "rules/resource-limits"

2. Setting the Kubernetes Target Version

Force a specific Kubernetes cluster version for deterministic validation. Yamlr supports validating from K8s 1.9 through 1.35+.

Note that Yamlr uses a strict resolution priority to determine the target cluster version:

CLI Flag: --kube-version (Highest priority)
Environment Variable: YAMLR_KUBE_VERSION
Auto-Detect: Yamlr Pro attempts live kubectl/cluster detection.
Config File: kubernetes.version (See below)

yaml
kubernetes:
  version: "v1.31"  # Enforce 1.31 deprecation validation rules globally

3. Healing & Remediation Directives

Control the automated fixing behavior globally. Note that providing explicit CLI flags (like --harden) will override these settings.

yaml
healing:
  # Auto-inject context-aware CPU/Memory requests and limits.
  enforce_limits: true

  # Auto-inject standard Liveness and Readiness probes if missing.
  enforce_probes: false

  # Prevent 'latest' tag drift by pinning images.
  fix_tags: true

  # Provide an exit code 1 if any vulnerability exceeds this rating.
  risk_threshold: high

  # Automatically inject a namespace for resources missing 'metadata.namespace'.
  enforce_namespace: true

  # [PRO] Enable Cross-Resource Auto-Fixing.
  # Leverages the ResourceGraph for selector alignment and referenced stubs.
  fix_refs: true

4. Workspace Scoping (Ignore Files)

Prevent Yamlr from analyzing or repairing third-party manifests or backup files. Note that all ignore patterns are strictly relative to the workspace root for portability.

yaml
ignore:
  files:
    - "vendor/**"       # Ignore third-party Helm charts
    - "tests/*.yaml"    # Ignore local test fixtures
    - "**/*.bak"        # Ignore legacy backup files

5. Security & Zero-Trust Hardening (Pro)

Yamlr Pro allows you to enforce rigid security compliance boundaries, such as trusted container registries and host filesystem mounts.

yaml
security:
  # Enforce image registry allow-lists. Scans will fail if unapproved registries are used.
  trusted_registries:
    - "docker.io"
    - "quay.io"
    - "my-company.jfrog.io"

  # Whitelist paths for HostPath volumes to prevent sandbox escapes.
  allowed_host_paths:
    - "/var/log"

Environment Variables Reference

Yamlr can also be configured dynamically via environment variables, which is optimal for highly orchestrated CI/CD pipelines.

Variable	Description
`YAMLR_KUBE_VERSION`	Override target Kubernetes version (e.g. `1.31`)
`YAMLR_LICENSE_KEY`	[Pro] Enterprise license key for offline validation
`YAMLR_PRO`	[Pro] Force enable Enterprise mode features
`YAMLR_LOG_LEVEL`	Engine verbosity (`DEBUG`, `INFO`, `ERROR`)
`YAMLR_CATALOG_PATH`	Path to custom OpenAPI schema catalog storage
`YAMLR_PROVIDER`	Cluster provider hint (`eks`, `gke`, `minikube`, `auto`)
`NO_COLOR`	Disable ANSI colors in formatting output