اجرای Hermes Agent روی EKS: از docker-compose تا Helm

ai-agents aws eks kubernetes llm helm devops

به‌روزرسانی، آبان ۲۵۸۵: اگه می‌خوای برای هر نفر از تیمت یه ایجنت جدا و ایزوله پشت HTTPS راه بندازی، آموزش ایجنت چندکاربره‌ی Hermes روی Kubernetes رو ببین.

تو یه ورکشاپ داخلی دوروزه قرار شد Hermes Agent رو به‌عنوان یه پلتفرم ایجنت هوش مصنوعی ارزیابی کنیم که روی زیرساخت خودمون اجرا بشه. کار با یه بالا آوردن سریع با docker-compose شروع شد و آخرش رسید به یه چارت Helm اختصاصی، یه دیپلوی روی EKS که ایمیجش از ECR میاد، و یه حس تحسین واقعی برای این‌که تیم Nous Research چقدر روی طراحی حلقه‌ی ایجنت فکر کرده. این‌جا کل مسیر رو تعریف می‌کنم، از یه کانتینر محلی تا یه کلاستر Kubernetes که تقریباً در حد پروداکشنه.

ایجنت Hermes چیه؟

پروژه‌ی Hermes یه فریم‌ورک متن‌باز برای ایجنت‌های هوش مصنوعیه که Nous Research، یه سازمان مستقل تحقیقات هوش مصنوعی، توسعه‌ش داده. ویژگی اصلیش یه حلقه‌ی یادگیری بسته هست: ایجنت از تجربه‌هاش مهارت می‌سازه، تو استفاده‌های بعدی اون مهارت‌ها رو بهتر می‌کنه، بین جلسه‌ها یه حافظه‌ی ماندگار از این‌که تو کی هستی نگه می‌داره، و تو گفت‌وگوهای قبلی خودش می‌گرده تا کانتکست مرتبط رو یادش بیاد. به مدل خاصی هم بسته نیست. می‌تونی به OpenRouter، سرویس AWS Bedrock یا هر اندپوینت سازگار با OpenAI وصلش کنی و با hermes model همون لحظه مدل رو عوض کنی.

یه چیز رو همین اول روشن کنم، چون عبارت «خودبهبود» معمولاً آدم رو یاد یادگیری تقویتی می‌ندازه: این ایجنت مدل زیرین رو نه فاین‌تیون می‌کنه، نه دوباره آموزش می‌ده. هیچ‌جا هیچ به‌روزرسانی گرادیانی اتفاق نمی‌افته. بهبود کاملاً تو لایه‌ی مهندسی کانتکست رخ می‌ده: مهارت‌ها به‌شکل پرامپت‌های ساختاریافته ذخیره می‌شن، حافظه متنیه دست‌چین‌شده که به کانتکست سیستمی تزریق می‌شه، و پروفایل‌های کاربر واقعیت‌هایی رو جمع می‌کنن که روی شکل جواب‌های ایجنت اثر می‌ذارن. می‌شه اسمش رو گذاشت یه رویکرد استنتاج نیمه‌نظارتی: هنوز یه آدم تو حلقه هست که چیزهای ماندگار رو تأیید و هرس می‌کنه، ولی خود ایجنت هم خودش رو به ذخیره‌ی چیزهای مفید هل می‌ده و با گذشت زمان تعریف مهارت‌هاش رو بهتر می‌کنه. هوش از مدل میاد؛ پیوستگی و رشد از چیزیه که جلوی مدل می‌ذاری.

از نظر معماری، این ایجنت به‌شکل دو تا پروسه اجرا می‌شه:

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

هر دو پروسه یه پوشه‌ی HERMES_HOME مشترک دارن (~/.hermes روی سیستم محلی، /opt/data توی کانتینرها).

قدم ۱: اجرای محلی با docker-compose

ریپوی اصلی پروژه یه فایل docker-compose.yml داره که ساختار دوسرویسی رو تمیز پوشش می‌ده. چند تا نکته همون اول ارزش گفتن داره.

