helm-fullstack-chart

Chart Helm réutilisable pour applications web full-stack (frontend React + backend Node.js + MongoDB) sur K3s / K3d, publié en OCI sur GHCR.

Un même chart couvre le développement local, la préproduction et la production : chaque environnement active ses propres options (TLS, sécurité, autoscaling, sauvegardes, monitoring) par simple combinaison de fichiers de values.

Dépôt vitrine. Version publique d'un chart utilisé en production comme dépendance d'un chart applicatif privé. Les valeurs propres à l'application réelle ont été remplacées par des valeurs génériques (my-app, example.com). L'infrastructure qui l'héberge est présentée dans k3s-gitops-platform.

Démarrage rapide

# 1. Installer les dépendances du chart
helm dependency update

# 2. Déployer en local (k3d, sans TLS)
helm upgrade --install my-release . -f values-k3d.yaml

C'est tout pour un environnement de développement local. Pour preprod/production, voir Installation et Environnements ci-dessous.

Points d'attention

Ces quatre points sont les pièges les plus probables lors d'un déploiement :

⚠️ Point	Détail
TLS	Géré nativement par Traefik via ACME/Let's Encrypt. `cert-manager` n'est pas requis et ne doit jamais être activé (`ingress.tls.certManager.enabled=true`) en même temps que le certResolver Traefik : les deux mécanismes entrent en conflit silencieux et aucun certificat n'est émis.
Monitoring	Prometheus, Grafana, Loki et Promtail sont installés au niveau infra via ArgoCD, pas par ce chart. Ce chart crée uniquement les `ServiceMonitor` / `PrometheusRule` qui s'y branchent via les CRDs déjà présentes sur le cluster.
Secrets obligatoires	`backend.secrets.mongodbUri`, `backend.secrets.jwtSecret` et `database.secrets.password` n'ont pas de valeur par défaut : le déploiement échoue tant qu'ils ne sont pas renseignés (directement en dev, via Infisical/External Secrets en preprod/prod).
Seed Job en production	`seedJob.enabled` doit être mis à `false` en production : il est pensé pour initialiser des données de démo, pas pour une base contenant des données réelles.

Garde-fous

templates/00-validation.yaml ne crée aucune ressource : il fait échouer helm install / helm upgrade avant tout déploiement si la configuration est dangereuse. Exemples :

