Custom CA Certificate Configuration

This guide explains how to configure custom Certificate Authority (CA) certificates for Dify Enterprise in Helm Chart deployments. This feature is essential for environments that use self-signed certificates or private PKI infrastructure.

Overview

When enabled, Dify will trust both system-wide CA certificates and your custom CA certificate for all outbound HTTPS connections. This is particularly useful when:

Your organization uses an internal PKI (Public Key Infrastructure).
You are deploying in air-gapped environments with self-signed certificates.
External services (Redis, databases, S3, vector databases, etc.) use certificates signed by a private CA.
You need to establish trust with internal HTTPS endpoints.

How It Works

The custom CA implementation uses the following approach:

Initialization: An init container runs before each Dify pod starts.
CA Bundle Creation: The init container combines system CA certificates (from the base image) with your custom CA certificate (from a Kubernetes Secret).
Environment Setup: Environment variables are configured to point Python, Node.js, curl, and AWS CLI to the combined CA bundle.
Runtime Trust: All Dify components use the combined CA bundle for SSL/TLS verification.

Prerequisites

Kubernetes cluster with Dify Helm chart installed (or ready to install).
Your custom CA certificate in PEM format.
kubectl access to your cluster.
Basic understanding of Kubernetes Secrets.

Configuration Steps

1. Prepare Your CA Certificate

Your CA certificate must be in PEM format (Base64-encoded, enclosed in BEGIN CERTIFICATE and END CERTIFICATE markers). Verify your certificate format:

# Your certificate should look like this:
cat your-ca.crt
# -----BEGIN CERTIFICATE-----
# MIIDXTCCAkWgAwIBAgIJAKJ... (Base64 content)
# ...
# -----END CERTIFICATE-----

If you have a DER-encoded certificate, convert it to PEM:

openssl x509 -inform der -in your-ca.der -out your-ca.crt

2. Create a Kubernetes Secret

Create a Kubernetes Secret containing your CA certificate.

kubectl create secret generic dify-custom-ca \
  --from-file=ca.crt=your-ca.crt \
  --namespace=<your-dify-namespace>

Note:

Secret name: dify-custom-ca (you can choose any name).

Key name: ca.crt (default, can be customized in values.yaml).

Namespace: Must be in the same namespace as your Dify deployment.

Verify the secret was created:

kubectl get secret dify-custom-ca -n <your-dify-namespace>
kubectl describe secret dify-custom-ca -n <your-dify-namespace>

3. Configure values.yaml

Edit your Helm values.yaml file to enable custom CA.

global:
  customCA:
    # Enable custom CA certificate support
    enabled: true
    # Name of the Kubernetes secret containing your CA certificate
    existingSecret: "dify-custom-ca"
    # Key name in the secret (must match the key you used in Step 2)
    key: ca.crt
    # Mount path for the combined CA bundle inside containers
    # (Advanced: usually no need to change this)
    mountPath: /etc/dify/custom-ca
    # Init container image used to combine system CAs with custom CA
    # For air-gapped environments, replace with your private registry
    initImage: alpine:3.20

Minimal configuration (using defaults):

global:
  customCA:
    enabled: true
    existingSecret: "dify-custom-ca"

4. Deploy or Update Dify

For new installations:

helm install dify dify/dify \
  --namespace dify \
  --values values.yaml

For existing installations:

helm upgrade dify dify/dify \
  --namespace dify \
  --values values.yaml

Note: Changes to the custom CA configuration require a pod restart to take effect. The CA bundle is generated once during pod initialization.

Verification

After deployment, verify that the custom CA is properly configured.

1. Check Init Containers

Check if the init containers ran successfully.

# List pods
kubectl get pods -n dify

# Check init container logs for a specific pod (e.g., api pod)
kubectl logs <api-pod-name> -n dify -c init-custom-ca

You should see output indicating the CA bundle was created successfully.

2. Verify Environment Variables

Exec into a running pod and check the environment variables.

# Exec into a running pod
kubectl exec -it <api-pod-name> -n dify -- sh

# Check environment variables
env | grep -E 'SSL_CERT_FILE|REQUESTS_CA_BUNDLE|CURL_CA_BUNDLE|NODE_EXTRA_CA_CERTS|AWS_CA_BUNDLE'

Expected output:

