# ایجنت چندکاربره‌ی Hermes روی Kubernetes

> به هر نفر از تیمت یه ایجنت Hermes مخصوص خودش بده، همه روی یه کلاستر Kubernetes. هر کاربر نیم‌اسپیس، ریلیز Helm، والیوم، سکرت، پالیسی شبکه و آدرس HTTPS خودش رو داره؛ برای همین هیچ ایجنتی نمی‌تونه حافظه یا فایل‌های یکی دیگه رو بخونه، با کلید API یا رمز داشبورد یکی دیگه وارد بشه، یا داخل کلاستر مستقیم به ایجنت دیگه‌ای وصل بشه. همه‌ی دستورها روی یه کلاستر تازه از اول تا آخر اجرا شدن.

- URL: https://ashkmb.com/fa/tutorials/multi-user-hermes-agent-kubernetes/
- Author: Ashkan Kamyab (https://ashkmb.com)
- Published: 2026-11-20
- Language: fa
- Difficulty: intermediate
- Duration: 60 min
- Prerequisites: داکر، برای یه کلاستر تمرینی محلی با kind (یا هر کلاستری که CNI اون NetworkPolicy رو اعمال کنه); ابزار kubectl 1.36 به بالا، Helm 3.8 به بالا (برای چارت‌های OCI)، kind، curl، openssl و python3; یه کلید API از OpenRouter، ترجیحاً یه کلید جدا با سقف اعتبار کم
- 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

آخر این آموزش، هر نفر از تیمت یه [ایجنت Hermes](https://github.com/NousResearch/hermes-agent) مخصوص خودش داره که روی یه کلاستر مشترک Kubernetes اجرا می‌شه و آدرس HTTPS خودش رو داره، مثلاً `alice.hermes.example.com`. هر ایجنت نیم‌اسپیس، والیوم، سکرت و کلید API خودش رو داره. پالیسی شبکه نمی‌ذاره هیچ ایجنتی مستقیم به ایجنت دیگه وصل بشه، و هیچ‌کدومشون هم اعتبارنامه‌ای برای API کلاستر ندارن. اضافه کردن یه نفر جدید فقط یه دستوره.

همه‌ی دستورهای پایین رو قبل از انتشار، به همین ترتیب، روی یه کلاستر محلی تازه اجرا کردم. نسخه‌ها توی کادر بالا هستن. اگه از قبل کلاستر داری، تنها شرط واقعی اینه که CNI اون پالیسی‌های شبکه رو اعمال کنه؛ CNI پیش‌فرض kind این کار رو نمی‌کنه.

## چرا برای هر کاربر یه Hermes جدا

ایجنت Hermes می‌تونه با یه پروسه به چند نفر جواب بده. گیت‌وی پیام‌رسان Hermes لیست کاربرهای مجاز داره، و پروفایل‌هاش به هر ایجنت کانفیگ و حافظه‌ی جدا می‌دن. ولی هر دوشون یه پروسه و یه فایل‌سیستم مشترک دارن. ایجنت یه شل واقعی داره. بک‌اند پیش‌فرض ترمینالش روی `local` تنظیم شده، یعنی دستورها رو توی کانتینر خودش اجرا می‌کنه. هر چیزی که ایجنتِ یه نفر بتونه بخونه، ایجنت بقیه هم می‌تونه بخونه.

برای همین این‌جا واحد ایزوله‌سازی، خود پاده: برای هر نفر یه نیم‌اسپیس، یه دیپلویمنت و یه والیوم. اون‌وقت Kubernetes مرزهای محکم رو مجانی بهت می‌ده: فایل‌سیستم جدا، سکرت جدا، پالیسی شبکه و سهمیه‌ی منابع.

اصلاً یه ایجنت همه‌منظوره برای هر نفر ابزار درستیه؟ من اتوماسیون خودم رو از Hermes بردم سمت [پایپ‌لاین‌های ثابت](https://ashkmb.com/fa/blog/why-i-left-hermes-agent/)، چون کارهام از قبل معلوم بودن. ولی برای تیمی که یه دستیار همه‌منظوره می‌خواد، دستیاری که به سؤال‌های باز جواب بده، توی وب بگرده و هر وقت ازش خواستن ابزار اجرا کنه، ایجنت همه‌منظوره دقیقاً همون چیزیه که لازم داره. اگه فقط برای خودت یه ایجنت لازم داری، [نسخه‌ی تک‌کاربره روی EKS](https://ashkmb.com/fa/blog/hermes-agent-eks-deployment/) ساده‌تره.

## چی می‌سازی

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

هر چیزی که یه کاربر لازم داره از یه چارت کوچیک Helm میاد که توی گام ۳ می‌نویسیش. گیت‌وی و گواهی مشترکن و فقط یه بار نصب می‌شن.

قبل از شروع، کلید OpenRouter رو توی شلت بذار. همه‌ی دستورهای بعدی از همون‌جا می‌خوننش:

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

یه پوشه‌ی کاری برای فایل‌هایی که الان می‌نویسی بساز:

```bash
mkdir -p hermes-k8s && cd hermes-k8s
```

## گام ۱: یه کلاستر تمرینی بساز

اگه از قبل کلاستری داری که CNI اون پالیسی شبکه رو اعمال می‌کنه (Calico، Cilium و بیشتر سرویس‌های مدیریت‌شده این‌طورن)، از این گام بگذر.

افزونه‌ی شبکه‌ی پیش‌فرض kind پالیسی‌های شبکه رو قبول می‌کنه ولی اعمالشون نمی‌کنه: پالیسی‌ها اعمال‌شده به نظر میان، ولی همه‌ی اتصال‌ها برقرار می‌شن و بررسی‌های ایزوله بودن توی گام ۹ شکست می‌خورن. برای همین کلاستر بدون CNI بالا میاد و [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
```

**بررسی:** هر دو نود `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
```

## گام ۲: پروژه‌های Envoy Gateway و cert-manager رو نصب کن

کاربرها از راه HTTPS و با [Gateway API](https://gateway-api.sigs.k8s.io/) به ایجنتشون می‌رسن. پروژه‌ی **Envoy Gateway** این API رو پیاده می‌کنه و تعریف‌های منبع سفارشی (CRD) مربوط به Gateway API رو هم با چارت خودش نصب می‌کنه. انتخاب Gateway API به‌جای یه اینگرس کنترلر عمدی بود: پروژه‌ی ingress-nginx که کامیونیتی Kubernetes نگهش می‌داشت، مارس ۲۰۲۶ آرشیو شد. [این‌جا نوشتم تو عمل چی معنی داشت](https://ashkmb.com/fa/blog/ingress-nginx-archived-upstream/). ابزار **cert-manager** هم گواهی TLS رو صادر می‌کنه.

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

**بررسی:** هر دو کنترلر بالا هستن و منابع سفارشی Gateway API نصب شدن.

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

## گام ۳: چارت Helm مخصوص هر کاربر رو بنویس

این چارت هر چیزی که یه کاربر توی نیم‌اسپیس خودش لازم داره رو می‌سازه. دو تا ویژگی ایمیج رسمی طراحی این چارت رو تعیین کردن.

**ایمیج با کاربر root بالا میاد و بعد به یه کاربر بدون دسترسی root سوییچ می‌کنه.** سیستم init اون (s6-overlay) مالکیت والیوم داده رو درست می‌کنه و بعد همه‌ی پروسه‌های Hermes رو با کاربر `hermes` (شناسه‌ی ۱۰۰۰۰) اجرا می‌کنه. اگه `runAsNonRoot` بذاری، همین شروع خراب می‌شه، و ایمیج کاربر دلخواه با پرچم `--user` رو هم قبول نمی‌کنه. برای همین پاد همون انتری‌پوینت پیش‌فرض رو نگه می‌داره. در عوض سه تا قفل داره: افزایش سطح دسترسی خاموشه، فقط پنج قابلیت لینوکس که init لازم داره می‌مونن، و پروفایل پیش‌فرض seccomp روشنه.

**مدل توی کانفیگ خود Hermes ثابت می‌شه.** گیت‌وی Hermes مدل رو از فایل `config.yaml` روی والیوم می‌خونه. پیش‌فرض ایمیج یه مدل بزرگ و گرونه، و یه متغیر محیطی هم برای گیت‌وی Hermes جاش رو نمی‌گیره. یه کانتینر init موقع هر بار بالا اومدن `hermes config set` رو اجرا می‌کنه، تا مقدار Helm مرجع اصلی بمونه.

فایل‌ها:

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

سرویس‌اکانت هیچ توکنی رو مانت نمی‌کنه، پس شلِ ایجنت هیچ اعتبارنامه‌ای برای API کلاستر نداره. والیوم بعد از حذف ریلیز باقی می‌مونه، چون حافظه‌ی کاربر توشه:

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

دیپلویمنت، گیت‌وی Hermes رو همراه سرور API سازگار با OpenAI (پورت ۸۶۴۲) و داشبورد وب (پورت ۹۱۱۹) توی یه پاد اجرا می‌کنه. اگه داشبورد قراره از بیرون پاد در دسترس باشه، حتماً احراز هویت می‌خواد. برای همین ارائه‌دهنده‌ی داخلی نام کاربری و رمز رو براش فعال می‌کنی:

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

یه سهمیه سقف مصرف هر کاربر رو تعیین می‌کنه، تا یه ایجنتِ از کنترل خارج‌شده منابع بقیه رو نخوره:

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

**بررسی:** چارت بدون خطا از بررسی `helm lint` می‌گذره.

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

```text
1 chart(s) linted, 0 chart(s) failed
```

## گام ۴: اولین کاربر رو اضافه کن

هر کاربر یه نیم‌اسپیس با لیبل تننت می‌گیره؛ گیت‌وی توی گام ۷ از همین لیبل استفاده می‌کنه. یه سکرت هم می‌گیره با چهار مقدار: کلید OpenRouter، یه کلید API تصادفی برای ایجنتش، و یه رمز تصادفی برای داشبورد به‌همراه یه کلید برای امضای نشست‌ها. سکرت بیرون از Helm ساخته می‌شه، تا کلیدها هیچ‌وقت توی `values.yaml` یا تاریخچه‌ی ریلیزهای Helm نیفتن.

برای این‌که مثال کوتاه بمونه، همه‌ی کاربرها یه کلید OpenRouter مشترک می‌گیرن. هر ایجنت می‌تونه کلیدهای توی محیط خودش رو بخونه، برای همین توی یه تیم واقعی به هر نفر یه کلید OpenRouter جدا بده (بخش سخت‌تر کردن رو ببین).

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

بار اول باید یه ایمیج بزرگ دانلود بشه، برای همین `--wait` ممکنه چند دقیقه طول بکشه.

**بررسی:** پاد در حال اجراست و کانتینر init مدل رو ثابت کرده.

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

## گام ۵: با ایجنتت حرف بزن

تا وقتی هنوز آدرس عمومی‌ای وجود نداره، با پورت‌فوروارد به ایجنت Alice برس. کلید API اون توی سکرت خودشه:

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

حالا یه درخواست واقعی. این API با فرمت چت OpenAI حرف می‌زنه، پس هر کلاینت سازگار با OpenAI هم کار می‌کنه:

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

**بررسی:** ایجنت از راه مدل جواب می‌ده.

```text
hello from alice
```

داشبورد هم روی پورت ۹۱۱۹ همین‌طوری کار می‌کنه. نام کاربری Alice همون `alice` و رمزش مقدار `HERMES_DASHBOARD_BASIC_AUTH_PASSWORD` توی سکرت خودشه.

## گام ۶: شبکه رو قفل کن

الان هر پادی توی کلاستر می‌تونه به ایجنت Alice برسه، و ایجنت اون هم می‌تونه به همه‌جا برسه. سه تا پالیسی درستش می‌کنن: اول همه‌چی ممنوع، بعد برای خروج فقط DNS و HTTPS به اینترنت عمومی، و برای ورود فقط پراکسی‌های گیت‌وی.

قانون خروجی عمداً باز گذاشته شده. ایجنت Hermes یه دستیار همه‌منظوره‌ست که ابزارهای وبش اینترنت باز لازم دارن، و پالیسی شبکه‌ی استاندارد اصلاً نمی‌تونه بر اساس نام دامنه کار کنه. چیزی که کنار می‌ذاره مهم‌تره: همه‌ی بازه‌های آدرس خصوصی. یعنی ایجنت به هیچ پادِ تننت دیگه‌ای نمی‌رسه، به آدرس داخلی سرویس‌های کلاستر هم همین‌طور. به آدرس متادیتای کلود (`169.254.169.254`) هم نمی‌رسه؛ همون جایی که بیشتر کلودها اعتبارنامه‌های نود رو نگه می‌دارن.

دو چیز رو این پالیسی نمی‌بنده. از راه گیت‌وی عمومی، ایجنتِ یه کاربر می‌تونه مثل هر کلاینت دیگه‌ای روی اینترنت به آدرس یه کاربر دیگه برسه؛ اون‌جا کلید API و رمز داشبورد هر کاربره که ازش محافظت می‌کنه. و اگه API سرور کلاسترت اندپوینت عمومی داره، ایجنت روی پورت ۴۴۳ بهش می‌رسه؛ اون‌جا نبودِ توکن و RBAC جلوش رو می‌گیرن. برای بستن مشکل اول، آدرس لودبالانسر گیت‌وی رو به لیست `except` اضافه کن.

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

**بررسی:** پالیسی‌ها وجود دارن، ایجنت هنوز به اینترنت می‌رسه، و آدرس متادیتا تایم‌اوت می‌شه (کد خروج ۲۸ برای `curl`).

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

## گام ۷: برای هر کاربر یه آدرس جدا بذار

یه گیت‌وی مشترک Kubernetes، اتصال TLS رو برای همه‌ی زیردامنه‌های `hermes.example.com` ترمینیت می‌کنه و فقط از نیم‌اسپیس‌های تننت روت قبول می‌کنه. ریلیز هر کاربر یه HTTPRoute برای آدرس خودش اضافه می‌کنه: مسیرهایی که با `/v1` شروع می‌شن می‌رن سمت API و بقیه سمت داشبورد.

برای تمرین، cert-manager یه CA خصوصی کوچیک می‌سازه و گواهی وایلدکارت رو با اون امضا می‌کنه. **توی پروداکشن**، به‌جای ClusterIssuer به اسم `hermes-ca` از Let's Encrypt با یه سالور DNS-01 استفاده کن؛ گواهی وایلدکارت فقط با DNS-01 صادر می‌شه. بعد رکورد DNS زیردامنه‌ها رو به آدرس گیت‌وی وصل کن.

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

حالا تمپلیت روت، و ریلیز Alice با گیت‌وی روشن:

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

توی یه کلاستر روی کلود، گیت‌وی یه آدرس لودبالانسر می‌گیره. کلاستر kind لودبالانسر نداره، برای همین وضعیت Programmed گیت‌وی روی False می‌مونه، با دلیل `AddressNotAssigned`، و به‌جاش با پورت‌فوروارد به پراکسی می‌رسی. دستور `curl --resolve` نام واقعی رو می‌فرسته، پس TLS و مسیریابی دقیقاً مثل پروداکشن امتحان می‌شن:

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

**بررسی:** API از راه HTTPS جواب می‌ده، و داشبورد به صفحه‌ی ورودش ریدایرکت می‌کنه.

```text
hello over https
dashboard: 302
```

## گام ۸: کاربرهای بیشتر اضافه کن

گام‌های ۴ و ۷ برای یه کاربر توی یه اسکریپت کوچیک جا می‌شن. اجرای دوباره‌ش بی‌خطره: اگه سکرت از قبل باشه نگهش می‌داره، پس کلیدهای کاربر عوض نمی‌شن.

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

**بررسی:** دو ایجنت، هر کدوم توی نیم‌اسپیس خودش.

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

برای حذف یه کاربر، ریلیزش رو با `helm uninstall` حذف کن و نیم‌اسپیسش رو پاک کن. به‌خاطر پالیسی `keep` روی والیوم، دستور `helm uninstall` به‌تنهایی حافظه‌ی کاربر رو نگه می‌داره؛ پاک کردن نیم‌اسپیس اون رو برای همیشه حذف می‌کنه:

```bash no-run
helm uninstall hermes -n hermes-bob
kubectl delete namespace hermes-bob
```

## گام ۹: ایزوله بودن رو ثابت کن

پنج بررسی، هر کدوم یه مرز مهم.

**۱. ایجنت Alice به ایجنت Bob نمی‌رسه.** پالیسی خروجی Alice آدرس‌های خصوصی رو می‌بنده، و پالیسی ورودی Bob فقط گیت‌وی رو قبول می‌کنه. دستور `curl` بعد از ۵ ثانیه تایم‌اوت می‌شه (کد خروج ۲۸):

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

**۲. هیچ چیز دیگه‌ای توی کلاستر هم به ایجنت Bob نمی‌رسه**، حتی پادی توی یه نیم‌اسپیس که اصلاً پالیسی نداره:

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

**۳. کلید Alice روی ایجنت Bob کار نمی‌کنه:**

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

**۴. ایجنت هیچ اعتبارنامه‌ای برای Kubernetes نداره.** هیچ توکنی مانت نشده، و سرویس‌اکانت اجازه‌ی خوندن هیچ چیزی رو نداره:

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

**۵. کلید خود Bob هنوز برای Bob کار می‌کنه:**

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

**بررسی:** هر پنج‌تا، به ترتیب.

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

## عیب‌یابی

| نشونه | علت | راه‌حل |
|---|---|---|
| پالیسی‌های شبکه هستن، ولی توی بررسی ۱ یا ۲ گام ۹ اتصال برقرار می‌شه | CNI پالیسی شبکه رو اعمال نمی‌کنه (kindnet پیش‌فرض kind و بعضی راه‌اندازی‌های حداقلی) | مثل گام ۱ از Calico یا Cilium استفاده کن |
| پاد موقع شروع با پیام `[stage2] ERROR: container started with --user` از کار می‌افته | `runAsUser` یا `runAsNonRoot` روی پاد تنظیم شده | حذفشون کن؛ سیستم init ایمیج باید با root شروع کنه و خودش به شناسه‌ی ۱۰۰۰۰ می‌ره (گام ۳) |
| ایجنت جواب می‌ده، ولی صورت‌حساب OpenRouter یه مدل گرون نشون می‌ده | گیت‌وی Hermes مدل رو از `config.yaml` می‌خونه، نه از `HERMES_INFERENCE_MODEL` | کانتینر init با اسم `set-model` رو نگه دار؛ با `kubectl exec deploy/hermes -c hermes -- hermes config get model.default` چکش کن |
| گیت‌وی `Programmed=False` با دلیل `AddressNotAssigned` نشون می‌ده | لودبالانسر وجود نداره (kind، سرور فیزیکی) | روی kind طبیعیه؛ از پورت‌فوروارد گام ۷ استفاده کن، یا MetalLB یا cloud-provider-kind نصب کن |
| خطای `curl: (60)` یا روی مک `couldn't get X509-issuer name` | کلاینت به CA تمرینی اعتماد نداره، یا گواهی نهایی (leaf) خودامضاست و فیلد `subject` نداره | گزینه‌ی `--cacert hermes-ca.crt` رو بده؛ به‌جای امضای مستقیم گواهی وایلدکارت با `selfSigned`، همون ClusterIssuer به اسم `hermes-ca` از گام ۷ رو نگه دار |
| API با کلید درست هم `401` می‌ده | یه خط `API_SERVER_KEY` توی `/opt/data/.env` بر متغیرهای محیطی پاد اولویت داره (لاگ‌ها درباره‌ش هشدار می‌دن) | اون خط رو از `.env` روی والیوم پاک کن، یا کلید رو توی سکرت عوض کن و ری‌استارت کن |
| داشبورد بالا نمیاد و لاگ‌ها از نبود ارائه‌دهنده‌ی احراز هویت می‌گن | داشبورد روی آدرسی غیر از لوپ‌بک بدون احراز هویت شروع نمی‌کنه | مقدارهای `HERMES_DASHBOARD_BASIC_AUTH_*` رو نگه دار، یا OIDC تنظیم کن |
| بعد از گام ۶، DNS ایجنت دیگه هیچ آدرسی رو پیدا نمی‌کنه | کلاستر از NodeLocal DNSCache (`169.254.20.10`) استفاده می‌کنه که توی بازه‌ی کنارگذاشته‌شده‌ی `169.254.0.0/16` قرار داره | یه قانون خروجی برای `169.254.20.10/32` روی پورت ۵۳، هم UDP هم TCP، اضافه کن |
| `helm install --wait` برای اولین کاربر تایم‌اوت می‌شه | ایمیج بزرگه و اولین دانلودش طول می‌کشه | `--timeout` رو بیشتر کن؛ پیشرفت دانلود رو با `kubectl -n hermes-alice describe pod` ببین |

## سخت‌تر کردن برای پروداکشن

- **ترافیک خروجی رو بیشتر محدود کن**، اگه کاربرهات وب باز لازم ندارن. پالیسی شبکه‌ی استاندارد فقط بازه‌ی IP می‌شناسه. با قانون‌های `toFQDNs` توی Cilium می‌شه خروجی رو با اسم، فقط به `openrouter.ai` محدود کرد.
- **برای داشبورد از OIDC استفاده کن**، نه نام کاربری و رمز مشترک. Hermes از یه ارائه‌دهنده‌ی OpenID Connect روی زیرساخت خودت پشتیبانی می‌کنه (`HERMES_DASHBOARD_OIDC_ISSUER`، `HERMES_DASHBOARD_OIDC_CLIENT_ID`). ژوئن ۲۰۲۶ مهاجم‌ها دنبال داشبوردها و سرورهای API ایجنت Hermes گشتن که بدون احراز هویت روی اینترنت باز بودن، و ازشون سوءاستفاده کردن. برای همینه که داشبورد الان بدون احراز هویت اصلاً بالا نمیاد. با هر اندپوینت ایجنت مثل یه شل از راه دور رفتار کن، چون دقیقاً همینه.
- **برای هر کاربر یه کلید جدای OpenRouter**، هر کدوم با سقف اعتبار خودش. این‌طوری اگه یه کلید لو بره فقط یه نفر درگیره، حلقه‌ی بی‌پایانِ یه نفر بودجه‌ی همه رو خالی نمی‌کنه، و هزینه‌ی هر نفر جدا دیده می‌شه.
- **از والیوم‌ها نسخه‌ی پشتیبان بگیر.** مسیر `/opt/data` حافظه، نشست‌ها و مهارت‌های هر کاربر رو نگه می‌داره. با اسنپ‌شات زمان‌بندی‌شده از والیوم‌ها (یا Velero)، ری‌استارت پاد فقط یه ری‌استارته؛ بدونش ممکنه کل دستیار رو از دست بدی.
- **اپراتور به‌جای Helm.** یه اپراتور کامیونیتی برای Hermes روی OperatorHub هست. یه ریلیز ساده‌ی Helm برای هر کاربر راحت‌تر خونده و دیباگ می‌شه، برای همین این آموزش از اون استفاده می‌کنه.

## پاک‌سازی

کلاستر تمرینی و هر چیزی که توشه رو پاک کن:

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