Introduction

Kustomize errors under the resources section are usually caused by path issues, invalid directory layout, or mixing old and new syntax patterns. The error message can look vague, but the failure is often deterministic once you inspect file structure carefully. This guide provides a repeatable debug workflow and a clean base-overlay setup.

Core Topic Sections

Understand what resources expects

In modern Kustomize, resources should point to files or directories that resolve to valid Kubernetes manifests. If a directory is listed, that directory should itself contain a valid kustomization.yaml.

Typical valid examples:

1. resources: ["deployment.yaml", "service.yaml"]
2. resources: ["../base"] where ../base contains its own kustomization.yaml

Typical invalid examples:

1. Wrong relative path from current kustomization.yaml location.
2. Directory listed without a nested kustomization.yaml.
3. Typo in file extension or file name.

Use a known-good base and overlay layout

A predictable directory tree prevents most path mistakes:

1app/
2  base/
3    deployment.yaml
4    service.yaml
5    kustomization.yaml
6  overlays/
7    dev/
8      kustomization.yaml

base/kustomization.yaml:

1apiVersion: kustomize.config.k8s.io/v1beta1
2kind: Kustomization
3resources:
4  - deployment.yaml
5  - service.yaml

overlays/dev/kustomization.yaml:

1apiVersion: kustomize.config.k8s.io/v1beta1
2kind: Kustomization
3resources:
4  - ../../base
5nameSuffix: -dev
6commonLabels:
7  env: dev

Build command:

kustomize build overlays/dev

Or with kubectl integration:

kubectl kustomize overlays/dev
kubectl apply -k overlays/dev

Debug path and file resolution quickly

When kustomize build fails, verify each path from the perspective of the file being executed, not your shell location assumption.

Useful checks:

pwd
ls -la overlays/dev
ls -la ../../base

Then validate individual manifests:

kubectl apply --dry-run=client -f base/deployment.yaml
kubectl apply --dry-run=client -f base/service.yaml

If single manifests are valid but Kustomize fails, the issue is almost always path resolution or Kustomization syntax.

Watch for deprecated patterns

Older docs may mention bases. Current Kustomize uses resources. Mixing versions across local binaries and CI can cause confusing errors.

Recommended checks:

kustomize version
kubectl version --client

Pin tool versions in CI and local dev containers to avoid environment-specific behavior.

Handle symlinks and remote paths carefully

Symlinked directories or remote references can behave differently depending on security flags and tool versions. If you suspect path traversal restrictions:

1. Replace symlink with real path temporarily.
2. Build with standalone kustomize and with kubectl kustomize.
3. Compare outputs and errors.

Use the simpler path first, then reintroduce indirection only if needed.

Keep overlays minimal and explicit

Overlays should declare only environment-specific differences. Avoid copying full base resources into overlays. Smaller overlays make path errors obvious and reduce merge conflicts.

Good overlay content usually includes:

1. Base reference in resources.
2. Patches for changed fields.
3. Optional name suffix and labels.

This keeps configuration readable and easier to review.

Verification before apply

Treat Kustomize output as build artifact. Always inspect generated manifests before cluster apply in production pipelines.

kustomize build overlays/dev > /tmp/dev.yaml
kubectl apply --dry-run=server -f /tmp/dev.yaml

This catches schema or reference issues early and protects cluster reliability.

Common Pitfalls

• Using relative paths that are correct from shell location but wrong from Kustomization file location.
• Listing a directory in resources that does not contain a valid kustomization.yaml.
• Mixing deprecated bases usage with current tool expectations.
• Relying on different local and CI Kustomize versions.
• Applying directly without validating generated output first.

Summary

• Most resources errors are path or structure problems, not Kubernetes API issues.
• Use a clear base-overlay layout where every referenced directory has a Kustomization file.
• Validate manifests and tool versions to isolate version-related confusion.
• Keep overlays small and explicit to reduce path mistakes.
• Build and dry-run generated YAML before deployment.