Déployer sur Kubernetes

Vaks PM · Déploiement sur un cluster existant · Kubernetes · juin 2026

Vue d'ensemble

Vaks PM est livré sous la forme d'un petit ensemble d'images de conteneur et est conçu pour fonctionner entièrement sur une infrastructure contrôlée par l'organisation, sans dépendance obligatoire à un service en ligne externe. Les seules connexions sortantes optionnelles sont un relais de messagerie (pour les notifications) et un fournisseur d'identité d'entreprise (pour l'authentification unique).

Ce guide couvre le parcours d'installation Kubernetes, destiné aux organisations qui exploitent déjà un cluster Kubernetes. L'autre parcours pris en charge, un installateur guidé qui provisionne un cluster Docker Swarm de zéro via SSH, est documenté séparément dans Déployer sur Docker Swarm. Les deux parcours exécutent la même application à partir des mêmes images ; le choix est dicté par l'outillage opérationnel existant, pas par des différences de fonctionnalités.

L'installation utilise Helm, le gestionnaire de paquets de Kubernetes. Un chart (paquet Helm) prêt à l'emploi est fourni dans le dépôt à deploy/helm/vaks-pm. Le chart déploie tous les services applicatifs sans état et, en option, les trois dépendances de support (base de données, cache, stockage objet) soit à l'intérieur du cluster (pour l'évaluation), soit en pointant vers des services externes existants (la recommandation de production).

Glossaire

Les acronymes et termes utilisés tout au long de ce guide, définis ici une fois pour référence.

Architecture déployée

