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:

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 ./rendered

Options to consider:

• --values values.yaml: Use specific values file
• --set key=value: Override individual values
• --show-only templates/deployment.yaml: Render specific template
• --validate: Validate against Kubernetes OpenAPI schema
• --include-crds: Include CRDs in rendered output
• --is-upgrade: Simulate upgrade scenario
• --kube-version 1.28.0: Target specific Kubernetes version

Common issues caught:

• Template syntax errors (Go template issues)
• Undefined variables or values
• Type mismatches (string vs. integer)
• Missing required values
• Logic errors in conditionals or loops
• Incorrect indentation in nested templates

For template errors:

• Identify the template file and line number
• Check if values are properly defined in values.yaml
• Verify template function usage (quote, required, default, include, etc.)
• Test with different value combinations

Stage 5: YAML Syntax Validation

Validate YAML syntax and formatting of rendered templates:

find ./rendered -type f \\( -name "*.yaml" -o -name "*.yml" \\) \\
  -exec yamllint -c assets/.yamllint {} +

Common issues caught:

• Indentation errors (tabs vs spaces)
• Trailing whitespace
• Line length violations
• Syntax errors
• Duplicate keys
• Document start/end markers

Auto-fix approach:

• For simple issues (indentation, trailing spaces), propose fixes using the Edit tool
• For template-generated issues, fix the source template, not rendered output
• Always show the user what will be changed before applying fixes

Stage 6: CRD Detection and Documentation Lookup

Before schema validation, detect if the chart contains or renders Custom Resource Definitions:

# Check crds/ directory
if [ -d <chart-directory>/crds ]; then
  find <chart-directory>/crds -type f \\( -name "*.yaml" -o -name "*.yml" \\) \\
    -exec bash scripts/detect_crd_wrapper.sh {} +
fi

# Check rendered templates
find ./rendered -type f \\( -name "*.yaml" -o -name "*.yml" \\) \\
  -exec bash scripts/detect_crd_wrapper.sh {} +

The script outputs JSON with resource information:

[
  {
    "kind": "Certificate",
    "apiVersion": "cert-manager.io/v1",
    "group": "cert-manager.io",
    "version": "v1",
    "isCRD": true,
    "name": "example-cert"
  }
]

For each detected CRD:

1. Try context7 MCP first (preferred):

   Use mcp__context7__resolve-library-id with the CRD project name
   Example: "cert-manager" for cert-manager.io CRDs
            "prometheus-operator" for monitoring.coreos.com CRDs
            "istio" for networking.istio.io CRDs
   
   Then use mcp__context7__query-docs with:
   - libraryId from resolve step
   - query: The CRD kind and relevant features (e.g., "Certificate spec required fields")
   

2. Fallback to web.search_query (web search) if Context7 fails:

   Search query pattern:
   "<kind>" "<group>" kubernetes CRD "<version>" documentation spec
   
   Example:
   "Certificate" "cert-manager.io" kubernetes CRD "v1" documentation spec
   "Prometheus" "monitoring.coreos.com" kubernetes CRD "v1" documentation spec
   

3. Extract key information:

   • Required fields in spec
   • Field types and validation rules
   • Examples from documentation
   • Version-specific changes or deprecations
   • Common configuration patterns

Why this matters: CRDs have custom schemas not available in standard Kubernetes validation tools. Understanding the CRD's spec requirements prevents validation errors and ensures correct resource configuration.

Stage 7: Schema Validation

Validate rendered templates against Kubernetes schemas:

find ./rendered -type f \\( -name "*.yaml" -o -name "*.yml" \\) -exec \\
  kubeconform \\
    -schema-location default \\
    -schema-location 'https://raw.githubusercontent.com/datreeio/CRDs-catalog/main/{{.Group}}/{{.ResourceKind}}_{{.ResourceAPIVersion}}.json' \\
    -summary \\
    -verbose \\
    {} +

Options to consider:

• Add -strict to reject unknown fields (recommended for production)
• Add -ignore-missing-schemas if working with custom/internal CRDs
• Add -kubernetes-version 1.28.0 to validate against specific K8s version
• Add -output json for programmatic processing

Common issues caught:

• Invalid apiVersion or kind
• Missing required fields
• Wrong field types
• Invalid enum values
• Unknown fields (with -strict)

