Container Registry for Plugins

​

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.

     Copy

     #!/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.

     Copy

     chmod +x ./generate-image-repo-secret.sh
     

   • 1.4 Execute script to create Kubernetes secret.

     Copy

     # ./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.

2. Syncing images to your private registry.