• Validating Helm charts before packaging or deployment
• Debugging Helm template rendering errors
• Testing chart templates with different values
• Working with Custom Resource Definitions (CRDs) that need documentation
• Implementing or refactoring Helm template helpers (

  _helpers.tpl

  )
• Performing dry-run tests to catch admission controller errors
• Ensuring charts follow Helm and Kubernetes best practices
• Automating repetitive template patterns with Helm functions
• The user asks to "validate", "lint", "check", "test", or "improve" Helm charts
• Creating or optimizing template functions like

  include

  ,

  tpl

  ,

  required

  , etc.

bash scripts/setup_tools.sh

• 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)

bash scripts/validate_chart_structure.sh <chart-directory>

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)

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

helm lint <chart-directory> --strict

• --values <values-file>

  : Test with specific values

• --set key=value

  : Override specific values

• --debug

  : Show detailed error information

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

• For template errors, identify the problematic template file
• Show the user the specific line causing issues
• Propose fixes using the Edit tool
• Re-run

  helm lint

  after fixes

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

• --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

• 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

• 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

yamllint -c assets/.yamllint ./rendered/*.yaml

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

• 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

The script outputs JSON with resource information:
```json
[
  {
    "kind": "Certificate",
    "apiVersion": "cert-manager.io/v1",
    "group": "cert-manager.io",
    "version": "v1",
    "isCRD": true,
    "name": "example-cert"
  }
]

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__get-library-docs with:
   - context7CompatibleLibraryID from resolve step
   - topic: The CRD kind and relevant features (e.g., "Certificate spec")
   - tokens: 5000 (adjust based on need)

2. Fallback to WebSearch 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

kubeconform \
  -schema-location default \
  -schema-location 'https://raw.githubusercontent.com/datreeio/CRDs-catalog/main/{{.Group}}/{{.ResourceKind}}_{{.ResourceAPIVersion}}.json' \
  -summary \
  -verbose \
  ./rendered/*.yaml

• 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

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

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

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

2. Missing container securityContext - Each container should have:
   yaml

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

3. Missing resource limits/requests - Check for:
   yaml

   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

undefined

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

| Stage | Status | Issues |
|-------|--------|--------|
| 1. Tool Check | ✅ Passed | All tools available |
| 2. Structure | ⚠️ Warning | Missing: .helmignore, NOTES.txt |
| 3. Helm Lint | ✅ Passed | 0 errors |
| 4. Template Render | ✅ Passed | 5 templates rendered |
| 5. YAML Syntax | ✅ Passed | No yamllint errors |
| 6. CRD Detection | ✅ Passed | 1 CRD documented |
| 7. Schema Validation | ✅ Passed | All resources valid |
| 8. Dry-Run | ✅ Passed | No cluster errors |
| 9. Security Check | ⚠️ Warning | Missing securityContext |

• Template syntax errors
• Missing required fields
• Schema validation failures
• Dry-run failures

• Deprecated Kubernetes APIs
• Missing securityContext
• Missing resource limits/requests
• Using

  :latest

  image tag
• Missing recommended files (_helpers.tpl, .helmignore, NOTES.txt)

• Missing values.schema.json
• Missing README.md
• Optimization opportunities

• File path and line number (if applicable)
• Before/after code blocks
• Explanation of why this change is recommended

undefined

• If

  _helpers.tpl

  is missing → Recommend:

  bash scripts/generate_helpers.sh <chart>

• If

  .helmignore

  is missing → Recommend: Copy from

  assets/.helmignore

• If

  values.schema.json

  is missing → Recommend: Copy and customize from

  assets/values.schema.json

• If

  NOTES.txt

  is missing → Recommend: Create post-install notes template
• If

  README.md

  is missing → Recommend: Create chart documentation

• Errors: X
• Warnings: Y
• Info: Z

1. Review proposed changes above
2. Apply changes manually or use helm-generator skill
3. Re-run validation to confirm fixes

undefined

templates/_helpers.tpl

1. Chart name helper:

{{/*
Expand the name of the chart.
*/}}
{{- define "mychart.name" -}}
{{- default .Chart.Name .Values.nameOverride | trunc 63 | trimSuffix "-" }}
{{- end }}

1. Fullname helper:

{{/*
Create a default fully qualified app name.
*/}}
{{- define "mychart.fullname" -}}
{{- if .Values.fullnameOverride }}
{{- .Values.fullnameOverride | trunc 63 | trimSuffix "-" }}
{{- else }}
{{- $name := default .Chart.Name .Values.nameOverride }}
{{- if contains $name .Release.Name }}
{{- .Release.Name | trunc 63 | trimSuffix "-" }}
{{- else }}
{{- printf "%s-%s" .Release.Name $name | trunc 63 | trimSuffix "-" }}
{{- end }}
{{- end }}
{{- end }}

