Skip to main content

Dify Enterprise Edition デプロイメントガイド(AWS)

本ドキュメントでは、AWS クラウド環境に Dify Enterprise Edition をデプロイする方法について説明します。以下のいずれかの方法でデプロイできます。
  • Terraform 経由(推奨)
  • CDK 経由(非推奨・廃止予定)
  • 手動でインフラストラクチャを作成してデプロイ(非推奨)

オプション 1:Terraform によるデプロイ

Terraform スクリプトはオープンソース化されました。最新バージョンと利用方法は langgenius/dify-ee-terraform-aws を参照してください。

前提条件

  1. ローカルに kubectlhelmaws cli がインストールされていること。
  2. 以下のリソースを作成する権限を持つ AWS アカウントがあること。
Terraform は、Dify Enterprise Edition のデプロイに必要な以下のクラウドリソースを自動的に作成します。事前に Terraform 設定ファイルを変更することで、リソースの仕様を調整できます。
  • AWS EKS(Elastic Kubernetes Service):Dify コアサービスのデプロイ用。ノードはインターネットアクセスまたは NAT Gateway 設定が必要
  • AWS S3(Simple Storage Service):永続ストレージ用
  • AWS ECR(Elastic Container Registry):Dify プラグインのインストール用。Dify イメージと Helm Charts のホスティングも可能
  • AWS RDS Aurora Postgres:アプリケーションデータと監査レコードを保存するリレーショナルデータベース
  • AWS OpenSearch:RAG(Retrieval Augmented Generation)関連機能用のベクトルデータベース
  • Amazon ElastiCache:データアクセスを高速化するマネージド Redis キャッシュサービス

オプション 2:CDK によるデプロイ(非推奨)

⚠️ 非推奨: CDK によるデプロイは新規環境では推奨されません。Terraform をご利用ください。aws-cdk-for-dify リポジトリは履歴参照用に残されており、今後の更新は行われません。

オプション 3:手動でインフラストラクチャを作成してデプロイ

1. インフラストラクチャの作成

以下の表の推奨設定を参考に、実際の要件に合わせてインフラストラクチャを作成してください(波括弧 内の値は実際の値に置き換えてください)。
バージョンに関する注意(重要): 以下の表に記載しているバージョンは「利用可能な範囲/バージョン系列」の目安です。実際のデプロイ前に、対象 AWS リージョンのコンソールまたは AWS CLI で、各サービスでサポートされているバージョン(EKS Kubernetes、Aurora PostgreSQL、OpenSearch、ElastiCache Redis など)を必ず確認してください。リージョンによる差異やバージョンの廃止により、リソース作成に失敗する可能性があります。

テスト環境インフラストラクチャ設定リファレンス

注意: 単一ノードで unstructured サービスを有効にする場合は、ディスク容量を 40 GB に増やしてください。

本番環境インフラストラクチャ設定リファレンス

また、インフラストラクチャのセキュリティを確保するために、適切な Virtual Private Cloud(VPC)とセキュリティグループ(SG)を作成する必要があります。

2. values.yaml の設定