préprod / production sans External Secrets, ou sans ClusterSecretStore défini ;
images en latest ou sans tag en préprod / production (tag sha-… obligatoire) ;
backups de production sans copie hors site (R2), ou sans nom de base valide ;
restore-test ou restore-prod activés sans R2 ou sans collection à vérifier ;
restauration de production avec un nom de backup implicite ou dangereux (le job exige en plus la confirmation RESTORE:<dbName> à l'exécution).

Ces garde-fous sont eux-mêmes testés en CI (voir CI & release).

Prérequis

Helm v3.x
Kubernetes 1.25+ (K3s ou K3d)
External Secrets Operator (pour les secrets en preprod/prod)
Infisical (gestionnaire de secrets)
Stack monitoring installée au niveau infra via ArgoCD (kube-prometheus-stack + loki-stack)

Installation

Utilisation comme dépendance dans un autre chart

Déclarer la dépendance dans le Chart.yaml du chart applicatif :

dependencies:
  - name: fullstack-app
    version: "^1.0.0"
    repository: "oci://ghcr.io/roxane451"

helm dependency update

Puis surcharger les valeurs avec les fichiers propres à l'application :

helm upgrade --install my-release . \
  -f values-k3s-base.yaml \
  -f values-preprod.yaml \
  --namespace my-namespace

Installation directe

helm install my-release oci://ghcr.io/roxane451/fullstack-app \
  --version <version> \
  -f my-values.yaml

Environnements

Environnement	Values à combiner	URL exemple
développement local (k3d)	`values-k3d.yaml`	http://localhost
preprod	`values-k3s-base.yaml` + `values-preprod.yaml`	https://preprod.my-app.fr
production	`values-k3s-base.yaml` + `values-production.yaml`	https://my-app.fr

Services par environnement

Applicatif

Service	k3d local	preprod	production
Frontend	✅ 1 replica	✅ 1 replica	✅ 2 replicas (HA)
Backend	✅ 1 replica	✅ 1 replica	✅ 2 replicas (HA)
MongoDB	✅	✅	✅
Seed Job	✅	✅	❌ (désactivé — données réelles)
Autoscaling (HPA)	❌	❌	✅ (2→4 replicas)

Réseau & TLS

Service	k3d local	preprod	production
Ingress	✅ Traefik	✅ Traefik	✅ Traefik
TLS	❌ HTTP only	✅ Let's Encrypt staging	✅ Let's Encrypt prod (natif Traefik)
Redirect HTTPS	❌	❌	✅

Sécurité (par environnement)

Service	k3d local	preprod	production
Pod Security Standards	❌	✅ restricted	✅ restricted
Network Policies	❌	✅	✅
Resource Quota	❌	✅	✅
Limit Range	❌	✅	✅
RBAC	✅	✅	✅
External Secrets	❌ (secrets directs)	✅ Infisical	✅ Infisical

Observabilité (par environnement)

La stack monitoring (Prometheus, Grafana, Loki) est installée au niveau infra via ArgoCD, indépendamment de ce chart. Ce chart crée uniquement les ressources qui s'y branchent.

Service	k3d local	preprod	production
ServiceMonitor backend	❌	❌	✅
PrometheusRules (alertes)	❌	❌	✅
Prometheus	✅ infra	✅ infra	✅ infra
Grafana	✅ infra	✅ infra	✅ infra
Loki + Promtail	✅ infra	✅ infra	✅ infra

Stockage & Backups

Paramètre	k3d local	preprod	production
StorageClass	`local-path`	`local-path`	`local-path`
Volume MongoDB	10 Gi	10 Gi	20 Gi
Backup MongoDB	❌	✅ (rétention 7j)	✅ (rétention 30j, R2)

Values

Global

Paramètre	Description	Défaut
`global.appName`	Nom de l'application	`my-app`
`global.environment`	Environnement (`development`, `preprod`, `production`)	`development`
`global.domain`	Domaine de l'application	`localhost`
`global.imageRegistry`	Registry des images Docker	`my-registry.example.com`

Backend

Paramètre	Description	Défaut
`backend.enabled`	Activer le backend	`true`
`backend.image.repository`	Image Docker du backend	`my-registry.example.com/my-app/backend`
`backend.image.tag`	Tag de l'image — surchargé par le CI	`latest`
`backend.replicaCount`	Nombre de replicas	`1`
`backend.secrets.mongodbUri`	URI MongoDB complète	`""` ⚠️ obligatoire
`backend.secrets.jwtSecret`	Clé secrète JWT (min. 32 caractères)	`""` ⚠️ obligatoire
`backend.jwtExpiry`	Durée de validité des tokens JWT	`24h`
`backend.autoscaling.enabled`	Activer le HPA	`false`
`backend.autoscaling.minReplicas`	Replicas minimum (HPA)	`1`
`backend.autoscaling.maxReplicas`	Replicas maximum (HPA)	`3`
`backend.resources.requests.cpu`	CPU demandé	`100m`
`backend.resources.requests.memory`	Mémoire demandée	`256Mi`
`backend.resources.limits.cpu`	CPU limite	`500m`
`backend.resources.limits.memory`	Mémoire limite	`512Mi`

Frontend

Paramètre	Description	Défaut
`frontend.enabled`	Activer le frontend	`true`
`frontend.image.repository`	Image Docker du frontend	`my-registry.example.com/my-app/frontend`
`frontend.image.tag`	Tag de l'image — surchargé par le CI	`latest`
`frontend.replicaCount`	Nombre de replicas	`1`
`frontend.autoscaling.enabled`	Activer le HPA	`false`
`frontend.resources.requests.cpu`	CPU demandé	`50m`
`frontend.resources.requests.memory`	Mémoire demandée	`128Mi`
`frontend.resources.limits.cpu`	CPU limite	`200m`
`frontend.resources.limits.memory`	Mémoire limite	`256Mi`

Base de données (MongoDB)

Paramètre	Description	Défaut
`database.enabled`	Activer MongoDB	`true`
`database.image.tag`	Version MongoDB	`7.0`
`database.secrets.username`	Utilisateur MongoDB	`mongoUser`
`database.secrets.password`	Mot de passe MongoDB	`""` ⚠️ obligatoire
`database.persistence.storageClass`	StorageClass Kubernetes	`local-path`
`database.persistence.size`	Taille du volume MongoDB	`10Gi`
`database.backup.enabled`	Activer les backups	`false`
`database.backup.schedule`	Cron de backup	`0 2 * * *`
`database.backup.retentionDays`	Rétention des backups (jours)	`7`
`database.backup.storage`	Taille du volume de backup	`20Gi`
`database.backup.r2.enabled`	Activer l'upload vers Cloudflare R2	`false`
`database.exporter.image.repository`	Image du sidecar mongodb_exporter	`percona/mongodb_exporter`
`database.exporter.image.tag`	Tag du sidecar mongodb_exporter	`0.40`
`database.exporter.port`	Port exposé par le sidecar mongodb_exporter	`9216`

ℹ️ Le sidecar mongodb_exporter n'a pas de flag d'activation dédié : il est ajouté automatiquement au pod MongoDB dès que monitoring.enabled=true (voir templates/database/statefulset.yaml).

Ingress

Paramètre	Description	Défaut
`ingress.enabled`	Activer l'Ingress	`true`
`ingress.className`	Ingress controller	`traefik`
`ingress.tls.enabled`	Activer TLS	`false`
`ingress.tls.secretName`	Nom du secret TLS	`tls-my-app`
`ingress.tls.clusterIssuer`	ClusterIssuer cert-manager (si activé)	`letsencrypt-staging`
`ingress.tls.certManager.enabled`	Activer cert-manager pour le TLS — voir Points d'attention	`false`
`ingress.security.hstsSeconds`	Durée HSTS en secondes	`31536000`
`ingress.rateLimit.average`	Limite moyenne de requêtes (rate limiting Traefik)	`100`
`ingress.rateLimit.burst`	Limite en pic (rate limiting Traefik)	`200`

Sécurité (paramètres)

Paramètre	Description	Défaut
`security.podSecurityStandards.enabled`	Activer Pod Security Standards	`false`
`security.podSecurityStandards.enforce`	Niveau PSS	`restricted`
`security.networkPolicies.enabled`	Activer les NetworkPolicies	`false`
`security.networkPolicies.ingressNamespace`	Namespace de l'ingress controller	`kube-system`
`security.rbac.enabled`	Activer le RBAC	`true`
`security.resourceQuota.enabled`	Activer le ResourceQuota	`false`
`security.limitRange.enabled`	Activer le LimitRange	`false`

External Secrets (Infisical)

Paramètre	Description	Défaut
`externalSecrets.enabled`	Activer External Secrets	`false`
`externalSecrets.secretStores.backend`	ClusterSecretStore pour le backend	`my-secret-store`
`externalSecrets.secretStores.database`	ClusterSecretStore pour MongoDB	`my-secret-store`
`externalSecrets.secretStores.r2`	ClusterSecretStore pour Cloudflare R2	`my-secret-store`

Seed Job

Paramètre	Description	Défaut
`seedJob.enabled`	Activer le job d'initialisation de la base	`true`
`seedJob.backoffLimit`	Nombre de tentatives en cas d'échec	`3`
`seedJob.ttlSecondsAfterFinished`	Durée avant suppression automatique du job	`3600`
`seedJob.initContainer.image`	Image busybox pour l'init container	`busybox:1.36`

Observabilité (paramètres)

Paramètre	Description	Défaut
`monitoring.enabled`	Activer ServiceMonitor + PrometheusRules	`false`
`monitoring.stack.enabled`	Déployer kube-prometheus-stack (local uniquement)	`false`
`monitoring.logs.enabled`	Déployer loki-stack (local uniquement)	`false`
`monitoring.alerts.enabled`	Activer les alertes Prometheus	`false`
`monitoring.minimalAlerts.enabled`	Activer les alertes minimales (CrashLoop, restarts)	`false`
`monitoring.minimalAlerts.podRestartThreshold`	Seuil de restarts pour alerte	`3`
`monitoring.prometheus.interval`	Intervalle de scrape	`30s`
`monitoring.prometheus.scrapeTimeout`	Timeout de scrape	`10s`

⚠️ monitoring.stack.enabled et monitoring.logs.enabled sont réservés au développement local (k3d). En preprod/production, la stack monitoring est gérée par ArgoCD au niveau infra.

Réseau

Paramètre	Description	Défaut
`network.dnsPort`	Port DNS utilisé dans les NetworkPolicies	`53`

CI & release

Workflow unique : .github/workflows/ci-release.yml, sans aucun secret à configurer (tout passe par le GITHUB_TOKEN).

Étape	Déclencheur	Contrôles
Lint	PR et push	`helm lint --strict` sur les values par défaut, k3d, préprod et production
Tests de rendu	PR et push	`helm template` par environnement + assertions sur le rendu (probes, CronJobs de backup et de restore, alertes)
Test négatif	PR et push	vérifie que le chart refuse un backup de production sans R2
Release	push sur `main`	semantic-release : version calculée depuis les Conventional Commits, `Chart.yaml` mis à jour, tag et release GitHub
Publication	nouvelle release	`helm package` + `helm push` vers `oci://ghcr.io/roxane451/fullstack-app`

La stack de monitoring (kube-prometheus-stack, Loki) n'est pas une dépendance du chart : elle est installée au niveau infrastructure. Le chart ne crée que les ServiceMonitor et PrometheusRule qui s'y branchent.

Licence

Apache 2.0 — Roxane451

Navigation Menu

Repository navigation

About

Repository files navigation

helm-fullstack-chart

Sommaire

Démarrage rapide

Points d'attention

Garde-fous

Prérequis

Installation

Utilisation comme dépendance dans un autre chart

Installation directe

Environnements

Services par environnement

Applicatif

Réseau & TLS

Sécurité (par environnement)

Observabilité (par environnement)

Stockage & Backups

Values

Global

Backend

Frontend

Base de données (MongoDB)

Ingress

Sécurité (paramètres)

External Secrets (Infisical)

Seed Job

Observabilité (paramètres)

Réseau

CI & release

Licence

About

Releases

Packages

Contributors

Languages

Name		Name	Last commit message	Last commit date
.github/workflows		.github/workflows
templates		templates
.gitignore		.gitignore
.helmignore		.helmignore
.pre-commit-config.yaml		.pre-commit-config.yaml
.releaserc		.releaserc
Chart.yaml		Chart.yaml
LICENSE		LICENSE
README.md		README.md
package-lock.json		package-lock.json
package.json		package.json
values-k3d.yaml		values-k3d.yaml
values-k3s-base.yaml		values-k3s-base.yaml
values-preprod.yaml		values-preprod.yaml
values-production.yaml		values-production.yaml
values.yaml		values.yaml

Latest commit

History

Folders and files

Repository files navigation

helm-fullstack-chart

Sommaire

Démarrage rapide

Points d'attention

Garde-fous

Prérequis

Installation

Utilisation comme dépendance dans un autre chart

Installation directe

Environnements

Services par environnement

Applicatif

Réseau & TLS

Sécurité (par environnement)

Observabilité (par environnement)

Stockage & Backups

Values

Global

Backend

Frontend

Base de données (MongoDB)

Ingress

Sécurité (paramètres)

External Secrets (Infisical)

Seed Job

Observabilité (paramètres)

Réseau

CI & release

Licence

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages