# 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.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 ライセンスです。