Comment installer n8n sur Ku­ber­netes ?

Ku­ber­netes permet de déployer, de gérer et de mettre à l’échelle des ap­pli­ca­tions comme n8n dans des con­te­neurs. Dans ce guide, vous découvrez comment installer n8n sur Ku­ber­netes afin de créer une base propre et com­pré­hen­sible pour son uti­li­sa­tion future.

Étape 1 : vérifier les prérequis et choisir le serveur adapté

Avant d’installer n8n avec Ku­ber­netes, vous avez d’abord besoin d’un serveur Linux, idéa­le­ment avec une adresse IP publique fixe, votre propre domaine ou sous-domaine et un accès root. Pour ce guide, le plus simple est d’utiliser un seul serveur basé sur Ubuntu, sur lequel un Ku­ber­netes léger comme K3s sera ensuite configuré. K3s est bien adapté pour débuter et intègre déjà plusieurs com­po­sants typiques de Ku­ber­netes.

De plus, il est important de choisir une taille de serveur réaliste. Vous devez tenir compte du fait que Ku­ber­netes apporte lui-même des com­po­sants système sup­plé­men­taires et que n8n a aussi besoin de mémoire ainsi que de CPU. Vous trouverez ci-après quelques cas d’usage typiques et les serveurs adaptés.

En­vi­ron­ne­ment d’ap­pren­tis­sage et de test pour un usage privé

Si vous souhaitez d’abord découvrir n8n sur Ku­ber­netes, une petite con­fi­gu­ra­tion de serveur suffit largement. Dans ce scénario, l’objectif principal est de créer vos premiers workflows n8n, de com­prendre l’interface et de tester des au­to­ma­ti­sa­tions simples. La charge reste gé­né­ra­le­ment faible, car seuls quelques workflows s’exécutent en parallèle et aucune uti­li­sa­tion per­ma­nente n’a lieu en arrière-plan. Pour cela, un VPS avec 2 vCores, 2 Go de RAM et 80 Go NVMe est le plus souvent suffisant. Gardez toutefois à l’esprit que Ku­ber­netes consomme déjà des res­sources, ce qui limite les per­for­mances dis­po­nibles. Cette variante n’est donc que par­tiel­le­ment adaptée aux workflows pro­duc­tifs ou exécutés en continu.

Uti­li­sa­teurs privés avec usage en pro­duc­tion ou petites startups

Si vous souhaitez utiliser n8n Ku­ber­netes ac­ti­ve­ment au quotidien, par exemple pour des au­to­ma­ti­sa­tions entre des outils, des API ou vos propres projets, vous devriez prévoir un peu plus de per­for­mances. Dans ce cas d’usage, les workflows s’exécutent ou sont dé­clen­chés par des webhooks. Les premières uti­li­sa­tions en équipe ou les petits projets sont aussi en­vi­sa­geables. Une con­fi­gu­ra­tion avec 4 vCores, 4 Go de RAM et 120 Go NVMe offre un bon compromis entre per­for­mances et coûts. Vous disposez ainsi de réserves suf­fi­santes pour plusieurs exé­cu­tions de workflows en parallèle. Cette variante constitue donc une bonne base pour un usage en pro­duc­tion.

PME avec plusieurs workflows et exé­cu­tions ré­gu­lières

Pour les petites et moyennes en­tre­prises, n8n est souvent utilisé pour au­to­ma­ti­ser des processus métier. Des exemples typiques sont l’in­té­gra­tion de systèmes de CRM, les au­to­ma­ti­sa­tions d’email ou le trai­te­ment des commandes provenant d’une boutique en ligne. Dans de tels scénarios, les workflows s’exécutent ré­gu­liè­re­ment et parfois en parallèle, ce qui augmente nettement la charge du système. Une con­fi­gu­ra­tion avec 6 vCores, 8 Go de RAM et 240 Go NVMe fournit ici une base stable pour un fonc­tion­ne­ment en pro­duc­tion. Vous bé­né­fi­ciez d’exé­cu­tions plus rapides et évitez les goulets d’étran­gle­ment lorsque plusieurs processus tournent si­mul­ta­né­ment. Vous disposez en outre d’une marge suf­fi­sante pour étendre l’ins­tal­la­tion ul­té­rieu­re­ment.

