20. November 2026 · Fortgeschritten · 60 Min.
Hermes Agent für mehrere Nutzer auf Kubernetes
Was Sie am Ende haben
Geben Sie jeder Person in Ihrem Team einen eigenen Hermes Agent auf einem gemeinsamen Kubernetes-Cluster. Jeder Nutzer bekommt einen Namespace, ein Helm-Release, ein Volume, ein Secret, eine Network Policy und einen eigenen HTTPS-Hostnamen. So kann kein Agent das Gedächtnis oder die Dateien eines anderen lesen, dessen API-Key oder Dashboard-Passwort verwenden oder sich innerhalb des Clusters direkt mit einem anderen Agenten verbinden. Jeder Befehl wurde auf einem frischen Cluster vollständig durchgespielt.
Voraussetzungen
- Docker für einen lokalen Übungscluster mit kind (oder ein beliebiger Cluster, dessen CNI NetworkPolicy durchsetzt)
- kubectl 1.36 oder neuer, Helm 3.8 oder neuer (OCI-Charts), kind, curl, openssl und python3
- Ein OpenRouter-API-Key, am besten ein eigener mit kleinem Guthabenlimit
Getestet mit
- kubernetes
- 1.37.0 (kind 0.33.0)
- hermes-agent
- v2026.9.24 (0.21.5)
- helm
- 4.3.1
- calico
- 3.33.1
- envoy-gateway
- 1.10.0 (Gateway API 1.6.1)
- cert-manager
- 1.21.3
Getestet am 20. November 2026
Am Ende dieses Tutorials hat jede Person in Ihrem Team einen eigenen Hermes Agent auf einem gemeinsamen Kubernetes-Cluster, erreichbar unter einer eigenen HTTPS-Adresse wie alice.hermes.example.com. Jeder Agent läuft in einem eigenen Namespace mit eigenem Volume, eigenem Secret und eigenem API-Key. Network Policies verhindern, dass ein Agent einen anderen direkt erreicht, und keiner von ihnen hat Zugangsdaten für die Kubernetes-API. Eine weitere Person hinzuzufügen ist ein einziger Befehl.
Ich habe jeden Befehl unten vor der Veröffentlichung der Reihe nach auf einem frischen lokalen Cluster ausgeführt. Die Versionen stehen im Kasten oben. Wenn Sie bereits einen Cluster haben, gibt es nur eine harte Voraussetzung: ein CNI, das NetworkPolicy durchsetzt. Das Standard-CNI von kind tut das nicht.
Warum ein Hermes pro Nutzer
Hermes kann mehrere Personen aus einem Prozess bedienen. Sein Messaging-Gateway kennt Nutzer-Allowlists, und seine Profile geben jedem Agenten eine eigene Konfiguration und ein eigenes Gedächtnis. Beides teilt sich aber einen Prozess und ein Dateisystem. Der Agent hat eine echte Shell (das Standard-Terminal-Backend ist local, er führt Befehle also in seinem eigenen Container aus), und was der Agent der einen Person lesen kann, kann der Agent der anderen auch lesen.
Die Einheit der Isolation ist hier deshalb der Pod: ein Namespace, ein Deployment, ein Volume pro Person. Kubernetes liefert damit harte Grenzen gleich mit: getrennte Dateisysteme, getrennte Secrets, Network Policies und Resource Quotas.
Ist ein allgemeiner Agent pro Person überhaupt das richtige Werkzeug? Meine eigene Automatisierung habe ich von Hermes auf feste Pipelines umgestellt, weil meine Aufgaben im Voraus bekannt waren. Ein Team, das einen allgemeinen Assistenten möchte, der offene Fragen beantwortet, im Web sucht und auf Zuruf Werkzeuge ausführt, ist genau der Fall, für den ein allgemeiner Agent gemacht ist. Wenn Sie nur einen Agenten für sich selbst brauchen, ist die Einzelnutzer-Variante auf EKS einfacher.
Was Sie bauen
flowchart TB
alice(["https://alice.hermes.example.com"])
bob(["https://bob.hermes.example.com"])
gw["Gateway hermes<br/>Envoy Gateway, wildcard TLS from cert-manager"]
alice --> gw
bob --> gw
subgraph A["namespace hermes-alice"]
adep["Deployment hermes, 1 pod<br/>:8642 API (/v1), :9119 dashboard (/)"]
apvc[("PVC hermes-data<br/>/opt/data: memory")]
asec[/"Secret hermes-secrets<br/>keys, password"/]
apol["NetworkPolicy, quota<br/>in: gateway only<br/>out: DNS + public HTTPS"]
adep --- apvc
adep --- asec
adep --- apol
end
subgraph B["namespace hermes-bob"]
bdep["Deployment hermes, 1 pod<br/>same chart, own values"]
bown["own PVC, Secret,<br/>NetworkPolicy, quota"]
bdep --- bown
end
gw --> adep
gw --> bdep
Alles, was ein Nutzer braucht, kommt aus einem kleinen Helm-Chart, das Sie in Schritt 3 schreiben. Das Gateway und das Zertifikat werden geteilt und nur einmal installiert.
Legen Sie vorher Ihren OpenRouter-Key in Ihrer Shell ab. Alle späteren Befehle lesen ihn von dort:
export OPENROUTER_API_KEY='sk-or-...'
Legen Sie ein Arbeitsverzeichnis für die Dateien an, die Sie gleich schreiben:
mkdir -p hermes-k8s && cd hermes-k8s
Schritt 1: Einen Übungscluster anlegen
Überspringen Sie diesen Schritt, wenn Sie bereits einen Cluster haben, dessen CNI NetworkPolicy durchsetzt (Calico, Cilium und die meisten Managed-Angebote tun das).
Das Standard-CNI von kind akzeptiert NetworkPolicy-Objekte und ignoriert sie dann: Die Policies sehen angewendet aus, jede Verbindung geht trotzdem durch, und die Isolationsprüfungen in Schritt 9 schlagen fehl. Deshalb startet der Cluster ohne CNI und bekommt Calico:
cat > kind-hermes.yaml <<'EOF'
kind: Cluster
apiVersion: kind.x-k8s.io/v1alpha4
networking:
disableDefaultCNI: true # kind's default CNI ignores NetworkPolicy; Calico enforces it
podSubnet: 192.168.0.0/16
nodes:
- role: control-plane
- role: worker
EOF
kind create cluster --name hermes --config kind-hermes.yaml --image kindest/node:v1.37.0
kubectl apply -f https://raw.githubusercontent.com/projectcalico/calico/v3.33.1/manifests/calico.yaml >/dev/null
kubectl -n kube-system rollout status ds/calico-node --timeout=300s
kubectl wait --for=condition=Ready nodes --all --timeout=180s
Prüfen: Beide Nodes sind Ready.
kubectl get nodes
NAME STATUS ROLES AGE VERSION
hermes-control-plane Ready control-plane 2m v1.37.0
hermes-worker Ready <none> 2m v1.37.0
Schritt 2: Envoy Gateway und cert-manager installieren
Die Nutzer erreichen ihren Agenten über HTTPS durch die Gateway API. Envoy Gateway implementiert sie und installiert die CRDs der Gateway API mit seinem Chart. Die Gateway API statt eines Ingress-Controllers ist eine bewusste Wahl: Das Community-Projekt ingress-nginx wurde im März 2026 archiviert (was das in der Praxis bedeutet hat). cert-manager stellt das TLS-Zertifikat aus.
helm install eg oci://docker.io/envoyproxy/gateway-helm --version v1.10.0 \
-n envoy-gateway-system --create-namespace --wait >/dev/null
helm install cert-manager oci://quay.io/jetstack/charts/cert-manager --version v1.21.3 \
-n cert-manager --create-namespace --set crds.enabled=true --wait >/dev/null
Prüfen: Beide Controller laufen, und die CRDs der Gateway API existieren.
kubectl get deploy -n envoy-gateway-system envoy-gateway -o jsonpath='{.status.readyReplicas}{"\n"}'
kubectl get deploy -n cert-manager cert-manager -o jsonpath='{.status.readyReplicas}{"\n"}'
kubectl get crd gateways.gateway.networking.k8s.io -o jsonpath='{.metadata.annotations.gateway\.networking\.k8s\.io/bundle-version}{"\n"}'
1
1
v1.6.1
Schritt 3: Das Helm-Chart pro Nutzer schreiben
Das Chart erzeugt alles, was ein Nutzer in seinem Namespace braucht. Zwei Eigenschaften des offiziellen Images prägen es.
Das Image startet als root und wechselt dann zu einem unprivilegierten Nutzer. Sein Init-System (s6-overlay) korrigiert die Besitzrechte des Daten-Volumes und führt danach jeden Hermes-Prozess als Nutzer hermes (UID 10000) aus. Mit runAsNonRoot bricht dieser Start, und ein beliebiges --user lehnt das Image ab. Der Pod behält deshalb den Standard-Entrypoint, aber ohne Privilege Escalation, ohne jede Linux-Capability außer den fünf, die das Init braucht, und mit dem Standard-Seccomp-Profil.
Das Modell wird in der Hermes-eigenen Konfiguration festgelegt. Das Gateway liest das Modell aus config.yaml auf dem Volume. Der Standard des Images ist ein großes, teures Modell, und eine Umgebungsvariable überschreibt es für das Gateway nicht. Ein Init-Container führt bei jedem Start hermes config set aus, sodass der Helm-Wert die maßgebliche Quelle bleibt.
Die Dateien:
mkdir -p charts/hermes-user/templates
cat > charts/hermes-user/Chart.yaml <<'EOF'
apiVersion: v2
name: hermes-user
description: One isolated Hermes Agent for one user
type: application
version: 0.1.0
appVersion: "v2026.9.24"
EOF
cat > charts/hermes-user/values.yaml <<'EOF'
# The user this release belongs to. Used in labels and the hostname.
user: ""
image:
repository: nousresearch/hermes-agent
tag: v2026.9.24
pullPolicy: IfNotPresent
# Model the agent uses, through OpenRouter.
model: google/gemini-2.5-flash
# Secret (created outside Helm) holding OPENROUTER_API_KEY, API_SERVER_KEY,
# HERMES_DASHBOARD_BASIC_AUTH_PASSWORD and HERMES_DASHBOARD_BASIC_AUTH_SECRET.
existingSecret: hermes-secrets
storage:
size: 5Gi
storageClassName: "" # empty = cluster default
resources:
requests: { cpu: 250m, memory: 512Mi }
limits: { cpu: "2", memory: 2Gi }
quota:
cpu: "2"
memory: 4Gi
storage: 20Gi
gateway:
enabled: false
name: hermes
namespace: hermes-gateway
domain: hermes.example.com # the user gets <user>.<domain>
EOF
cat > charts/hermes-user/templates/_helpers.tpl <<'EOF'
{{- define "hermes.labels" -}}
app.kubernetes.io/name: hermes
app.kubernetes.io/instance: {{ .Release.Name }}
hermes.example.com/user: {{ required "set --set user=<name>" .Values.user | quote }}
{{- end }}
{{- define "hermes.selector" -}}
app.kubernetes.io/name: hermes
app.kubernetes.io/instance: {{ .Release.Name }}
{{- end }}
EOF
Der ServiceAccount bindet kein Token ein, die Shell des Agenten hat also keine Zugangsdaten für die Kubernetes-API. Das Volume bleibt beim Deinstallieren des Releases erhalten, weil es das Gedächtnis des Nutzers enthält:
cat > charts/hermes-user/templates/serviceaccount.yaml <<'EOF'
apiVersion: v1
kind: ServiceAccount
metadata:
name: hermes
labels: {{- include "hermes.labels" . | nindent 4 }}
automountServiceAccountToken: false
EOF
cat > charts/hermes-user/templates/pvc.yaml <<'EOF'
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
name: hermes-data
labels: {{- include "hermes.labels" . | nindent 4 }}
annotations:
helm.sh/resource-policy: keep # uninstalling the release keeps the user's memory
spec:
accessModes: [ReadWriteOnce]
resources:
requests:
storage: {{ .Values.storage.size }}
{{- with .Values.storage.storageClassName }}
storageClassName: {{ . }}
{{- end }}
EOF
Das Deployment betreibt das Gateway mit dem OpenAI-kompatiblen API-Server (Port 8642) und dem Web-Dashboard (Port 9119) in einem Pod. Ohne Auth-Provider verweigert das Dashboard den Start auf einer Nicht-Loopback-Adresse, deshalb bekommt es den eingebauten Provider mit Nutzername und Passwort:
cat > charts/hermes-user/templates/deployment.yaml <<'EOF'
apiVersion: apps/v1
kind: Deployment
metadata:
name: hermes
labels: {{- include "hermes.labels" . | nindent 4 }}
spec:
replicas: 1
strategy:
type: Recreate # the volume is ReadWriteOnce: never two pods at once
selector:
matchLabels: {{- include "hermes.selector" . | nindent 6 }}
template:
metadata:
labels: {{- include "hermes.labels" . | nindent 8 }}
spec:
serviceAccountName: hermes
automountServiceAccountToken: false
securityContext:
seccompProfile: { type: RuntimeDefault }
initContainers:
# Pin the model in the user's config.yaml on every start, so the Helm value is the source of truth.
- name: set-model
image: "{{ .Values.image.repository }}:{{ .Values.image.tag }}"
imagePullPolicy: {{ .Values.image.pullPolicy }}
command: ["sh", "-c"]
args:
- |
hermes config set model.provider openrouter &&
hermes config set model.default "$MODEL"
env:
- { name: MODEL, value: {{ .Values.model | quote }} }
- { name: HERMES_DOCKER_EXEC_AS_ROOT, value: "1" }
securityContext:
allowPrivilegeEscalation: false
capabilities:
drop: [ALL]
add: [CHOWN, DAC_OVERRIDE, FOWNER]
volumeMounts:
- { name: data, mountPath: /opt/data }
containers:
- name: hermes
image: "{{ .Values.image.repository }}:{{ .Values.image.tag }}"
imagePullPolicy: {{ .Values.image.pullPolicy }}
args: ["gateway", "run"]
env:
- { name: API_SERVER_ENABLED, value: "true" }
- { name: API_SERVER_HOST, value: "0.0.0.0" }
- { name: API_SERVER_MODEL_NAME, value: {{ printf "hermes-%s" .Values.user | quote }} }
- { name: HERMES_DASHBOARD, value: "1" }
- { name: HERMES_DASHBOARD_BASIC_AUTH_USERNAME, value: {{ .Values.user | quote }} }
envFrom:
- secretRef:
name: {{ .Values.existingSecret }}
ports:
- { name: api, containerPort: 8642 }
- { name: dashboard, containerPort: 9119 }
readinessProbe:
httpGet: { path: /health, port: api }
periodSeconds: 10
livenessProbe:
httpGet: { path: /health, port: api }
initialDelaySeconds: 60
periodSeconds: 30
resources: {{- toYaml .Values.resources | nindent 12 }}
securityContext:
# The image's init starts as root, fixes ownership of /opt/data,
# then runs every Hermes process as the unprivileged user hermes (UID 10000).
allowPrivilegeEscalation: false
capabilities:
drop: [ALL]
add: [CHOWN, DAC_OVERRIDE, FOWNER, SETUID, SETGID]
volumeMounts:
- { name: data, mountPath: /opt/data }
volumes:
- name: data
persistentVolumeClaim:
claimName: hermes-data
EOF
cat > charts/hermes-user/templates/service.yaml <<'EOF'
apiVersion: v1
kind: Service
metadata:
name: hermes
labels: {{- include "hermes.labels" . | nindent 4 }}
spec:
selector: {{- include "hermes.selector" . | nindent 4 }}
ports:
- { name: api, port: 8642, targetPort: api }
- { name: dashboard, port: 9119, targetPort: dashboard }
EOF
Eine Quota begrenzt, was ein Nutzer verbrauchen kann, damit ein außer Kontrolle geratener Agent die anderen nicht aushungert:
cat > charts/hermes-user/templates/quota.yaml <<'EOF'
apiVersion: v1
kind: ResourceQuota
metadata:
name: hermes
labels: {{- include "hermes.labels" . | nindent 4 }}
spec:
hard:
limits.cpu: {{ .Values.quota.cpu | quote }}
limits.memory: {{ .Values.quota.memory }}
requests.storage: {{ .Values.quota.storage }}
persistentvolumeclaims: "2"
pods: "4"
---
apiVersion: v1
kind: LimitRange
metadata:
name: hermes
labels: {{- include "hermes.labels" . | nindent 4 }}
spec:
limits:
- type: Container
default: { cpu: 500m, memory: 512Mi }
defaultRequest: { cpu: 100m, memory: 128Mi }
EOF
Prüfen: Das Chart besteht den Lint ohne Fehler.
helm lint ./charts/hermes-user --set user=alice | tail -1
1 chart(s) linted, 0 chart(s) failed
Schritt 4: Den ersten Nutzer anlegen
Jeder Nutzer bekommt einen Namespace (als Tenant markiert, was das Gateway in Schritt 7 nutzt) und ein Secret mit vier Werten: den OpenRouter-Key, einen zufälligen API-Key für seinen Agenten sowie ein zufälliges Dashboard-Passwort und ein Secret zum Signieren der Sitzungen. Das Secret entsteht außerhalb von Helm, damit die Schlüssel weder in einer Values-Datei noch in der Release-Historie von Helm landen.
Damit das Beispiel kurz bleibt, bekommen alle Nutzer denselben OpenRouter-Key. Jeder Agent kann die Schlüssel in seiner eigenen Umgebung lesen; geben Sie in einem echten Team deshalb jeder Person einen eigenen OpenRouter-Key (siehe Härtung).
u=alice
kubectl create namespace hermes-$u
kubectl label namespace hermes-$u hermes.example.com/tenant=true
kubectl -n hermes-$u create secret generic hermes-secrets \
--from-literal=OPENROUTER_API_KEY="$OPENROUTER_API_KEY" \
--from-literal=API_SERVER_KEY="$(openssl rand -hex 32)" \
--from-literal=HERMES_DASHBOARD_BASIC_AUTH_PASSWORD="$(openssl rand -hex 16)" \
--from-literal=HERMES_DASHBOARD_BASIC_AUTH_SECRET="$(openssl rand -hex 32)"
helm install hermes ./charts/hermes-user -n hermes-$u --set user=$u --wait --timeout 10m >/dev/null
Der erste Start lädt ein großes Image, --wait kann daher einige Minuten dauern.
Prüfen: Der Pod läuft, und der Init-Container hat das Modell festgelegt.
kubectl -n hermes-alice get pods
kubectl -n hermes-alice logs deploy/hermes -c set-model
NAME READY STATUS RESTARTS AGE
hermes-6d9f8b7c4d-x2k8p 1/1 Running 0 3m
✓ Set model.provider = openrouter in /opt/data/config.yaml
✓ Set model.default = google/gemini-2.5-flash in /opt/data/config.yaml
Schritt 5: Mit dem Agenten sprechen
Solange es noch keinen öffentlichen Hostnamen gibt, erreichen Sie Alices Agenten über einen Port-Forward. Ihr API-Key steht in ihrem Secret:
kubectl -n hermes-alice port-forward svc/hermes 8642:8642 >/dev/null &
PF=$!
sleep 3
ALICE_KEY=$(kubectl -n hermes-alice get secret hermes-secrets -o jsonpath='{.data.API_SERVER_KEY}' | base64 -d)
curl -s localhost:8642/health; echo
curl -s -o /dev/null -w 'without a key: %{http_code}\n' localhost:8642/v1/models
{"status": "ok", "platform": "hermes-agent", "version": "0.21.5"}
without a key: 401
Jetzt eine echte Anfrage. Die API spricht das Chat-Format von OpenAI, also funktioniert auch jeder OpenAI-kompatible Client:
curl -s localhost:8642/v1/chat/completions \
-H "Authorization: Bearer $ALICE_KEY" -H 'Content-Type: application/json' \
-d '{"model": "hermes-alice", "messages": [{"role": "user", "content": "Reply with exactly: hello from alice"}]}' \
| python3 -c 'import sys, json; print(json.load(sys.stdin)["choices"][0]["message"]["content"])'
kill $PF
Prüfen: Der Agent antwortet über das Modell.
hello from alice
Das Dashboard funktioniert genauso auf Port 9119. Der Nutzername ist alice, das Passwort ist HERMES_DASHBOARD_BASIC_AUTH_PASSWORD in ihrem Secret.
Schritt 6: Das Netzwerk abriegeln
Im Moment kann jeder Pod im Cluster Alices Agenten erreichen, und ihr Agent kann alles erreichen. Drei Policies ändern das: alles verbieten, dann ausgehend DNS und HTTPS ins öffentliche Internet erlauben und eingehend nur die Proxys des Gateways.
Die ausgehende Regel ist absichtlich großzügig. Hermes ist ein allgemeiner Assistent, dessen Web-Werkzeuge das offene Internet brauchen, und eine Standard-NetworkPolicy kann ohnehin keine Hostnamen abgleichen. Wichtiger ist, was sie ausschließt: jeden privaten Adressbereich, also keinen Pod eines anderen Tenants, keine clusterinterne Service-Adresse und keinen Cloud-Metadaten-Endpunkt (169.254.169.254, wo bei den meisten Clouds die Zugangsdaten des Nodes liegen).
Zwei Dinge verhindert diese Policy nicht. Über das öffentliche Gateway erreicht der Agent eines Nutzers den Hostnamen eines anderen wie jeder Client im Internet; dort schützen ihn der API-Key und das Dashboard-Passwort des jeweiligen Nutzers. Und wenn der API-Server Ihres Clusters einen öffentlichen Endpunkt hat, erreicht der Agent ihn auf Port 443; dort stoppen ihn das fehlende Token und RBAC. Um die erste Lücke zu schließen, nehmen Sie die Load-Balancer-Adresse Ihres Gateways in die except-Liste auf.
cat >> charts/hermes-user/values.yaml <<'EOF'
networkPolicy:
enabled: true
# Namespace of the gateway's proxy pods, the only allowed inbound source.
proxyNamespace: envoy-gateway-system
EOF
cat > charts/hermes-user/templates/networkpolicy.yaml <<'EOF'
{{- if .Values.networkPolicy.enabled }}
# 1. Nothing in or out by default.
apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
metadata:
name: default-deny
labels: {{- include "hermes.labels" . | nindent 4 }}
spec:
podSelector: {}
policyTypes: [Ingress, Egress]
---
# 2. Out: DNS, and HTTPS to the public internet only (model API, web tools).
# Private ranges are excluded: no other tenant, no cluster service, no cloud metadata.
apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
metadata:
name: hermes-egress
labels: {{- include "hermes.labels" . | nindent 4 }}
spec:
podSelector:
matchLabels: {{- include "hermes.selector" . | nindent 6 }}
policyTypes: [Egress]
egress:
- to:
- namespaceSelector:
matchLabels: { kubernetes.io/metadata.name: kube-system }
podSelector:
matchLabels: { k8s-app: kube-dns }
ports:
- { protocol: UDP, port: 53 }
- { protocol: TCP, port: 53 }
- to:
- ipBlock:
cidr: 0.0.0.0/0
except: [10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16, 100.64.0.0/10, 169.254.0.0/16]
ports:
- { protocol: TCP, port: 443 }
---
# 3. In: only from the gateway's proxies.
apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
metadata:
name: hermes-ingress
labels: {{- include "hermes.labels" . | nindent 4 }}
spec:
podSelector:
matchLabels: {{- include "hermes.selector" . | nindent 6 }}
policyTypes: [Ingress]
ingress:
- from:
- namespaceSelector:
matchLabels: { kubernetes.io/metadata.name: {{ .Values.networkPolicy.proxyNamespace }} }
ports:
- { protocol: TCP, port: 8642 }
- { protocol: TCP, port: 9119 }
{{- end }}
EOF
helm upgrade hermes ./charts/hermes-user -n hermes-alice --set user=alice --wait >/dev/null
Prüfen: Die Policies existieren, der Agent erreicht weiterhin das Internet, und die Metadaten-Adresse läuft in ein Timeout (curl-Exit-Code 28).
kubectl -n hermes-alice get networkpolicy
kubectl -n hermes-alice exec deploy/hermes -c hermes -- \
curl -s -m 8 -o /dev/null -w 'public HTTPS: %{http_code}\n' https://openrouter.ai/api/v1/models
kubectl -n hermes-alice exec deploy/hermes -c hermes -- \
sh -c 'curl -s -m 5 http://169.254.169.254/ || echo "metadata: blocked (exit $?)"'
NAME POD-SELECTOR AGE
default-deny <none> 5s
hermes-egress app.kubernetes.io/instance=hermes,app.kubernetes.io/name=hermes 5s
hermes-ingress app.kubernetes.io/instance=hermes,app.kubernetes.io/name=hermes 5s
public HTTPS: 200
metadata: blocked (exit 28)
Schritt 7: Jeden Nutzer unter einem eigenen Hostnamen erreichbar machen
Ein gemeinsames Gateway terminiert TLS für *.hermes.example.com und akzeptiert Routen nur aus Namespaces, die als Tenant markiert sind. Das Release jedes Nutzers fügt eine HTTPRoute für dessen eigenen Hostnamen hinzu: /v1 geht an die API, alles andere an das Dashboard.
Zum Üben erzeugt cert-manager eine kleine private CA und signiert damit das Wildcard-Zertifikat. In der Produktion ersetzen Sie den ClusterIssuer hermes-ca durch Let’s Encrypt mit einem DNS-01-Solver (ein Wildcard-Zertifikat braucht DNS-01) und lassen *.hermes.example.com auf die Adresse des Gateways zeigen.
mkdir -p platform
cat > platform/gateway.yaml <<'EOF'
apiVersion: gateway.networking.k8s.io/v1
kind: GatewayClass
metadata:
name: eg
spec:
controllerName: gateway.envoyproxy.io/gatewayclass-controller
---
apiVersion: v1
kind: Namespace
metadata:
name: hermes-gateway
---
# Practice CA: a self-signed root that signs the wildcard certificate.
# In production, replace the "hermes-ca" ClusterIssuer with Let's Encrypt and a DNS-01 solver
# (a wildcard certificate needs DNS-01).
apiVersion: cert-manager.io/v1
kind: ClusterIssuer
metadata:
name: selfsigned
spec:
selfSigned: {}
---
apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
name: hermes-practice-ca
namespace: cert-manager
spec:
isCA: true
commonName: hermes-practice-ca
secretName: hermes-practice-ca
privateKey: { algorithm: ECDSA, size: 256 }
issuerRef: { name: selfsigned, kind: ClusterIssuer }
---
apiVersion: cert-manager.io/v1
kind: ClusterIssuer
metadata:
name: hermes-ca
spec:
ca:
secretName: hermes-practice-ca
---
apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
name: hermes-wildcard
namespace: hermes-gateway
spec:
secretName: hermes-wildcard-tls
commonName: "*.hermes.example.com"
dnsNames: ["*.hermes.example.com"]
issuerRef: { name: hermes-ca, kind: ClusterIssuer }
---
apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
name: hermes
namespace: hermes-gateway
spec:
gatewayClassName: eg
listeners:
- name: https
protocol: HTTPS
port: 443
hostname: "*.hermes.example.com"
tls:
mode: Terminate
certificateRefs:
- name: hermes-wildcard-tls
allowedRoutes:
namespaces:
from: Selector
selector:
matchLabels:
hermes.example.com/tenant: "true"
EOF
kubectl apply -f platform/gateway.yaml
kubectl -n hermes-gateway wait --for=condition=Ready certificate/hermes-wildcard --timeout=120s
kubectl -n hermes-gateway wait --for=condition=Accepted gateway/hermes --timeout=120s
Jetzt das Routen-Template und Alices Release mit eingeschaltetem Gateway:
cat > charts/hermes-user/templates/httproute.yaml <<'EOF'
{{- if .Values.gateway.enabled }}
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
name: hermes
labels: {{- include "hermes.labels" . | nindent 4 }}
spec:
parentRefs:
- name: {{ .Values.gateway.name }}
namespace: {{ .Values.gateway.namespace }}
sectionName: https
hostnames:
- {{ printf "%s.%s" .Values.user .Values.gateway.domain | quote }}
rules:
# OpenAI-compatible API
- matches:
- path: { type: PathPrefix, value: /v1 }
backendRefs:
- { name: hermes, port: 8642 }
# Everything else: the web dashboard
- backendRefs:
- { name: hermes, port: 9119 }
{{- end }}
EOF
helm upgrade hermes ./charts/hermes-user -n hermes-alice --set user=alice --set gateway.enabled=true --wait >/dev/null
In einem Cloud-Cluster bekommt das Gateway eine Load-Balancer-Adresse (kubectl -n hermes-gateway get gateway hermes). kind hat keinen Load Balancer, daher bleibt das Gateway auf Programmed=False mit dem Grund AddressNotAssigned, und Sie erreichen den Proxy stattdessen über einen Port-Forward. curl --resolve sendet den echten Hostnamen, TLS und Routing werden also genau wie in der Produktion durchlaufen:
kubectl -n envoy-gateway-system wait --for=condition=Ready pod \
-l gateway.envoyproxy.io/owning-gateway-name=hermes --timeout=180s >/dev/null
kubectl -n hermes-gateway get secret hermes-wildcard-tls -o jsonpath='{.data.ca\.crt}' | base64 -d > hermes-ca.crt
GW_SVC=$(kubectl -n envoy-gateway-system get svc -l gateway.envoyproxy.io/owning-gateway-name=hermes -o name)
kubectl -n envoy-gateway-system port-forward "$GW_SVC" 8443:443 >/dev/null &
GW_PF=$!
sleep 3
hcurl() { curl -s --cacert hermes-ca.crt --resolve "$1.hermes.example.com:8443:127.0.0.1" "${@:2}"; }
hcurl alice https://alice.hermes.example.com:8443/v1/chat/completions \
-H "Authorization: Bearer $ALICE_KEY" -H 'Content-Type: application/json' \
-d '{"model": "hermes-alice", "messages": [{"role": "user", "content": "Reply with exactly: hello over https"}]}' \
| python3 -c 'import sys, json; print(json.load(sys.stdin)["choices"][0]["message"]["content"])'
hcurl alice -o /dev/null -w 'dashboard: %{http_code}\n' https://alice.hermes.example.com:8443/
Prüfen: Die API antwortet über HTTPS, und das Dashboard leitet auf seine Login-Seite um.
hello over https
dashboard: 302
Schritt 8: Weitere Nutzer anlegen
Die Schritte 4 und 7 für einen Nutzer passen in ein kleines Skript. Es lässt sich gefahrlos erneut ausführen: Ein vorhandenes Secret bleibt erhalten, die Schlüssel eines Nutzers ändern sich also nicht.
cat > add-user.sh <<'EOF'
#!/usr/bin/env bash
# Usage: ./add-user.sh <user> (needs OPENROUTER_API_KEY in the environment)
set -euo pipefail
u="$1"
ns="hermes-$u"
kubectl create namespace "$ns" --dry-run=client -o yaml | kubectl apply -f -
kubectl label namespace "$ns" hermes.example.com/tenant=true --overwrite
if ! kubectl -n "$ns" get secret hermes-secrets >/dev/null 2>&1; then
kubectl -n "$ns" create secret generic hermes-secrets \
--from-literal=OPENROUTER_API_KEY="$OPENROUTER_API_KEY" \
--from-literal=API_SERVER_KEY="$(openssl rand -hex 32)" \
--from-literal=HERMES_DASHBOARD_BASIC_AUTH_PASSWORD="$(openssl rand -hex 16)" \
--from-literal=HERMES_DASHBOARD_BASIC_AUTH_SECRET="$(openssl rand -hex 32)"
fi
helm upgrade --install hermes ./charts/hermes-user -n "$ns" \
--set user="$u" --set gateway.enabled=true --wait --timeout 10m
EOF
chmod +x add-user.sh
./add-user.sh bob >/dev/null
Prüfen: zwei Agenten, einer pro Namespace.
kubectl get pods -A -l app.kubernetes.io/name=hermes
NAMESPACE NAME READY STATUS RESTARTS AGE
hermes-alice hermes-7c5d9b8f6-q4wzl 1/1 Running 0 6m
hermes-bob hermes-5f8b6c7d9-m2xkj 1/1 Running 0 1m
Um einen Nutzer zu entfernen, deinstallieren Sie das Release und löschen den Namespace. Wegen der keep-Policy am Volume behält helm uninstall allein das Gedächtnis; erst das Löschen des Namespace entfernt es endgültig:
helm uninstall hermes -n hermes-bob
kubectl delete namespace hermes-bob
Schritt 9: Die Isolation beweisen
Fünf Prüfungen, jede eine Grenze, auf die es ankommt.
1. Alices Agent erreicht Bobs Agenten nicht. Ihre Egress-Policy blockiert private Adressen, und seine Ingress-Policy akzeptiert nur das Gateway. curl gibt nach 5 Sekunden auf (Exit-Code 28):
kubectl -n hermes-alice exec deploy/hermes -c hermes -- \
sh -c 'curl -s -m 5 http://hermes.hermes-bob:8642/health || echo "alice -> bob: blocked (exit $?)"'
2. Auch sonst erreicht nichts im Cluster Bobs Agenten, nicht einmal ein Pod in einem Namespace ganz ohne Policies:
kubectl run probe -n default --rm -i --restart=Never --quiet --image=curlimages/curl:8.17.0 --command -- \
sh -c 'curl -s -m 5 http://hermes.hermes-bob:8642/health || echo "default -> bob: blocked (exit $?)"'
3. Alices Key öffnet Bobs Agenten nicht:
hcurl bob -o /dev/null -w 'alice key on bob: %{http_code}\n' \
-H "Authorization: Bearer $ALICE_KEY" https://bob.hermes.example.com:8443/v1/models
4. Der Agent hat keine Kubernetes-Zugangsdaten. Es ist kein Token eingebunden, und der ServiceAccount darf nichts lesen:
kubectl -n hermes-alice exec deploy/hermes -c hermes -- \
sh -c 'ls /var/run/secrets/kubernetes.io/serviceaccount 2>/dev/null || echo "no service account token"'
kubectl auth can-i get secrets -n hermes-bob --as=system:serviceaccount:hermes-alice:hermes || true
5. Bobs eigener Key funktioniert für Bob weiterhin:
BOB_KEY=$(kubectl -n hermes-bob get secret hermes-secrets -o jsonpath='{.data.API_SERVER_KEY}' | base64 -d)
hcurl bob -o /dev/null -w 'bob key on bob: %{http_code}\n' \
-H "Authorization: Bearer $BOB_KEY" https://bob.hermes.example.com:8443/v1/models
kill $GW_PF
Prüfen: alle fünf, der Reihe nach.
alice -> bob: blocked (exit 28)
default -> bob: blocked (exit 28)
alice key on bob: 401
no service account token
no
bob key on bob: 200
Fehlersuche
| Symptom | Ursache | Lösung |
|---|---|---|
| Network Policies existieren, aber Prüfung 1 oder 2 in Schritt 9 verbindet sich | Das CNI setzt NetworkPolicy nicht durch (kindnet von kind, manche Minimal-Setups) | Calico oder Cilium verwenden, wie in Schritt 1 |
Pod beendet sich beim Start mit [stage2] ERROR: container started with --user | runAsUser/runAsNonRoot am Pod gesetzt | Entfernen; das Init des Images muss als root starten und wechselt selbst zu UID 10000 (Schritt 3) |
| Der Agent antwortet, aber die OpenRouter-Abrechnung zeigt ein teures Modell | Das Gateway liest das Modell aus config.yaml, nicht aus HERMES_INFERENCE_MODEL | Den Init-Container set-model behalten; prüfen mit kubectl exec deploy/hermes -c hermes -- hermes config get model.default |
Gateway zeigt Programmed=False, Grund AddressNotAssigned | Kein Load Balancer (kind, Bare Metal) | Auf kind erwartet; den Port-Forward aus Schritt 7 verwenden oder MetalLB bzw. cloud-provider-kind installieren |
curl: (60) oder unter macOS couldn't get X509-issuer name | Der Client vertraut der Übungs-CA nicht, oder das Zertifikat ist ein selbstsigniertes Zertifikat ohne Subject | --cacert hermes-ca.crt übergeben; den CA-Issuer aus Schritt 7 behalten, statt das Wildcard-Zertifikat direkt mit selfSigned zu signieren |
API antwortet mit 401 trotz richtigem Key | Eine Zeile API_SERVER_KEY in /opt/data/.env hat Vorrang vor der Pod-Umgebung (die Logs warnen davor) | Die Zeile aus .env auf dem Volume entfernen oder den Key im Secret rotieren und neu starten |
| Das Dashboard startet nicht, die Logs nennen einen fehlenden Auth-Provider | Das Dashboard verweigert ohne Authentifizierung den Start auf einer Nicht-Loopback-Adresse | Die Werte HERMES_DASHBOARD_BASIC_AUTH_* behalten oder OIDC konfigurieren |
| Der Agent kann nach Schritt 6 keinen Hostnamen mehr auflösen | Der Cluster nutzt NodeLocal DNSCache (169.254.20.10), das im ausgeschlossenen Bereich 169.254.0.0/16 liegt | Eine Egress-Regel für 169.254.20.10/32 auf Port 53 UDP und TCP hinzufügen |
helm install --wait läuft beim ersten Nutzer in ein Timeout | Das Image ist groß, der erste Pull dauert | --timeout erhöhen; den Fortschritt mit kubectl -n hermes-alice describe pod prüfen |
Härtung für die Produktion
- Ausgehenden Verkehr weiter einschränken, wenn Ihre Nutzer das offene Web nicht brauchen. Eine Standard-NetworkPolicy kennt nur IP-Bereiche. Mit den
toFQDNs-Regeln von Cilium lässt sich der Verkehr namentlich aufopenrouter.aibegrenzen. - OIDC für das Dashboard statt des gemeinsamen Nutzernamens und Passworts. Hermes unterstützt einen selbst gehosteten OpenID-Connect-Provider (
HERMES_DASHBOARD_OIDC_ISSUER,HERMES_DASHBOARD_OIDC_CLIENT_ID). Offen erreichbare Hermes-Dashboards und API-Server ohne Authentifizierung wurden im Juni 2026 im Internet gescannt und missbraucht; deshalb startet das Dashboard heute nicht mehr ohne Auth. Behandeln Sie jeden Agenten-Endpunkt wie eine entfernte Shell, denn genau das ist er. - Ein OpenRouter-Key pro Nutzer, jeder mit eigenem Guthabenlimit. Ein geleakter Key betrifft dann nur eine Person, die Endlosschleife einer Person kann nicht das Budget aller aufbrauchen, und die Kosten sind pro Person sichtbar.
- Die Volumes sichern.
/opt/dataenthält Gedächtnis, Sitzungen und Skills jedes Nutzers. Ein Snapshot-Zeitplan für Volumes (oder Velero) macht den Unterschied zwischen einem Pod-Neustart und einem verlorenen Assistenten. - Ein Operator statt Helm. Auf OperatorHub gibt es einen Hermes-Operator aus der Community. Ein einfaches Helm-Release pro Nutzer ist leichter zu lesen und zu debuggen, deshalb verwendet dieses Tutorial eines.
Aufräumen
Löschen Sie den Übungscluster samt Inhalt:
cd ..
kind delete cluster --name hermes