Distribution Helm via OCI : publier des charts sur registries modernes

Les registres OCI, pour Open Container Initiative, permettent de stocker des charts Helm au même endroit que vos images. Un seul registre, une seule authentification, une gestion unifiée des artefacts. Depuis Helm 3.8, le support OCI est stable et recommandé en production.

Prérequis

• Helm v4.3 installé (helm version), la version sur laquelle ce guide est mesuré
• 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é)

Ce que vous allez apprendre

• Pourquoi OCI pour les charts Helm
• S'authentifier sur un registry
• Packager et publier un chart
• Consommer un chart depuis OCI
• Stratégies de naming et versioning
• Registries compatibles

---

Pourquoi OCI pour les charts Helm

Un registre OCI est le même stockage que celui de vos images de conteneurs, et c'est tout l'intérêt : une seule infrastructure, une seule authentification, une seule politique de rétention. Ce chapitre explique ce que ce choix remplace, puis ce qu'il apporte concrètement par rapport à un dépôt de charts classique.

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 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 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

Glissez pour voir

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. Deux lignes méritent une lecture attentive. L'immutabilité est native, un tag OCI pointant vers un digest. La découverte, en revanche, est le point faible du modè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)

Glissez pour voir

OCI est un standard ouvert, et c'est ce qui distingue ce choix d'un enfermement. Un chart publié sur Harbor se consomme à l'identique depuis GHCR, ECR, ACR ou Docker Hub : la référence change, pas les commandes. Vous n'êtes donc lié à aucun fournisseur, ce qui est rarement vrai des solutions de distribution propriétaires, et une migration de registre se réduit à republier les archives ailleurs.

---

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é par docker login sur le registre visé, Helm en profite sans manipulation supplémentaire. 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.

Harbor

# 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

GHCR

# 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

ECR

# 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

Docker Hub

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

Credentials en CI/CD

Ne jamais stocker de credentials en clair. Utilisez les secrets de votre CI (GitLab CI variables, GitHub Secrets, Vault).

---

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 registre d'entreprise. La version déclarée dans Chart.yaml est la seule source du tag OCI, il n'existe aucun paramètre --tag sur helm push. Oublier de l'incrémenter est l'erreur la plus fréquente : la commande échoue si le registre interdit l'écrasement, ou remplace silencieusement le contenu s'il l'autorise.

1. Vérifier le chart

   Avant de publier, validez la qualité :

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

2. Packager le chart

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

   La version vient de Chart.yaml :

   Chart.yaml

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

3. Pousser vers le registry

   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.

4. 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 d'intégration continue. 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

Côté consommation, une référence oci:// remplace le couple dépôt plus nom de chart partout où Helm attend un chart. Deux façons de faire coexistent, l'installation directe et le téléchargement préalable, et elles ne se valent pas dès qu'il s'agit d'inspecter avant de déployer.

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 registre, et les chaînes qui vérifient la signature avant d'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

Si vous ajoutez --destination pour ranger l'archive ailleurs, créez le répertoire d'abord : Helm ne le crée pas, et sa sortie est trompeuse. Elle annonce le succès du téléchargement avant d'échouer à l'écriture, sur un nom de fichier temporaire qui ne ressemble à rien :

Pulled: registry.example.com/charts/my-chart:1.2.3
Error: open absent/my-chart-1.2.3.tgz3992314192: no such file or directory

Le chart a bien été récupéré, rien n'a été écrit. Un mkdir -p placé avant le helm pull dans le script d'intégration continue suffit à éviter tout le diagnostic.

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 il embarque, 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

Le nom et la version d'un chart deviennent, en OCI, un chemin de dépôt et un tag, exactement comme pour une image. Les conventions qui suivent évitent les deux problèmes classiques : des charts qu'on ne retrouve pas dans un registre partagé, et des versions redéplaçables qui ruinent la reproductibilité.

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 registre. Le tableau montre deux formes valides : Harbor impose un projet à un seul niveau, GHCR accepte un chemin imbriqué. Vérifiez cette contrainte avant de figer une convention d'équipe.

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

Glissez pour voir

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, mettez 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

Glissez pour voir

Immutabilité des tags

Une fois publié, un tag ne doit jamais être écrasé en production. Pour corriger une anomalie, incrémentez la version. Les tags mouvants comme latest ou main ne sont acceptables qu'en développement, jamais dans une chaîne de déploiement.

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 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.

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

---

Registries compatibles

Tous les registres conformes à la distribution spec de l'OCI acceptent les charts : il n'y a 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

Glissez pour voir

En entreprise, Harbor reste le choix le plus complet pour héberger des charts. Il apporte une interface dédiée, un scan de vulnérabilités, la réplication entre instances et des quotas par projet, le tout en open source. Les registres des fournisseurs de cloud font le travail aussi, mais rarement avec cet ensemble de fonctions sans supplément.

---

Erreurs fréquentes

Les messages renvoyés par les registres 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

Glissez pour voir

---

Lab C1, Publier sur un registry OCI

Ce lab enchaîne le cycle complet sur un chart jetable, pour éviter de découvrir les erreurs d'authentification sur un chart de production. Prévoyez un registre accessible et les droits d'écriture correspondants : c'est la seule étape que le lab ne peut pas vous fournir.

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

1. 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

2. Se connecter au registry

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

3. Packager et publier

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

4. 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

5. 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

---

Contrôle de connaissances

Cinq questions sur la distribution : ce qui détermine le tag d'un chart poussé, pourquoi référencer par digest, et la sortie trompeuse d'un pull vers un dossier absent.

Contrôle de connaissances

Validez vos connaissances avec ce quiz interactif

5 questions

5 min.

80% requis

Informations

• Le chronomètre démarre au clic sur Démarrer
• Questions à choix multiples, vrai/faux et réponses courtes
• Vous pouvez naviguer entre les questions
• Les résultats détaillés sont affichés à la fin

Démarrer le quiz

Lance le quiz et démarre le chronomètre

Pour aller plus loin

• Migrer vers Helm v4 : La place que prend OCI dans la nouvelle version, et ce qui disparaît.

×

📖 Voir la documentation →