Dify Enterprise Edition Deployment Guide (AWS)
This document describes how to deploy Dify Enterprise Edition in an AWS cloud environment. You can choose any of the following methods to complete the deployment:- Via Terraform (Recommended)
- Via CDK (Deprecated, no longer recommended)
- Manually create infrastructure and deploy (Not recommended)
Option 1: Build via Terraform
The Terraform scripts are now open-source. Get the latest version and usage instructions from langgenius/dify-ee-terraform-aws.
Prerequisites
kubectl,helm, andaws cliare installed locally.- An AWS account with permissions to create the following resources.
- AWS EKS (Elastic Kubernetes Service): For deploying Dify core services; nodes need internet access or NAT Gateway configuration
- AWS S3 (Simple Storage Service): For persistent storage
- AWS ECR (Elastic Container Registry): For Dify plugin installation; can also host Dify images and Helm Charts
- AWS RDS Aurora Postgres: Relational database for storing application data and audit records
- AWS OpenSearch: Vector database for RAG (Retrieval Augmented Generation) related features
- Amazon ElastiCache: Managed Redis caching service for accelerating data access
Option 2: Build via CDK (Deprecated)
⚠️ Deprecated: The CDK deployment path is no longer recommended for new deployments — please use Terraform instead. The aws-cdk-for-dify repository is kept only as a historical reference and is no longer actively maintained.
Option 3: Manually Create Infrastructure and Deploy
1. Create Infrastructure
Please refer to the recommended configurations in the table below and create infrastructure according to your actual needs. (Replace content in double brackets with actual values)Version note (important): The versions in the table below are provided as “available ranges/version families” for reference. Before deployment, please make sure to verify in the AWS Console of your target AWS Region (or via AWS CLI) which versions are currently supported (EKS Kubernetes, Aurora PostgreSQL, OpenSearch, ElastiCache Redis, etc.) to avoid resource creation failures caused by regional differences or version deprecations.
Testing Environment Infrastructure Configuration Reference
Note: If enabling the unstructured service on a single node, increase disk capacity to 40 GB.
Production Environment Infrastructure Configuration Reference
Additionally, you need to create appropriate Virtual Private Cloud (VPC) and Security Groups (SG) to ensure infrastructure security.
2. Configure values.yaml
After creating the database, S3, and other infrastructure, please refer to the following example to configurevalues.yaml (replace content in double brackets with actual values). Before this, you need to create four databases in the database: dify, enterprise, audit, dify_plugin_daemon, and replace the corresponding configuration items such as rds_main_database_name in values.yaml.
3.9.x notes (per patch release):
- ⚠️ Known issue:
persistence.s3.endpointmust be left empty for AWS S3 (affects both 3.9.0 and 3.9.1). WhenuseAwsS3: trueanduseAwsManagedIam: trueare set in 3.9.x, providing a non-emptyendpointbreaks plugin installation. Setendpoint: ""when using AWS S3 so the SDK derives the regional host automatically. The example below already reflects this. S3-compatible non-AWS object stores (MinIO, OSS, etc.) are not affected.- ⚠️ Known issue: OpenSearch as a vector store breaks file uploads to the knowledge base in 3.9.0 / 3.9.1. Contact the Dify support team to obtain a hotfix image.
- Database schema change (since 3.9.0, NOT reverted in 3.9.1): The legacy
externalPostgresblock has been replaced byexternalDatabase. The new structure supports Postgres / MySQL / TiDB engines and exposes a single top-leveluser/passwordpair; all logical databases (dify,enterprise,audit,plugin_daemon) share this credential set by default. This rename was not rolled back in 3.9.1 — the entire 3.9.x line usesexternalDatabase.- Per-database credential overrides via
databaseCredentials(added in 3.9.1): Starting from 3.9.1,externalDatabaseexposes adatabaseCredentialssub-block that lets you set a separateuser/passwordfor an individual logical database, overriding the top-level global credentials; if left empty or unset, the entry falls back to the global pair.databaseCredentialsis NOT available in 3.9.0 — only the top-level globaluser/passwordcan be used there. The example below uses the new schema with thedatabaseCredentialssection commented out by default; uncomment it on 3.9.1+ as needed.- Bundled MinIO sub-chart removed (since 3.9.0): External object storage (S3 here) is now required.
- First-deploy probe delay: The API pod’s readiness/liveness probes wait up to 5 minutes for the in-pod database migration to complete (
api.readinessProbe.initialDelaySeconds=120,api.livenessProbe.initialDelaySeconds=300). Slow startup of the API pod immediately afterhelm installis expected.
3. Configure S3 and ECR Permissions
To ensure Dify services start properly and the plugin system functions correctly, theapi, worker, workerBeat, plugin_daemon, and plugin_connector Deployments require S3 access permissions, and the per-plugin build / runtime Pods spawned via DifyPlugin CRs additionally require ECR push / pull permissions. The specific reasons why these services need these permissions will be explained in detail later.
You can configure permissions in one of the following two ways:
- IRSA Mode: IAM Roles for Service Accounts, enabling secure and fine-grained permission control (Recommended)
- Access Key (AK/SK) Mode: Provide credentials via environment variables
IRSA Mode Configuration
Dify recommends using IRSA to configure ServiceAccount permissions. You can contact the Dify technical support team forone-click IRSA deployment scripts.
IRSA establishes a trust relationship between the EKS cluster and IAM through an OIDC Provider, allowing Pods to securely obtain AWS permissions via ServiceAccounts without configuring Access Keys in the Pod. The overall architecture is as follows:
Note (3.9.x): The Helm chart automatically creates two additional ServiceAccounts —Below are the ServiceAccount permission descriptions required by Dify Enterprise Edition:dify-plugin-controller-sa(used by thedify-crd-controllerDeployment) anddify-plugin-manager-sa(used by thedify-plugin-managerDeployment, new in 3.9.x). Neither of them needs an IRSA role binding — both only need in-cluster Kubernetes RBAC (namespace-scopedRolefor CRD / Deployment / Job / Service / ConfigMap management), which the chart also installs. Do NOT annotate them witheks.amazonaws.com/role-arn.
💡 Special Note About CRD Installation Dify Enterprise Edition only requires namespace-level permissions during installation. However, since CRD itself is a cluster-level resource, appropriate cluster permissions are required during installation. If you don’t have cluster-level permissions, you can install the CRD separately first, then install the remaining components. The CRD itself is just an API structure declaration registered in Kubernetes. When its corresponding Controller is namespace-level, it cannot access or modify resources across namespaces.
Step 1: Verify IAM OIDC Provider
Before configuring IRSA, ensure the cluster has IAM OIDC Provider enabled. If the cluster was created manually, it’s recommended to enable or verify using theeksctl command-line tool. The IAM OIDC Provider establishes a trust relationship that allows the EKS cluster to prove Pod identity to IAM, enabling Pods to securely obtain AWS permissions.
Step 2: Create AWS IAM Policies
You need to create the following three IAM policies: Policy 1: S3 Access Policy (name is customizable, e.g.DifyS3Policy)
DifyECRPolicy)
Used for plugin image push and management, including ECR authentication, repository management, image push, and audit logging permissions:
Policy 3: ECR Pull-Only Policy (name is customizable, e.g.{your_ecr_repo_prefix}is the name prefix of your ECR repositories. For example, if you configureimageRepoPrefixin Step 5 as123456789.dkr.ecr.us-east-1.amazonaws.com/dify-ee, then the ECR repository prefix here isdify-ee, and the Resource should bearn:aws:ecr:us-east-1:123456789:repository/dify-ee*.
DifyECRPullOnlyPolicy)
Used only for pulling plugin runtime images:
Step 3: Create AWS IAM Roles
Create the following three roles and attach the policies from Step 2 to the corresponding roles (role names can be customized):
Obtain the corresponding role ARNs:
Replace{oidc_id}with the OIDC Provider ID of your EKS cluster. You can obtain it with the following command:
Step 4: Bind Roles to EKS ServiceAccounts
ServiceAccount (SA) is a mechanism that allows Pods in EKS to obtain specific AWS permissions to access cloud resources (such as S3).Create the following four ServiceAccounts and add the corresponding role ARN to the
eks.amazonaws.com/role-arn annotation. Only these four SAs need IRSA binding — dify-plugin-controller-sa and dify-plugin-manager-sa are auto-created by Helm with RBAC-only permissions and do not need any role-arn.
Example commands to create ServiceAccounts (replace
$DIFY_EE_* with the role ARNs obtained in Step 3):
Optional — alternate SA names provisioned by some Terraform modules. Newer revisions of the Dify Terraform module additionally createdify-plugin-build-sa(S3+ECR Role) anddify-plugin-build-run-sa(ECR Pull Role) as semantically clearer names for the same two IAM roles. They are not referenced by the Helm chart by default — to use them, setplugin_connector.customServiceAccount: "dify-plugin-build-sa"andplugin_connector.runnerServiceAccount: "dify-plugin-build-run-sa"in yourvalues.yaml(the chart writes both values into each DifyPlugin CR, which is what actually binds the SA to build / runtime Pods). Either naming scheme works as long as the value invalues.yamlmatches an SA that carries the correct role-arn.
Step 5: Configure ServiceAccount in values.yaml
Modify Helm’svalues.yaml and add the following configuration (only ServiceAccount and ECR-related configurations are shown below, other configurations are omitted). imageRepoPrefix can be customized:
‼️dify-plugin-connector-sais auto-created by Helm for theplugin_connectorDeployment (you only need to annotate it with the S3 role-arn after install).dify-plugin-crd-saanddify-plugin-runner-saare referenced via theplugin_connector.customServiceAccount/runnerServiceAccountvalues above — the chart writes these into every DifyPlugin CR it creates, and it is those CR-spawned Pods (build + runtime) that actually consume the IRSA permissions.dify-plugin-controller-saanddify-plugin-manager-sa(the SAs used by thedify-crd-controlleranddify-plugin-managerDeployments themselves) are Helm-created and RBAC-only — do not setserviceAccountNameforplugin_controller/plugin_manager, and do not annotate those SAs with a role-arn.
‼️ AboutadditionalWorkersand IRSA. The Helm chart template does NOT propagateworker.serviceAccountNameto entries underadditionalWorkers(seetemplates/additional-worker-deployment.yaml). If you choose to enable anyadditionalWorkers[*]entry — e.g. for queue isolation in a larger deployment — you must (1) overrideworker.celeryQueueson the mainworkerblock to exclude the queues you split out, otherwise both Deployments will consume the same queues and produce duplicate execution; AND (2) explicitly setadditionalWorkers[i].serviceAccountName: "dify-api-sa"on each enabled entry so the worker pod can reach S3 via IRSA.
Access Key Mode Configuration
Step 1: Prepare Credentials
Create an IAM user with only S3 and ECR permissions, and obtain its Access Key and Secret Key.Step 2: Create Kubernetes Secret
plugin_connector service via imageRepoSecret in values.yaml in the next step.
Step 3: Configure values.yaml
4. Install AWS ALB (Application Load Balancer)
To make Dify Enterprise Edition accessible via domain name, you need to install AWS ALB (Application Load Balancer). You can also choose to use Nginx Ingress Controller or other Ingress Controllers. AWS ALB is recommended because it integrates seamlessly with Dify Enterprise Edition and provides better performance and scalability. Please visit https://docs.aws.amazon.com/eks/latest/userguide/lbc-manifest.html for the AWS ALB installation guide.If you cannot install AWS ALB, you can use Nginx Ingress Controller as an alternative:After AWS ALB installation is complete, you can confirm whether the service is running properly with the following command:
values.yaml:
global configuration. You can verify the domain and create a certificate through AWS Certificate Manager.
5. Execute Installation
Please visit https://langgenius.github.io/dify-helm/#/ for detailed installation instructions.
‼️ It is not recommended to install Dify in the default namespace.
6. Verify Service Status
- Update kubectl access credentials:
- Verify EKS nodes are running properly:
- Verify Dify service status:
- Confirm ALB is working properly:
‼️ Please configure the DNSName from the above command output as a CNAME record, resolving to the various domains required by Dify.
7. Initialize Service
Installation is now complete. Please visit enterprise.dify.yourdomain.com to log in to the Dify Enterprise Edition admin console for further configuration and usage.Known issues (3.9.0 / 3.9.1)
The following issues affect Dify Enterprise 3.9.0 and 3.9.1. They are also called out inline next to the relevant configuration above; this section consolidates them for visibility.1. persistence.s3.endpoint must be left empty when using AWS S3
When useAwsS3: true and useAwsManagedIam: true are set, providing a non-empty persistence.s3.endpoint breaks plugin installation. Set endpoint: "" so the AWS SDK derives the regional host automatically:
2. OpenSearch as a vector store: file uploads to the knowledge base fail
WhenvectorDB.externalType: "opensearch" is configured, files cannot be uploaded to the knowledge base.
Workaround: contact the Dify support team to obtain a hotfix image.