Migration depuis Helm
De Helm à Sherpack
Même modèle mental. Syntaxe Jinja2 familière. Vrai lookup(),
CRDs intelligents, lock files. Écrit en Rust, un seul binaire, sans
écosystème de plugins à gérer.
$ sherpack convert ./mon-helm-chart✓ 43 templates analysés✓ Go templates → Jinja2✓ Écrit dans ./mon-helm-chart-pack/Pack.yaml$ _
Pourquoi se donner la peine ?
Sherpack n'essaie pas de remplacer Helm partout — il essaie d'être meilleur que Helm sur ce qui fait mal, et un quasi drop-in pour le reste. Si tu as déjà souhaité que l'un des points ci-dessous soit différent, ce guide est pour toi.
Les Go templates font mal
{{- if .Values.foo -}} et la gymnastique des
pipelines, c'est une taxe quotidienne. Sherpack utilise
Jinja2 — la syntaxe que les développeurs Python
connaissent par cœur.
Les CRDs sont gelés sous Helm
Helm ne met jamais à jour les CRDs après l'install. Sherpack analyse les changements (24 catégories), classe la sûreté, et te laisse mettre à jour en confiance.
Reproductible par défaut
Pack.lock.yaml avec policies de version (Strict,
SemverPatch, SemverMinor). Les conflits de dépendance en losange
remontent comme erreurs, pas comme overrides silencieux.
Un binaire, ~19 Mo
Rust natif. Pas de runtime Go. Pas de gestionnaire de plugins. Server-Side Apply, chunking du release storage au-delà de 1 Mo, et génération de secrets idempotente sont nativement intégrés.
Migrer en 60 secondes
- 01
Convertir
Lance
sherpack convertsur ton chart Helm existant.$ sherpack convert ./mon-helm-chart -o ./mon-pack
- 02
Rendre
Vérifie le rendu exactement comme avec
helm template.$ sherpack template ma-release ./mon-pack
- 03
Installer
Même commande, mêmes flags, même cycle de vie de release.
$ sherpack install ma-release ./mon-pack -n production
Antisèche de syntaxe
Quasiment chaque construction de template Helm a un équivalent en une ligne dans Sherpack. Le converter le fait pour toi, mais connaître la correspondance aide à lire et ajuster le résultat.
{% if values.ingress.enabled %}
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: {{ release.name }}
labels:
{{ labels() | nindent(4) }}
spec:
{% for h in values.ingress.hosts %}
- host: {{ h.host | quote }}
{% endfor %}
{% endif %}
Plus de correspondances
| Concept | Helm | Sherpack |
|---|---|---|
| Conditionnel | {{- if .Values.x }}…{{- end }} | {% if values.x %}…{% endif %} |
| Boucle | {{- range .Values.list }} | {% for x in values.list %} |
| Filtre pipeline | {{ .Values.x | upper }} | {{ values.x | upper }} |
| Helper indent | {{ … | nindent 4 }} | {{ … | nindent(4) }} |
| Define / include | {{ define "x" }} + {{ include "x" . }} | {% macro x() %} + {{ x() }} |
| Whitespace | {{- … -}} | {%- … -%} |
| Données chart | .Chart.Name | pack.name |
| Release | .Release.Name | release.name |
| Values | .Values.x | values.x |
| API Files | .Files.Get "config.json" | files.Get("config.json") |
| Lookup | lookup "v1" "Secret" .Release.Namespace "x" | lookup("v1", "Secret", release.namespace, "x") |
Équivalence des commandes
Pas besoin de réapprendre la CLI. Les verbes mappent presque un pour un.
| Helm | Sherpack | Notes |
|---|---|---|
helm install | sherpack install | --wait, --atomic, --dry-run supportés |
helm upgrade | sherpack upgrade | --install, --reuse-values, --reset-values |
helm uninstall | sherpack uninstall | --keep-history supporté |
helm rollback | sherpack rollback | |
helm list | sherpack list | --all-namespaces supporté |
helm status | sherpack status | flags --manifest, --show-values |
helm history | sherpack history | |
helm template | sherpack template | --set, -f, --show-only |
helm lint | sherpack lint | + validation JSON Schema |
helm package | sherpack package | avec manifest SHA256 |
helm verify | sherpack verify | Minisign à la place de PGP |
helm test | sherpack test | exécute les hooks de phase test |
helm repo add | sherpack repo add | HTTP + OCI |
helm repo update | sherpack repo update | |
helm repo index | sherpack repo index | --url, --merge |
helm search repo | sherpack search | cache SQLite FTS5 |
helm pull | sherpack pull | |
helm push | sherpack push | registres OCI |
helm dependency update | sherpack dependency update | avec Pack.lock.yaml |
helm completion bash | sherpack completion bash | bash, zsh, fish, powershell, elvish |
Le nouveau modèle de lookup()
Le lookup de Helm interroge le cluster au moment du rendu pendant
install/upgrade et retourne {} pendant helm template. Sherpack
fait exactement la même chose, mais avec un twist : chaque résultat
non-vide produit un warning structuré pour que le non-déterminisme
ne soit pas silencieux.
Ce qui change par rapport à Helm : timeout (5s par
défaut, override avec SHERPACK_LOOKUP_TIMEOUT_SECS), cache
par-rendu pour dédupliquer les appels identiques, et warnings agrégés
pour faire remonter le non-déterminisme GitOps. Voir le guide dédié LOOKUP.md pour les patterns de migration.
Parité fonctionnelle d'un coup d'œil
| Helm | Sherpack | |
|---|---|---|
| Moteur de templates | Go templates | Jinja2 (MiniJinja) |
API .Files | ✓ | ✓ |
templates/NOTES.txt | ✓ | ✓ |
| Subcharts (scoping values + globals) | ✓ | ✓ |
| Hooks (9 phases) | ✓ | ✓ + sync waves |
| Server-Side Apply | ✓ | ✓ |
lookup() | ✓ | ✓ + timeout + warnings |
Runner helm test | ✓ | ✓ (sherpack test) |
helm repo index | ✓ | ✓ (sherpack repo index) |
| Shell completion | ✓ | ✓ |
| Push/pull OCI | ✓ | ✓ |
Pack.lock.yaml (policies semver) | ✗ | ✓ |
| Détection conflit en losange | ✗ | ✓ |
| Mises à jour CRD intelligentes | ✗ | ✓ (24 types de changement) |
| Chunking du release storage > 1 Mo | ✗ | ✓ |
| Génération de secrets idempotente | ✗ | ✓ (generate_secret) |
| Protection redirect cross-origine | ✗ | ✓ |
| Système de plugins | ✓ | ✗ |
helm get notes/hooks/metadata | ✓ | partiel |
| Recherche Artifact Hub | ✓ | ✗ |
Pièges à connaître
Les warnings lookup() demandent un niveau de log élevé
lookup() demandent un niveau de log élevéSherpack utilise tracing. La CLI est en niveau
warn par défaut sur les crates sherpack et écrit sur
stderr — tu vois donc les warnings lookup. Pour plus de détail,
mets RUST_LOG=info ou utilise --debug.
.helmignore n'est pas honoré au packaging
.helmignore n'est pas honoré au packagingLe converter le renomme en .sherpackignore mais
sherpack package ne le lit pas encore. Si tu as des
fichiers à exclure du paquet, supprime-les avant de packager.
Certaines fonctions Sprig n'ont pas d'équivalent direct
dateModify, dateInZone, htpasswd,
bcrypt, fromToml/toToml, et
les helpers OS/URL ne sont pas portés. Le converter les flag pour
qu'ils apparaissent dans le rapport de warnings.
Pas (encore) d'écosystème de plugins
Des outils comme helm-diff, helm-secrets, helm-git n'ont pas de
remplaçants directs. Le natif Sherpack couvre le diff
(--diff), la génération idempotente de secrets, et les
lock files — mais si tu dépends fortement de plugins, évalue
avec attention.
Tu peux faire tourner Sherpack et Helm côte à côte
Sherpack stocke les releases sous un label différent
(app.kubernetes.io/managed-by=sherpack) et utilise des
annotations différentes. Les releases Helm restent invisibles à
Sherpack et inversement — pratique pendant une migration progressive.
FAQ
Mes charts Helm existants continueront-ils de fonctionner avec Helm ?
Oui. sherpack convert écrit un nouveau Pack dans un dossier
séparé ; ton chart d'origine n'est pas touché. Fais tourner les deux côte
à côte tant que tu n'es pas confiant dans la migration.
Et les subcharts et les umbrella charts ?
Sherpack gère les subcharts avec la même sémantique de scoping de values
et de globals que Helm. Le dossier charts/ devient
packs/ ; les références dans Pack.yaml miroitent
le bloc dependency du Chart.yaml de Helm.
La sortie rendue est-elle byte-identique à celle de Helm ?
Pour la plupart des charts, oui — modulo les whitespaces et les
différences listées dans l'antisèche. Lance
sherpack template et helm template sur les mêmes
entrées et fais un diff pour vérifier avant d'installer en production.
Puis-je utiliser Sherpack avec ArgoCD ou Flux ?
Oui — rends avec sherpack template et laisse le contrôleur
GitOps appliquer. Ne mélange pas sherpack install impératif
avec la réconciliation GitOps ; choisis l'un ou l'autre.
Performance vs Helm ?
Binaire Rust natif, ~19 Mo, pas de runtime Go. Les temps de rendu pour les charts typiques sont sub-secondes. Le moteur MiniJinja est rapide, mais les vrais gains sont sur la recherche (SQLite FTS5) et la résolution de dépendances.