SSL_CERT_FILE=/etc/dify/custom-ca/ca-bundle.crt
REQUESTS_CA_BUNDLE=/etc/dify/custom-ca/ca-bundle.crt
CURL_CA_BUNDLE=/etc/dify/custom-ca/ca-bundle.crt
NODE_EXTRA_CA_CERTS=/etc/dify/custom-ca/ca-bundle.crt
AWS_CA_BUNDLE=/etc/dify/custom-ca/ca-bundle.crt

3. Verify CA Bundle Content

Inside the pod, verify the bundle contains your certificate.

# Inside the pod
cat /etc/dify/custom-ca/ca-bundle.crt | grep -A 5 "BEGIN CERTIFICATE" | tail -10

# Count certificates in the bundle
grep -c "BEGIN CERTIFICATE" /etc/dify/custom-ca/ca-bundle.crt

The bundle should contain multiple certificates (system CAs + your custom CA).

Environment Variables Reference

The custom CA feature sets the following environment variables to ensure broad compatibility. All variables point to the same combined CA bundle: /etc/dify/custom-ca/ca-bundle.crt (or your custom mountPath).

Variable	Purpose	Used By
`SSL_CERT_FILE`	OpenSSL/LibreSSL	General SSL libraries, Python requests
`REQUESTS_CA_BUNDLE`	Python requests library	Python HTTP clients
`CURL_CA_BUNDLE`	curl command	Shell scripts, curl-based tools
`NODE_EXTRA_CA_CERTS`	Node.js	Node.js HTTPS client
`AWS_CA_BUNDLE`	AWS SDK	S3, AWS service connections

Affected Components

When custom CA is enabled, the following Dify components automatically use the custom CA bundle:

API Server (api-deployment)
Worker (worker-deployment)
Worker Beat (worker-beat-deployment)
Trigger Worker (trigger-worker-deployment)
Enterprise Service (enterprise-deployment)
Enterprise Audit (enterprise-audit-deployment)
Sandbox (sandbox-deployment)
Gateway (caddy-deploy)
SSRF Proxy (ssrf-proxy-deployment)
Unstructured (unstructured-deployment)
Plugin Daemon (plugin-daemon)
Plugin Manager (plugin-manager)
Plugin Controller (plugin-controller)

Troubleshooting

Pods stuck in Init:0/1

Cause: Init container init-custom-ca is failing. Solution:

# Check init container logs
kubectl logs <pod-name> -n dify -c init-custom-ca

Common causes:

initImage cannot be pulled (air-gapped environment).
Secret not found or wrong namespace.
Wrong key name in secret.

SSL verification errors after enabling custom CA

Cause: Your custom CA certificate might not be properly formatted or is incomplete. Solution:

Verify certificate is valid PEM format:

openssl x509 -in your-ca.crt -text -noout

Check if it’s a full chain (if your CA requires intermediate certificates). Concatenate multiple certificates if needed:
cat intermediate-ca.crt root-ca.crt > combined-ca.crt

Update the secret and restart pods:

kubectl delete secret dify-custom-ca -n dify
kubectl create secret generic dify-custom-ca \
  --from-file=ca.crt=combined-ca.crt -n dify
kubectl rollout restart deployment -n dify

Changes to custom CA secret not taking effect

Cause: The CA bundle is created during pod initialization. Updating the secret doesn’t automatically update running pods. Solution: You must restart pods after updating the secret.

kubectl rollout restart deployment -n dify

Init container cannot pull alpine:3.20 image

Cause: Air-gapped environment or restricted registry access. Solution: Use your private registry in values.yaml.

global:
  customCA:
    enabled: true
    existingSecret: "dify-custom-ca"
    initImage: your-registry.company.com/alpine:3.20

Supported alternatives:

Alpine-based: alpine:3.20, alpine:3.19
Debian-based: ubuntu:22.04, debian:12
Any image containing /etc/ssl/certs/ca-certificates.crt (Debian/Ubuntu) or /etc/ssl/cert.pem (Alpine).

Advanced Configuration

Using a Different Secret Key Name

If your secret uses a different key name:

global:
  customCA:
    enabled: true
    existingSecret: "my-ca-secret"
    key: custom-ca.pem  # Different key name

Custom Mount Path

If you need to change where the CA bundle is mounted:

global:
  customCA:
    enabled: true
    existingSecret: "dify-custom-ca"
    mountPath: /custom/path/to/ca

