Fundamental concepts

---

1 - The three main concepts

Concept	Description	Analogy
Chart	Package containing the templates	Source code
Release	Deployed instance of a chart	Application in production
Repository	Collection of charts	npm registry

---

2 - Charts in detail

2.1 What is a Chart?

A Chart is a bundle of files that describes a set of Kubernetes resources.

wordpress/
├── Chart.yaml          # Informations sur le chart
├── Chart.lock          # Versions lockées des dépendances
├── values.yaml         # Valeurs de configuration par défaut
├── values.schema.json  # Schéma JSON des values (optionnel)
├── charts/             # Charts dont ce chart dépend
├── crds/               # Custom Resource Definitions
├── templates/          # Templates + fonctions helpers
│   ├── NOTES.txt       # Notes affichées après installation
│   ├── _helpers.tpl    # Fonctions helpers partagées
│   ├── deployment.yaml
│   ├── service.yaml
│   ├── ingress.yaml
│   └── tests/          # Tests du chart
│       └── test-connection.yaml
├── LICENSE             # License du chart
└── README.md           # Documentation

2.2 Chart.yaml

# Chart.yaml
apiVersion: v2                    # API version du chart (v2 pour Helm 3)
name: mon-application             # Nom du chart
version: 1.0.0                    # Version du chart (SemVer)
appVersion: "2.1.0"               # Version de l'application packagée
description: Une application web  # Description
type: application                 # application ou library

# Métadonnées optionnelles
keywords:
  - web
  - api
home: https://example.com
sources:
  - https://github.com/example/repo
maintainers:
  - name: John Doe
    email: [email protected]
    url: https://johndoe.com
icon: https://example.com/icon.png
deprecated: false
kubeVersion: ">=1.20.0"          # Versions K8s compatibles

# Annotations personnalisées
annotations:
  category: Web Application
  licenses: Apache-2.0

# Dépendances
dependencies:
  - name: postgresql
    version: "12.x.x"
    repository: "https://charts.bitnami.com/bitnami"
    condition: postgresql.enabled
    tags:
      - database
  - name: redis
    version: "17.x.x"
    repository: "https://charts.bitnami.com/bitnami"
    condition: redis.enabled

2.3 Chart types

Type	Description	Usage
application	Deploys K8s resources	Most charts
library	Provides helpers/templates	Shared charts

# Chart de type library
apiVersion: v2
name: common-templates
type: library
version: 1.0.0

---

3 - Releases in detail

3.1 What is a Release?

A Release is an instance of a chart deployed in the cluster with a specific configuration.

3.2 Release storage

Release information is stored in Kubernetes Secrets.

# Voir les secrets de release
kubectl get secrets -l owner=helm

# Exemple de secret
# sh.helm.release.v1.my-release.v1

# Structure du nom:
# sh.helm.release.v1.<release-name>.v<revision>

3.3 Lifecycle of a release

3.4 Revisions

Each operation creates a new revision:

# Historique des révisions
helm history my-release

# REVISION    UPDATED                     STATUS      CHART           DESCRIPTION
# 1           Mon Nov 13 10:00:00 2023    superseded  nginx-1.0.0     Install complete
# 2           Mon Nov 13 11:00:00 2023    superseded  nginx-1.1.0     Upgrade complete
# 3           Mon Nov 13 12:00:00 2023    deployed    nginx-1.1.0     Rollback to 2

# Rollback à une révision spécifique
helm rollback my-release 1

---

4 - Repositories in detail

4.1 Repository types

4.2 Classic HTTP repository

Structure of an HTTP repository:

https://charts.example.com/
├── index.yaml              # Index de tous les charts
├── nginx-1.0.0.tgz        # Chart packagé
├── nginx-1.1.0.tgz
├── wordpress-5.0.0.tgz
└── wordpress-5.1.0.tgz