Équipes en crois­sance, agences ou en­vi­ron­ne­ments fortement au­to­ma­ti­sés

Lorsque n8n Ku­ber­netes est utilisé de manière intensive et que de nombreux workflows fonc­tion­nent si­mul­ta­né­ment, les exigences aug­men­tent con­si­dé­ra­ble­ment. Dans les agences ou les équipes plus im­por­tantes, de nom­breuses au­to­ma­ti­sa­tions s’exécutent souvent en parallèle, car elles couvrent le marketing, le trai­te­ment des données et les processus internes. Les workflows plus complexes, avec plusieurs appels d’API ou des durées d’exécution plus longues, sont également courants. Une con­fi­gu­ra­tion plus puissante avec 8 vCores, 16 Go de RAM et 480 Go NVMe garantit la stabilité et de bonnes per­for­mances système. Cette variante offre des réserves suf­fi­santes pour la crois­sance et les pics de charge plus élevés. Elle constitue une bonne base pour une extension ul­té­rieure vers des con­fi­gu­ra­tions Ku­ber­netes plus évo­lu­tives.

Tableau ré­ca­pi­tu­la­tif : serveurs et scénarios d’uti­li­sa­tion

Pour des scénarios par­ti­cu­liè­re­ment étendus, avec de nom­breuses exé­cu­tions si­mul­ta­nées ou des services sup­plé­men­taires sur le même serveur, une con­fi­gu­ra­tion plus im­por­tante avec 12 vCores, 24 Go de RAM et 720 Go NVMe peut être per­ti­nente.

Étape 2 : préparer le serveur et installer les paquets de base

Connectez-vous à votre serveur Ubuntu via SSH, puis mettez à jour les sources de paquets ainsi que les paquets déjà installés. Cette étape est im­por­tante pour démarrer sur une base propre et à jour.

sudo apt update && sudo apt upgrade -y
sudo apt install -y curl wget nano openssl

Vous pouvez ensuite vérifier que le serveur est joignable et qu’il dispose déjà d’une adresse IP publique :

hostname -I

Vérifiez l’adresse IP publique auprès de votre hébergeur. Notez cette adresse, car vous en aurez besoin dans un instant pour l’entrée DNS de votre sous-domaine.

Étape 3 : faire pointer le sous-domaine vers le serveur

Créez chez votre four­nis­seur de domaine un en­re­gis­tre­ment A pour le sous-domaine de votre choix. Si votre instance n8n Ku­ber­netes doit ensuite être ac­ces­sible sous n8n.votre-domaine.fr, ce sous-domaine doit pointer pré­ci­sé­ment vers l’adresse IP publique de votre serveur. Ce n’est que lorsque cet en­re­gis­tre­ment DNS est actif que le HTTPS et l’accès externe peuvent fonc­tion­ner de manière fiable.

Un en­re­gis­tre­ment DNS typique ressemble à ceci :

Type : A
Nom : n8n
Valeur : 203.0.113.10
TTL : 3600

Étape 4 : installer K3s

Pour les débutants, K3s est gé­né­ra­le­ment l’une des solutions les plus simples pour déployer Ku­ber­netes sur un serveur unique. K3s intègre par défaut plusieurs com­po­sants im­por­tants sous forme d’addons, notamment Traefik comme con­trô­leur d’ingress et une prise en charge du stockage per­sis­tant local.

Installez d’abord K3s avec la commande suivante :

curl -sfL https://get.k3s.io | sh -

Vérifiez ensuite avec la commande suivante si le service est en cours d’exécution :

sudo systemctl status k3s

Si tout a démarré cor­rec­te­ment, vous pouvez récupérer l’état du cluster :

sudo k3s kubectl get nodes

Close

Pour faciliter l’uti­li­sa­tion de kubectl, il est pré­fé­rable de définir un alias :

echo 'alias kubectl="sudo k3s kubectl"' >> ~/.bashrc
source ~/.bashrc
kubectl get nodes

Si votre serveur apparaît ici avec l’état « Ready », Ku­ber­netes est prêt à être utilisé.

Étape 5 : installer Helm