services:
  gateway:
    build: .
    image: hermes-agent
    container_name: hermes
    restart: unless-stopped
    network_mode: host
    volumes:
      - ~/.hermes:/opt/data
    environment:
      - HERMES_UID=${HERMES_UID:-10000}
      - HERMES_GID=${HERMES_GID:-10000}
      # Uncomment both to expose the API server:
      # - API_SERVER_HOST=0.0.0.0
      # - API_SERVER_KEY=${API_SERVER_KEY}
    command: ["gateway", "run"]

  dashboard:
    image: hermes-agent
    container_name: hermes-dashboard
    restart: unless-stopped
    network_mode: host
    depends_on:
      - gateway
    volumes:
      - ~/.hermes:/opt/data
    environment:
      - HERMES_UID=${HERMES_UID:-10000}
      - HERMES_GID=${HERMES_GID:-10000}
    command: ["dashboard", "--host", "127.0.0.1", "--no-open"]

الگوی HERMES_UID / HERMES_GID رو یه مرحله‌ی init از s6-overlay داخل ایمیج مدیریت می‌کنه: کانتینر با کاربر روت بالا میاد، کاربر داخلی hermes رو با gosu/usermod به UID کاربر میزبانت نگاشت می‌کنه، و بعد، قبل از این‌که هیچ سرویس تحت نظارتی شروع بشه، دسترسی‌هاش رو پایین میاره. این‌طوری فایل‌هایی که زیر /opt/data ساخته می‌شن برای کاربر میزبانت قابل خوندن می‌مونن، بدون این‌که لازم باشه با chown کلی ور بری.

استفاده از network_mode: host روی لپ‌تاپ توسعه عمدیه. گیت‌وی و داشبورد از طریق localhost با هم حرف می‌زنن، و کاربر میزبان بدون هیچ تنظیم تکراری برای نگاشت پورت، مستقیم روی پورت‌های آشنا بهشون دسترسی داره.

داشبورد به‌طور پیش‌فرض و عمداً فقط روی 127.0.0.1 گوش می‌ده. کامنت‌های خود پروژه دلیلش رو صریح گفتن: داشبورد کلیدهای API رو نگه می‌داره و هیچ لایه‌ی احراز هویتی نداره. اگه دسترسی از راه دور می‌خوای، راه درست یه تونل SSH هست (ssh -L 9119:localhost:9119)، نه باز کردنش روی 0.0.0.0 تو یه شبکه‌ی مشترک.

سریع‌ترین راه شروع:

HERMES_UID=$(id -u) HERMES_GID=$(id -g) docker compose up -d

بعد برای داشبورد http://localhost:9119 رو باز کن و وقتی با hermes model یه ارائه‌دهنده انتخاب کردی، از خط فرمان یا پنل چت داشبورد یه گفت‌وگو شروع کن.

قدم ۲: ساختن ایمیج و پوش کردنش به ECR

برای دیپلوی روی EKS لازم بود ایمیج توی رجیستری خصوصی ECR خودمون باشه، نه این‌که محلی بیلد بشه.

# Authenticate to ECR
aws ecr get-login-password --region eu-central-1 \
  | docker login --username AWS --password-stdin \
    <account-id>.dkr.ecr.eu-central-1.amazonaws.com

# Build from the upstream Dockerfile
docker build -t hermes-agent .

# Tag and push
docker tag hermes-agent \
  <account-id>.dkr.ecr.eu-central-1.amazonaws.com/hermes-agent:latest
docker push \
  <account-id>.dkr.ecr.eu-central-1.amazonaws.com/hermes-agent:latest

فایل Dockerfile پروژه از بیلد چندمرحله‌ای استفاده می‌کنه: یه مرحله‌ی بیلد وابستگی‌های پایتون رو با uv نصب می‌کنه، و یه مرحله‌ی اجرا ایجنت رو روی یه ایمیج پایه‌ی سبک بسته‌بندی می‌کنه که s6-overlay از قبل توش هست. ایمیج خودکفاست (نه سایدکاری داره، نه سیستم init بیرونی که بخوای سیم‌کشیش کنی).

