Chart Format

Chart Format defines the structure and content requirements of a Helm chart, which is a package format used to define, install, and manage Kubernetes applications. It specifies the organization of files and metadata needed for Helm to correctly process the chart, render Kubernetes manifests, and support chart lifecycle operations such as packaging, versioning, and deployment.

Overview of Chart Format

A Helm chart is a directory with a specific hierarchical structure containing a collection of files and directories. These files define Kubernetes resources, configuration templates, default values, and metadata. The chart format ensures that Helm can reliably locate and interpret these components to generate Kubernetes manifests tailored for different deployment environments.

A chart directory typically includes:

• A mandatory Chart.yaml file describing the chart’s metadata.
• A templates/ directory containing Kubernetes manifest templates.
• An optional values.yaml file providing default configuration values.
• Other optional files such as README.md, LICENSE, and charts/ directory for dependencies.

Chart.yaml

Purpose

Chart.yaml is the core metadata file in the chart root directory. It must be a valid YAML file containing essential information that Helm uses to identify, categorize, and version the chart.

Required Fields

• apiVersion: Specifies the schema version of the chart format (e.g., v2).
• name: The chart’s name, unique within a repository.
• version: The chart version, following semantic versioning (semver).
• description: A brief summary of what the chart does.

Optional Fields

• type: Defines the chart type (e.g., application or library).
• keywords: An array of terms to aid in chart discovery.
• home: URL for the chart’s home page.
• sources: URLs to the source code or documentation.
• maintainers: List of maintainers with name and contact details.
• icon: URL or path to an icon image representing the chart.
• appVersion: The version of the application contained within the chart.
• dependencies: Specifies other charts required as dependencies.

Example:

apiVersion: v2
name: myapp
description: A Helm chart for Kubernetes
type: application
version: 1.2.3
appVersion: 1.16.0
keywords:
  - web
  - backend
maintainers:
  - name: Jane Doe
    email: jane@example.com
sources:
  - https://github.com/example/myapp
icon: https://example.com/icon.png
dependencies:
  - name: redis
    version: 14.4.0
    repository: https://charts.bitnami.com/bitnami

Templates Directory

Purpose

The templates/ directory contains Kubernetes manifest templates written in YAML combined with Go template syntax. These templates are rendered at installation time using values from values.yaml or user overrides, producing fully formed Kubernetes resource definitions.

Contents and Usage

• Each file corresponds to one or more Kubernetes resource definitions.
• Files may include resources such as Deployments, Services, ConfigMaps, Secrets, and more.
• Template helpers can be defined in _helpers.tpl.
• Template files can use conditional logic, loops, and custom functions.
• Rendered output is validated by Helm before applying to the cluster.

Example template snippet (deployment.yaml):

apiVersion: apps/v1
kind: Deployment
metadata:
  name: {{ include "myapp.fullname" . }}
  labels:
    app: {{ include "myapp.name" . }}
spec:
  replicas: {{ .Values.replicaCount }}
  selector:
    matchLabels:
      app: {{ include "myapp.name" . }}
  template:
    metadata:
      labels:
        app: {{ include "myapp.name" . }}
    spec:
      containers:
        - name: {{ .Chart.Name }}
          image: "{{ .Values.image.repository }}:{{ .Values.image.tag }}"
          ports:
            - containerPort: {{ .Values.service.port }}

Values.yaml

Purpose

values.yaml provides default configuration values for the chart templates. Users may override these values when installing or upgrading a release, enabling customization without modifying the chart templates directly.

Structure

• YAML format listing configuration keys and their default values.
• Supports nested structures for complex configurations.
• Values are referenced in templates using the .Values object.

Example:

replicaCount: 3

image:
  repository: nginx
  tag: stable

service:
  type: ClusterIP
  port: 80

Optional Files and Directories

README.md

A file containing documentation about the chart, usage instructions, and configuration guidance.

LICENSE

Specifies the licensing terms under which the chart is distributed.

charts/

A directory containing chart dependencies packaged as .tgz archives or unpacked charts. Helm uses this directory to manage and resolve chart dependencies during installation or upgrade.

crds/

A directory for CustomResourceDefinition manifests that should be installed before any other templates. Helm treats these specially to ensure CRDs are applied in the correct order.

Chart Archives

Charts can be packaged into compressed archive files (.tgz) for distribution. The archive maintains the directory structure and files as defined by the chart format. Helm installs charts from these archives by extracting and rendering their contents.

Chart API Versions

The apiVersion field in Chart.yaml defines the version of the chart format schema. Currently, the most common versions are:

• v1: Legacy chart format with limitations on features such as dependencies and CRDs.
• v2: Introduced improvements including better dependency management, support for CRDs, and stricter validation.

Using the correct apiVersion ensures Helm processes the chart in accordance with the expected specification.

Summary of Chart Format Requirements

The chart format ensures that Helm can reliably package, distribute, and deploy Kubernetes applications, maintaining consistency across environments and simplifying application lifecycle management.