データベース、S3、その他のインフラストラクチャを作成した後、以下の例を参考に values.yaml を設定してください(波括弧 内の値を実際の値に置き換えてください)。設定の前に、PostgreSQL 上に difyenterpriseauditdify_plugin_daemon の 4 つのデータベースを作成し、values.yaml 内の rds_main_database_namerds_plugin_daemon_database_namerds_enterprise_database_namerds_audit_database_name を、作成したデータベース名で置き換えてください。
3.9.x の注意事項(パッチバージョンごと):
  • ⚠️ 既知の問題:AWS S3 使用時、persistence.s3.endpoint は空文字にする必要があります(3.9.0 / 3.9.1 いずれも該当)。 3.9.x で useAwsS3: true および useAwsManagedIam: true を指定した状態で endpoint に値を設定すると、プラグインのインストールが失敗します。AWS S3 を使用する場合は endpoint: "" を指定してください。 これにより、SDK がリージョンに応じた適切なエンドポイントを自動的に使用します。以下の例ではすでに空にしてあります。S3 互換の非 AWS オブジェクトストレージ(MinIO、OSS など)は影響を受けません。
  • ⚠️ 既知の問題:3.9.0 / 3.9.1 で OpenSearch をベクトルストアとして使用すると、ナレッジベースへのファイルアップロードが失敗します。 Dify 技術サポートチームに連絡し、ホットフィックスイメージを入手してください。
  • データベース設定構造の変更(3.9.0 以降、3.9.1 でもロールバックされていません):externalPostgres ブロックは externalDatabase に置き換えられました。新しい構造は Postgres / MySQL / TiDB の 3 つのエンジンに対応し、トップレベルでグローバルな user / password を 1 組指定すると、すべての論理データベース(difyenterpriseauditplugin_daemon)がデフォルトでこの認証情報を共有します。この変更は 3.9.1 でもロールバックされておらず、3.9.x 系全体で externalDatabase を使用します。
  • データベース単位の認証情報の上書き databaseCredentials(3.9.1 以降の新機能): 3.9.1 から externalDatabase 内に databaseCredentials サブブロックが追加され、論理データベース単位で user / password を個別に指定し、トップレベルのグローバル認証情報を上書きできるようになりました。空または未指定の場合は、グローバル設定にフォールバックします。3.9.0 では databaseCredentials は利用できません(トップレベルのグローバル user / password のみ使用可能)。以下の例は新しい構造に基づいており、databaseCredentials の部分はデフォルトでコメントアウトしてあります。3.9.1 以降では、必要に応じて有効化してください。
  • 同梱 MinIO サブチャートの削除(3.9.0 以降): 外部オブジェクトストレージ(本ドキュメントでは S3)が必須となります。
  • 初回デプロイ時のプローブ待機: Pod 内でのデータベースマイグレーションの完了を待つため、API Pod の Readiness/Liveness プローブには最大 5 分程度の待機時間を設けています(api.readinessProbe.initialDelaySeconds=120api.livenessProbe.initialDelaySeconds=300)。helm install の直後に API Pod の起動が遅いのは想定内の挙動です。

3. S3 と ECR 権限の設定

Dify サービスを正常に起動し、プラグインシステムを正しく機能させるためには、apiworkerworkerBeatplugin_daemonplugin_connector の各 Deployment に S3 アクセス権限が必要です。また、DifyPlugin CR から生成されるプラグインのビルド/実行時 Pod には ECR のプッシュ/プル権限も必要です。各サービスにこれらの権限が必要な理由については、以下の ServiceAccount 権限一覧表で詳しく説明します。 権限は、以下の 2 つの方法のいずれかで設定できます。
  • IRSA モード:IAM Roles for Service Accounts。安全できめ細かな権限制御が可能(推奨)
  • アクセスキー(AK/SK)モード:環境変数を介して認証情報を提供

IRSA モード設定

Dify では、IRSA を使用した ServiceAccount 権限の設定を推奨しています。IRSA を一括でセットアップするデプロイスクリプトについては、Dify 技術サポートチームにお問い合わせください。 IRSA は OIDC プロバイダーを介して EKS クラスターと IAM 間の信頼関係を確立し、Pod 側にアクセスキーを設定しなくても、ServiceAccount を通じて安全に AWS 権限を取得できるようにします。全体的なアーキテクチャは以下のとおりです。
注意(3.9.x): Helm チャートは、以下の 2 つの ServiceAccount を追加で自動作成します。
  • dify-plugin-controller-sadify-crd-controller Deployment が使用)
  • dify-plugin-manager-sa(3.9.x で新規追加された dify-plugin-manager Deployment が使用)
