Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

diff

Show the difference between rendered manifests and the current cluster state.

Synopsis

nyl diff [OPTIONS] <FILE>

Description

The diff command renders manifests, compares them with live cluster state, and prints changes. For shared rendering behavior and namespace resolution details, see Rendering Pipeline.

Arguments

  • <FILE> - Path to the manifest file to diff (required)

Options

Common Options

  • --only-source-kind <KIND> - Filter top-level resources by kind (e.g., ConfigMap, Deployment) or by apiVersion/kind (e.g., apps/v1/Deployment) before expansion.
  • --only-kind <KIND,...> - Filter final rendered manifests to only include specific kinds (post-render).
  • --exclude-kind <KIND,...> - Filter final rendered manifests to exclude specific kinds (post-render, mutually exclusive with --only-kind).
  • -p, --profile <PROFILE> - Profile to use for rendering. If omitted, Nyl tries default; if profiles exist but default is missing, diff fails with an error.
  • --max-depth <MAX_DEPTH> - Maximum evaluation depth for recursive resource expansion (default: 10)
  • --track-parent - Track parent resource information in annotations

Release Options

  • --name <NAME> - Release name (required if no NylRelease in file)
  • --namespace <NAMESPACE> - Release namespace (required if no NylRelease in file)

Cluster Options

  • --context <CONTEXT> - Kubernetes context to use

Diff Options

  • --summary - Show summary only (counts, no detailed diff)
  • --mode <MODE> - Diff mode: normalized (default) or raw
    • normalized: Uses server-side apply to filter server defaults (like kubectl diff)
    • raw: Compares raw manifests without server normalization
  • --append-release - Preview diff as if current manifests were merged with the previous deployed release

Examples

Basic Diff

# Show diff for a manifest file
nyl diff manifest.yaml

# Diff with specific profile
nyl diff -p production manifest.yaml

# Diff only top-level ConfigMap resources
nyl diff --only-source-kind ConfigMap manifest.yaml

# Diff only final rendered Deployments
nyl diff --only-kind Deployment manifest.yaml

Summary Mode

# Show only the summary
nyl diff --summary manifest.yaml

Diff Modes

# Normalized mode (default) - filters server defaults
nyl diff --mode normalized manifest.yaml

# Raw mode - shows all differences including server defaults
nyl diff --mode raw manifest.yaml

Release Management

# Diff with explicit release name
nyl diff --name my-release --namespace default manifest.yaml

# Use different Kubernetes context
nyl diff --context production manifest.yaml

Output

The diff command shows:

  • Green (+): Lines that will be added
  • Red (-): Lines that will be removed
  • Summary: Count of resources to create, update, or delete

Notes

  • Nyl processes single files only. Directory paths are not supported.
  • A NylRelease resource in the manifest provides release metadata automatically.
  • Normalized mode is recommended for most use cases as it matches kubectl diff behavior.
  • If no previous release state exists, diff still compares desired resources against live state but cannot determine prune candidates; a warning is shown and to delete remains incomplete.
  • See Rendering Pipeline for namespace resolution and filter semantics.