Le Helm Chart officiel de n8n nécessite Helm 3.12 ou une version plus récente. Helm est un ges­tion­naire de paquets pour Ku­ber­netes et joue un rôle similaire à celui d’apt sous Ubuntu. Au lieu de créer et de gérer ma­nuel­le­ment des fichiers de con­fi­gu­ra­tion in­di­vi­duels, vous pouvez installer avec Helm des ap­pli­ca­tions complètes sous forme de « charts ». L’ins­tal­la­tion devient ainsi nettement plus simple, plus claire et moins sujette aux erreurs.

Helm est par­ti­cu­liè­re­ment utile pour les débutants, car vous n’avez pas besoin de com­prendre ou d’écrire chaque fichier YAML sé­pa­ré­ment. Vous adaptez seulement quelques pa­ra­mètres centraux, et Helm se charge au­to­ma­ti­que­ment du reste. Les mises à jour ou mo­di­fi­ca­tions ul­té­rieures sont plus simples, car Helm gère l’état de votre ins­tal­la­tion.

Installez Helm di­rec­te­ment sur votre serveur. La do­cu­men­ta­tion of­fi­cielle de Helm décrit l’ins­tal­la­tion via des binaires pré­com­pi­lés. Sous Ubuntu, l’ins­tal­la­tion au moyen du script fourni est toutefois courante et par­ti­cu­liè­re­ment simple :

curl -fsSL -o get_helm.sh https://raw.githubusercontent.com/helm/helm/main/scripts/get-helm-3
chmod 700 get_helm.sh
./get_helm.sh

Avec la première commande, vous té­lé­char­gez le script d’ins­tal­la­tion. Ensuite, vous rendez le fichier exé­cu­table et vous l’exécutez. Le script installe au­to­ma­ti­que­ment Helm dans la version ap­pro­priée sur votre système.

Vérifiez ensuite si l’ins­tal­la­tion a réussi en affichant la version installée :

helm version

Close

Si un numéro de version com­pa­tible s’affiche, Helm est cor­rec­te­ment installé et vous pouvez utiliser le chart n8n.

Étape 6 : créer un namespace pour n8n

Pour séparer clai­re­ment les res­sources n8n des autres objets Ku­ber­netes, créez main­te­nant un namespace dédié. Il s’agit d’une bonne pratique courante dans Ku­ber­netes.

kubectl create namespace n8n

Vérifiez ensuite si le namespace existe bien :

kubectl get namespaces

Close

Étape 7 : installer cert-manager pour les cer­ti­fi­cats TLS

Pour une ins­tal­la­tion ac­ces­sible pu­bli­que­ment, n8n doit être dis­po­nible via HTTPS. Pour le TLS, n8n re­com­mande l’uti­li­sa­tion d’un reverse proxy ou d’une couche HTTP/HTTPS en amont. Dans ce tutoriel, Traefik remplit ce rôle dans Ku­ber­netes, tandis que cert-manager au­to­ma­tise l’émission et le re­nou­vel­le­ment des cer­ti­fi­cats. Vous pouvez aussi installer cert-manager via un chart Helm. Utilisez pour cela la commande suivante :

helm install cert-manager oci://quay.io/jetstack/charts/cert-manager \
--namespace cert-manager \
--create-namespace \
--set crds.enabled=true

Vérifiez ensuite les pods. Les pods sont la plus petite unité exé­cu­table dans Ku­ber­netes. Ils con­tien­nent un ou plusieurs con­te­neurs qui s’exécutent ensemble sur un même nœud et partagent certaines res­sources, comme le réseau et le stockage.

kubectl get pods -n cert-manager

Close

Attendez que tous les pods aient atteint le statut « Running » ou « Completed ».

Étape 8 : créer un Clus­te­rIs­suer Let’s Encrypt

Pour que cert-manager puisse ensuite créer au­to­ma­ti­que­ment des cer­ti­fi­cats pour votre domaine, créez main­te­nant un Clus­te­rIs­suer Let’s Encrypt. Un Clus­te­rIs­suer est une con­fi­gu­ra­tion centrale dans Ku­ber­netes qui définit auprès de quel four­nis­seur les cer­ti­fi­cats sont obtenus et comment la vé­ri­fi­ca­tion de votre domaine est effectuée. Dans ce cas, Let’s Encrypt est utilisé comme four­nis­seur gratuit de cer­ti­fi­cats TLS.

