Dify Enterprise Edition デプロイメントガイド(AWS)
本ドキュメントでは、AWS クラウド環境に Dify Enterprise Edition をデプロイする方法について説明します。以下のいずれかの方法でデプロイできます。- Terraform 経由(推奨)
- CDK 経由(非推奨・廃止予定)
- 手動でインフラストラクチャを作成してデプロイ(非推奨)
オプション 1:Terraform によるデプロイ
Terraform スクリプトはオープンソース化されました。最新バージョンと利用方法は langgenius/dify-ee-terraform-aws を参照してください。
前提条件
- ローカルに
kubectl、helm、aws cliがインストールされていること。 - 以下のリソースを作成する権限を持つ AWS アカウントがあること。
- 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 上に dify、enterprise、audit、dify_plugin_daemon の 4 つのデータベースを作成し、values.yaml 内の rds_main_database_name、rds_plugin_daemon_database_name、rds_enterprise_database_name、rds_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 組指定すると、すべての論理データベース(dify、enterprise、audit、plugin_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=120、api.livenessProbe.initialDelaySeconds=300)。helm installの直後に API Pod の起動が遅いのは想定内の挙動です。
3. S3 と ECR 権限の設定
Dify サービスを正常に起動し、プラグインシステムを正しく機能させるためには、api、worker、workerBeat、plugin_daemon、plugin_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 Enterprise Edition に必要な ServiceAccount 権限の一覧は以下のとおりです。いずれも IRSA ロールのバインドは不要です。 必要なのはクラスター内の Kubernetes RBAC のみ(ネームスペーススコープの
dify-plugin-controller-sa(dify-crd-controllerDeployment が使用)dify-plugin-manager-sa(3.9.x で新規追加されたdify-plugin-managerDeployment が使用)Roleで CRD / Deployment / Job / Service / ConfigMap を管理)であり、これもチャートが併せて作成します。eks.amazonaws.com/role-arnアノテーションは付与しないでください。
💡 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 権限を安全に取得できるようにします。
ステップ 2:AWS IAM ポリシーの作成
以下の 3 つの IAM ポリシーを作成する必要があります。 ポリシー 1:S3 アクセスポリシー(名前は任意。例:DifyS3Policy)
DifyECRPolicy)
プラグインイメージのプッシュと管理に使用します。ECR 認証、リポジトリ管理、イメージプッシュ、監査ログの権限を含みます。
ポリシー 3:ECR プル専用ポリシー(名前は任意。例:{your_ecr_repo_prefix}は ECR リポジトリ名のプレフィックスです。たとえば、ステップ 5 でimageRepoPrefixを123456789.dkr.ecr.us-east-1.amazonaws.com/dify-eeと設定した場合、ここでの ECR リポジトリプレフィックスはdify-eeとなり、Resource にはarn:aws:ecr:us-east-1:123456789:repository/dify-ee*を指定します。
DifyECRPullOnlyPolicy)
プラグインのランタイムイメージのプルにのみ使用します。
ステップ 3:AWS IAM ロールの作成
以下の 3 つのロールを作成し、ステップ 2 のポリシーを該当するロールにアタッチします(ロール名は任意)。
対応するロール ARN を取得します。
{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-sa と dify-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.yamlでplugin_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_connectorDeployment 向けに Helm が自動作成します(インストール後に S3 用の role-arn アノテーションを追加してください)。dify-plugin-crd-saとdify-plugin-runner-saは、いずれの Deployment にも直接は割り当てられません。代わりに、上記で設定したplugin_connector.customServiceAccount/runnerServiceAccountの値が、チャートが生成するすべての DifyPlugin CR に書き込まれます。そして、その CR に基づいて生成されるビルド/実行時 Pod が実際に IRSA 権限を使用します。dify-plugin-controller-saとdify-plugin-manager-sa(dify-crd-controllerおよびdify-plugin-managerDeployment 自体の SA)は Helm が作成し、RBAC のみで動作します。plugin_controller/plugin_managerにserviceAccountNameを設定しないでください。 また、これら 2 つの SA に role-arn を付与しないでください。
‼️additionalWorkersと IRSA について。 Helm チャートのテンプレートは、worker.serviceAccountNameをadditionalWorkersの各エントリに伝播しません(templates/additional-worker-deployment.yamlを参照)。additionalWorkers[*]のいずれかを有効化する場合(例:大規模デプロイメントでのキュー分離)は、以下の 2 つの対応が必要です。
- メインの
workerブロックでworker.celeryQueuesを上書きし、分離したキューを除外する。そうしないと、両方の Deployment が同一キューを消費し、重複処理が発生します。- 有効化した各エントリに
additionalWorkers[i].serviceAccountName: "dify-api-sa"を設定する。これを行わないと、worker Pod は IRSA 経由で S3 にアクセスできません。
アクセスキーモード設定
ステップ 1:認証情報の準備
S3 と ECR 権限のみを持つ IAM ユーザーを作成し、そのアクセスキーとシークレットキーを取得します。ステップ 2:Kubernetes Secret の作成
values.yaml の imageRepoSecret を通じて 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 を設定します。
global 設定で TLS を有効にします。AWS Certificate Manager でドメインを検証し、証明書を作成できます。
5. インストールの実行
詳細なインストール手順については、https://langgenius.github.io/dify-helm/#/ をご覧ください。
‼️ default ネームスペースへの Dify のインストールは推奨されません。
6. サービスステータスの確認
- kubectl のアクセス認証情報を更新します。
- EKS ノードが正常に動作していることを確認します。
- Dify のサービスステータスを確認します。
- 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 がリージョンに応じた適切なエンドポイントを自動的に使用します。
2. ベクトルストアに OpenSearch を使用すると、ナレッジベースへのファイルアップロードが失敗します
vectorDB.externalType: "opensearch" を設定している場合、ナレッジベースへのファイルアップロードができません。
回避策: Dify 技術サポートチームにホットフィックスイメージをリクエストしてください。