254 lines
9.0 KiB
Markdown
254 lines
9.0 KiB
Markdown
# n8n Helm Chart
|
||
|
||
Kubernetes 上に [n8n](https://n8n.io/) ワークフロー自動化ツールをデプロイする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` の場合）
|
||
|
||
## インストール
|
||
|
||
```bash
|
||
helm repo add cafepieters https://git.cafepieters.com/api/packages/helmchart/helm
|
||
helm repo update
|
||
helm install my-n8n cafepieters/n8n
|
||
```
|
||
|
||
### カスタム値を指定してインストール
|
||
|
||
```bash
|
||
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
|
||
|
||
本番・高可用性構成向け。複数レプリカが可能になります。
|
||
|
||
```yaml
|
||
n8n:
|
||
database:
|
||
type: postgresdb
|
||
postgresdb:
|
||
host: postgres.default.svc.cluster.local
|
||
database: n8n
|
||
user: n8n
|
||
password: your-password
|
||
```
|
||
|
||
## Ingress の設定例
|
||
|
||
```yaml
|
||
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` に記録します。
|
||
以降の起動でこのキーが変わると起動エラーになります。
|
||
|
||
### 推奨設定
|
||
|
||
初回インストール前に明示的にキーを指定することを推奨します:
|
||
|
||
```bash
|
||
helm install my-n8n cafepieters/n8n \
|
||
--set n8n.encryptionKey="$(openssl rand -hex 24)"
|
||
```
|
||
|
||
または `values.yaml` に記載:
|
||
|
||
```yaml
|
||
n8n:
|
||
encryptionKey: "your-fixed-encryption-key"
|
||
```
|
||
|
||
> **注意**: 未指定の場合、初回インストール時にランダム生成されます。`helm upgrade` では `lookup` で既存 Secret の値を維持するため通常は問題ありませんが、明示指定が最も安全です。
|
||
|
||
### キーのミスマッチが起きた場合の復旧
|
||
|
||
PVC 上の n8n コンフィグから元のキーを読み出します。Pod がクラッシュ中でも以下で取得できます
|
||
（`my-n8n-n8n` は PVC 名 = `kubectl get pvc` で確認）:
|
||
|
||
```bash
|
||
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` の値を確認し、以下でアップグレードして復旧します:
|
||
|
||
```bash
|
||
helm upgrade my-n8n cafepieters/n8n \
|
||
--set n8n.encryptionKey="<上で確認したキー>"
|
||
```
|
||
|
||
## バージョン履歴
|
||
|
||
| バージョン | n8n | 変更内容 |
|
||
|---|---|---|
|
||
| 2.27.3 | 2.27.3 | 自動更新 |
|
||
| 2.26.3 | 2.26.3 | 自動更新ワークフロー修正（GitHub Releases + Docker Hub ハイブリッドソース） |
|
||
| 2.22.2 | 2.22.2 | 自動更新 |
|
||
| 2.21.3 | 2.21.3 | 自動更新 |
|
||
| 2.20.6 | 2.20.6 | 自動更新 |
|
||
| 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](https://github.com/n8n-io/n8n/blob/master/LICENSE.md) のもとで配布されています。
|
||
このHelmチャートは Apache-2.0 ライセンスです。
|