Skip to main content
Mapagam

Linting and Validating Charts

1. Linting Chart Templates

Rule Description Severity Fix
apiVersion Must be present and valid Error Ensure apiVersion is set to a valid Kubernetes API version (e.g., v1, apps/v1)
kind Must be present and valid Error Set kind to a valid Kubernetes resource kind (e.g., Deployment, Service)
metadata.name Must be present and follow naming conventions Error Use lowercase alphanumeric characters, hyphens, and dots only (e.g., my-app)
spec.template.spec.containers Must define at least one container Error Add a container definition inside spec.template.spec.containers
spec.template.spec.containers.image Must be present and valid Error Specify a valid image name (e.g., nginx:latest)
spec.template.spec.containers.name Must be present and unique within the pod Error Assign a unique name to each container (e.g., web-server)
spec.template.spec.containers.resources Optional but recommended Warning Add resource limits and requests to prevent overconsumption

Example: Linting a Deployment Template

apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-app-deployment
spec:
  replicas: 3
  selector:
    matchLabels:
      app: my-app
  template:
    metadata:
      labels:
        app: my-app
    spec:
      containers:
      - name: web-server
        image: nginx:latest
        ports:
        - containerPort: 80

2. Checking Chart Structure

Check Description Command Notes
Chart.yaml Required file containing chart metadata helm lint . Must include name, version, appVersion, and apiVersion
templates/ Directory containing Kubernetes manifest templates helm template . Must contain valid Kubernetes YAML
values.yaml Default values for chart templates helm inspect values . Must be valid YAML with proper structure
charts/ Sub-charts directory (if any) ls charts/ Should only contain valid chart directories
README.md Documentation for the chart (optional but recommended) cat README.md Helps users understand chart usage and configuration

Example: Validating Chart Structure

helm lint .
helm template . --debug
helm inspect values .
Note: The helm lint command checks for common issues in chart structure and content.

3. Validating Chart.yaml

Field Description Required Example
apiVersion API version of the chart format Yes "v2"
name Name of the chart Yes "my-app"
version Chart version (semantic versioning) Yes "1.0.0"
appVersion Version of the application being deployed No "1.2.3"
description Short description of the chart No "A Helm chart for my application"
home Home page URL of the chart No "https://example.com"
sources Source URLs for the chart No ["https://github.com/example/my-app"]
maintainers List of chart maintainers No [{name: "John Doe", email: "john@example.com"}]
icon URL to an icon image No "https://example.com/icon.png"
keywords List of keywords for the chart No ["web", "application"]
annotations Arbitrary metadata for the chart No {"helm.sh/chart": "my-app-1.0.0"}

Example: Valid Chart.yaml

apiVersion: v2
name: my-app
version: 1.0.0
appVersion: "1.2.3"
description: A Helm chart for my application
home: https://example.com
sources:
  - https://github.com/example/my-app
maintainers:
  - name: John Doe
    email: john@example.com
icon: https://example.com/icon.png
keywords:
  - web
  - application
annotations:
  helm.sh/chart: my-app-1.0.0
Note: The apiVersion field must be set to v2 for charts using the latest Helm chart format.

4. Validating Template Syntax

Feature Description Example
Template Syntax Uses Go template syntax for rendering values {{ .Values.service.port }}
Functions Available functions for template logic {{ include "mychart.labels" . }}
Pipelines Chaining functions with pipes {{ .Values.service.name | upper }}

Example: Validating Template Syntax

apiVersion: v1
kind: Service
metadata:
  name: {{ include "mychart.fullname" . }}
spec:
  ports:
    - port: {{ .Values.service.port }}
      targetPort: {{ .Values.service.targetPort }}
Note: Helm templates must be valid Go templates. Use helm template to validate syntax.

5. Using Strict Linting

Example: Enabling strict linting in Helm

helm lint --strict my-chart
Flag Description Default
--strict Fail on warnings during linting false
Note: The --strict flag makes linting fail on any warning, ensuring charts meet the highest standards.
Warning: Using --strict may cause linting to fail on charts that are otherwise valid but have minor issues.

6. Checking Values Schema

