Helm Chart values.yaml 重要パラメータ完全ガイド – 必須変更・環境別調整・デフォルト維持の判断基準

Dify Enterprise を Kubernetes に展開する際、values.yaml はデプロイの全体像を決定する最も重要なファイルである。公式のインストールコマンド helm upgrade -i dify -f values.yaml dify/dify が示すとおり、本番環境の構成差異はすべてこのファイルに集約される。

パラメータの数は多いが、すべてを理解する必要はない。重要なのは「必ず変更すべきパラメータ」「環境ごとに調整するパラメータ」「デフォルトのままでよいパラメータ」の 3 層に分類し、優先順位を付けて管理することである。

なお、公式は values の複雑さに対応するため dify-ee-helm-chart-values-generator を提供しており、初期構成の生成に活用できる。

1. values.yaml の全体構造

helm show values dify/dify で出力される主要セクションは以下のとおりである。

values.yaml
├── global              # グローバル設定（イメージレジストリ、プルシークレット等）
├── api                 # API サーバー設定
├── worker              # Worker サーバー設定
├── web                 # Web フロントエンド設定
├── sandbox             # コード実行 Sandbox 設定
├── enterprise          # Enterprise 固有設定（License 等）
├── ingress             # Ingress / ドメイン設定
├── persistence         # 永続化設定
├── externalPostgres    # 外部 PostgreSQL 接続
├── externalRedis       # 外部 Redis 接続
├── externalS3          # 外部オブジェクトストレージ接続
├── postgresql          # 内蔵 PostgreSQL（検証用）
├── redis               # 内蔵 Redis（検証用）
└── pluginDaemon        # プラグイン Daemon 設定

2. 必ず変更すべきパラメータ（Must Change）

以下のパラメータはデフォルト値のまま本番運用してはならない。

2.1 ドメインと Ingress

ingress:
  enabled: true
  className: "nginx"  # 環境に応じて alb, traefik 等
  annotations:
    cert-manager.io/cluster-issuer: "letsencrypt-prod"
    nginx.ingress.kubernetes.io/proxy-body-size: "50m"
  tls:
    - secretName: dify-tls-cert
      hosts:
        - console.dify.example.co.jp
        - api.dify.example.co.jp
        - app.dify.example.co.jp
        - upload.dify.example.co.jp
        - enterprise.dify.example.co.jp
  hosts:
    console:
      host: console.dify.example.co.jp
    api:
      host: api.dify.example.co.jp
    app:
      host: app.dify.example.co.jp
    upload:
      host: upload.dify.example.co.jp
    enterprise:
      host: enterprise.dify.example.co.jp

注意: Dify Enterprise は console / api / app / upload / enterprise / trigger と複数のエンドポイントを持つ。DNS とワイルドカード証明書の設計を事前に行うこと。

2.2 Secret / 内部通信キー

api:
  secretKey: ""       # 必ず強ランダム値に変更
  innerApiKey: ""     # 必ず強ランダム値に変更

生成例:

# 32 バイトの hex 文字列を生成
openssl rand -hex 32

本番では existingSecret を使い、values.yaml に平文で書かない構成を推奨する。

api:
  existingSecret: "dify-api-secrets"
  existingSecretKeys:
    secretKey: "SECRET_KEY"
    innerApiKey: "INNER_API_KEY"

2.3 Enterprise License モード

enterprise:
  enabled: true
  licenseMode: "online"   # オフライン環境では "offline" に変更

オフラインモードの場合、License ファイルの配置方法は公式の License Activation ドキュメントを参照する。

2.4 外部データベース接続

本番では内蔵 PostgreSQL を無効化し、外部マネージド DB を使う。

# 内蔵 PostgreSQL を無効化
postgresql:
  enabled: false

# 外部 PostgreSQL を有効化
externalPostgres:
  enabled: true
  host: "dify-prod.cluster-xxxx.ap-northeast-1.rds.amazonaws.com"
  port: 5432
  username: "dify_app"
  database: "dify_production"
  existingSecret: "dify-postgres-secret"
  existingSecretPasswordKey: "password"
  sslMode: "require"    # 本番では SSL 必須

2.5 外部 Redis 接続

redis:
  enabled: false

externalRedis:
  enabled: true
  host: "dify-prod.xxxxx.apne1.cache.amazonaws.com"
  port: 6379
  existingSecret: "dify-redis-secret"
  existingSecretPasswordKey: "password"
  useSsl: true