تو مانیفست‌های Kubernetes پایین، imagePullPolicy: Always باعث می‌شه هر بار که پاد ری‌استارت می‌شه، تازه‌ترین :latest کشیده بشه. تو یه پایپ‌لاین واقعی با SHA کامیت تگ می‌زنی و رول‌اوت‌ها رو از همین راه کنترل می‌کنی؛ برای یه PoC، همون latest کافیه.

قدم ۳: مانیفست Kubernetes

این مانیفست خامیه که آخرش بهش رسیدیم. بخش به بخش با هم مرورش کنیم:

نیم‌اسپیس و سکرت

apiVersion: v1
kind: Namespace
metadata:
  name: hermes-agent

---
apiVersion: v1
kind: Secret
metadata:
  name: hermes-secrets
  namespace: hermes-agent
type: Opaque
data:
  API_SERVER_KEY: "<base64-encoded-random-key>"

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

kubectl create secret generic hermes-secrets \
  --from-literal=API_SERVER_KEY="$(openssl rand -hex 32)" \
  -n hermes-agent --dry-run=client -o yaml | kubectl apply -f -

هیچ‌وقت کلید واقعی رو توی فایل YAML کامیت نکن. مقدار جانگهدار توی مانیفست بالا فقط یادآوریه که باید عوضش کنی. از اون بهتر، سکرت رو بیرون از این مسیر مدیریت کن، مثلاً با ابزاری مثل External Secrets Operator که از سیستم مدیریت سکرت‌هات تغذیه می‌شه.

ولوم‌های ماندگار

apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: hermes-data-gateway
  namespace: hermes-agent
spec:
  accessModes:
    - ReadWriteOnce
  storageClassName: gp3
  resources:
    requests:
      storage: 10Gi

گیت‌وی و داشبورد هر کدوم PVC خودشون رو دارن. ReadWriteOnce به دیسک EBS از نوع GP3 نگاشت می‌شه. هر لحظه فقط یه نود می‌تونه مانتش کنه، که مشکلی نیست چون هر دیپلویمنت فقط یه رپلیکا داره. اگه گیت‌وی رو افقی اسکیل کنی، به ReadWriteMany (یعنی EFS) نیاز داری، ولی برای ایجنتی که وضعیت گفت‌وگو رو نگه می‌داره، یه رپلیکا به‌هرحال پیش‌فرض معقولیه.

سرویس‌اکانت با IRSA

apiVersion: v1
kind: ServiceAccount
metadata:
  name: hermes-agent
  namespace: hermes-agent
  annotations:
    eks.amazonaws.com/role-arn: arn:aws:iam::<account-id>:role/hermes-agent-role

انوتیشن eks.amazonaws.com/role-arn نقطه‌ی ورود IRSA (نقش‌های IAM برای سرویس‌اکانت‌ها) هست. اگه روی کلاسترت Pod Identity Agent یا ارائه‌دهنده‌ی OIDC تنظیم شده باشه، هر پادی که از این سرویس‌اکانت استفاده کنه، خودکار یه سری اعتبارنامه‌ی کوتاه‌عمر و محدود به hermes-agent-role توی کانتینرش تزریق می‌شه (نه کلید ثابت AWS لازمه، نه اشتراک پروفایل نمونه‌ی EC2).

تو مورد ما، نقش IAM دسترسی bedrock:InvokeModel (و bedrock:InvokeModelWithResponseStream) رو روی مدل‌هایی می‌ده که می‌خواستیم در دسترس باشن. این‌طوری گیت‌وی برای استنتاج مستقیم سرویس Bedrock رو صدا می‌زنه و برای ارائه‌دهنده‌ی LLM به هیچ کلید API شخص ثالثی نیاز نیست. احراز هویت رو هویت ابری خود ایجنت انجام می‌ده. اگه روی AWS نیستی یا Bedrock برات مهم نیست، می‌تونی کلاً این انوتیشن رو حذف کنی و کلیدهای ارائه‌دهنده رو به‌شکل متغیرهای محیطی اضافه، از طریق سکرت بدی.