Pour les débutants, la va­li­da­tion via HTTP-01 est gé­né­ra­le­ment la plus simple, car elle ne nécessite aucune connexion à une API DNS. Let’s Encrypt vérifie à la place si votre domaine est joignable en ré­cu­pé­rant un fichier spé­ci­fique via votre site Web. Si cette requête aboutit, le domaine est considéré comme vérifié et le cer­ti­fi­cat est émis.

Créez un fichier nommé clusterissuer.yaml :

nano clusterissuer.yaml

Dans ce fichier, dé­fi­nis­sez ensuite les pa­ra­mètres suivants :

apiVersion: cert-manager.io/v1
kind: ClusterIssuer
metadata:
    name: letsencrypt-prod
spec:
    acme:
        email: votre-adresseemail@exemple.fr
        server: https://acme-v02.api.letsencrypt.org/directory
        privateKeySecretRef:
            name: letsencrypt-prod
        solvers:
            - http01:
                    ingress:
                        ingressClassName: traefik

Remplacez l’adresse email par la vôtre. Elle sera utilisée par Let’s Encrypt pour vous informer d’éléments im­por­tants, comme l’ex­pi­ra­tion prochaine de cer­ti­fi­cats.

Appliquez ensuite le fichier à votre cluster Ku­ber­netes :

kubectl apply -f clusterissuer.yaml

Ainsi, le Clus­te­rIs­suer est créé et dis­po­nible pour toutes les ap­pli­ca­tions du cluster. Vérifiez ensuite que la ressource a bien été créée :

kubectl get clusterissuer

Close

Si le Clus­te­rIs­suer s’affiche, la con­fi­gu­ra­tion a réussi. L’émission du cer­ti­fi­cat se fera ensuite au­to­ma­ti­que­ment dès que n8n sera ac­ces­sible via un domaine et qu’un Ingress cor­res­pon­dant aura été configuré.

Étape 9 : créer le Secret n8n avec les prin­ci­pales variables d’en­vi­ron­ne­ment

Le chart Helm officiel attend plusieurs valeurs centrales sous forme de Secret, notamment N8N_ENCRYPTION_KEY, N8N_HOST, N8N_PORT et N8N_PROTOCOL. Ces valeurs sont toujours requises. Remplacez n8n.votre-domaine.fr par votre véritable sous-domaine, puis exécutez la commande suivante :

kubectl create secret generic n8n-secrets -n n8n \
--from-literal=N8N_ENCRYPTION_KEY=$(openssl rand -hex 32) \
--from-literal=N8N_HOST=n8n.votre-domaine.fr \
--from-literal=N8N_PORT=5678 \
--from-literal=N8N_PROTOCOL=https \
--from-literal=WEBHOOK_URL=https://n8n.votre-domaine.fr/ \
--from-literal=N8N_PROXY_HOPS=1

Étape 10 : créer le fichier values pour l’ins­tal­la­tion de n8n

Nous allons installer n8n Ku­ber­netes en mode Stan­da­lone. Cela signifie que n8n fonc­tionne avec une con­fi­gu­ra­tion simple : il s’exécute dans un seul Pod et ne nécessite pas de services sup­plé­men­taires comme une base de données externe ou Redis. Une base de données SQLite intégrée est utilisée à la place. Cette variante est idéale pour les premiers projets, les petites ins­tal­la­tions ou l’ap­pren­tis­sage, car elle est nettement moins complexe.

Pour que Helm sache comment n8n doit être configuré, créez main­te­nant un fichier de con­fi­gu­ra­tion nommé n8n-values.yaml.

nano n8n-values.yaml

Dans ce fichier, vous dé­fi­nis­sez les prin­ci­paux pa­ra­mètres de votre ins­tal­la­tion, par exemple les variables d’en­vi­ron­ne­ment, l’espace de stockage ou le domaine.

queueMode:
    enabled: false
database:
    type: sqlite
    useExternal: false
redis:
    enabled: false
persistence:
    enabled: true
    size: 10Gi