# index.yaml
apiVersion: v1
entries:
  nginx:
    - name: nginx
      version: 1.1.0
      description: NGINX web server
      urls:
        - https://charts.example.com/nginx-1.1.0.tgz
      created: "2023-11-13T10:00:00Z"
      digest: sha256:abc123...
    - name: nginx
      version: 1.0.0
      urls:
        - https://charts.example.com/nginx-1.0.0.tgz
generated: "2023-11-13T10:00:00Z"

4.3 OCI Registry

Helm 3 supports OCI (Open Container Initiative) registries.

# Login à un registry OCI
helm registry login ghcr.io -u username

# Push un chart vers OCI
helm push mychart-1.0.0.tgz oci://ghcr.io/myorg/charts

# Pull depuis OCI
helm pull oci://ghcr.io/myorg/charts/mychart --version 1.0.0

# Installer depuis OCI
helm install myrelease oci://ghcr.io/myorg/charts/mychart --version 1.0.0

4.4 Create your own repository

# Avec ChartMuseum (serveur dédié)
docker run -d -p 8080:8080 \
  -e STORAGE=local \
  -e STORAGE_LOCAL_ROOTDIR=/charts \
  -v $(pwd)/charts:/charts \
  ghcr.io/helm/chartmuseum:latest

# Avec GitHub Pages
# 1. Créer un repo GitHub
# 2. Packager le chart
helm package ./mon-chart

# 3. Générer l'index
helm repo index . --url https://username.github.io/charts

# 4. Push et activer GitHub Pages

---

5 - Values in detail

5.1 Values hierarchy

Values can be defined at several levels:

5.2 values.yaml file

# values.yaml
# Configuration de l'image
image:
  repository: nginx
  tag: "1.25"
  pullPolicy: IfNotPresent

# Réplicas
replicaCount: 3

# Service
service:
  type: ClusterIP
  port: 80

# Ressources
resources:
  limits:
    cpu: 500m
    memory: 512Mi
  requests:
    cpu: 100m
    memory: 128Mi

# Ingress
ingress:
  enabled: false
  className: nginx
  hosts:
    - host: example.local
      paths:
        - path: /
          pathType: Prefix

# Configuration personnalisée
config:
  database:
    host: localhost
    port: 5432
  features:
    - feature1
    - feature2

5.3 Override the values

# Avec un fichier
helm install myapp ./chart -f production.yaml

# Avec plusieurs fichiers (fusion)
helm install myapp ./chart -f base.yaml -f production.yaml

# Avec --set (valeurs simples)
helm install myapp ./chart --set replicaCount=5

# Avec --set (valeurs imbriquées)
helm install myapp ./chart --set image.tag=v2.0.0

# Avec --set (listes)
helm install myapp ./chart --set 'ingress.hosts[0].host=example.com'

# Avec --set-string (forcer le type string)
helm install myapp ./chart --set-string image.tag=1.0

# Avec --set-file (contenu de fichier)
helm install myapp ./chart --set-file config.data=./config.json

# Combinaison
helm install myapp ./chart \
  -f base.yaml \
  -f production.yaml \
  --set replicaCount=10 \
  --set image.tag=v2.0.0

5.4 Validation schema

// values.schema.json
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "required": ["replicaCount", "image"],
  "properties": {
    "replicaCount": {
      "type": "integer",
      "minimum": 1,
      "maximum": 10
    },
    "image": {
      "type": "object",
      "required": ["repository"],
      "properties": {
        "repository": {
          "type": "string"
        },
        "tag": {
          "type": "string",
          "default": "latest"
        }
      }
    },
    "service": {
      "type": "object",
      "properties": {
        "type": {
          "type": "string",
          "enum": ["ClusterIP", "NodePort", "LoadBalancer"]
        }
      }
    }
  }
}

---

6 - Relationships between concepts

---

Summary

In this chapter, we dived deeper into:

• Charts: structure, Chart.yaml, types
• Releases: lifecycle, storage, revisions
• Repositories: HTTP, OCI, creation
• Values: hierarchy, override, validation

---

Next step

In the next chapter, we will explore the anatomy of a Chart in detail.

→ Next chapter: Anatomy of a Chart

---

← Back to the table of contents