دیپلویمنت گیت‌وی

دیپلویمنت گیت‌وی، جدا از متغیرهای بدیهی، دو تا متغیر محیطی داره که مهم‌ان:

env:
  - name: API_SERVER_HOST
    value: "0.0.0.0"
  - name: API_SERVER_KEY
    valueFrom:
      secretKeyRef:
        name: hermes-secrets
        key: API_SERVER_KEY
        optional: true

مقدار API_SERVER_HOST: "0.0.0.0" سرور API رو روی همه‌ی اینترفیس‌های داخل پاد باز می‌کنه تا سرویس Kubernetes (از نوع ClusterIP) بتونه ترافیک رو بهش برسونه. روی لپ‌تاپ توسعه این کار می‌تونست یه نگرانی امنیتی باشه؛ داخل پادی که هیچ مسیر بیرونی نداره، فقط باعث می‌شه سرویس از داخل کلاستر در دسترس باشه.

مقدار API_SERVER_KEY از سکرت خونده می‌شه تا هیچ‌وقت توی مشخصات دیپلویمنت دیده نشه. optional: true یعنی پاد حتی اگه اون کلید توی سکرت نباشه هم بالا میاد. موقع راه‌اندازی اولیه به کار میاد، ولی تو یه دیپلوی واقعی، وقتی سکرت سر جاش قرار گرفت، optional رو برمی‌داری.

دیپلویمنت داشبورد

args: ["dashboard", "--host", "0.0.0.0", "--no-open", "--insecure"]

سه تا فلگ که هر کدوم یه مشکل متفاوت رو حل می‌کنن:

  • --host 0.0.0.0: همون استدلال گیت‌وی؛ اگه داشبورد فقط روی لوپ‌بک گوش بده، سرویس ClusterIP نمی‌تونه بهش برسه.
  • --no-open: رفتار «باز کردن مرورگر موقع شروع» رو خاموش می‌کنه؛ رفتاری که روی لپ‌تاپ توسعه منطقیه، ولی توی یه کانتینر بدون نمایشگر بی‌صدا (یا با سروصدا) شکست می‌خوره.
  • --insecure: این یکی مهمه. سرور HTTP داخلی داشبورد به‌طور پیش‌فرض اصرار داره که درخواست‌ها روی یه FQDN مشخص برسن؛ بدون --insecure، هر درخواستی که از ALB بیاد (با یه هدر Host متفاوت یا یه مسیر مسیریابی داخلی) رد می‌شه. توی کانتینری که پشت لودبالانسره، --insecure عقب‌گرد امنیتی حساب نمی‌شه. خاتمه‌ی TLS و کنترل دسترسی تو لایه‌ی ALB انجام می‌شن.

سرویس‌ها و اینگرس

هر دو دیپلویمنت سرویس ClusterIP دارن. بخش جالب، اینگرسه:

rules:
  - host: hermes.internal.your-domain.com
    http:
      paths:
        - path: /
          pathType: Prefix
          backend:
            service:
              name: hermes-dashboard
              port:
                name: http
        - path: /api/
          pathType: Prefix
          backend:
            service:
              name: hermes-gateway
              port:
                name: api
        - path: /v1/
          pathType: Prefix
          backend:
            service:
              name: hermes-gateway
              port:
                name: api

مسیر / به داشبورد می‌ره؛ /api/ و /v1/ به گیت‌وی. پیشوند /v1/ همون اندپوینت سازگار با OpenAI هست، پس هر ابزاری که با API چت OpenAI حرف می‌زنه، می‌تونه به https://hermes.internal.your-domain.com/v1/ اشاره کنه و Hermes رو بدون هیچ تغییری جای ارائه‌دهنده‌ش بذاره.

اینگرس با alb.ingress.kubernetes.io/scheme: internal علامت خورده و توی یه گروه ALB به اسم internal قرار گرفته؛ هیچ‌وقت روی اینترنت عمومی در دسترس نیست. ریدایرکت SSL هم تو لایه‌ی ALB با یه سیاست TLS 1.2 به بالا اجباری شده.

