n8n/README.md

n8n Helm Chart

Kubernetes 上に n8n ワークフロー自動化ツールをデプロイするHelmチャートです。 Raspberry Pi などのベアメタル上で動作する Kubernetes クラスタ（ARM64）を想定した構成です。

特徴

• n8nio/n8n 公式マルチアーキテクチャイメージ（linux/arm64 / Raspberry Pi 4以降対応）
• シングルコンテナ構成（軽量・シンプル）
• データ永続化（PVC）
• SQLite（デフォルト）/ PostgreSQL 選択可能
• Basic認証・暗号化キー管理（Secret）
• Ingress / HPA / PDB / NetworkPolicy 対応

前提条件

• Kubernetes 1.19 以上
• Helm 3.x
• PersistentVolume プロビジョナー（persistence.enabled: true の場合）

インストール

helm repo add cafepieters https://git.cafepieters.com/api/packages/helmchart/helm
helm repo update
helm install my-n8n cafepieters/n8n

カスタム値を指定してインストール

helm install my-n8n cafepieters/n8n \
  --set n8n.host=n8n.example.com \
  --set n8n.protocol=https \
  --set ingress.enabled=true

チャート構成

リソース	説明
Deployment	n8n 本体（シングルコンテナ、strategy: Recreate）
Service	LoadBalancer / ClusterIP（ポート 5678）
PVC	n8n データ（ワークフロー・認証情報・SQLite DB）永続化
Secret	暗号化キー・Basic認証パスワード・DBパスワード
Ingress	オプション（nginx ingress controller 対応）
HPA	オプション（※SQLiteモード時はスケールアウト非推奨）
PDB	Pod Disruption Budget
NetworkPolicy	オプション

設定リファレンス

イメージ

パラメータ	デフォルト	説明
image.registry	docker.io	レジストリ
image.repository	n8nio/n8n	イメージ名
image.tag	2.19.2	イメージタグ
image.pullPolicy	IfNotPresent	Pull ポリシー

サービス

パラメータ	デフォルト	説明
service.type	LoadBalancer	Service タイプ
service.port	5678	公開ポート

n8n 設定

パラメータ	デフォルト	説明
n8n.host	n8n.local	ホスト名（Webhook URL 生成に使用）
n8n.protocol	http	プロトコル（http / https）
n8n.webhookUrl	""	Webhook ベース URL（未設定時は host/protocol から生成）
n8n.timezone	Asia/Tokyo	タイムゾーン
n8n.logLevel	info	ログレベル（error/warn/info/verbose/debug）
n8n.encryptionKey	""	暗号化キー（空の場合は初回インストール時に自動生成、以降は既存値を維持）
n8n.existingSecret	""	既存 Secret 名（指定時は Secret を自動作成しない）

Basic認証

パラメータ	デフォルト	説明
n8n.basicAuth.enabled	false	Basic認証の有効化
n8n.basicAuth.user	admin	ユーザー名
n8n.basicAuth.password	""	パスワード（空の場合は自動生成）
n8n.basicAuth.existingSecret	""	既存 Secret 名

実行履歴の管理

パラメータ	デフォルト	説明
n8n.executions.pruneData	true	古い実行データを削除する
n8n.executions.pruneDataMaxAge	336	保持する最大時間数（336h = 14日）
n8n.executions.pruneDataMaxCount	10000	保持する最大件数

データベース

パラメータ	デフォルト	説明
n8n.database.type	sqlite	DB種別（sqlite / postgresdb）
n8n.database.postgresdb.host	postgres.default.svc.cluster.local	PostgreSQL ホスト
n8n.database.postgresdb.port	5432	PostgreSQL ポート
n8n.database.postgresdb.database	n8n	データベース名
n8n.database.postgresdb.user	""	ユーザー名
n8n.database.postgresdb.password	""	パスワード
n8n.database.postgresdb.existingSecret	""	既存 Secret 名

永続化

パラメータ	デフォルト	説明
persistence.enabled	true	PVC による永続化
persistence.storageClass	""	StorageClass（空の場合はデフォルト）
persistence.accessMode	ReadWriteOnce	アクセスモード
persistence.size	5Gi	ストレージサイズ
persistence.existingClaim	""	既存 PVC 名

