# Hermes Agent für mehrere Nutzer auf Kubernetes

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

- URL: https://ashkmb.com/de/tutorials/multi-user-hermes-agent-kubernetes/
- Author: Ashkan Kamyab (https://ashkmb.com)
- Published: 2026-11-20
- Language: de
- Difficulty: intermediate
- Duration: 60 min
- Prerequisites: 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
- Tested: 2026-11-20; 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

Am Ende dieses Tutorials hat jede Person in Ihrem Team einen eigenen [Hermes Agent](https://github.com/NousResearch/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](https://ashkmb.com/de/blog/why-i-left-hermes-agent/) 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](https://ashkmb.com/de/blog/hermes-agent-eks-deployment/) einfacher.

## Was Sie bauen

```mermaid
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:

```bash no-run
export OPENROUTER_API_KEY='sk-or-...'
```

Legen Sie ein Arbeitsverzeichnis für die Dateien an, die Sie gleich schreiben:

```bash
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](https://docs.tigera.io/calico/latest/about/):

```bash
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`.

```bash
kubectl get nodes
```

```text
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](https://gateway-api.sigs.k8s.io/). **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](https://ashkmb.com/de/blog/ingress-nginx-archived-upstream/)). **cert-manager** stellt das TLS-Zertifikat aus.

```bash
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.

```bash
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"}'
```

```text
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:

```bash
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:

```bash
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:

```bash
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:

```bash
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.

```bash
helm lint ./charts/hermes-user --set user=alice | tail -1
```

```text
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).

```bash
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.

```bash
kubectl -n hermes-alice get pods
kubectl -n hermes-alice logs deploy/hermes -c set-model
```

```text
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:

```bash
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
```

```text
{"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:

```bash
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.

```text
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.

```bash
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).

```bash
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 $?)"'
```

```text
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.

```bash
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:

```bash
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:

```bash
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.

```text
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.

```bash
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.

```bash
kubectl get pods -A -l app.kubernetes.io/name=hermes
```

```text
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:

```bash no-run
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):

```bash
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:

```bash
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:**

```bash
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:

```bash
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:**

```bash
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.

```text
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 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:

```bash
cd ..
kind delete cluster --name hermes
```
