← Back to Index

Deploying Dify on OpenShift 4.18 with Helm

Introduction

Dify is an open-source LLM application development platform. The upstream project is primarily designed to run via Docker Compose and does not officially support direct installation on Kubernetes or OpenShift. While community-driven Helm charts, such as the one from BorisPolonsky, facilitate deployment on Kubernetes, they often fail on OpenShift out-of-the-box.

This failure is typically due to OpenShift’s stringent security model, which, by default, prevents containers from running with root privileges. Standard Kubernetes deployments that assume root access will be blocked by OpenShift’s Security Context Constraints (SCCs).

This guide provides a step-by-step procedure to overcome these security hurdles and successfully deploy Dify on an OpenShift 4.18 cluster. The solution involves installing the Helm chart and then applying specific security configurations required by the OpenShift environment.

Prerequisites

Before you begin, ensure you have the following:

  • Access to an OpenShift 4.18 cluster with administrator privileges.
  • The oc (OpenShift CLI) tool installed and configured to connect to your cluster.
  • The helm CLI tool installed.

Deployment Procedure

Step 1: Download the Dify Helm Chart

First, download the Helm chart package from its GitHub releases. This package contains all the necessary Kubernetes resource definitions for deploying Dify and its dependencies.

wget https://github.com/BorisPolonsky/dify-helm/releases/download/dify-0.31.0/dify-0.31.0.tgz

Step 2: Install the Helm Chart

Next, use Helm to install the chart into your OpenShift cluster. We will create a dedicated namespace, dify, for this deployment.

The --wait flag ensures that the command waits until all the initial resources are created. Note that at this stage, some pods may fail to start and will be stuck in a CrashLoopBackOff or Error state due to permission issues. This is expected, and we will resolve it in the following steps.

helm install wzh-dify /<path to>/dify-0.31.0.tgz \
--create-namespace -n dify \
--wait

Step 3: Grant Privileged Access to Service Accounts

OpenShift uses Security Context Constraints (SCCs) to manage pod permissions. By default, pods run under the restricted SCC, which is highly secure but prevents containers from running as the root user. The Dify application components require elevated privileges to function correctly.

We will grant the privileged SCC to the service accounts used by the Dify pods. This allows the containers managed by these service accounts to run as root.

# Grant privileged access to the default service account in the 'dify' namespace
oc adm policy add-scc-to-user privileged -z default -n dify

# Grant privileged access to the Redis service account created by the Helm chart
oc adm policy add-scc-to-user privileged -z wzh-dify-redis -n dify

Step 4: Patch Deployments with the Correct Security Context

Although we have granted privileged access, the deployments themselves must be explicitly configured to use it. We need to patch each deployment to set the runAsUser and fsGroup to 0 (root) in their security context. This ensures the pods are created with the permissions granted by the privileged SCC.

The following script automates this process by iterating through all deployments in the dify namespace and applying the required patch.

# Get the names of all deployments in the 'dify' namespace
DEPLOYMENTS=$(kubectl get deployment -n dify -o jsonpath='{.items[*].metadata.name}')

# Loop through and patch each deployment
for DEP in $DEPLOYMENTS; do
  echo "Patching deployment '$DEP'..."
  kubectl patch deployment $DEP -n dify --type='json' -p='[{"op": "add", "path": "/spec/template/spec/securityContext", "value": {"runAsUser": 0, "fsGroup": 0}},{"op": "add", "path": "/spec/template/spec/securityContext/seLinuxOptions", "value": { "level": "s0:c12,c28" }}]'
done

Step 5: Verification

After patching the deployments, the pods will automatically restart with the new security context. You can monitor the status of the pods to ensure they are all running successfully.

oc get pods -n dify

Once all pods are in the Running state, your Dify instance is ready. You can expose the Dify service by creating a Route in OpenShift to access the web interface.

Conclusion

By addressing OpenShift’s specific security requirements, we have successfully deployed Dify using a community Helm chart. The key steps were to grant the privileged SCC to the necessary service accounts and patch the deployments to run with the appropriate security context. This process serves as a common pattern for adapting Kubernetes-native applications to the more secure OpenShift environment.