comfyui-helm-chart

ComfyUI Helm Chart

Artifact Hub Build Status

A Helm chart for deploying ComfyUI on Kubernetes with GPU support. You can see an example usage here.

Prerequisites

Installation

helm repo add comfyui https://mmmateusz.github.io/comfyui-helm-chart
helm repo update
helm install comfyui comfyui/comfyui

Configuration

Key Default Description
workloadType StatefulSet Workload type: StatefulSet (default, required for local persistent storage) or Deployment (reserved for future HA)
image.repository yanwk/comfyui-boot Container image — see YanWenKun/ComfyUI-Docker
image.tag "" (Chart.appVersion) Image tag
image.pullPolicy IfNotPresent Image pull policy
replicaCount 1 Number of replicas
service.type ClusterIP Service type
service.ports 8188, 8080 Service ports (ComfyUI, code-server)
ingress.enabled false Enable ingress
ingress.hostname comfyui.example.com Ingress hostname
ingress.tls.enabled false Enable TLS
route.enabled false Enable Gateway API HTTPRoute
route.apiVersion gateway.networking.k8s.io/v1 Route API version
route.kind HTTPRoute Route kind
route.hostnames [] Hostnames to match
route.parentRefs [] References to parent Gateways
route.httpsRedirect false Create a separate HTTP→HTTPS redirect route
route.matches [{path: {type: PathPrefix, value: /}}] Route match rules
route.filters [] Route filters
route.additionalRules [] Extra route rules prepended before the backend rule
route.backendRef.group "" Backend API group ("" = core, i.e. Service)
route.backendRef.kind Service Backend kind
route.backendRef.port "" (first service port) Backend port override
route.backendRef.weight 1 Backend weight
route.annotations {} Annotations added to the route
route.extraLabels {} Extra labels added to the route
gpu.enabled true Request NVIDIA GPU
gpu.count 1 Number of GPUs
runtimeClassName "" Pod runtime class (e.g. nvidia)
persistence.enabled true Enable persistent storage
persistence.size 50Gi PVC size
persistence.storageClass "" StorageClass (empty = cluster default)
persistence.existingClaim "" Use an existing PVC instead of creating one
persistence.mounts see values.yaml List of {mountPath, subPath} entries — each maps a container path to a subdirectory of the PVC, skipping the ComfyUI installation itself
env [] Extra environment variables
envFrom [] Environment from ConfigMaps / Secrets
nodeSelector {} Node selector
tolerations [] Pod tolerations
affinity {} Pod affinity rules
resources {} CPU/memory resource requests and limits
podAnnotations {} Pod annotations
serviceAccount.create true Create a ServiceAccount
customNode405Fix true Install a built-in custom node that fixes 405 errors on /userdata/ paths containing special characters (spaces, Unicode) — see #1475
managerConfig.enabled false Render and mount ComfyUI-Manager’s config.ini from a ConfigMap. The mount is read-only, so this fully overwrites the file on every deploy — settings not listed in managerConfig.content revert to Manager defaults, and changes made later through the Manager UI will not persist
managerConfig.path /root/ComfyUI/user/__manager/config.ini Path to config.ini inside the container
managerConfig.content see values.yaml Full contents of config.ini

GPU nodes

GPU nodes are commonly tainted. Add a matching toleration:

tolerations:
  - key: nvidia.com/gpu
    operator: Exists
    effect: NoSchedule

To use the NVIDIA container runtime without consuming a GPU resource slot (useful when GPU access is controlled via runtimeClassName rather than device plugin limits), set:

gpu:
  enabled: false
runtimeClassName: nvidia

Ingress with basic auth (ingress-nginx)

htpasswd -c auth myuser
kubectl create secret generic comfyui-basic-auth --from-file=auth

ingress:
  enabled: true
  className: nginx
  annotations:
    nginx.ingress.kubernetes.io/auth-type: basic
    nginx.ingress.kubernetes.io/auth-secret: comfyui-basic-auth
    nginx.ingress.kubernetes.io/auth-realm: "Authentication Required"
  hostname: comfyui.example.com
  tls:
    enabled: true
    secretName: comfyui-tls

Gateway API

As an alternative to Ingress, the chart supports Kubernetes Gateway API via an HTTPRoute (or any other supported route kind).

Basic HTTPRoute:

route:
  enabled: true
  hostnames:
    - comfyui.example.com
  parentRefs:
    - name: my-gateway
      namespace: gateway-ns
      sectionName: https

With HTTP→HTTPS redirect (requires the gateway to have both an http and an https listener):

route:
  enabled: true
  httpsRedirect: true
  hostnames:
    - comfyui.example.com
  parentRefs:
    - name: my-gateway
      namespace: gateway-ns
      sectionName: https
  # Optional: override parentRefs for the redirect route only
  # redirect:
  #   parentRefs:
  #     - name: my-gateway
  #       namespace: gateway-ns
  #       sectionName: http

The redirect route automatically appends sectionName: http to each parentRef when route.redirect is not set explicitly.

Forwarding to the code-server port instead of the default ComfyUI port:

route:
  enabled: true
  hostnames:
    - code.example.com
  parentRefs:
    - name: my-gateway
  backendRef:
    port: 8080

Troubleshooting / known issues

405 errors on /userdata/ paths with special characters

ComfyUI’s /api/userdata/ and /userdata/ endpoints return 405 when the file path contains spaces or Unicode characters because the URL is double-encoded before routing (issue #1475).

The chart ships a fix enabled by default (customNode405Fix: true). It installs a Python middleware as a custom node via an init container on every pod start. Introduced in 0.6.0 Chart version.

Asset list disappears after restart

After a pod restart, the list of output assets visible in the ComfyUI UI may appear empty. This is a known bug in ComfyUI itself, not a problem with the Helm deployment or persistence — the files are still on the PVC. See ComfyUI issue #13061 for details and status.

ERROR: 1 required model is missing

ComfyUI requires at least one checkpoint model to function. If you see this error, download a proposed model and place it inside the container at:

/root/ComfyUI/models/checkpoints/

Roadmap

This site is open source. Improve this page.