1. Chart reference helper:

{{/*
Create chart name and version as used by the chart label.
*/}}
{{- define "mychart.chart" -}}
{{- printf "%s-%s" .Chart.Name .Chart.Version | replace "+" "_" | trunc 63 | trimSuffix "-" }}
{{- end }}

1. Standard labels helper:

{{/*
Common labels
*/}}
{{- define "mychart.labels" -}}
helm.sh/chart: {{ include "mychart.chart" . }}
{{ include "mychart.selectorLabels" . }}
{{- if .Chart.AppVersion }}
app.kubernetes.io/version: {{ .Chart.AppVersion | quote }}
{{- end }}
app.kubernetes.io/managed-by: {{ .Release.Service }}
{{- end }}

1. Selector labels helper:

{{/*
Selector labels
*/}}
{{- define "mychart.selectorLabels" -}}
app.kubernetes.io/name: {{ include "mychart.name" . }}
app.kubernetes.io/instance: {{ .Release.Name }}
{{- end }}

1. ServiceAccount name helper:

{{/*
Create the name of the service account to use
*/}}
{{- define "mychart.serviceAccountName" -}}
{{- if .Values.serviceAccount.create }}
{{- default (include "mychart.fullname" .) .Values.serviceAccount.name }}
{{- else }}
{{- default "default" .Values.serviceAccount.name }}
{{- end }}
{{- end }}

• Values used in multiple templates
• Complex logic that's repeated
• Label sets that should be consistent
• Name generation patterns
• Conditional resource inclusion

1. required

   - Enforce required values:

apiVersion: v1
kind: Service
metadata:
  name: {{ required "A valid service name is required!" .Values.service.name }}

1. default

   - Provide fallback values:

replicas: {{ .Values.replicaCount | default 1 }}

1. quote

   - Safely quote string values:

env:
  - name: DATABASE_HOST
    value: {{ .Values.database.host | quote }}

1. include

   - Use helpers with pipeline:

metadata:
  labels:
    {{- include "mychart.labels" . | nindent 4 }}

1. tpl

   - Render strings as templates:

{{- tpl .Values.customConfig . }}

1. toYaml

   - Convert objects to YAML:

{{- with .Values.resources }}
resources:
  {{- toYaml . | nindent 2 }}
{{- end }}

1. fromYaml

   - Parse YAML strings:

{{- $config := .Values.configYaml | fromYaml }}

1. merge

   - Merge maps:

{{- $merged := merge .Values.override .Values.defaults }}

1. lookup

   - Query cluster resources (use carefully):

{{- $secret := lookup "v1" "Secret" .Release.Namespace "my-secret" }}
{{- if $secret }}
  # Secret exists, use it
{{- else }}
  # Create new secret
{{- end }}

1. Conditional resource creation:

{{- if .Values.ingress.enabled -}}
apiVersion: networking.k8s.io/v1
kind: Ingress

2. **Range over lists:**
```yaml
{{- range .Values.extraEnvVars }}
- name: {{ .name }}
  value: {{ .value | quote }}
{{- end }}

1. Range over maps:

{{- range $key, $value := .Values.configMap }}
{{ $key }}: {{ $value | quote }}
{{- end }}

1. With blocks for scoping:

{{- with .Values.nodeSelector }}
nodeSelector:
  {{- toYaml . | nindent 2 }}
{{- end }}

1. Named templates with custom context:

{{- include "mychart.container" (dict "root" . "container" .Values.mainContainer) }}

image.repository is the container image registry and name

image.tag overrides the image tag (default is chart appVersion)

undefined

1. Identify repetition:
   • Same label sets across resources
   • Repeated name generation logic
   • Common conditional patterns
2. Common helper patterns to recommend:
   • Chart name helper (

     .name

     )
   • Fullname helper (

     .fullname

     )
   • Chart version label (

     .chart

     )
   • Common labels (

     .labels

     )
   • Selector labels (

     .selectorLabels

     )
   • ServiceAccount name (

     .serviceAccountName

     )
3. When to recommend helpers:
   • Missing

     _helpers.tpl

     file
   • Repeated code patterns across templates
   • Inconsistent label usage
   • Long resource names that need truncation

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

• Chart structure and metadata
• Template conventions and patterns
• Values file organization
• Security best practices
• Resource limits and requests
• Common validation issues and fixes

Chart.yaml

charts/

1. Update dependencies:

helm dependency update <chart-directory>

1. List dependencies:

helm dependency list <chart-directory>

1. Validate dependencies:
   • Check that dependency versions are available
   • Verify dependency values are properly scoped
   • Test templates with dependency resources
2. Override dependency values:

undefined

• Run

  scripts/setup_tools.sh

  to check availability
• Provide installation instructions
• Skip optional stages but document what was skipped
• Continue with available tools

• Show the specific template file and line number
• Check if values are defined in values.yaml
• Verify template function syntax
• Test with simpler value combinations
• Use

  --debug

  flag for detailed error messages

• Fall back to client-side validation
• Use rendered templates with kubectl
• Skip cluster validation if no kubectl config
• Document limitations in validation report

• Document that documentation lookup failed
• Attempt validation with kubeconform CRD schemas
• Suggest manual CRD inspection:
  bash

  kubectl get crd <crd-name>.group -o yaml
  kubectl explain <kind>

• Continue to next stage even if one fails
• Collect all errors before presenting to user
• Prioritize fixing Helm lint errors first
• Then fix template errors
• Finally fix schema/validation errors

**Solutions:**

1. **Remove extended attributes:**
   ```bash
   # Remove all extended attributes from a file
   xattr -c /path/to/chart/Chart.yaml

   # Remove all extended attributes recursively from chart directory
   xattr -cr /path/to/chart/