Note: Changing mountPath updates all environment variables automatically.

Multiple CA Certificates

If you need to trust multiple custom CAs, concatenate them into a single file:

cat ca1.crt ca2.crt ca3.crt > combined-ca.crt
kubectl create secret generic dify-custom-ca \
  --from-file=ca.crt=combined-ca.crt -n dify

Air-Gapped Environments

For completely air-gapped deployments:

Mirror the init image to your private registry:

docker pull alpine:3.20
docker tag alpine:3.20 your-registry.company.com/alpine:3.20
docker push your-registry.company.com/alpine:3.20

Update values.yaml:

global:
  customCA:
    enabled: true
    existingSecret: "dify-custom-ca"
    initImage: your-registry.company.com/alpine:3.20

FAQ

Can I disable custom CA after enabling it?

Yes, set global.customCA.enabled: false and upgrade the Helm release. Pods will restart without the custom CA configuration.

Does this affect TLS between Dify components?

No, this only affects outbound HTTPS connections from Dify to external services (databases, S3, APIs, etc.). Internal component communication is not affected.

What if my database also requires a custom CA?

The custom CA feature covers database connections too. Ensure your database server’s certificate is signed by the CA you’ve configured.

Can I use intermediate certificates?

Yes, concatenate the full chain (intermediate + root CA) into a single file before creating the secret.

How do I update the CA certificate without downtime?

Kubernetes Secrets can be updated, but pods must be restarted. For zero-downtime updates:

Update the secret.
Use kubectl rollout restart with rolling update strategy (default).
Pods will restart one by one, maintaining service availability.

Deployment

Advanced Configuration

Cloud Infrastructure

Custom CA Certificate Configuration

Overview

How It Works

Prerequisites

Configuration Steps

1. Prepare Your CA Certificate

2. Create a Kubernetes Secret

3. Configure values.yaml

4. Deploy or Update Dify

Verification

1. Check Init Containers

2. Verify Environment Variables

3. Verify CA Bundle Content

Environment Variables Reference

Affected Components

Troubleshooting

Pods stuck in Init:0/1

SSL verification errors after enabling custom CA

Changes to custom CA secret not taking effect

Init container cannot pull alpine:3.20 image

Advanced Configuration

Using a Different Secret Key Name

Custom Mount Path

Multiple CA Certificates

Air-Gapped Environments

FAQ

Can I disable custom CA after enabling it?

Does this affect TLS between Dify components?

What if my database also requires a custom CA?

Can I use intermediate certificates?

How do I update the CA certificate without downtime?

​Overview

​How It Works

​Prerequisites

​Configuration Steps

​1. Prepare Your CA Certificate

​2. Create a Kubernetes Secret

​3. Configure values.yaml

​4. Deploy or Update Dify

​Verification

​1. Check Init Containers

​2. Verify Environment Variables

​3. Verify CA Bundle Content

​Environment Variables Reference

​Affected Components

​Troubleshooting

​Pods stuck in Init:0/1

​SSL verification errors after enabling custom CA

​Changes to custom CA secret not taking effect

​Init container cannot pull alpine:3.20 image

​Advanced Configuration

​Using a Different Secret Key Name

​Custom Mount Path

​Multiple CA Certificates

​Air-Gapped Environments

​FAQ

​Can I disable custom CA after enabling it?

​Does this affect TLS between Dify components?

​What if my database also requires a custom CA?

​Can I use intermediate certificates?

​How do I update the CA certificate without downtime?

Overview

How It Works

Prerequisites

Configuration Steps

1. Prepare Your CA Certificate

2. Create a Kubernetes Secret

3. Configure values.yaml

4. Deploy or Update Dify

Verification

1. Check Init Containers

2. Verify Environment Variables

3. Verify CA Bundle Content

Environment Variables Reference

Affected Components

Troubleshooting

Pods stuck in Init:0/1

SSL verification errors after enabling custom CA

Changes to custom CA secret not taking effect

Init container cannot pull alpine:3.20 image

Advanced Configuration

Using a Different Secret Key Name

Custom Mount Path

Multiple CA Certificates

Air-Gapped Environments

FAQ

Can I disable custom CA after enabling it?

Does this affect TLS between Dify components?

What if my database also requires a custom CA?

Can I use intermediate certificates?

How do I update the CA certificate without downtime?