2.6 外部オブジェクトストレージ

externalS3:
  enabled: true
  bucket: "dify-enterprise-prod"
  region: "ap-northeast-1"
  endpoint: ""  # AWS S3 の場合は空、MinIO の場合は URL を指定
  existingSecret: "dify-s3-secret"
  existingSecretKeys:
    accessKey: "AWS_ACCESS_KEY_ID"
    secretKey: "AWS_SECRET_ACCESS_KEY"

3. 環境ごとに調整するパラメータ（Per-Environment）

3.1 レプリカ数

3.2 リソース制限

# 本番向け -- 各コンポーネントに明示的に定義
api:
  resources:
    requests:
      cpu: "2"
      memory: "4Gi"
    limits:
      cpu: "4"
      memory: "8Gi"

worker:
  resources:
    requests:
      cpu: "2"
      memory: "4Gi"
    limits:
      cpu: "4"
      memory: "8Gi"

web:
  resources:
    requests:
      cpu: "500m"
      memory: "512Mi"
    limits:
      cpu: "1"
      memory: "1Gi"

sandbox:
  resources:
    requests:
      cpu: "500m"
      memory: "512Mi"
    limits:
      cpu: "1"
      memory: "1Gi"

3.3 ログレベル

# 検証環境
api:
  env:
    LOG_LEVEL: "DEBUG"

# 本番環境
api:
  env:
    LOG_LEVEL: "WARNING"

3.4 SMTP 設定（メール通知）

api:
  env:
    MAIL_TYPE: "smtp"
    SMTP_SERVER: "smtp.example.co.jp"
    SMTP_PORT: "587"
    SMTP_USE_TLS: "true"
    SMTP_USERNAME: "dify-noreply@example.co.jp"
    MAIL_DEFAULT_SEND_FROM: "Dify Enterprise <dify-noreply@example.co.jp>"
  existingSecret: "dify-smtp-secret"

3.5 SSO / SAML 連携

Enterprise 版では SAML / OIDC による SSO が利用可能である。Azure AD や Okta との連携を行う場合、以下を設定する。

enterprise:
  sso:
    enabled: true
    protocol: "saml"
    # 具体的な IdP 設定は管理コンソールから行う

3.6 Sandbox ネットワーク制限

sandbox:
  env:
    ALLOWED_SYSCALLS: ""  # 許可するシステムコールを限定
  networkPolicy:
    enabled: true
    # 許可する通信先を明示的に指定

4. デフォルトのまま維持してよいパラメータ（Keep Default）

以下は特段の要件がない限り変更不要である。

5. パラメータ分類サマリ表

6. values.yaml のバージョン管理

6.1 Git リポジトリでの管理

values.yaml はインフラのコードそのものであり、Git で管理する。

infra-repo/
├── helm/
│   └── dify/
│       ├── base-values.yaml        # 全環境共通
│       ├── testing-values.yaml     # 検証環境上書き
│       ├── staging-values.yaml     # ステージング上書き
│       └── production-values.yaml  # 本番環境上書き
├── secrets/
│   └── README.md                   # Secret の管理方針を記載
└── scripts/
    └── deploy.sh                   # デプロイスクリプト

6.2 デプロイコマンド例

# 本番デプロイ（base + 環境別の values を重ねて適用）
helm upgrade -i dify dify/dify \
  -n dify-production \
  -f helm/dify/base-values.yaml \
  -f helm/dify/production-values.yaml \
  --wait --timeout 10m

デプロイ前に helm diff プラグインで変更内容を確認する習慣を付けること。

7. トラブルシューティング

よくある values 起因の問題

9. まとめ

Helm Chart の values.yaml は Dify Enterprise デプロイの「設計書」である。すべてのパラメータを読み解く必要はないが、以下の優先順位で対応することを推奨する。

1. 初日に対応: ドメイン・Secret・外部 DB/Redis/S3・License モード
2. 環境構築時に対応: レプリカ数・リソース制限・ログレベル・SMTP・SSO
3. 運用開始後に対応: 必要に応じて実験的機能やプラグイン設定を追加

values.yaml を Git で管理し、環境ごとに分離し、デプロイ前に helm diff で差分を確認する。この 3 つの習慣を身につけることが、安定した Dify Enterprise 運用の基盤となる。