/helm-validator

name: helm-validator
description: Validate, lint, audit, check Helm charts — Chart.yaml, templates, values.yaml, CRDs, schemas.

Helm Chart Validator & Analysis Toolkit

Overview

This skill provides a comprehensive validation and analysis workflow for Helm charts, combining Helm-native linting, template rendering, YAML validation, schema validation, CRD documentation lookup, and security best practices checking.

**IMPORTANT: This validator is read-only by default.** It analyzes charts and proposes improvements. Only modify files when the user explicitly asks to apply fixes.

Trigger Cases

Use this skill when one or more of these top cases apply:

• The user asks to validate, lint, check, test, or troubleshoot a Helm chart
• Helm templates fail to render, lint, or produce valid Kubernetes YAML
• A pre-deployment quality gate is needed (schema, dry-run, security checks)
• CRD resources are present and their spec fields must be verified against docs
• The user wants a severity-based validation report with proposed remediations

Trigger phrase examples:

• "Validate this Helm chart before release"
• "Why does `helm template` fail?"
• "Check this chart for Kubernetes and security issues"

Out of scope by default:

• New chart scaffolding or broad chart generation (use `helm-generator`)

Role Boundaries

• This skill validates and reports; it does not silently rewrite user files.
• It can propose concrete patches and apply them only when the user explicitly requests fixes.
• If execution constraints block a stage, it must continue with reachable stages and document the skip reason.

Execution Model

1. Run stages in order (1 through 10). 2. Keep going after stage-level failures to collect complete findings, unless rendering fails and no manifests exist. 3. If Stage 4 produces no manifests, mark Stages 5 to 9 as blocked and continue to Stage 10 reporting. 4. Treat Stage 8 as environment-dependent optional; treat Stage 9 and Stage 10 as mandatory when manifests exist. 5. For every skipped stage, record the exact tool/environment reason in the final summary table.

Quick Execution Modes

Mode A: Local Validation (no cluster required)

bash scripts/setup_tools.sh
bash scripts/validate_chart_structure.sh <chart-directory>
helm lint <chart-directory> --strict
helm template <release-name> <chart-directory> --values <values-file> --debug --output-dir ./rendered
find ./rendered -type f \( -name "*.yaml" -o -name "*.yml" \) -exec yamllint -c assets/.yamllint {} +
find ./rendered -type f \( -name "*.yaml" -o -name "*.yml" \) -exec kubeconform -summary -verbose {} +

Mode B: Full Validation (cluster available)

Run Mode A plus Stage 8 dry-run commands in this document.

Validation & Testing Workflow

Follow this sequential validation workflow. Each stage catches different types of issues:

Stage 1: Tool Check

Before starting validation, verify required tools are installed:

bash scripts/setup_tools.sh

Required tools:

• **helm**: Helm package manager for Kubernetes (v3+)
• **yamllint**: YAML syntax and style linting
• **kubeconform**: Kubernetes schema validation with CRD support
• **kubectl**: Cluster dry-run testing (optional but recommended)

Fallback policy for unavailable tools or environment constraints:

| Condition | Action | Stage status | |-----------|--------|--------------| | `helm` missing | Run Stage 2 only, then report Stages 3 to 9 as skipped/blocked | ⚠️ Warning | | `yamllint` missing | Use `yq` syntax checks if available; otherwise skip Stage 5 | ⚠️ Warning | | `kubeconform` missing | Skip Stage 7 and rely on Stage 6 CRD/manual checks | ⚠️ Warning | | `kubectl` missing or no kube-context | Skip Stage 8, continue with remaining stages | ⚠️ Warning | | No internet access for CRD docs | Use local CRD manifests and kubeconform output, mark doc lookup incomplete | ⚠️ Warning |

If tools are missing, provide installation instructions from `scripts/setup_tools.sh` output and continue with the fallback path above.

Stage 2: Helm Chart Structure Validation

Verify the chart follows the standard Helm directory structure:

bash scripts/validate_chart_structure.sh <chart-directory>

**Expected structure:**

mychart/
  Chart.yaml          # Chart metadata (required)
  values.yaml         # Default values (required)
  values.schema.json  # JSON Schema for values validation (optional)
  templates/          # Template directory (required)
    _helpers.tpl      # Template helpers (recommended)
    NOTES.txt         # Post-install notes (recommended)
    *.yaml            # Kubernetes manifest templates
  charts/             # Chart dependencies (optional)
  crds/               # Custom Resource Definitions (optional)
  .helmignore         # Files to ignore during packaging (optional)

**Common issues caught:**

• Missing required files (Chart.yaml, values.yaml, templates/)
• Invalid Chart.yaml syntax or missing required fields
• Malformed values.schema.json
• Incorrect file permissions

Stage 3: Helm Lint

Run Helm's built-in linter to catch chart-specific issues:

helm lint <chart-directory> --strict

**Optional flags:**

• `--values <values-file>`: Test with specific values
• `--set key=value`: Override specific values
• `--debug`: Show detailed error information

**Common issues caught:**

• Invalid Chart.yaml metadata
• Template syntax errors
• Missing or undefined values
• Deprecated Kubernetes API versions
• Chart best practice violations

**Auto-fix approach:**

• For template errors, identify the problematic template file
• Show the user the specific line causing issues
• Propose a patch/diff for the fix
• Apply fixes only if the user explicitly asks
• Re-run `helm lint` after fixes are applied

Stage 4: Template Rendering

Render templates locally to verify they produce valid YAML:

helm template <release-name> <chart-directory> \
  --values <values-file> \
  --debug \
  --output-dir ./r