1. Create files using shell commands instead:
   bash

   # Use cat with heredoc instead of direct file writes
   cat > Chart.yaml << 'EOF'
   apiVersion: v2
   name: mychart
   version: 0.1.0
   EOF

2. Copy from helm-created chart:
   bash

   # Create a fresh chart and copy structure
   helm create temp-chart
   cp -r temp-chart/* /path/to/your/chart/
   rm -rf temp-chart

helm create

cat > file << 'EOF'

1. Be clear and concise about what was found
2. Explain why issues matter (e.g., "This will cause pod creation to fail")
3. Provide context from Helm best practices when relevant
4. Group related issues (e.g., all missing helper issues together)
5. Use file:line references when available
6. Show confidence level for auto-fixes (high confidence = syntax, low = logic changes)
7. Always provide a summary after applying fixes including:
   • What was changed and why
   • File and line references for each fix
   • Total count of issues resolved
   • Final validation status
   • Any remaining warnings or recommendations

• Check for deprecated Kubernetes APIs
• Ensure Helm chart apiVersion is v2 (for Helm 3+)
• For CRDs, ensure the apiVersion matches what's in the cluster
• Use

  kubectl api-versions

  to list available API versions
• Reference version-specific documentation when available
• Set

  kubeVersion

  constraint in Chart.yaml if needed

1. Create test resources:

undefined

• Checks for required validation tools (helm, yamllint, kubeconform, kubectl)
• Provides installation instructions for missing tools
• Verifies versions of installed tools
• Usage:

  bash scripts/setup_tools.sh

• Validates Helm chart directory structure
• Checks for required files (Chart.yaml, values.yaml, templates/)
• Verifies file formats and syntax
• Usage:

  bash scripts/validate_chart_structure.sh <chart-directory>

• Wrapper script that handles Python dependency management
• Automatically creates temporary venv if PyYAML is not available
• Calls detect_crd.py to parse YAML files
• Usage:

  bash scripts/detect_crd_wrapper.sh <file.yaml>

• Parses YAML files to identify Custom Resource Definitions
• Extracts kind, apiVersion, group, and version information
• Outputs JSON for programmatic processing
• Requires PyYAML (handled automatically by wrapper script)
• Can be called directly:

  python3 scripts/detect_crd.py <file.yaml>

• Generates standard Helm helpers (_helpers.tpl) for a chart
• Creates fullname, labels, and selector helpers
• Usage:

  bash scripts/generate_helpers.sh <chart-directory>

• Comprehensive guide to Helm chart best practices
• Covers template patterns, helper functions, values structure
• Common validation issues and how to fix them
• Security and performance recommendations
• Load when providing context for Helm-specific issues

• Comprehensive guide to Kubernetes YAML best practices
• Covers metadata, labels, resource limits, security context
• Common validation issues and how to fix them
• Load when providing context for Kubernetes-specific issues

• Reference guide for Helm template functions
• Examples of all built-in functions
• Sprig function library reference
• Custom function patterns
• Load when implementing complex templates

• Standard .helmignore file for excluding files from packaging
• Pre-configured with common patterns

• Pre-configured yamllint rules for Kubernetes YAML
• Follows Kubernetes conventions (2-space indentation, line length, etc.)
• Can be customized per project
• Usage:

  yamllint -c assets/.yamllint <file.yaml>

• Example JSON Schema for values validation
• Can be copied and customized for specific charts
• Provides type safety and validation