یه نکته درباره‌ی انتخاب مدل و هزینه

برای ورکشاپ از مدل Claude Sonnet 4.6 (از طریق AWS Bedrock) استفاده کردیم، نه Opus. دلیلش ساده‌ست: Opus به‌ازای هر توکن تقریباً ۵ برابر Sonnet گرون‌تره، و برای کارهایی که به ایجنت سپردیم (بازبینی کد، نوشتن اسکریپت، جواب دادن به سؤال‌ها درباره‌ی مستندات داخلی) Sonnet همه رو خوب از پس براومد. هرچی ایجنت بیشتر کار کنه و تو یه جلسه فراخوانی ابزار بیشتری انجام بده، هزینه‌ی توکن بیشتر روی هم جمع می‌شه؛ برای همین مهمه که سطح مدل رو با پیچیدگی واقعی کار جور کنی.

خود Hermes این کار رو ساده می‌کنه: با hermes model می‌تونی وسط جلسه ارائه‌دهنده و مدل رو عوض کنی، بدون این‌که کانتکست از دست بره. بعضی جلسه‌ها رو با Sonnet شروع کردیم و فقط وقتی به کارهای استدلالی چندمرحله‌ای و واقعاً پیچیده خوردیم، رفتیم سراغ Opus. در عمل، این شاید یه بار تو کل اون دو روز پیش اومد.

قدم ۴: بسته‌بندیش به‌شکل یه چارت Helm

وقتی مانیفست خام پایدار شد، تبدیلش کردیم به یه چارت Helm. ساختار چارت حداقلیه:

hermes/
├── Chart.yaml
├── values.yaml
└── templates/
    ├── _helpers.tpl
    ├── namespace.yaml
    ├── secret.yaml
    ├── pvc.yaml
    ├── serviceaccount.yaml
    ├── deployment-gateway.yaml
    ├── deployment-dashboard.yaml
    ├── service-gateway.yaml
    ├── service-dashboard.yaml
    └── ingress.yaml

فایل values.yaml همون تنظیماتی رو در اختیارت می‌ذاره که واقعاً می‌خوای بین محیط‌ها عوضشون کنی: تگ ایمیج، ریکوئست‌ها و لیمیت‌های منابع، حجم ذخیره‌سازی، ARN نقش IRSA، هاست اینگرس، و این‌که نیم‌اسپیس و سکرت رو خود چارت مدیریت کنه یا بیرون از چارت باشن. هر چیزی که توی مانیفست یه رشته‌ی ثابت بود، این‌جا یه متغیر تمپلیت می‌شه.

این مهمه چون آدرس ایمیج تو ECR، شناسه‌ی ARN نقش IAM، شناسه‌ی ARN گواهی ACM و اسم هاست اینگرس همه به محیط وابسته‌ان. بدون چارت، یا باید چند تا نسخه از مانیفست رو نگه داری یا تو CI جست‌وجو و جایگزینی انجام بدی. با چارت، یه helm upgrade --install با یه فایل مقادیر جدا برای هر محیط کافیه.

گزینه‌ی secret.create: false توی فایل مقادیر بهت اجازه می‌ده به چارت بگی مدیریت سکرت رو کنار بذاره، تا بتونی از External Secrets Operator یا Vault استفاده کنی و کلید واقعی رو بیرون از کنترل چارت تزریق کنی. تو پروداکشن سراغ همین الگو می‌ریم.

بعد از دو روز به کجا رسیدیم

ایجنت رو دیپلوی کردیم، با یه مدل که از Bedrock سرو می‌شد تنظیمش کردیم، و چند تا سناریوی PoC رو امتحان کردیم: این‌که ایجنت اسکریپت شل بنویسه و اجرا کنه، مستندات داخلی رو خلاصه کنه، و با قابلیت ساختن ساب‌ایجنت، کارهای چندمرحله‌ای رو هماهنگ کنه. حلقه‌ی یادگیری همون‌طور که ادعا شده بود کار کرد. مهارت‌هایی که روز اول به ایجنت یاد دادیم، روز دوم بدون این‌که صریحاً بخوایم توی کانتکستش ظاهر شدن.

