HTTP-Proxys richtig setzen: Bun, Node, Docker und Kubernetes

In Unternehmensnetzen läuft ausgehender Traffic häufig über einen HTTP-Proxy. Damit ProcessCube®-Komponenten dorthin finden, steuern drei Umgebungsvariablen das Verhalten: HTTP_PROXY, HTTPS_PROXY, NO_PROXY. Die Tücke: Bun und Node gehen unterschiedlich damit um, und in Docker und Kubernetes kommen Fallstricke dazu.

Welche Komponente läuft worauf?

Welche Regeln gelten, hängt von der Laufzeit-Basis der jeweiligen Komponente ab:

Faustregel: Bun-Komponenten verstehen die Proxy-Variablen sofort, Node-Komponenten brauchen NODE_USE_ENV_PROXY=1 (oder eine Bibliothek).

Die drei Variablen

NO_PROXY ist nicht standardisiert — das Matching unterscheidet sich je nach Runtime, und das ist der häufigste Stolperstein:

Bun — versteht die Variablen nativ

Bun respektiert HTTP_PROXY / HTTPS_PROXY / NO_PROXY in fetch() und bei bun install ohne weiteres Zutun. Da die ProcessCube® CLI ein Bun-Single-Binary ist, gilt das direkt für pc:

export HTTPS_PROXY=http://proxy.firma.local:8080
export NO_PROXY=localhost,127.0.0.1,.firma.local
pc engine login --url https://engine.extern.example.com

• Per-Request lässt sich der Proxy auch über die proxy-Option von fetch() setzen.
• Seit Bun 1.3.9 wird NO_PROXY auch dann ausgewertet, wenn ein Proxy explizit über die proxy-Option übergeben wird.

Node — opt-in (Node 24) oder Bibliothek

Anders als Bun ignoriert Nodes eingebautes fetch / node:http / node:https die Proxy-Variablen standardmäßig.

NODE_USE_ENV_PROXY=1 \
HTTPS_PROXY=http://proxy.firma.local:8080 \
NO_PROXY=localhost,127.0.0.1 \
node app.js

Docker

docker build \
  --build-arg HTTPS_PROXY=http://proxy.firma.local:8080 \
  --build-arg NO_PROXY=localhost,127.0.0.1,.firma.local \
  -t meine-app .

docker run \
  -e HTTPS_PROXY=http://proxy.firma.local:8080 \
  -e NO_PROXY=localhost,127.0.0.1,.firma.local \
  -e NODE_USE_ENV_PROXY=1 \
  ghcr.io/processcube-io/engine

Kubernetes / k3s

In Pods werden die Variablen am saubersten über eine ConfigMap gesetzt und per envFrom eingebunden:

apiVersion: v1
kind: ConfigMap
metadata:
  name: proxy-env
data:
  HTTP_PROXY: "http://proxy.firma.local:8080"
  HTTPS_PROXY: "http://proxy.firma.local:8080"
  # App-Pods (Node/Bun) matchen per Hostname → DNS-Suffixe, KEINE CIDRs
  NO_PROXY: "localhost,127.0.0.1,.svc,.svc.cluster.local,.cluster.local"

# Deployment (Auszug)
spec:
  template:
    spec:
      containers:
        - name: engine
          envFrom:
            - configMapRef:
                name: proxy-env
          env:
            - name: NODE_USE_ENV_PROXY   # Engine/Low-Code laufen auf Node 24
              value: "1"

Für k3s selbst (Image-Pulls über containerd, Go) gehören die Proxy-Variablen in die systemd-Env-Datei:

# /etc/systemd/system/k3s.service.env
HTTP_PROXY=http://proxy.firma.local:8080
HTTPS_PROXY=http://proxy.firma.local:8080
NO_PROXY=localhost,127.0.0.1

k3s ergänzt die Cluster-internen Pod-/Service-CIDRs und die Cluster-DNS-Domain automatisch zu NO_PROXY seines eigenen Prozesses — die obige Liste reicht daher für k3s aus. Für die Anwendungs-Pods gilt das jedoch nicht; dort die vollständige NO_PROXY-Liste (siehe ConfigMap oben) selbst pflegen.

Checkliste

• ✅ HTTPS_PROXY gesetzt (nicht nur HTTP_PROXY) — der meiste Traffic ist https://.
• ✅ Proxy-Wert als http://…-URL (nicht https://).
• ✅ Node: NODE_USE_ENV_PROXY=1 (Node 24) oder eine Proxy-Bibliothek — sonst wirkungslos.
• ✅ NO_PROXY umfasst interne Ziele: localhost, Engine/Authority, Service-Namen, in k8s die Cluster-DNS-Suffixe (.svc.cluster.local). CIDRs nur für Go-Tools (k3s/containerd), nicht für Node/Bun.
• ✅ Im Zweifel Groß- und Kleinschreibung der Variablen setzen.

Weiterführend

• Node.js: Enterprise Network Configuration  — NODE_USE_ENV_PROXY und NO_PROXY-Matching-Regeln (Hostname/Suffix, kein CIDR)
• Node.js 24 Release Notes 
• Bun: Proxy HTTP requests using fetch()