Quelles que soient les options choisies, le système en exécution est le même ensemble de services. L'application est sans état là où elle peut l'être (les services api, web et worker ne détiennent aucune donnée locale et passent à l'échelle horizontalement) ; tout l'état durable vit dans trois magasins de support : PostgreSQL, Redis et le magasin d'objets S3.

Une tâche de migration de schéma (un hook Helm nommé vaks-pm-dbpush) s'exécute automatiquement à chaque installation et mise à niveau, avant le démarrage des services, pour synchroniser la structure de la base de données. Aucune étape de migration manuelle n'est requise.

Routage réseau (Ingress)

Le chart génère un unique Ingress qui répartit le trafic d'un seul nom d'hôte par chemin de requête :

Modes de tenancy

Le chart prend en charge deux modèles de tenancy, sélectionnés par tenancy.mode. Ceci est indépendant de la décision mono-vs-HA de la section suivante.

Prérequis et état initial

Les listes ci-dessous décrivent le point de départ attendu avant l'exécution de toute commande d'installation. L'état initial attendu est un cluster Kubernetes opérationnel sur lequel l'administrateur dispose des pleins droits sur au moins un namespace.

Cluster et poste de travail

Réseau et certificats

• Un nom d'hôte public pour l'instance (par exemple pm.example.com) et l'autorité pour créer un enregistrement DNS le pointant vers le point d'entrée du contrôleur Ingress.
• Pour la production, un certificat TLS pour ce nom d'hôte, fourni comme un Secret Kubernetes existant ou émis automatiquement par un gestionnaire de certificats (par exemple cert-manager).
• Seul le port HTTPS standard (443) doit être joignable depuis les clients ; tout le reste reste à l'intérieur du cluster.

Optionnel, configurable après l'installation

• Un relais de messagerie sortant (SMTP) pour les notifications.
• Un fournisseur d'identité d'entreprise (par exemple Microsoft Entra ID) uniquement si l'authentification unique est requise.
• Pour la production : des services PostgreSQL, Redis et S3 existants. Pour l'évaluation seulement, le chart peut embarquer les trois dans le cluster.

Mono vs HA · choisir la topologie

Le chart peut s'installer sous deux formes très différentes. Ce choix est indépendant du mode de tenancy et constitue la décision la plus lourde de conséquences pour un déploiement de production. Lire le tableau attentivement : une installation mono ne convient qu'à l'évaluation.

Dimensionnement

Les valeurs ci-dessous sont les requests (réservations) par défaut du chart, indicatives pour un déploiement de production servant environ 200 utilisateurs. À ajuster à la charge observée. L'unité m est le milli-cœur de processeur (1000 m = 1 vCPU) ; Mi et Gi sont des mébioctets et des gibioctets de mémoire.

Images · miroir et identifiants de pull

Trois images applicatives sont requises : vaks-pm/api, vaks-pm/web et vaks-pm/worker. Les recopier dans un registre que le cluster peut atteindre, puis noter l'adresse hôte de ce registre (par exemple registry.example.com). Définir l'hôte comme image.registry ; le chart ajoute le dépôt (vaks-pm/api et ainsi de suite), donnant registry.example.com/vaks-pm/api. Ne pas répéter le segment vaks-pm dans image.registry.

Si le registre stocke les images sous des noms différents, surcharger image.api.repository, image.web.repository et image.worker.repository. Les trois images partagent un seul tag (image.tag, par défaut l'appVersion du chart).

Créer le namespace et, pour un registre privé, un Secret de pull à référencer ensuite via imagePullSecrets :

kubectl create namespace vaks-pm

# Private registry only:
kubectl -n vaks-pm create secret docker-registry regcred \
  --docker-server=registry.example.com \
  --docker-username=<user> \
  --docker-password=<password>

Secrets

L'application requiert quatre secrets obligatoires. Les générer avec de fortes valeurs aléatoires :

openssl rand -hex 32      # jwtAccessSecret
openssl rand -hex 32      # jwtRefreshSecret
openssl rand -base64 32   # mfaEncryptionKey
openssl rand -hex 32      # workerApiToken

Fichiers de valeurs

La configuration vit dans un fichier de valeurs passé avec -f. Deux exemples complets suivent : le Scénario A pour la production (dépendances externes, réplicas HA, anti-affinité) et le Scénario B pour l'évaluation (dépendances embarquées, réplicas uniques).

Scénario A · Production (PostgreSQL / Redis / S3 externes, HA)

Le Kubernetes propre à l'organisation, une base de données et un cache gérés, un service S3 existant, et des réplicas répartis entre les nœuds par anti-affinité. Mode mono-organisation (dedicated).

image:
  registry: registry.example.com   # host only; chart appends vaks-pm/api|web|worker
  tag: "1.0.0"
imagePullSecrets:
  - name: regcred

publicBaseUrl: https://pm.example.com
tenancy:
  mode: dedicated

# --- HA replicas ---
api:
  replicaCount: 3
  affinity:
    podAntiAffinity:
      preferredDuringSchedulingIgnoredDuringExecution:
        - weight: 100
          podAffinityTerm:
            topologyKey: kubernetes.io/hostname
            labelSelector:
              matchLabels: { app.kubernetes.io/component: api }
web:
  replicaCount: 2
worker:
  replicaCount: 3

# --- Database: managed / external ---
postgresql:
  enabled: false
externalDatabase:
  url: "postgresql://vakspm:<password>@pg.internal.example.com:5432/vakspm?schema=public"

# --- Cache: managed / external ---
redis:
  enabled: false
externalRedis:
  url: "redis://redis.internal.example.com:6379"

# --- Object storage: existing S3 service (e.g. MinIO / Ceph / AWS) ---
minio:
  enabled: false
s3:
  external:
    endpoint: "https://s3.internal.example.com:9000"
    region: us-east-1
    useSSL: true
    forcePathStyle: true        # true for MinIO/Ceph/Garage
    accessKey: "<access-key>"
    secretKey: "<secret-key>"   # prefer secrets.existingSecret
    bucketPrefix: ""
    createBuckets: true

ingress:
  enabled: true
  className: nginx
  host: pm.example.com
  tls:
    enabled: true
    secretName: pm-example-tls

# Prefer secrets.existingSecret in production (see Secrets section).
secrets:
  jwtAccessSecret: "<openssl rand -hex 32>"
  jwtRefreshSecret: "<openssl rand -hex 32>"
  mfaEncryptionKey: "<openssl rand -base64 32>"
  workerApiToken: "<openssl rand -hex 32>"

Scénario B · Évaluation (tout embarqué, réplicas uniques)

Toutes les dépendances à l'intérieur du cluster, adapté à une mise en place rapide ou hors ligne. Réplicas réduits à 1.

image:
  registry: registry.example.com   # host only; chart appends vaks-pm/api|web|worker
  tag: "1.0.0"

publicBaseUrl: https://pm.example.test
tenancy:
  mode: dedicated

api:    { replicaCount: 1 }
web:    { replicaCount: 1 }
worker: { replicaCount: 1 }

postgresql: { enabled: true }
redis:      { enabled: true }
minio:      { enabled: true }

ingress:
  enabled: true
  className: nginx
  host: pm.example.test
  tls: { enabled: false }

# Creates the demo organization and administrator account.
migrations:
  seedDemo: true

secrets:
  jwtAccessSecret: "<openssl rand -hex 32>"
  jwtRefreshSecret: "<openssl rand -hex 32>"
  mfaEncryptionKey: "<openssl rand -base64 32>"
  workerApiToken: "<openssl rand -hex 32>"

Stockage S3

Vaks PM stocke les fichiers binaires (pièces jointes de tâches, logos de branding, modèles de documents, chartes de projet et archives d'audit compressées) dans un magasin d'objets compatible S3. Toute implémentation conforme convient (Amazon S3, MinIO, Ceph RGW, Garage, NetApp StorageGRID, Wasabi…). Le chart traduit la section de stockage en variables d'environnement ; seuls les paramètres ci-dessous changent d'un fournisseur à l'autre.

L'application utilise cinq buckets (noms indiqués avant l'application du préfixe) : charter-blobs, document-templates, vaks-pm-attachments, vaks-pm-branding, vaks-pm-audit-archive. Lorsque createBuckets vaut false, créer ces cinq buckets (préfixés) au préalable et accorder au compte de service les droits de lecture, écriture, suppression et liste sur eux. Au démarrage, l'API journalise une ligne S3 backend: … résumant la configuration en vigueur.

Installation Helm

Avant d'installer, valider le rendu du chart par rapport au fichier de valeurs :

helm lint ./deploy/helm/vaks-pm -f values-production.yaml

helm template vaks-pm ./deploy/helm/vaks-pm -f values-production.yaml \
  | kubectl apply --dry-run=client -f -

Puis installer. Le --timeout laisse à la tâche de migration de schéma le temps de se terminer :

helm install vaks-pm ./deploy/helm/vaks-pm \
  -n vaks-pm --create-namespace \
  -f values-production.yaml \
  --timeout 5m

Attendre que les pods deviennent prêts :

kubectl -n vaks-pm get pods
kubectl -n vaks-pm rollout status deploy/vaks-pm-api

Vérification

Surveiller le hook de migration de schéma pendant son exécution (il se supprime automatiquement en cas de succès), puis valider chaque chemin réseau. Remplacer pm.example.com par le nom d'hôte configuré.

# Schema-migration job. It is a Helm hook DELETED automatically on success,
# so watch it while it runs rather than after:
kubectl -n vaks-pm get pods -w        # the vaks-pm-dbpush-* pod should reach Completed
# If it FAILS, the job is kept; read its logs:
kubectl -n vaks-pm logs job/vaks-pm-dbpush

# API readiness (expected response: {"status":"ok","db":"up"})
curl -s https://pm.example.com/api/v1/health/ready

# API liveness
curl -s https://pm.example.com/api/v1/health/live

# Home page (expected: HTTP 200)
curl -s -o /dev/null -w "%{http_code}\n" https://pm.example.com/

Chiffrement sur Kubernetes · vue d'ensemble

Un déploiement complet comporte trois préoccupations de chiffrement indépendantes. Elles sont orthogonales (en activer une n'active pas les autres), et seules les deux premières sont prises en charge par les valeurs de démarrage rapide.

• Secrets au niveau champ. Les secrets applicatifs (mot de passe SMTP, graines multi-facteurs, secrets client d'authentification unique) sont chiffrés à l'intérieur de la base de données par l'application elle-même, via le chiffrement à enveloppe (une DEK par tenant enveloppée par une KEK). Activé par défaut.
• En transit. Le trafic réseau : navigateur↔cluster (la bordure externe), les sauts internes vers les dépendances (base de données, cache, stockage objet), et le trafic de pod à pod.
• Au repos. Les données sur disque : les volumes de dépendances (PVC) et les Secrets Kubernetes (qui détiennent le trousseau de KEK, les clés de signature et les identifiants) dans le magasin de données du cluster.

Secrets au niveau champ (chiffrement à enveloppe)

Les champs sensibles sont chiffrés avec une DEK par tenant enveloppée par une KEK. C'est intégré et fonctionne d'emblée : la KEK est par défaut MFA_ENCRYPTION_KEY (enregistrée sous la ref env), un chemin qui fonctionne toujours à la fois pour le chiffrement et le déchiffrement. Rien de plus n'est requis pour une configuration de base.

Le chiffrement au niveau champ protège les secrets listés, pas le gros des données métier (projets, tâches, utilisateurs). Protéger l'ensemble du jeu de données au repos relève de la couche de chiffrement des volumes dans Au repos.

Options de garde (crypto.*)

Deux modèles de garde existent ; tous deux sont portables entre les parcours Swarm et Kubernetes, car l'application ne fait que lire un répertoire de trousseau monté (crypto.keysDir, par défaut /etc/vaks/keys) et ne se soucie pas de qui l'a monté.

• Trousseau de clés local. Monter un trousseau versionné de fichiers nommés kek_v<N> (base64, 32 octets) et pointer crypto.activeKek vers la version que les nouvelles écritures doivent utiliser ; les clés plus anciennes restent utilisables pour déchiffrer les blobs hérités. Fournir les clés en ligne via crypto.keks (le chart construit un Secret), ou, choix recommandé pour la production, référencer un Secret géré hors bande avec crypto.existingSecret, monté en lecture seule dans api/worker/controlplane. Cela permet la rotation de la KEK sans rechiffrer les données.
• Garde par KMS / HSM externe. Définir crypto.provider à kms ou hsm pour déplacer l'enveloppe/désenveloppe de la KEK hors de la machine, afin que la clé maîtresse ne réside jamais dans le cluster. Pour KMS, renseigner crypto.kms.keyId / region / endpoint (préférer l'identité de charge de travail aux clés statiques ; sinon un Secret via crypto.kms.existingSecret). Pour un HSM sur site, déployer le sidecar courtier de clés PKCS#11 et définir crypto.hsm.brokerUrl / keyLabel avec le jeton partagé dans crypto.hsm.existingSecret. Seule la KEK quitte la machine ; la DEK par tenant reste locale. La migration est en ligne : déployer avec le fournisseur défini, puis ré-envelopper via Admin → Clés de chiffrement.

En transit

Bordure externe (Ingress)

Terminer HTTPS au niveau de l'Ingress en fournissant un certificat comme un Secret Kubernetes existant, ou en laissant un gestionnaire de certificats en émettre un :

ingress:
  enabled: true
  className: nginx          # or traefik
  host: pm.example.com
  tls:
    enabled: true
    secretName: pm-example-tls  # cert-manager or supplied

Services internes (base de données, cache, stockage objet)

Ces sauts transportent les données de l'application vers ses dépendances et sont en clair sauf s'ils sont activés. Chacun est un réglage distinct :

Réseau de pod à pod

La façon la plus simple de chiffrer tout le trafic intra-cluster d'un coup, y compris les sauts vers la base de données, le cache, le stockage objet et tout courtier KMS/HSM, est de chiffrer le réseau de pods lui-même plutôt que chaque service individuellement :

• CNI chiffré. Par exemple un backend WireGuard (tel que k3s --flannel-backend=wireguard-native), ou Cilium / Calico avec le chiffrement activé. Cela chiffre le trafic de pods de nœud à nœud sans aucun changement de l'application.
• mTLS de maillage de services. Un maillage (Istio, Linkerd) impose le TLS mutuel entre les pods.

Au repos

Volumes de données (PVC)

Les volumes de la base de données, du cache et du stockage objet contiennent l'ensemble du jeu de données (pas seulement les secrets au niveau champ). Les chiffrer avec une StorageClass chiffrée ; seuls les volumes sont chiffrés, jamais le système d'exploitation du nœud :

postgresql:
  persistence:
    storageClass: gp3-encrypted   # a cloud-KMS or CSI-encrypted class
# do the same for redis.persistence.storageClass / minio.persistence.storageClass,
# or use managed services with provider-side encryption

Options : une classe de stockage en bloc chiffrée d'un fournisseur cloud (adossée à un KMS), un pilote Container Storage Interface (CSI) avec chiffrement, ou des nœuds dont les disques sont chiffrés (par exemple LUKS, Linux Unified Key Setup). Lorsque les dépendances sont externes/gérées, utiliser plutôt le chiffrement du fournisseur (chiffrement RDS, chiffrement côté serveur S3, et ainsi de suite).

Secrets Kubernetes

Le trousseau de KEK, les clés de signature et les identifiants de base de données/stockage vivent dans des Secrets Kubernetes. Un Secret n'est qu'encodé en base64 dans le magasin de données du cluster, non chiffré par défaut. Le protéger avec l'un des éléments suivants :

• Chiffrement du magasin de données au repos. Une EncryptionConfiguration avec un fournisseur aescbc ou (mieux) un fournisseur kms sur le serveur d'API. Sur k3s, c'est le k3s secrets-encrypt enable intégré, qui requiert le magasin de données etcd embarqué (installer avec --cluster-init ; il n'a aucun effet sur le magasin de données SQLite par défaut).
• Magasin de secrets externe. L'External Secrets Operator, un pilote de secrets CSI ou un contrôleur de Secrets scellés, afin que le matériel cryptographique provienne d'un coffre plutôt que d'être stocké dans le magasin de données. Cela se combine avec secrets.existingSecret et crypto.existingSecret.
• Garde de la KEK hors machine. Déplacer la KEK vers un KMS/HSM (voir Secrets au niveau champ) signifie que la clé la plus sensible n'est jamais dans un Secret Kubernetes du tout.

Exemple HA chiffré

Ce fichier de valeurs consolidé réunit la forme HA de production avec chaque contrôle de chiffrement au niveau applicatif activé. Il repose toujours sur des contrôles au niveau du cluster (CNI chiffré, chiffrement des Secrets du magasin de données) configurés en dehors de Helm, comme noté dans les commentaires.

image:
  registry: registry.example.com
  tag: "1.0.0"
imagePullSecrets:
  - name: regcred

publicBaseUrl: https://pm.example.com
tenancy:
  mode: dedicated

# --- HA replicas + anti-affinity ---
api:    { replicaCount: 3 }
web:    { replicaCount: 2 }
worker: { replicaCount: 3 }

# --- External, managed, TLS-terminating dependencies ---
postgresql:
  enabled: false
externalDatabase:
  url: "postgresql://vakspm:<password>@pg.internal.example.com:5432/vakspm?schema=public&sslmode=require"
redis:
  enabled: false
externalRedis:
  url: "rediss://redis.internal.example.com:6379"   # rediss:// = TLS
minio:
  enabled: false
s3:
  external:
    endpoint: "https://s3.internal.example.com:9000"
    region: us-east-1
    useSSL: true                # TLS to object storage
    forcePathStyle: true
    accessKey: "<access-key>"
    secretKey: "<secret-key>"
    createBuckets: true

# --- In-transit TLS to PostgreSQL with CA verification ---
tls:
  postgres: true                # PG_TLS=1
  postgresCaSecret: pg-ca       # Secret holding ca.crt
  postgresVerifyMode: verify-full

# --- External edge TLS ---
ingress:
  enabled: true
  className: nginx
  host: pm.example.com
  tls:
    enabled: true
    secretName: pm-example-tls

# --- Field-level KEK: versioned keyring with rotation ---
crypto:
  existingSecret: vaks-pm-keyring   # holds kek_v1, kek_v2, …
  activeKek: v2                     # new writes wrap with kek_v2

# --- All sensitive values from an out-of-band Secret ---
secrets:
  existingSecret: vaks-pm-secrets

# Cluster-level controls configured OUTSIDE Helm (plan before building):
#   * encrypted CNI (e.g. WireGuard) for pod-to-pod traffic
#   * datastore Secret encryption (EncryptionConfiguration / k3s secrets-encrypt)
#   * encrypted StorageClass for any in-cluster PVCs (none here: all deps external)

Mise à niveau

Une mise à niveau pointe la release vers un tag d'image plus récent et réapplique le chart. Le client ne construit ni ne modifie jamais de code — seul le tag change. Comme les services applicatifs sont sans état et exécutent plusieurs réplicas, Kubernetes procède par rolling update (les nouveaux pods doivent passer leur sonde de readiness avant que les anciens ne soient retirés), donc l'opération est sans interruption. Le schéma de base de données voyage avec l'image et est appliqué par un Job de type hook Helm ; il n'y a donc pas de pack de migrations SQL à jouer séparément dans le cas courant.

1 · Mettre le nouveau tag d'image en miroir

Le chart tire les trois images (api, web, worker) depuis le registre nommé dans image.registry, au tag indiqué dans image.tag. Mettre d'abord la nouvelle version en miroir dans ce registre (voir Images · miroir et identifiants de pull), pour que chaque nœud puisse la tirer. Épingler un tag de version unique (par ex. 1.4.0) plutôt qu'un tag mobile, afin que la révision déployée soit reproductible.

2 · Lancer la mise à niveau

Fixer le nouveau tag et réappliquer le même fichier de valeurs. Le --timeout laisse au hook de migration de schéma le temps de se terminer avant que Helm ne bascule les pods applicatifs :

helm upgrade vaks-pm ./deploy/helm/vaks-pm \
  -n vaks-pm -f values-production.yaml \
  --set image.tag=1.4.0 --timeout 5m

kubectl -n vaks-pm rollout status deploy/vaks-pm-api      # new pods Ready
kubectl -n vaks-pm rollout status deploy/vaks-pm-web

Helm exécute le hook vaks-pm-dbpush (ci-dessous) en étape pre-upgrade, de sorte que le schéma est aligné avant le démarrage des nouveaux pods api. Si le hook échoue, la mise à niveau s'arrête et les pods en fonctionnement continuent de servir l'ancienne version.

3 · Schéma de base de données

Le schéma voyage dans l'image. Le chart embarque un Job de type hook Helm, vaks-pm-dbpush, qui exécute prisma db push à l'installation et à la mise à niveau (conditionné par migrations.enabled, actif par défaut). Il s'auto-supprime en cas de succès et est conservé en cas d'échec pour inspection — donc pour une mise à niveau de routine, il n'y a aucune étape de migration manuelle.

# observer le hook pendant qu'il tourne (supprimé en cas de succès) :
kubectl -n vaks-pm get pods -w             # vaks-pm-dbpush-* doit atteindre Completed
kubectl -n vaks-pm logs job/vaks-pm-dbpush # présent uniquement s'il a ÉCHOUÉ

kubectl -n vaks-pm run dbpush --rm -it --restart=Never \
  --image=<registre>/vaks-pm/api:1.4.0 \
  --env DATABASE_URL='postgresql://<owner>:…@<host>:5432/<db>' \
  -- sh -c 'cd /app/api && npx prisma db push --accept-data-loss'

4 · Retour arrière

Pour revenir à la release précédente (tag d'image, valeurs et manifestes) :

helm history vaks-pm -n vaks-pm            # trouver la révision saine précédente
helm rollback vaks-pm <revision> -n vaks-pm --timeout 5m

5 · Vérifier après la mise à niveau

kubectl -n vaks-pm get pods                       # tous Running sur la nouvelle image
curl -s https://pm.example.com/api/v1/health/ready   # {"status":"ok","db":"up"}

Tous les pods applicatifs Running sur le nouveau tag, le hook de migration Completed, la connexion fonctionne, et un envoi de pièce jointe réussit (exerce le chemin S3). Ajouter une organisation (mode pooled) n'est pas une mise à niveau : provisionner un nouveau tenant avec sa propre base de données et son nom d'hôte ; les tenants existants ne sont pas perturbés.

Désinstallation

helm uninstall vaks-pm -n vaks-pm

Référence des paramètres

Les paramètres les plus utilisés. Voir deploy/helm/vaks-pm/values.yaml pour la liste exhaustive et commentée.

Dépannage

Connexes : Le produit · Architecture · Déployer sur Docker Swarm · Sécurité · Exploitation · Démo