Distribution Helm via OCI : publier des charts sur registries modernes

Les registries OCI (Open Container Initiative) permettent de stocker des charts Helm au même endroit que vos images Docker. Un seul registry, une seule authentification, une gestion unifiée des artefacts. Depuis Helm 3.8+, le support OCI est stable et recommandé pour les environnements de production.

Prérequis

Helm 3.8+ installé (helm version)
Un compte sur un registry OCI (Harbor, GHCR, ECR, ACR, Docker Hub)
Un chart packagé ou prêt à packager
Module 09, Qualité des charts (recommandé)

Pourquoi OCI pour les charts Helm

L'évolution de la distribution Helm

Comprendre d'où vient le modèle OCI explique pourquoi il s'est imposé. Pendant des années, publier un chart voulait dire héberger un index.yaml et des archives .tgz derrière un serveur web, avec un fichier d'index à régénérer et à republier à chaque version. Le tableau se lit de haut en bas comme une chronologie ; la colonne Limitations décrit à chaque fois le problème que la génération suivante a résolu.

Génération	Mécanisme	Limitations
Helm 2	Repos HTTP (index.yaml + tarballs)	Serveur web dédié, pas de sécurité native
Helm 3	Repos HTTP améliorés	Toujours un index.yaml à maintenir
Helm 3.8+	OCI registries	Même infra que les images, authentification intégrée

Avantages d'OCI

Le gain principal n'est pas technique mais opérationnel : vous supprimez une infrastructure. Plus de serveur web à maintenir, plus d'index à régénérer, plus d'authentification spécifique aux charts. Deux lignes méritent une lecture attentive. L'immutabilité est native parce qu'un tag OCI pointe vers un digest, donc vous pouvez référencer un chart de façon reproductible. La découverte, en revanche, est le point faible du modèle : helm search n'expose que le Artifact Hub et les dépôts HTTP ajoutés localement, il ne sait pas parcourir un registry OCI. C'est l'API ou l'interface du registry qui joue ce rôle.

Aspect	Repos HTTP classiques	OCI registries
Infrastructure	Serveur web dédié + index.yaml	Votre registry d'images existant
Authentification	Basic auth ou tokens custom	Même auth que vos images Docker
Immutabilité	Dépend de votre config	Native (un tag = un digest)
Signature	Fichier .prov séparé	Cosign/Notation intégrés
Découverte	`helm search repo`	UI ou API du registry (`helm search` ne couvre pas OCI)

S'authentifier sur un registry

helm registry login écrit ses identifiants dans le même fichier que Docker, ~/.docker/config.json : si vous êtes déjà authentifié avec docker login sur le registry visé, Helm en profite sans manipulation supplémentaire. Choisissez l'onglet correspondant à votre plateforme. Dans tous les cas, préférez --password-stdin : un mot de passe passé en argument atterrit dans l'historique du shell et dans la table des processus.

# Login avec username/password
helm registry login harbor.example.com

# Login avec robot account (CI/CD)
helm registry login harbor.example.com \
  --username 'robot$myproject+ci' \
  --password-stdin < /path/to/token

# Créer un PAT avec scope write:packages
# https://github.com/settings/tokens

echo $GITHUB_TOKEN | helm registry login ghcr.io \
  --username $GITHUB_USERNAME \
  --password-stdin

# Login via AWS CLI
aws ecr get-login-password --region eu-west-1 | \
  helm registry login 123456789.dkr.ecr.eu-west-1.amazonaws.com \
  --username AWS \
  --password-stdin

# Login classique Docker
helm registry login registry-1.docker.io \
  --username $DOCKER_USERNAME \
  --password-stdin < ~/.docker/token

Packager et publier un chart

La publication se joue en quatre temps, et l'ordre a son importance : un chart poussé ne se retire pas facilement d'un registry d'entreprise. La version déclarée dans Chart.yaml est la seule source du tag OCI, il n'y a pas de paramètre --tag sur helm push. Oublier de l'incrémenter est l'erreur la plus fréquente : la commande échouera si le registry interdit l'écrasement, ou remplacera silencieusement le contenu s'il l'autorise.

Vérifier le chart

Avant de publier, validez la qualité :

helm lint ./my-chart
helm template ./my-chart > /dev/null  # Vérifie le rendu

Packager le chart

helm package ./my-chart
# Crée my-chart-1.2.3.tgz

La version vient de Chart.yaml :

apiVersion: v2
name: my-chart
version: 1.2.3      # Version du chart
appVersion: "2.0.0" # Version de l'application

Pousser vers le registry
Fenêtre de terminal
```
helm push my-chart-1.2.3.tgz oci://harbor.example.com/myproject
```
Résultat :
```
Pushed: harbor.example.com/myproject/my-chart:1.2.3
Digest: sha256:abc123...
```
Notez le digest affiché : c'est lui qu'il faut consigner si vous voulez pouvoir redéployer exactement cette version plus tard.

Vérifier la publication

helm show chart oci://harbor.example.com/myproject/my-chart --version 1.2.3

Workflow complet en une commande

Enchaîner les trois étapes avec && garantit qu'un lint en échec arrête tout avant le push. C'est la forme à reprendre dans un job de CI. Attention au joker my-chart-*.tgz de la dernière ligne : s'il reste une archive d'une version précédente dans le répertoire, helm push recevra plusieurs fichiers. Faites le ménage ou nommez explicitement l'archive attendue.

# Lint → Package → Push
helm lint ./my-chart && \
helm package ./my-chart && \
helm push my-chart-*.tgz oci://harbor.example.com/myproject

Consommer un chart depuis OCI

Installation directe

Une référence oci:// s'utilise partout où Helm attend un chart, sans avoir ajouté le moindre dépôt au préalable. Précisez toujours --version : sans elle, Helm résout la version la plus récente publiée, et votre déploiement dépendra de ce que quelqu'un aura poussé entre-temps.

# Installer depuis OCI
helm install my-release oci://harbor.example.com/myproject/my-chart \
  --version 1.2.3 \
  -n my-namespace \
  --create-namespace

Pull local puis install

Séparer le téléchargement de l'installation devient nécessaire dans deux situations : les environnements où le cluster n'a pas accès au registry, et les chaînes qui vérifient la signature du chart avant de l'appliquer. L'archive récupérée est le fichier exact publié, ce qui permet de calculer son empreinte et de la comparer à celle attendue.

# Télécharger le chart
helm pull oci://harbor.example.com/myproject/my-chart --version 1.2.3

# Installer depuis le tarball local
helm install my-release ./my-chart-1.2.3.tgz -n my-namespace

Inspecter avant d'installer

Ces trois commandes ne téléchargent que les métadonnées et n'installent rien. Elles répondent aux trois questions à se poser devant un chart inconnu : quelle version d'application embarque-t-il, quelles valeurs sont modifiables, et quelles sont les instructions de l'auteur. Sur un chart tiers, helm show values est le minimum à lire avant tout déploiement.

# Voir les métadonnées
helm show chart oci://harbor.example.com/myproject/my-chart --version 1.2.3

# Voir les values par défaut
helm show values oci://harbor.example.com/myproject/my-chart --version 1.2.3

# Voir le README
helm show readme oci://harbor.example.com/myproject/my-chart --version 1.2.3

Stratégies de naming et versioning

Convention de nommage

La structure d'une référence OCI reprend celle d'une image de conteneur, à ceci près que la partie projet peut contenir plusieurs niveaux selon le registry. Le tableau montre deux formes valides : Harbor impose un projet à un seul niveau, GHCR accepte un chemin imbriqué sous l'organisation. Vérifiez cette contrainte avant de figer une convention d'équipe, elle n'est pas la même partout.

oci://<registry>/<project>/<chart-name>:<version>

Exemple	Registry	Project	Chart	Version
`oci://harbor.example.com/platform/nginx`	harbor.example.com	platform	nginx	(latest)
`oci://ghcr.io/myorg/charts/api:2.1.0`	ghcr.io	myorg/charts	api	2.1.0

Stratégie de versioning recommandée

La version du chart suit le versionnage sémantique, avec une subtilité que ce tableau met en évidence : les métadonnées de build (ce qui suit le +) ne font pas partie de l'identité de la version et disparaissent du tag OCI. Deux builds 1.2.3+build.456 et 1.2.3+build.457 produiraient donc le même tag et s'écraseraient. Si vous générez un chart par exécution de pipeline, incluez le numéro de build dans la partie pre-release, après un tiret.

Situation	Version chart	Tag OCI
Release stable	`1.2.3`	`1.2.3`
Pre-release	`1.2.3-rc.1`	`1.2.3-rc.1`
Branche feature	`0.0.0-feature-xyz`	`feature-xyz`
CI automatique	`1.2.3+build.456`	`1.2.3`

Utiliser les digests pour la reproductibilité

Un tag reste une étiquette déplaçable ; un digest est calculé sur le contenu et ne peut donc pas désigner autre chose. Référencer un chart par digest garantit que le déploiement de demain applique exactement les manifestes d'aujourd'hui, même si quelqu'un republie le tag entre-temps. C'est la forme à privilégier dans un dépôt GitOps. Le digest s'obtient dans la sortie de helm push, ou avec helm show chart qui affiche la ligne Digest: avant les métadonnées.

# Référencer par digest (immuable)
helm install my-release oci://harbor.example.com/myproject/my-chart@sha256:abc123...

Registries compatibles

Tous les registries conformes à la distribution spec de l'OCI acceptent les charts, il n'y a donc pas de compatibilité à vérifier au sens strict. Ce qui diffère, c'est le format du chemin imposé par chacun et la façon dont l'interface présente les artefacts qui ne sont pas des images. La colonne « URL format » est celle que vous recopierez : une erreur de niveau de chemin produit un denied bien plus souvent qu'un vrai problème de droits.

Registry	URL format	Notes
Harbor	`oci://harbor.example.com/project`	Gratuit, self-hosted, UI native pour charts
GHCR	`oci://ghcr.io/owner/repo`	Intégré à GitHub, gratuit pour public
ECR	`oci://123456.dkr.ecr.region.amazonaws.com`	AWS natif, IAM intégré
ACR	`oci://myregistry.azurecr.io`	Azure natif
GCR/Artifact Registry	`oci://region-docker.pkg.dev/project/repo`	Google Cloud
Docker Hub	`oci://registry-1.docker.io/user`	Limites de pull sur free tier

Erreurs fréquentes

Les messages renvoyés par les registries sont volontairement peu bavards, pour ne pas révéler l'existence d'un dépôt à un utilisateur non autorisé. C'est pourquoi manifest unknown et denied désignent souvent la même situation vue de deux côtés : soit la référence est fausse, soit vous n'avez pas le droit de la voir. Vérifiez le chemin complet avant de demander des droits supplémentaires.

Erreur	Cause probable	Solution
`unauthorized`	Token expiré ou permissions insuffisantes	`helm registry logout` puis `login`
`manifest unknown`	Chart ou version inexistant	Vérifier le nom et la version
`denied: requested access...`	Pas de permission push	Vérifier les droits sur le projet
`Error: scheme "oci" not supported`	Helm < 3.8	Mettre à jour Helm

Lab C1, Publier sur un registry OCI

Ce lab enchaîne le cycle complet sur un chart jetable, pour vous éviter de découvrir les erreurs d'authentification sur un chart de production. Prévoyez un jeton avec la portée write:packages côté GitHub et un cluster de test accessible : la dernière étape installe réellement le chart. Le nettoyage final n'est pas optionnel, le namespace créé resterait sinon dans votre cluster.

Objectif : Packager un chart, le publier sur GHCR (ou Harbor local), puis l'installer depuis oci://.

Préparer le chart

# Utiliser un chart existant ou en créer un
helm create my-lab-chart
cd my-lab-chart

# Modifier la version dans Chart.yaml
sed -i 's/version: .*/version: 0.1.0/' Chart.yaml

Se connecter au registry

# GHCR
echo $GITHUB_TOKEN | helm registry login ghcr.io -u $GITHUB_USERNAME --password-stdin

Packager et publier

cd ..
helm package my-lab-chart
helm push my-lab-chart-0.1.0.tgz oci://ghcr.io/$GITHUB_USERNAME/charts

Vérifier et installer

# Vérifier
helm show chart oci://ghcr.io/$GITHUB_USERNAME/charts/my-lab-chart --version 0.1.0

# Installer
helm install test-release oci://ghcr.io/$GITHUB_USERNAME/charts/my-lab-chart \
  --version 0.1.0 \
  -n oci-lab \
  --create-namespace

Nettoyer

helm uninstall test-release -n oci-lab
kubectl delete namespace oci-lab

Critères de réussite :

Chart packagé (.tgz créé)
Push vers registry OCI réussi
helm show chart oci://... affiche les métadonnées
Installation depuis oci:// fonctionnelle

À retenir

OCI = standard ouvert pour stocker charts et images au même endroit
helm registry login = authentification (même credentials que Docker)
helm push = publier un chart packagé
helm pull / helm install oci:// = consommer depuis OCI
Immutabilité : ne jamais écraser un tag en production
Digests : utilisez @sha256:... pour la reproductibilité absolue

Prochaines étapes

11, Confiance et provenance Signer des charts pour garantir leur intégrité

12, CI/CD packaging Automatiser lint, package et publish en pipeline

Harbor Installer votre propre registry OCI

Cosign Signer des artefacts OCI avec Sigstore