リソース（Raspberry Pi 向けデフォルト）

パラメータ	デフォルト
resources.requests.cpu	250m
resources.requests.memory	256Mi
resources.limits.cpu	1000m
resources.limits.memory	512Mi

セキュアCookieの自動設定

N8N_SECURE_COOKIE は Ingress の設定に基づいて自動的に決定されます。手動設定は不要です。

条件	N8N_SECURE_COOKIE
ingress.enabled: false（LoadBalancer / HTTP直接アクセス）	false
ingress.enabled: true かつ ingress.tls 未設定	false
ingress.enabled: true かつ ingress.tls 設定済み	true

データ永続化について

n8n のデータ（ワークフロー定義・認証情報・実行履歴・SQLite DB）は /home/node/.n8n に保存されます。

重要: persistence.enabled: false の場合、Pod 再起動でデータがすべて失われます。本番環境では必ず true にしてください。

データベースの選択

SQLite（デフォルト）

シンプルな構成向け。スケールアウト不可（replicaCount: 1 固定推奨）。 Deployment の strategy: Recreate により、旧 Pod が停止してから新 Pod が起動します。

PostgreSQL

本番・高可用性構成向け。複数レプリカが可能になります。

n8n:
  database:
    type: postgresdb
    postgresdb:
      host: postgres.default.svc.cluster.local
      database: n8n
      user: n8n
      password: your-password

Ingress の設定例

ingress:
  enabled: true
  className: nginx
  annotations:
    cert-manager.io/cluster-issuer: letsencrypt-issuer
  hosts:
    - host: n8n.example.com
      paths:
        - path: /
          pathType: Prefix
  tls:
    - secretName: n8n-tls
      hosts:
        - n8n.example.com
n8n:
  host: n8n.example.com
  protocol: https

暗号化キーの管理

n8n は起動時に N8N_ENCRYPTION_KEY を使って認証情報を暗号化し、その値を /home/node/.n8n/config に記録します。 以降の起動でこのキーが変わると起動エラーになります。

推奨設定

初回インストール前に明示的にキーを指定することを推奨します:

helm install my-n8n cafepieters/n8n \
  --set n8n.encryptionKey="$(openssl rand -hex 24)"

または values.yaml に記載:

n8n:
  encryptionKey: "your-fixed-encryption-key"

注意: 未指定の場合、初回インストール時にランダム生成されます。helm upgrade では lookup で既存 Secret の値を維持するため通常は問題ありませんが、明示指定が最も安全です。

キーのミスマッチが起きた場合の復旧

PVC 上の n8n コンフィグから元のキーを読み出します。Pod がクラッシュ中でも以下で取得できます （my-n8n-n8n は PVC 名 = kubectl get pvc で確認）:

kubectl run n8n-key-reader --image=alpine --restart=Never \
  --overrides='{
    "spec": {
      "volumes": [{"name":"data","persistentVolumeClaim":{"claimName":"my-n8n-n8n"}}],
      "containers": [{"name":"c","image":"alpine",
        "command":["sh","-c","cat /data/config 2>/dev/null || cat /data/.n8n/config 2>/dev/null || echo NOT_FOUND"],
        "volumeMounts":[{"name":"data","mountPath":"/data"}]}]
    }
  }' --attach --rm

出力の encryptionKey の値を確認し、以下でアップグレードして復旧します:

helm upgrade my-n8n cafepieters/n8n \
  --set n8n.encryptionKey="<上で確認したキー>"

バージョン履歴

バージョン	n8n	変更内容
バージョン	n8n	変更内容
---	---	---
2.19.2-c	2.19.2	暗号化キー復旧手順を README に追加
2.19.2-b	2.19.2	暗号化キーを lookup で既存 Secret から維持、helm upgrade での再生成を防止
2.19.2-a	2.19.2	N8N_SECURE_COOKIE を Ingress/TLS 設定から自動判定（HTTP/LoadBalancer 環境対応）
2.19.2	2.19.2	初回リリース

ライセンス

n8n は Sustainable Use License のもとで配布されています。 このHelmチャートは Apache-2.0 ライセンスです。