secretRefs:
    existingSecret: n8n-secrets
main:
    extraEnv:
        - name: TZ
            value: Europe/Paris
ingress:
    enabled: true
    className: traefik
    annotations:
        cert-manager.io/cluster-issuer: letsencrypt-prod
    hosts:
        - host: n8n.votre-domaine.fr
            paths:
                - path: /
                    pathType: Prefix
    tls:
        - secretName: n8n-tls
            hosts:
                - n8n.votre-domaine.fr

Remplacez im­pé­ra­ti­ve­ment n8n.votre-domaine.fr par votre propre domaine. Ce fichier sert de point de contrôle central pour votre ins­tal­la­tion et peut être modifié à tout moment par la suite si vous souhaitez étendre votre con­fi­gu­ra­tion ou faire monter en charge n8n Ku­ber­netes.

Étape 11 : installer n8n avec le chart Helm officiel

Vient main­te­nant l’ins­tal­la­tion pro­pre­ment dite de n8n Ku­ber­netes à l’aide du chart Helm. Pour cela, exécutez la commande d’ins­tal­la­tion suivante :

helm install n8n oci://ghcr.io/n8n-io/n8n-helm-chart/n8n \
--version 1.0.0 \
-n n8n \
-f n8n-values.yaml

Vérifiez ensuite que les res­sources ont bien été créées :

kubectl get all -n n8n

Puis, examinez plus en détail les pods pour vous assurer que n8n a démarré cor­rec­te­ment et qu’aucune erreur ne s’est produite.

kubectl get pods -n n8n -w

Dès que le pod principal est en cours d’exécution et prêt, n8n est installé sur Ku­ber­netes dans le cluster.

Étape 12 : vérifier l’Ingress et le cer­ti­fi­cat

Comme vous avez déjà configuré l’Ingress et le TLS dans le fichier values, cert-manager devrait demander un cer­ti­fi­cat pour votre sous-domaine. Vérifiez d’abord l’Ingress :

kubectl get ingress -n n8n

Ensuite, vérifiez le cer­ti­fi­cat :

kubectl get certificate -n n8n
kubectl describe certificate n8n-tls -n n8n

Étape 13 : ouvrir n8n dans le na­vi­ga­teur et terminer la con­fi­gu­ra­tion initiale

Dès que l’Ingress est actif et que le cer­ti­fi­cat a été créé avec succès, ouvrez votre instance dans le na­vi­ga­teur :

https://n8n.votre-domaine.fr

Lors du premier accès, n8n vous guide à travers la con­fi­gu­ra­tion initiale. En général, vous créez d’abord le premier uti­li­sa­teur pour l’instance.

Close

Étape 14 : tester l’ins­tal­la­tion

Après la con­fi­gu­ra­tion initiale, vous devriez vérifier briè­ve­ment si l’ins­tal­la­tion fonc­tionne réel­le­ment cor­rec­te­ment. Pour cela, ouvrez l’éditeur n8n Ku­ber­netes, créez un simple workflow de test et en­re­gis­trez-le. Il est également utile de consulter les journaux du pod principal.

kubectl logs -n n8n -l app.kubernetes.io/component=main --tail=100

Si l’éditeur est ac­ces­sible, que la connexion fonc­tionne et qu’aucune erreur évidente n’apparaît dans les journaux, l’ins­tal­la­tion de base est terminée avec succès.

Étape 15 : ce qu’il faut savoir pour l’ex­ploi­ta­tion en pro­duc­tion

Pour les petites ins­tal­la­tions, le mode Stan­da­lone constitue un bon point de départ. Le chart officiel et la do­cu­men­ta­tion de n8n sur Ku­ber­netes dis­tin­guent toutefois clai­re­ment le mode Stan­da­lone du Queue Mode. Dès que plusieurs uti­li­sa­teurs, davantage d’exé­cu­tions si­mul­ta­nées ou une forte charge de webhooks entrent en jeu, le Queue Mode devient gé­né­ra­le­ment l’option la plus robuste. Dans ce cas, Post­greSQL et Redis s’ajoutent à l’ar­chi­tec­ture. Les workers peuvent alors être mis à l’échelle in­dé­pen­dam­ment.