چیزهایی که فرصت نشد سراغشون بریم: یکپارچگی کامل گیت‌وی پیام‌رسان‌ها، زمان‌بند cron، فشرده‌سازی مسیرهای اجرای ایجنت برای تولید داده‌ی آموزشی، و یکپارچگی عمیق‌تر با سرورهای MCP. این ایجنت اون‌قدر قابلیت داره که یه ورکشاپ دوروزه به‌زور یه گوشه‌ش رو می‌بینه.

وقتی داده‌ی معناداری از استفاده تو پروداکشن داشتیم، با یه گزارش کامل‌تر برمی‌گردم: این‌که جمع شدن مهارت‌ها تو طول چند هفته چطور دوام میاره، آیا سیستم حافظه به نگهداری فعال نیاز داره یا نه، و هزینه‌ی واقعی Bedrock تو مقیاس بالا چه شکلیه. این‌جا کلی چیز هست که ارزش داره درست و حسابی بررسی بشه.

کد مانیفست Kubernetes و چارت Helm توی مونوریپوی داخلی ما هست. اگه داری Hermes رو برای زیرساخت خودت ارزیابی می‌کنی، همون docker-compose خود پروژه نقطه‌ی شروع درستیه. همه‌ی چیزهایی که بالا گفتم فقط کارهاییه که لازم بود تا تو محیط خاص ما به سطح پروداکشن برسه.

$ cat KUBERNETES .md
· 8 دقیقه مطالعه

خطای ۴۰۱ توی EKS که ربطی به اعتبارنامه نداشت

پایپ‌لاین CI ما یه توکن معتبر EKS می‌ساخت، درست و تمیز ارائه‌ش می‌داد، و رد می‌شد. مشکل از اعتبارنامه‌های AWS نبود. مشکل کنترل دسترسی خودِ EKS بود، و خطا جلوی چشم همه بود: کلاستر برای نقشی که درخواست می‌داد هیچ ورودی دسترسی نداشت.

kubernetes eks aws devops platform-engineering troubleshooting
$ cat KUBERNETES .md
· 7 دقیقه مطالعه

کلاستر جدید روی هر نود ۱۱۰ پاد اجرا می‌کرد. پروداکشن روی ۵۸ گیر کرده بود.

همون نوع اینستنس، نصف تراکم پاد. بالا بردن سقف پادها روی یه کلاستر EKS زنده یعنی یه لانچ تمپلیت که نود گروپ هیچ‌وقت نمی‌تونه داشته باشه، یه تنظیم CNI که باید قبل از همه اعمال بشه، و یه پلن Terraform پر از تغییرهایی که هیچ‌کس نخواسته بود.

kubernetes aws eks terraform devops
$ cat KUBERNETES .md
· 12 دقیقه مطالعه

پروژه‌ی اصلی آرشیوشده. باگ امنیتی‌اش هنوز زنده‌ست.

یه‌شبه دو تا باگ امنیتی تو پیاده‌سازی HTTP/2 وب‌سرور NGINX منتشر شد که بدون احراز هویت اجازه‌ی اجرای کد از راه دور می‌دادن، و کنترلرهای اینگرس ما هم در معرضشون بودن. راه‌حل همیشگی، یعنی آپدیت به آخرین نسخه، هیچ دردی رو دوا نمی‌کرد: پروژه‌ی ingress-nginx از مارس آرشیو شده و آخرین نسخه‌اش یه NGINX داره که دیگه هیچ‌وقت پچ نمی‌شه. تو این پست می‌گم چطور ثابت کردم چی واقعاً قابل‌حمله بود، HTTP/2 رو موقتاً خاموش کردم، پچ‌ها رو روی بیلد خودمون بک‌پورت کردم و بدون قطعی رول‌اوتش کردم.

kubernetes security devops helm nginx