✦ For everyone, free.

Practical knowledge for real and everyday life

Home

Chart Metadata

Chart Metadata defines the structure and configuration of Helm charts, enabling consistent deployment and management of Kubernetes applications.

Chart Metadata defines the essential descriptive information about a Helm chart. It is specified in the Chart.yaml file located at the root of the chart directory. This metadata provides Helm and users with critical details such as the chart's identity, versioning, dependencies, and maintainers, enabling the proper management, distribution, and consumption of the chart.

Purpose and Role of Chart Metadata

Chart Metadata serves as the manifest for the Helm chart, offering a structured summary that Helm uses to validate, install, and upgrade charts. It ensures that charts can be uniquely identified, appropriately versioned, and linked with their dependencies. Additionally, it allows users and automated systems to understand the chart’s intent, origins, and compatibility.

Key Fields in Chart Metadata

name

  • The chart’s name.
  • Must be a lowercase string.
  • Used as the unique identifier within chart repositories and Helm commands.

version

  • The version of the chart itself.
  • Follows Semantic Versioning 2 (e.g., 1.2.3).
  • Indicates changes, updates, or fixes in the chart package.

apiVersion

  • Specifies the version of the chart API spec used.
  • Helm currently supports v1 and v2.
  • Determines which schema and features are available for the chart.

description

  • A brief human-readable explanation of what the chart does.
  • Should be concise but informative to convey the chart’s purpose.

type

  • Defines the chart type.
  • Common values include application (default) for deployable apps or library for reusable chart components.

keywords

  • An array of strings for searchability.
  • Helps users find the chart using relevant terms.

home

  • URL to the project’s homepage or website.
  • Provides a reference for users seeking more information.

sources

  • A list of URLs pointing to source code or related resources.
  • Useful for transparency and contribution.

dependencies

  • An array detailing other charts this chart depends on.
  • Each dependency includes fields like name, version, repository URL, and condition.
  • Enables Helm to manage complex applications by composing smaller charts.

maintainers

  • A list of individuals or teams responsible for the chart.
  • Contains name, email, and optionally URL.
  • Facilitates contact and support.

icon

  • A URL or local path to an image file representing the chart.
  • Used in UIs and repositories to visually identify the chart.

annotations

  • A map of key-value pairs for storing arbitrary metadata.
  • Can be used to add custom information without affecting core fields.

deprecated

  • Boolean flag indicating if the chart is deprecated.
  • Informs users that the chart should not be used for new deployments.

Example of a Complete Chart Metadata File

apiVersion: v2
name: myapp
description: A Helm chart for deploying MyApp
type: application
version: 1.0.0
appVersion: 2.1.0
keywords:
  - web
  - backend
  - api
home: https://myapp.example.com
sources:
  - https://github.com/myorg/myapp
maintainers:
  - name: Jane Doe
    email: jane.doe@example.com
    url: https://janedoe.dev
icon: https://myapp.example.com/icon.png
dependencies:
  - name: redis
    version: 14.8.8
    repository: https://charts.bitnami.com/bitnami
    condition: redis.enabled
annotations:
  category: backend
deprecated: false

Versioning Details

Chart Version (version)

The version field refers to the version of the Helm chart package itself. It must adhere strictly to semantic versioning (semver) to allow Helm to manage upgrades and rollbacks effectively.

Application Version (appVersion)

While not strictly part of the minimal required metadata, appVersion is often included to specify the version of the underlying application the chart deploys. It is a free-form string and does not affect Helm’s chart versioning logic.

Dependencies and Their Management

Chart dependencies are defined within the metadata to express the relationship and requirements on other charts. They enable modular, reusable packaging of complex applications.

Each dependency entry includes:

  • name: The dependent chart’s name.
  • version: The required version of the dependency.
  • repository: URL of the Helm chart repository hosting the dependency.
  • condition: An optional boolean path in the chart’s values to enable or disable the dependency.
  • tags: Optional string tags to group dependencies for selective enabling.

Helm uses this information to automatically fetch, update, and install dependent charts during operations.

Metadata Validation and Best Practices

  • The name and version fields are mandatory.
  • apiVersion should be set according to Helm’s supported schema versions.
  • Use semantic versioning consistently.
  • Provide concise and clear descriptions.
  • Include maintainers for accountability.
  • Use the keywords field to improve discoverability.
  • Keep dependencies up to date and accurately reflect the application requirements.
  • Use annotations for custom metadata without polluting core fields.

Impact on Helm Operations

Chart Metadata directly influences:

  • Chart packaging: Ensures correct version and naming.
  • Chart repositories: Enables indexing and searching.
  • Installation and upgrades: Helm relies on versioning and dependencies to manage lifecycle.
  • User experience: Metadata fields like description, icon, and maintainers inform and assist end users.

Properly structured and maintained Chart Metadata is critical for smooth operation within Helm ecosystems and for chart users to understand and trust the charts they deploy.

Related content