Property Description Values Notes
values.schema Defines the schema for validating values.yaml schema.json Path to the JSON schema file used for validation
values.schemaVersion Version of the schema format 1.0, 2.0 Used to determine schema validation rules

Example: values.schema in Chart.yaml

apiVersion: v2
name: my-app
version: 1.0.0
schema: values.schema.json

Example: values.schema.json

{
  "type": "object",
  "properties": {
    "replicaCount": {
      "type": "integer",
      "minimum": 0
    },
    "image": {
      "type": "object",
      "properties": {
        "repository": {"type": "string"},
        "tag": {"type": "string"}
      },
      "required": ["repository", "tag"]
    }
  },
  "required": ["replicaCount", "image"]
}
Note: The schema file must be in the chart root directory and referenced correctly in Chart.yaml.
Warning: Invalid schema definitions can cause chart validation to fail even if values.yaml is valid.

7. Validating Kubernetes Resources

Resource Type Validation Rule Notes
Deployment spec.template.spec.containers[*].image Image must be a valid Docker image reference
Service spec.selector Must match labels in pod template
ConfigMap data All keys must be valid DNS labels
Secret data All values must be base64 encoded
PersistentVolumeClaim spec.accessModes Must include one of ReadWriteOnce, ReadOnlyMany, or ReadWriteMany

Example: Validating Deployment Image

apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx-deployment
spec:
  replicas: 3
  selector:
    matchLabels:
      app: nginx
  template:
    metadata:
      labels:
        app: nginx
    spec:
      containers:
      - name: nginx
        image: nginx:1.21.6
Note: Helm uses kubeval to validate Kubernetes resources against the OpenAPI schema.
Warning: Invalid image references will cause deployment failures at runtime.

8. Generating Dry-Run Output

Example: Helm Template Command

helm template my-release ./my-chart
Option Values Description
--debug false Enable debug output
--output-dir ./output Directory to output rendered templates
--set key=value Set values for the chart
--values config.yaml Custom values file to use
Note: The helm template command renders the chart without installing it, useful for inspecting generated manifests.
Warning: Ensure all dependencies are resolved before running helm template to avoid missing resources in the output.

9. Using Template Command

Option Values Description
--debug false Print the final chart to stdout instead of installing it
--dry-run false Simulate installation without actually installing
--namespace default Kubernetes namespace to install the chart into
--set key=value Set values on the command line (can be used multiple times)
--values values.yaml Specify values in a YAML file or a URL to a values file

Example: Template Chart

helm template my-release ./my-chart --namespace my-namespace --set image.tag=v1.2.3

10. Debugging Template Rendering

Example: Using helm template to debug rendering

helm template my-release ./my-chart --debug
Flag Description Usage
--debug Enables debug output, showing rendered templates helm template --debug <release> <chart>
--dry-run Simulates installation without actually installing helm template --dry-run <release> <chart>
Note: The --debug flag is useful for inspecting the rendered Kubernetes manifests before deploying.
Warning: --debug can output sensitive data, so use it carefully in production environments.

Debugging Workflow

  • Use helm template --debug to inspect rendered templates
  • Validate output with kubectl apply --dry-run=client -f <output>
  • Check for missing values or incorrect template syntax

11. Validating Dependencies

Property Values Description
dependencies array List of chart dependencies
alias string Alias for the dependency
condition string Condition to enable the dependency
tags array Tags to filter dependencies
version string Version constraint for the dependency
repository string Repository URL or alias
import-values array Import values from parent chart

Example: Validating Dependencies in Chart.yaml

apiVersion: v2
name: my-app
version: 1.0.0
dependencies:
  - name: redis
    version: "12.0.0"
    repository: "https://charts.bitnami.com/bitnami"
    condition: redis.enabled
    tags:
      - database
  - name: postgresql
    version: "10.1.0"
    repository: "@official"
    alias: db
    import-values:
      - from: parent
        to: postgresql
Note: Helm validates dependencies during helm dependency update and helm template commands.
Warning: Ensure all dependencies are compatible with the chart's API version and Kubernetes version.

Was this article helpful?

Related Cheat Sheets