۲۹ آبان ۲۵۸۵ · متوسط · ۶۰ دقیقه
ایجنت چندکاربرهی Hermes روی Kubernetes
آخرش چی داری
به هر نفر از تیمت یه ایجنت Hermes مخصوص خودش بده، همه روی یه کلاستر Kubernetes. هر کاربر نیماسپیس، ریلیز Helm، والیوم، سکرت، پالیسی شبکه و آدرس HTTPS خودش رو داره؛ برای همین هیچ ایجنتی نمیتونه حافظه یا فایلهای یکی دیگه رو بخونه، با کلید API یا رمز داشبورد یکی دیگه وارد بشه، یا داخل کلاستر مستقیم به ایجنت دیگهای وصل بشه. همهی دستورها روی یه کلاستر تازه از اول تا آخر اجرا شدن.
پیشنیازها
- داکر، برای یه کلاستر تمرینی محلی با kind (یا هر کلاستری که CNI اون NetworkPolicy رو اعمال کنه)
- ابزار kubectl 1.36 به بالا، Helm 3.8 به بالا (برای چارتهای OCI)، kind، curl، openssl و python3
- یه کلید API از OpenRouter، ترجیحاً یه کلید جدا با سقف اعتبار کم
تستشده با
- 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 مخصوص خودش داره که روی یه کلاستر مشترک Kubernetes اجرا میشه و آدرس HTTPS خودش رو داره، مثلاً alice.hermes.example.com. هر ایجنت نیماسپیس، والیوم، سکرت و کلید API خودش رو داره. پالیسی شبکه نمیذاره هیچ ایجنتی مستقیم به ایجنت دیگه وصل بشه، و هیچکدومشون هم اعتبارنامهای برای API کلاستر ندارن. اضافه کردن یه نفر جدید فقط یه دستوره.
همهی دستورهای پایین رو قبل از انتشار، به همین ترتیب، روی یه کلاستر محلی تازه اجرا کردم. نسخهها توی کادر بالا هستن. اگه از قبل کلاستر داری، تنها شرط واقعی اینه که CNI اون پالیسیهای شبکه رو اعمال کنه؛ CNI پیشفرض kind این کار رو نمیکنه.
چرا برای هر کاربر یه Hermes جدا
ایجنت Hermes میتونه با یه پروسه به چند نفر جواب بده. گیتوی پیامرسان Hermes لیست کاربرهای مجاز داره، و پروفایلهاش به هر ایجنت کانفیگ و حافظهی جدا میدن. ولی هر دوشون یه پروسه و یه فایلسیستم مشترک دارن. ایجنت یه شل واقعی داره. بکاند پیشفرض ترمینالش روی local تنظیم شده، یعنی دستورها رو توی کانتینر خودش اجرا میکنه. هر چیزی که ایجنتِ یه نفر بتونه بخونه، ایجنت بقیه هم میتونه بخونه.
برای همین اینجا واحد ایزولهسازی، خود پاده: برای هر نفر یه نیماسپیس، یه دیپلویمنت و یه والیوم. اونوقت Kubernetes مرزهای محکم رو مجانی بهت میده: فایلسیستم جدا، سکرت جدا، پالیسی شبکه و سهمیهی منابع.
اصلاً یه ایجنت همهمنظوره برای هر نفر ابزار درستیه؟ من اتوماسیون خودم رو از Hermes بردم سمت پایپلاینهای ثابت، چون کارهام از قبل معلوم بودن. ولی برای تیمی که یه دستیار همهمنظوره میخواد، دستیاری که به سؤالهای باز جواب بده، توی وب بگرده و هر وقت ازش خواستن ابزار اجرا کنه، ایجنت همهمنظوره دقیقاً همون چیزیه که لازم داره. اگه فقط برای خودت یه ایجنت لازم داری، نسخهی تککاربره روی EKS سادهتره.
چی میسازی
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 رو توی شلت بذار. همهی دستورهای بعدی از همونجا میخوننش:
export OPENROUTER_API_KEY='sk-or-...'
یه پوشهی کاری برای فایلهایی که الان مینویسی بساز:
mkdir -p hermes-k8s && cd hermes-k8s
گام ۱: یه کلاستر تمرینی بساز
اگه از قبل کلاستری داری که CNI اون پالیسی شبکه رو اعمال میکنه (Calico، Cilium و بیشتر سرویسهای مدیریتشده اینطورن)، از این گام بگذر.
افزونهی شبکهی پیشفرض kind پالیسیهای شبکه رو قبول میکنه ولی اعمالشون نمیکنه: پالیسیها اعمالشده به نظر میان، ولی همهی اتصالها برقرار میشن و بررسیهای ایزوله بودن توی گام ۹ شکست میخورن. برای همین کلاستر بدون CNI بالا میاد و 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
بررسی: هر دو نود 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
گام ۲: پروژههای Envoy Gateway و cert-manager رو نصب کن
کاربرها از راه HTTPS و با Gateway API به ایجنتشون میرسن. پروژهی Envoy Gateway این API رو پیاده میکنه و تعریفهای منبع سفارشی (CRD) مربوط به Gateway API رو هم با چارت خودش نصب میکنه. انتخاب Gateway API بهجای یه اینگرس کنترلر عمدی بود: پروژهی ingress-nginx که کامیونیتی Kubernetes نگهش میداشت، مارس ۲۰۲۶ آرشیو شد. اینجا نوشتم تو عمل چی معنی داشت. ابزار cert-manager هم گواهی TLS رو صادر میکنه.
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 نصب شدن.
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
گام ۳: چارت Helm مخصوص هر کاربر رو بنویس
این چارت هر چیزی که یه کاربر توی نیماسپیس خودش لازم داره رو میسازه. دو تا ویژگی ایمیج رسمی طراحی این چارت رو تعیین کردن.
ایمیج با کاربر root بالا میاد و بعد به یه کاربر بدون دسترسی root سوییچ میکنه. سیستم init اون (s6-overlay) مالکیت والیوم داده رو درست میکنه و بعد همهی پروسههای Hermes رو با کاربر hermes (شناسهی ۱۰۰۰۰) اجرا میکنه. اگه runAsNonRoot بذاری، همین شروع خراب میشه، و ایمیج کاربر دلخواه با پرچم --user رو هم قبول نمیکنه. برای همین پاد همون انتریپوینت پیشفرض رو نگه میداره. در عوض سه تا قفل داره: افزایش سطح دسترسی خاموشه، فقط پنج قابلیت لینوکس که init لازم داره میمونن، و پروفایل پیشفرض seccomp روشنه.
مدل توی کانفیگ خود Hermes ثابت میشه. گیتوی Hermes مدل رو از فایل config.yaml روی والیوم میخونه. پیشفرض ایمیج یه مدل بزرگ و گرونه، و یه متغیر محیطی هم برای گیتوی Hermes جاش رو نمیگیره. یه کانتینر init موقع هر بار بالا اومدن hermes config set رو اجرا میکنه، تا مقدار Helm مرجع اصلی بمونه.
فایلها:
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 کلاستر نداره. والیوم بعد از حذف ریلیز باقی میمونه، چون حافظهی کاربر توشه:
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 (پورت ۸۶۴۲) و داشبورد وب (پورت ۹۱۱۹) توی یه پاد اجرا میکنه. اگه داشبورد قراره از بیرون پاد در دسترس باشه، حتماً احراز هویت میخواد. برای همین ارائهدهندهی داخلی نام کاربری و رمز رو براش فعال میکنی:
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
یه سهمیه سقف مصرف هر کاربر رو تعیین میکنه، تا یه ایجنتِ از کنترل خارجشده منابع بقیه رو نخوره:
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 میگذره.
helm lint ./charts/hermes-user --set user=alice | tail -1
1 chart(s) linted, 0 chart(s) failed
گام ۴: اولین کاربر رو اضافه کن
هر کاربر یه نیماسپیس با لیبل تننت میگیره؛ گیتوی توی گام ۷ از همین لیبل استفاده میکنه. یه سکرت هم میگیره با چهار مقدار: کلید OpenRouter، یه کلید API تصادفی برای ایجنتش، و یه رمز تصادفی برای داشبورد بههمراه یه کلید برای امضای نشستها. سکرت بیرون از Helm ساخته میشه، تا کلیدها هیچوقت توی values.yaml یا تاریخچهی ریلیزهای Helm نیفتن.
برای اینکه مثال کوتاه بمونه، همهی کاربرها یه کلید OpenRouter مشترک میگیرن. هر ایجنت میتونه کلیدهای توی محیط خودش رو بخونه، برای همین توی یه تیم واقعی به هر نفر یه کلید OpenRouter جدا بده (بخش سختتر کردن رو ببین).
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 مدل رو ثابت کرده.
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
گام ۵: با ایجنتت حرف بزن
تا وقتی هنوز آدرس عمومیای وجود نداره، با پورتفوروارد به ایجنت Alice برس. کلید API اون توی سکرت خودشه:
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
حالا یه درخواست واقعی. این API با فرمت چت OpenAI حرف میزنه، پس هر کلاینت سازگار با OpenAI هم کار میکنه:
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
بررسی: ایجنت از راه مدل جواب میده.
hello from alice
داشبورد هم روی پورت ۹۱۱۹ همینطوری کار میکنه. نام کاربری Alice همون alice و رمزش مقدار HERMES_DASHBOARD_BASIC_AUTH_PASSWORD توی سکرت خودشه.
گام ۶: شبکه رو قفل کن
الان هر پادی توی کلاستر میتونه به ایجنت Alice برسه، و ایجنت اون هم میتونه به همهجا برسه. سه تا پالیسی درستش میکنن: اول همهچی ممنوع، بعد برای خروج فقط DNS و HTTPS به اینترنت عمومی، و برای ورود فقط پراکسیهای گیتوی.
قانون خروجی عمداً باز گذاشته شده. ایجنت Hermes یه دستیار همهمنظورهست که ابزارهای وبش اینترنت باز لازم دارن، و پالیسی شبکهی استاندارد اصلاً نمیتونه بر اساس نام دامنه کار کنه. چیزی که کنار میذاره مهمتره: همهی بازههای آدرس خصوصی. یعنی ایجنت به هیچ پادِ تننت دیگهای نمیرسه، به آدرس داخلی سرویسهای کلاستر هم همینطور. به آدرس متادیتای کلود (169.254.169.254) هم نمیرسه؛ همون جایی که بیشتر کلودها اعتبارنامههای نود رو نگه میدارن.
دو چیز رو این پالیسی نمیبنده. از راه گیتوی عمومی، ایجنتِ یه کاربر میتونه مثل هر کلاینت دیگهای روی اینترنت به آدرس یه کاربر دیگه برسه؛ اونجا کلید API و رمز داشبورد هر کاربره که ازش محافظت میکنه. و اگه API سرور کلاسترت اندپوینت عمومی داره، ایجنت روی پورت ۴۴۳ بهش میرسه؛ اونجا نبودِ توکن و RBAC جلوش رو میگیرن. برای بستن مشکل اول، آدرس لودبالانسر گیتوی رو به لیست except اضافه کن.
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).
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)
گام ۷: برای هر کاربر یه آدرس جدا بذار
یه گیتوی مشترک Kubernetes، اتصال TLS رو برای همهی زیردامنههای hermes.example.com ترمینیت میکنه و فقط از نیماسپیسهای تننت روت قبول میکنه. ریلیز هر کاربر یه HTTPRoute برای آدرس خودش اضافه میکنه: مسیرهایی که با /v1 شروع میشن میرن سمت API و بقیه سمت داشبورد.
برای تمرین، cert-manager یه CA خصوصی کوچیک میسازه و گواهی وایلدکارت رو با اون امضا میکنه. توی پروداکشن، بهجای ClusterIssuer به اسم hermes-ca از Let’s Encrypt با یه سالور DNS-01 استفاده کن؛ گواهی وایلدکارت فقط با DNS-01 صادر میشه. بعد رکورد DNS زیردامنهها رو به آدرس گیتوی وصل کن.
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 با گیتوی روشن:
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 و مسیریابی دقیقاً مثل پروداکشن امتحان میشن:
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 جواب میده، و داشبورد به صفحهی ورودش ریدایرکت میکنه.
hello over https
dashboard: 302
گام ۸: کاربرهای بیشتر اضافه کن
گامهای ۴ و ۷ برای یه کاربر توی یه اسکریپت کوچیک جا میشن. اجرای دوبارهش بیخطره: اگه سکرت از قبل باشه نگهش میداره، پس کلیدهای کاربر عوض نمیشن.
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
بررسی: دو ایجنت، هر کدوم توی نیماسپیس خودش.
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
برای حذف یه کاربر، ریلیزش رو با helm uninstall حذف کن و نیماسپیسش رو پاک کن. بهخاطر پالیسی keep روی والیوم، دستور helm uninstall بهتنهایی حافظهی کاربر رو نگه میداره؛ پاک کردن نیماسپیس اون رو برای همیشه حذف میکنه:
helm uninstall hermes -n hermes-bob
kubectl delete namespace hermes-bob
گام ۹: ایزوله بودن رو ثابت کن
پنج بررسی، هر کدوم یه مرز مهم.
۱. ایجنت Alice به ایجنت Bob نمیرسه. پالیسی خروجی Alice آدرسهای خصوصی رو میبنده، و پالیسی ورودی Bob فقط گیتوی رو قبول میکنه. دستور curl بعد از ۵ ثانیه تایماوت میشه (کد خروج ۲۸):
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 نمیرسه، حتی پادی توی یه نیماسپیس که اصلاً پالیسی نداره:
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 کار نمیکنه:
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 نداره. هیچ توکنی مانت نشده، و سرویساکانت اجازهی خوندن هیچ چیزی رو نداره:
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 کار میکنه:
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
بررسی: هر پنجتا، به ترتیب.
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 برای هر کاربر راحتتر خونده و دیباگ میشه، برای همین این آموزش از اون استفاده میکنه.
پاکسازی
کلاستر تمرینی و هر چیزی که توشه رو پاک کن:
cd ..
kind delete cluster --name hermes