Kustomize Navigator
A Visual Studio Code extension that enhances your Kubernetes GitOps workflow by providing intelligent navigation between Kustomize YAML files.
See also: Helm Values Navigator — hover and go-to-definition for Helm .Values references, completions, and orphan diagnostics across environments.
Features
- Smart Navigation: Ctrl+click between Kustomize files; remote entries with a URI scheme (
https://, oci://, git::https://, …) open as links instead of bogus file paths (file:// resolves to a local path when used in resources)
- Back References: View which files reference the current file (hover on
apiVersion: line)
- Flux Support: Works with both standard Kustomize and Flux CD
- Flux cross-manifest links: Ctrl+click
sourceRef / chartRef / ArtifactGenerator sources entries to open the matching YAML in the repo (indexed by kind + metadata.name + namespace)
- Variable Highlighting: Highlights and validates Flux variable substitutions
- Intelligent Diagnostics: Identifies common configuration issues
- Comprehensive Patch Support: Full linking and highlighting for all patch formats (including deprecated ones for backward compatibility)
Quick Start
- Open a Kubernetes GitOps repository
- Use Ctrl+Click on any kustomization reference to navigate
- Hover over the
apiVersion: line to see which files reference the current file
- Hover over Flux variables for details and suggestions
Extension Settings
Key settings (see VS Code settings for all options):
kustomizeNavigator.highlightFluxVariables: Enable/disable Flux variable highlightingkustomizeNavigator.diagnostics.enabled: Toggle all diagnostic checkskustomizeNavigator.standardFluxVariables: List of standard Flux variables for autocompletionkustomizeNavigator.performance.enableFileSystemCache: Enable/disable file system operation caching (default: true)kustomizeNavigator.validateReferencePathCase: On Windows and macOS only, warn when YAML path spelling does not match on-disk names (would fail on a Linux / Flux checkout). On Linux this setting is ignored—the OS already enforces case. Uses realpath and a segment-by-segment directory check (default: true)
The extension supports all patch formats used in Kustomize and Flux:
Recommended (Current)
patches: Unified patch field supporting multiple formats:
- String format:
patches: [patch.yaml]
- Object with path:
patches: [{path: patch.yaml, target: {...}}]
- Inline patch:
patches: [{patch: |-..., target: {...}}]
Deprecated (Still Supported)
patchesStrategicMerge: Deprecated in Kustomize v5.0.0 (February 2023)
- Supported format:
patchesStrategicMerge: [patch.yaml]
- Use
patches field instead
patchesJson6902: Deprecated in Kustomize v5.0.0 (February 2023)
- Supported format:
patchesJson6902: [{path: patch.yaml, target: {...}}]
- Use
patches field instead
Note: All patch formats support clickable navigation links and hover information. The extension maintains backward compatibility with deprecated formats while recommending migration to the patches field.
Diagnostic Checks
The extension provides comprehensive validation for your Kubernetes and Flux configurations:
Kubernetes Checks
- Resource naming conventions
- Namespace requirements
- Image tag usage
- YAML formatting
Security Checks
- Privileged containers
- Host network usage
- Security context settings
Flux-specific Checks
- API version deprecation
- Recursive dependencies
- Variable substitution
- GitOps components
- Performance optimization
Each check can be individually enabled/disabled in settings.
Recent Changes
1.6.0 (2026-05-11)
- Multi-root workspace: all VS Code workspace folders are now scanned - no longer limited to the first folder.
- Cross-repo Flux links:
spec.path / patch / component links resolve against whichever workspace clone's origin matches GitRepository.spec.url, including clones in sibling directories or other workspace roots. Tooltip notes the resolved clone root for cross-repo links.
- Workspace git index: depth-1 scan under each workspace root; refreshed only on workspace-folder changes and
.git/config edits (not on every YAML save).
- Option A diagnostic: when a
GitRepository URL is known but no matching local clone exists, a Warning squiggle appears on sourceRef.name explaining why path links are absent.
- Hover path fix: Flux Kustomization reference hover resolves paths git-root-relative (aligned with Ctrl+click).
1.5.0 (2026-04-12)
- Flux foreign GitRepository:
spec.path / patch / component links open as local files only when sourceRef is a GitRepository and its spec.url matches this repo’s origin (same clone). Otherwise local links are omitted so paths are not resolved under the wrong tree. Remote https:// / oci:// / … links unchanged.
1.4.2 (2026-04-12)
- Remote URI detection: any
scheme:// reference (e.g. oci://, ssh://) and git::https://… are handled like https://; file:// is turned into a real filesystem path for the reference map
1.4.1 (2026-04-12)
- HTTP(S) coverage: defensive
resolveReference; reference map includes generators / transformers; Flux spec.components in the map when local; hovers match more fields, show remote URL hovers, and list components/config/CRDs/generators/transformers with correct links
1.4.0 (2026-04-12)
- Remote resources: URI entries in Kustomize and Flux open as links and are omitted from the local reference graph (see 1.4.2 for all
scheme:// types and file:// handling). Includes hovers and standard + Flux document links.
1.3.1 (2026-04-12)
- Path case validation: on Linux the link provider skips case checks entirely and the setting is documented as ignored there (no per-link branching; OS already case-sensitive)
1.3.0 (2026-04-12)
- Path case validation (Windows / macOS): warns when a Flux or Kustomize reference resolves case-insensitively but would fail on Linux / Flux; uses native
realpath plus a segment-by-segment directory check. Setting: kustomizeNavigator.validateReferencePathCase (default: true)
1.2.0 (2026-03-26)
- Flux cross-resource navigation: links from
Kustomization.spec.sourceRef, HelmRelease.spec.chartRef, and ArtifactGenerator.spec.sources[] to other manifests in the workspace when kind / name / namespace match (Artifact generators)
1.1.0 (2026-03-25)
- Build:
build.ps1 runs type-check, production webpack, and vsce package (.vsix in ./output)
- Dependencies: safe patch/minor updates (
glob, js-yaml, dev tooling); removed obsolete @types/glob (types ship with glob v10+)
- VS Code:
engines.vscode is ^1.85.0 so @vscode/vsce matches @types/vscode (the old >=1.0.0 range is rejected by vsce with current typings)
- Packaging: extension icon as
images/vscode-extension-icon.png; .vscodeignore excludes dev-only paths from the VSIX
- Docs: link to Helm Values Navigator in the intro
1.0.0 (2025-11-19)
- Release: First stable release with full Kustomize and Flux CD support
- Performance optimizations with intelligent caching (50-95% I/O reduction)
- Comprehensive patch format support and diagnostic checks
- VS Code engine requirement was
>=1.0.0 for broader compatibility (raised to ^1.85.0 in 1.1.0 for vsce/types alignment)
0.9.9 (2025-11-05)
- Simplified back reference display with underline decoration only
- Badge colors preserved (
[Kustomize] green, [Flux] red)
- Fixed duplicate hover messages for back references
0.9.8 (2025-11-05)
- Improved path normalization for back reference lookup
- Enhanced back reference visibility with underline styling
For complete version history, see CHANGELOG.md.
Known Issues
- Flux GitRepository path resolution (1.6.0): Local Ctrl+click targets for
spec.path / patches / components are resolved against whichever workspace clone's origin matches GitRepository.spec.url � either the clone containing the Flux YAML, or a sibling clone found at depth-1 under a workspace root. For OCIRepository, Bucket, HelmChart, etc., local path links are omitted (they reference a remote artifact, not a local tree). Remote URI strings (https://, oci://, �) still open as web links. If a GitRepository URL is known but no matching clone exists, a Warning diagnostic appears on sourceRef.name.
- May activate on YAML files without kustomization files
- Flux cross-manifest links only work when the target resource exists as YAML in the workspace; if
metadata.namespace is omitted on a reference, the referring object’s namespace is assumed (Flux convention). If the same kind + name exists in multiple namespaces and the reference is ambiguous, the link may not appear
Plans
- Multi-root / second clone: Implemented in 1.6.0. Workspace git scan depth is capped at 1 level below each root; add a deeper sub-repo as an explicit workspace folder if needed.
- Forge links: When the source is foreign, optional “open on GitHub/GitLab”
tree/ links using spec.url + spec.ref + path.
- Parser / back-refs: Align
getFluxResolvedReferences and related graph logic with the same source-repo rules as document links.
For details on performance optimizations, caching strategies, and implementation principles, see PERFORMANCE.md.
Building and packaging
From the repo root (PowerShell): .\build.ps1 installs dependencies if needed, runs tsc --noEmit, production webpack, and produces output\kustomize-navigator-<version>.vsix.
Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
License
This extension is licensed under the Apache 2.0.