For CRDs: If kubeconform reports "no schema found", this is expected. Use the documentation from Stage 6 to manually validate the spec fields.

Stage 7 success criteria (explicit):

• ✅ Passed: kubeconform exits 0, and no invalid resources are reported.
• ⚠️ Warning: only CRD schema-missing findings remain and Stage 6 documentation/manual verification is completed.
• ❌ Failed: any non-CRD schema violation, parse error, or unresolved required-field/type error.

Stage 8: Cluster Dry-Run (if available)

If kubectl is configured and cluster access is available, perform a server-side dry-run:

# Test installation
helm install <release-name> <chart-directory> \\
  --dry-run=server \\
  --debug \\
  --values <values-file>

# Test upgrade
helm upgrade <release-name> <chart-directory> \\
  --dry-run=server \\
  --debug \\
  --values <values-file>

If the Helm version does not support --dry-run=server, use --dry-run and document that only client-side Helm simulation was executed.

This catches:

• Admission controller rejections
• Policy violations (PSP, OPA, Kyverno, etc.)
• Resource quota violations
• Missing namespaces
• Invalid ConfigMap/Secret references
• Webhook validations
• Existing resource conflicts

If dry-run is not possible:

• Use kubectl with rendered templates: kubectl apply --dry-run=server -f ./rendered/
• Skip if no cluster access
• Document that cluster-specific validation was skipped

For updates to existing releases:

helm diff upgrade <release-name> <chart-directory>

This shows what would change, helping catch unintended modifications. (Requires helm-diff plugin)

Stage 8 success criteria (explicit):

• ✅ Passed: dry-run install and upgrade commands exit 0 with no admission/policy errors.
• ⚠️ Warning: stage skipped because kubectl/cluster context/access is unavailable, or only client-side fallback was possible.
• ❌ Failed: dry-run commands return non-zero due to admission webhooks, policy violations, namespace/quota errors, or reference errors.

Stage 9: Security Best Practices Check (MANDATORY)

IMPORTANT: This stage is MANDATORY. Analyze rendered templates for security best practices compliance.

Check rendered Deployment/Pod templates for:

1. Missing securityContext - Look for pods/containers without security settings:

   # Check if pod-level securityContext exists
   spec:
     securityContext:
       runAsNonRoot: true
       runAsUser: 1000
       fsGroup: 2000
   

2. Missing container securityContext - Each container should have:

   securityContext:
     allowPrivilegeEscalation: false
     readOnlyRootFilesystem: true
     runAsNonRoot: true
     capabilities:
       drop:
         - ALL
   

3. Missing resource limits/requests - Check for:

   resources:
     limits:
       cpu: "100m"
       memory: "128Mi"
     requests:
       cpu: "100m"
       memory: "128Mi"
   

4. Image tag issues - Flag if using :latest or no tag

5. Missing probes - Check for liveness/readiness probes

How to check: Read the rendered deployment YAML files and grep for these patterns:

# Check for securityContext
find ./rendered -type f \\( -name "*.yaml" -o -name "*.yml" \\) \\
  -exec grep -l "securityContext" {} +

# Check for resources
find ./rendered -type f \\( -name "*.yaml" -o -name "*.yml" \\) \\
  -exec grep -l "resources:" {} +

# Check for latest tag
find ./rendered -type f \\( -name "*.yaml" -o -name "*.yml" \\) \\
  -exec grep "image:.*:latest" {} +

Stage 10: Final Report (MANDATORY)

IMPORTANT: This stage is MANDATORY even if all validations pass. You MUST complete ALL of the following actions.

Default behavior is read-only. Do not modify files unless the user explicitly asks you to apply fixes.

Step 1: Load Reference Files (MANDATORY when warnings exist)

If ANY warnings, errors, or security issues were found, you MUST read:

Read references/helm_best_practices.md
Read references/k8s_best_practices.md

Use these references to provide context and recommendations for each issue found.

Step 2: Present Validation Summary

Always present a validation summary formatted as a table showing:

• Each validation stage executed (Stages 1-9)
• Status of each stage (✅ Passed, ⚠️ Warning, ❌ Failed)
• Count of issues found per stage

Example:

| Stage | Status | Issues |
|-------|--------|--------|
| 1. Tool Check | ✅ Passed | All tools available |
| 2. Structure | ⚠️ Warning | Missing: .helmignore, NOTES.txt |
| 3. Helm Lint |