いずれも IRSA ロールのバインドは不要です。 必要なのはクラスター内の Kubernetes RBAC のみ(ネームスペーススコープの Role で CRD / Deployment / Job / Service / ConfigMap を管理)であり、これもチャートが併せて作成します。 eks.amazonaws.com/role-arn アノテーションは付与しないでください。
Dify Enterprise Edition に必要な ServiceAccount 権限の一覧は以下のとおりです。
💡 CRD インストールに関する特別な注意 Dify Enterprise Edition は、インストール時にネームスペースレベルの権限のみを必要とします。ただし、CRD 自体はクラスターレベルのリソースであるため、インストール時には適切なクラスター権限が必要です。クラスターレベルの権限がない場合は、先に CRD を単独でインストールし、その後に残りのコンポーネントをインストールできます。CRD 自体は Kubernetes に登録される API スキーマの宣言にすぎず、これに紐づく Controller がネームスペースレベルで動作している限り、ネームスペースをまたいでリソースにアクセスしたり変更したりすることはありません。
ステップ 1:IAM OIDC プロバイダーの確認
IRSA を設定する前に、クラスターで IAM OIDC プロバイダーが有効になっていることを確認してください。クラスターを手動で作成した場合は、eksctl コマンドラインツールを使用して有効化することをお勧めします。IAM OIDC プロバイダーは、EKS クラスターが Pod の ID を IAM に対して証明できる信頼関係を確立し、Pod が AWS 権限を安全に取得できるようにします。
IRSA の設定には、AWS のロールとポリシー、およびクラスター上の ServiceAccount を作成する必要があります。ServiceAccount を作成する際は、Helm の設定と名前が競合して権限の割り当てに失敗するのを避けるため、デフォルトの名前のまま使用することをお勧めします。
ステップ 2:AWS IAM ポリシーの作成
以下の 3 つの IAM ポリシーを作成する必要があります。 ポリシー 1:S3 アクセスポリシー(名前は任意。例:DifyS3Policy
ポリシー 2:ECR フルアクセスポリシー(名前は任意。例:DifyECRPolicy プラグインイメージのプッシュと管理に使用します。ECR 認証、リポジトリ管理、イメージプッシュ、監査ログの権限を含みます。
{your_ecr_repo_prefix} は ECR リポジトリ名のプレフィックスです。たとえば、ステップ 5 で imageRepoPrefix123456789.dkr.ecr.us-east-1.amazonaws.com/dify-ee と設定した場合、ここでの ECR リポジトリプレフィックスは dify-ee となり、Resource には arn:aws:ecr:us-east-1:123456789:repository/dify-ee* を指定します。
ポリシー 3:ECR プル専用ポリシー(名前は任意。例:DifyECRPullOnlyPolicy プラグインのランタイムイメージのプルにのみ使用します。
ステップ 3:AWS IAM ロールの作成
以下の 3 つのロールを作成し、ステップ 2 のポリシーを該当するロールにアタッチします(ロール名は任意)。 対応するロール ARN を取得します。
各ロールの Trust Policy は、OIDC プロバイダーによるフェデレーション認証を許可するように設定する必要があります。Trust Policy のテンプレートは以下のとおりです。
{oidc_id} を EKS クラスターの OIDC プロバイダー ID に置き換えてください。以下のコマンドで取得できます。
ステップ 4:ロールを EKS ServiceAccount にバインド
ServiceAccount(SA)は、EKS 上の Pod が特定の AWS 権限を取得し、S3 などのクラウドリソースにアクセスできるようにするための仕組みです。
以下の 4 つの ServiceAccount を作成し、対応するロール ARN を eks.amazonaws.com/role-arn アノテーションに追加します。IRSA バインドが必要なのは、この 4 つのみです。 dify-plugin-controller-sadify-plugin-manager-sa は Helm が自動作成し、RBAC のみで動作するため、role-arn は不要です。 ServiceAccount 作成のコマンド例($DIFY_EE_* は、ステップ 3 で取得したロール ARN に置き換えてください)。
オプション:一部の Terraform モジュールが提供するエイリアス。 新しい Dify Terraform モジュールでは、同じ 2 つの IAM ロールに対して意味を明確にした別名として、dify-plugin-build-sa(S3+ECR ロール)と dify-plugin-build-run-sa(ECR プルロール)も作成されます。Helm チャートのデフォルトではこれらの名前は参照されません。 使用するには、values.yamlplugin_connector.customServiceAccount: "dify-plugin-build-sa" および plugin_connector.runnerServiceAccount: "dify-plugin-build-run-sa" を設定してください。チャートはこれら 2 つの値を各 DifyPlugin CR に書き込み、その CR を介してビルド/実行時 Pod に SA がバインドされます。 values.yaml の値が、適切な role-arn を持つ実在の SA 名と一致していれば、どちらの命名体系でも動作します。
ステップ 5:values.yaml で ServiceAccount を設定
Helm の values.yaml を変更し、以下の設定を追加します(以下は ServiceAccount と ECR 関連の設定のみを示しており、その他の設定は省略しています)。imageRepoPrefix は任意の値に変更できます。
‼️ dify-plugin-connector-sa は、plugin_connector Deployment 向けに Helm が自動作成します(インストール後に S3 用の role-arn アノテーションを追加してください)。 dify-plugin-crd-sadify-plugin-runner-sa は、いずれの Deployment にも直接は割り当てられません。代わりに、上記で設定した plugin_connector.customServiceAccount / runnerServiceAccount の値が、チャートが生成するすべての DifyPlugin CR に書き込まれます。そして、その CR に基づいて生成されるビルド/実行時 Pod が実際に IRSA 権限を使用します。 dify-plugin-controller-sadify-plugin-manager-sadify-crd-controller および dify-plugin-manager Deployment 自体の SA)は Helm が作成し、RBAC のみで動作します。plugin_controller / plugin_managerserviceAccountName を設定しないでください。 また、これら 2 つの SA に role-arn を付与しないでください。
‼️ additionalWorkers と IRSA について。 Helm チャートのテンプレートは、worker.serviceAccountNameadditionalWorkers の各エントリに伝播しませんtemplates/additional-worker-deployment.yaml を参照)。 additionalWorkers[*] のいずれかを有効化する場合(例:大規模デプロイメントでのキュー分離)は、以下の 2 つの対応が必要です。
  1. メインの worker ブロックで worker.celeryQueues を上書きし、分離したキューを除外する。そうしないと、両方の Deployment が同一キューを消費し、重複処理が発生します。
  2. 有効化した各エントリに additionalWorkers[i].serviceAccountName: "dify-api-sa" を設定する。これを行わないと、worker Pod は IRSA 経由で S3 にアクセスできません。

アクセスキーモード設定

ステップ 1:認証情報の準備
S3 と ECR 権限のみを持つ IAM ユーザーを作成し、そのアクセスキーとシークレットキーを取得します。
ステップ 2:Kubernetes Secret の作成
この Secret は、次のステップで values.yamlimageRepoSecret を通じて plugin_connector サービスに設定する必要があります。
ステップ 3:values.yaml の設定

4. AWS ALB(Application Load Balancer)のインストール

Dify Enterprise Edition にドメイン名でアクセスできるようにするには、AWS ALB(Application Load Balancer)をインストールする必要があります。Nginx Ingress Controller など他の Ingress Controller を使用することもできますが、AWS ALB は Dify Enterprise Edition とシームレスに統合でき、優れたパフォーマンスとスケーラビリティを実現できるため、こちらを推奨します。 AWS ALB のインストールガイドについては、https://docs.aws.amazon.com/eks/latest/userguide/lbc-manifest.html をご覧ください。
AWS ALB をインストールできない場合は、代替として Nginx Ingress Controller を使用できます。
AWS ALB のインストールが完了したら、以下のコマンドでサービスが正常に動作しているか確認できます。
インストール後、values.yaml で Ingress を設定します。
SSL 証明書を使って Dify Enterprise Edition のサービスを公開するには、ALB アノテーションで証明書を設定し、global 設定で TLS を有効にします。AWS Certificate Manager でドメインを検証し、証明書を作成できます。

5. インストールの実行

詳細なインストール手順については、https://langgenius.github.io/dify-helm/#/ をご覧ください。
‼️ default ネームスペースへの Dify のインストールは推奨されません。

6. サービスステータスの確認

  1. kubectl のアクセス認証情報を更新します。
  1. EKS ノードが正常に動作していることを確認します。
  1. Dify のサービスステータスを確認します。
  1. ALB が正常に動作していることを確認します。
‼️ 上記コマンドの出力に含まれる DNSName を、Dify で必要な各ドメインの CNAME レコードのターゲットとして設定してください。

7. サービスの初期化

これでインストールは完了です。enterprise.dify.yourdomain.com にアクセスし、Dify Enterprise Edition の管理コンソールにログインして、続けて設定や運用を進めてください。

既知の問題(3.9.0 / 3.9.1)

以下の問題は Dify Enterprise 3.9.0 / 3.9.1 に影響します。該当する設定箇所にも個別に注記していますが、確認しやすいよう本ページ末尾にもまとめています。

1. AWS S3 利用時、persistence.s3.endpoint は空文字列にする必要があります

useAwsS3: true および useAwsManagedIam: true を設定している状態で persistence.s3.endpoint に値を指定すると、プラグインのインストールが失敗します。"" を設定することで、AWS SDK がリージョンに応じた適切なエンドポイントを自動的に使用します。
AWS 以外の S3 互換オブジェクトストレージ(MinIO、OSS など)は影響を受けません。

2. ベクトルストアに OpenSearch を使用すると、ナレッジベースへのファイルアップロードが失敗します

vectorDB.externalType: "opensearch" を設定している場合、ナレッジベースへのファイルアップロードができません。 回避策: Dify 技術サポートチームにホットフィックスイメージをリクエストしてください。