eljefe80-comfyui-mqtt-node/KUBERNETES_INSTALL.md

Kubernetes/Helm Installation Guide

This guide covers installing the ComfyUI MQTT Node in a Kubernetes environment using Helm.

Overview

The installation uses an InitContainer approach that:

1. Copies node files from a ConfigMap to the custom_nodes directory
2. Installs Python dependencies (paho-mqtt)
3. Makes the node available when ComfyUI starts

Prerequisites

• Kubernetes cluster with kubectl access
• Existing ComfyUI Helm chart deployment
• kubectl configured to access your cluster

Installation Steps

Step 1: Create the ConfigMap

Apply the ConfigMap containing the MQTT node files:

kubectl apply -f kubernetes/configmap.yaml

Verify the ConfigMap was created:

kubectl get configmap comfyui-mqtt-node
kubectl describe configmap comfyui-mqtt-node

Step 2: Update Your Helm Chart

You have several options depending on your Helm chart structure:

Option A: Modify values.yaml (Recommended)

If your Helm chart supports custom initContainers via values.yaml, add the configuration from kubernetes/helm-values-example.yaml:

# In your values.yaml or custom-values.yaml

initContainers:
  - name: install-mqtt-node
    image: busybox:latest
    command:
      - sh
      - -c
      - |
        echo "Installing ComfyUI MQTT Node..."
        mkdir -p /comfyui/custom_nodes/comfyui-mqtt-node
        cp -v /mqtt-node-source/* /comfyui/custom_nodes/comfyui-mqtt-node/
        echo "MQTT Node files copied successfully"
    volumeMounts:
      - name: mqtt-node-config
        mountPath: /mqtt-node-source
      - name: custom-nodes
        mountPath: /comfyui/custom_nodes

  - name: install-mqtt-dependencies
    image: your-comfyui-image:tag  # Match your main container image
    command:
      - sh
      - -c
      - |
        pip install --no-cache-dir paho-mqtt>=1.6.1
    volumeMounts:
      - name: custom-nodes
        mountPath: /comfyui/custom_nodes

volumes:
  - name: mqtt-node-config
    configMap:
      name: comfyui-mqtt-node
  - name: custom-nodes
    emptyDir: {}

volumeMounts:
  - name: custom-nodes
    mountPath: /app/custom_nodes  # Adjust to your ComfyUI path

Option B: Modify Deployment Template

If you need to directly edit the deployment template, update your chart's templates/deployment.yaml to include the initContainers and volumes sections from kubernetes/deployment-snippet.yaml.

Step 3: Update Critical Configuration

IMPORTANT: Update these values to match your environment:

1. ComfyUI Image: Replace your-comfyui-image:tag with your actual ComfyUI container image
2. Custom Nodes Path: Verify the mount path matches your ComfyUI installation
   • Common paths: /app/custom_nodes, /comfyui/custom_nodes, /workspace/ComfyUI/custom_nodes
3. Dependencies: If Pillow or numpy are not in your base image, add them to the pip install command

Step 4: Deploy/Upgrade

Deploy the updated Helm chart:

# For new installation
helm install comfyui ./your-chart -f custom-values.yaml

# For upgrade
helm upgrade comfyui ./your-chart -f custom-values.yaml

# Or using the --set flag for quick tests
helm upgrade comfyui ./your-chart --set initContainers[0].image=busybox:latest

Step 5: Verify Installation

Check the pod status:

kubectl get pods -l app=comfyui

Check initContainer logs:

# Get pod name
POD_NAME=$(kubectl get pod -l app=comfyui -o jsonpath='{.items[0].metadata.name}')

# Check MQTT node installation log
kubectl logs $POD_NAME -c install-mqtt-node

# Check dependency installation log
kubectl logs $POD_NAME -c install-mqtt-dependencies

Expected output:

Installing ComfyUI MQTT Node...
'/mqtt-node-source/__init__.py' -> '/comfyui/custom_nodes/comfyui-mqtt-node/__init__.py'
'/mqtt-node-source/mqtt_node.py' -> '/comfyui/custom_nodes/comfyui-mqtt-node/mqtt_node.py'
'/mqtt-node-source/requirements.txt' -> '/comfyui/custom_nodes/comfyui-mqtt-node/requirements.txt'
MQTT Node files copied successfully

Check main container logs for node loading:

kubectl logs $POD_NAME -c comfyui | grep -i mqtt

Expected output:

Loading custom node: comfyui-mqtt-node
Successfully loaded: MQTTPublishImage
Successfully loaded: MQTTPublishImageJSON

Step 6: Test the Node

1. Access ComfyUI:

kubectl port-forward $POD_NAME 8188:8188

2. Open http://localhost:8188 in your browser

3. Right-click and add node → image → mqtt → "MQTT Publish Image"

4. Configure with your MQTT broker details

Configuration Options

Using Persistent Storage

For custom_nodes that persist across pod restarts:

volumes:
  - name: custom-nodes
    persistentVolumeClaim:
      claimName: comfyui-custom-nodes-pvc

Create the PVC:

apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: comfyui-custom-nodes-pvc
spec:
  accessModes:
    - ReadWriteOnce
  resources:
    requests:
      storage: 1Gi
  storageClassName: standard  # Adjust to your cluster

Using Secrets for MQTT Credentials

Create a secret for MQTT credentials:

kubectl create secret generic mqtt-credentials \
  --from-literal=username=your-username \
  --from-literal=password=your-password

Reference in your deployment:

env:
  - name: MQTT_USERNAME
    valueFrom:
      secretKeyRef:
        name: mqtt-credentials
        key: username
  - name: MQTT_PASSWORD
    valueFrom:
      secretKeyRef:
        name: mqtt-credentials
        key: password

Note: The current node implementation reads credentials from the UI. Future versions could read from environment variables.

Installing in a Specific Namespace

# Create namespace
kubectl create namespace comfyui

# Apply ConfigMap to namespace
kubectl apply -f kubernetes/configmap.yaml -n comfyui

# Deploy Helm chart to namespace
helm install comfyui ./your-chart -f custom-values.yaml -n comfyui

Troubleshooting

InitContainer Fails

Check logs:

kubectl logs $POD_NAME -c install-mqtt-node
kubectl logs $POD_NAME -c install-mqtt-dependencies

Common issues:

• Permission denied: Add chmod -R 755 command to initContainer
• Directory not found: Verify the custom_nodes mount path
• Image pull errors: Check image name and registry access

Node Not Appearing in ComfyUI

1. Check if files were copied:

kubectl exec $POD_NAME -- ls -la /app/custom_nodes/comfyui-mqtt-node

2. Check ComfyUI logs:

kubectl logs $POD_NAME | grep -A 10 "Loading custom"

3. Verify Python dependencies:

kubectl exec $POD_NAME -- pip list | grep paho-mqtt

Dependency Installation Fails

If pip install fails in initContainer:

1. Use the same image as main container (critical!)
2. Check Python version compatibility
3. Consider pre-building dependencies into your base image:

# In your ComfyUI Dockerfile
RUN pip install paho-mqtt>=1.6.1

MQTT Connection Issues

Test MQTT connectivity from the pod:

kubectl exec -it $POD_NAME -- sh

# Install mosquitto clients (if not available)
apt-get update && apt-get install -y mosquitto-clients

# Test connection
mosquitto_pub -h mqtt-broker.default.svc.cluster.local -t test -m "hello"

Advanced Configurations

Multiple ComfyUI Replicas

If running multiple ComfyUI replicas:

1. Use unique MQTT client IDs per pod:

env:
  - name: POD_NAME
    valueFrom:
      fieldRef:
        fieldPath: metadata.name

Then configure client_id in the node as: comfyui_${POD_NAME}

2. Consider using shared PersistentVolume with ReadWriteMany access mode

GitOps with ArgoCD/Flux

Store the ConfigMap in your GitOps repo:

your-gitops-repo/
├── base/
│   ├── kustomization.yaml
│   ├── configmap.yaml
│   └── deployment.yaml
└── overlays/
    ├── production/
    └── staging/

Sidecar Container Pattern (Alternative)

Instead of initContainer, run a sidecar that watches for updates:

containers:
  - name: mqtt-node-updater
    image: busybox:latest
    command:
      - sh
      - -c
      - |
        while true; do
          cp -u /mqtt-node-source/* /custom-nodes/comfyui-mqtt-node/
          sleep 300  # Check every 5 minutes
        done
    volumeMounts:
      - name: mqtt-node-config
        mountPath: /mqtt-node-source
      - name: custom-nodes
        mountPath: /custom-nodes

This allows updating the ConfigMap without restarting pods.

Updating the Node

To update to a new version:

1. Update the ConfigMap:

kubectl apply -f kubernetes/configmap.yaml

2. Restart the pods to trigger initContainer:

kubectl rollout restart deployment/comfyui

3. Verify the update:

kubectl logs $POD_NAME -c install-mqtt-node

Cleanup

Remove the MQTT node:

# Delete ConfigMap
kubectl delete configmap comfyui-mqtt-node

# Remove initContainers from your Helm values and upgrade
helm upgrade comfyui ./your-chart -f values-without-mqtt.yaml

# Or rollback
helm rollback comfyui

Production Considerations

1. Resource Limits: Add resources to initContainers:

resources:
  limits:
    cpu: 100m
    memory: 128Mi
  requests:
    cpu: 50m
    memory: 64Mi

2. Image Registry: Host your ComfyUI image in a private registry

3. Security Context: Run with non-root user:

securityContext:
  runAsNonRoot: true
  runAsUser: 1000
  fsGroup: 1000

4. Health Checks: Ensure ComfyUI readiness probes wait for custom nodes to load

5. Monitoring: Add logging/metrics for MQTT publish operations

Support

For Kubernetes-specific issues:

• Check pod events: kubectl describe pod $POD_NAME
• Review logs: kubectl logs $POD_NAME --all-containers
• Verify ConfigMap: kubectl get configmap comfyui-mqtt-node -o yaml

For MQTT node issues, see the main README.md troubleshooting section.