Supported Container Registries

  • AWS ECR(with AK/SK or IRSA)/ Azure ACR / Aliyun ACR / Tencent TCR / Dockerhub

Why Container Registry is Required

  • Dify Enterprise requires a container registry to store and manage plugin images.
  • The package of plugin is not a Docker image, but a compressed file that contains the plugin code and metadata.
  • When run on Kubernetes cluster, the package of plugin will be built into a Docker image, which is why a container registry is required.

Display Helm Chart Values

helm show values dify/dify

This is an example of the Container Registry configuration in the Helm chart values.

plugin_connector:
  imageRepoSecret: "image-repo-secret"
  imageRepoPrefix: "docker.io/your-image-repo-prefix"
  imageRepoType: docker
  ecrRegion: "us-east-1"

How to Configure Container Registry

  1. imageRepoSecret (Required): This is a Kubernetes secret that contains the credentials for accessing the container registry.
    • 1.1 Warning: The value of imageRepoSecret is fixed as image-repo-secret, which is the name of the Kubernetes secret that will be created during the deployment.

    • 1.2 Save the following script as generate-image-repo-secret.sh.

      #!/bin/bash    
      
      if [ "$#" -lt 3 ]; then
      echo "How to use: $0 <username> <password> <k8s-namespace> <registry: optional>"
      echo "Example: $0 myuser mypass default https://index.docker.io/v1/"
      exit 1
      fi
      
      USERNAME="$1"
      PASSWORD="$2"
      NAMESPACE="$3"
      REGISTRY="${4:-https://index.docker.io/v1/}"
      OUTPUT_FILE="./config.json"
      
      AUTH=$(echo -n "$USERNAME:$PASSWORD" | base64 | tr -d '\n')
      
      cat > "$OUTPUT_FILE" <<EOF
      {
      "auths": {
          "$REGISTRY": {
          "auth": "$AUTH"
          }
      }
      }
      EOF
      
      echo "Docker config.json already generate: $OUTPUT_FILE"
      
      kubectl -n $NAMESPACE create secret generic image-repo-secret --from-file=.dockerconfigjson=$OUTPUT_FILE --from-file=config.json=$OUTPUT_FILE --type=kubernetes.io/dockerconfigjson
      
      rm "$OUTPUT_FILE"
      
    • 1.3 Set Execution Permission.

      chmod +x ./generate-image-repo-secret.sh
      
    • 1.4 Execute script to create Kubernetes secret.

      # ./generate-image-repo-secret.sh <username> <password> <k8s-namespace> <registry: optional>.
      ./generate-image-repo-secret.sh myuser mypass default https://index.docker.io/v1/
      
  • imageRepoPrefix (Required): The prefix for the image repository, which is used to push the plugin images to the container registry.
  • imageRepoType (Required): The type of the container registry.
    • docker (Default): For Docker Hub or other Docker-compatible registries.
    • ecr: For AWS ECR.
  • ecrRegion (Optional): The region of the AWS ECR registry, if applicable.

Scheduling of Kubernetes for plugin pods

plugin_connector:
  nodeSelector: {}
  affinity: {}
  tolerations: []
  labels: {}
  • The plugin pods of (nodeSelector、affinity、tolerations、labels) are extended from the plugin_connector service.

How to configure if your country has network restrictions

If your network failed to access docker.io, you can use a custom image repository.

plugin_connector:
  gatewayImage: "nginx:1.27.3"
  shaderImage: "gcr.io/kaniko-project/executor:latest"
  busyBoxImage: "busybox:latest"
  awsCliImage: "amazon/aws-cli:latest"
  generatorConf: |
    generator:
      repo: langgenius
      python:
        pipMirror: ""
        preCompile: true
        versions:
          python3.13:
            langgenius: docker.io/langgenius/plugin-build-base-python:3.13
          python3.12:
            langgenius: docker.io/langgenius/plugin-build-base-python:3.12
          python3.11:
            langgenius: docker.io/langgenius/plugin-build-base-python:3.11
          python3.10:
            langgenius: docker.io/langgenius/plugin-build-base-python:3.10
  1. The list of images that need to be replaced:
  • gatewayImage: The image for the plugin gateway service.
  • shaderImage: The shader image used during plugin build.
  • busyBoxImage: The busybox image used during plugin runtime.
  • awsCliImage: The image for the AWS CLI. If you are not using AWS, ignore this image.
  • python3.xx: The base image for the plugin build.
  1. Syncing images to your private registry.