Hermes Agent für mehrere Nutzer auf Kubernetes

kuberneteshelmai-agentshermessecurity

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.

  • 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
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

SymptomUrsacheLösung
Network Policies existieren, aber Prüfung 1 oder 2 in Schritt 9 verbindet sichDas 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 --userrunAsUser/runAsNonRoot am Pod gesetztEntfernen; 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 ModellDas Gateway liest das Modell aus config.yaml, nicht aus HERMES_INFERENCE_MODELDen Init-Container set-model behalten; prüfen mit kubectl exec deploy/hermes -c hermes -- hermes config get model.default
Gateway zeigt Programmed=False, Grund AddressNotAssignedKein 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 nameDer 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 KeyEine 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-ProviderDas Dashboard verweigert ohne Authentifizierung den Start auf einer Nicht-Loopback-AdresseDie Werte HERMES_DASHBOARD_BASIC_AUTH_* behalten oder OIDC konfigurieren
Der Agent kann nach Schritt 6 keinen Hostnamen mehr auflösenDer Cluster nutzt NodeLocal DNSCache (169.254.20.10), das im ausgeschlossenen Bereich 169.254.0.0/16 liegtEine 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 TimeoutDas 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 auf openrouter.ai begrenzen.
  • 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/data enthä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

Markdown-Version