اتصال API Catalog با Postman Insights Agent

Postman Insights Agent سرویس‌های Kubernetes شما را پایش می‌کند و می‌تواند API Catalog را به صورت خودکار با serviceهای کشف‌شده پر کند. روش پیشنهادی برای شروع، Discovery Mode است؛ در این حالت agent را یک‌بار deploy می‌کنید و بدون پیکربندی جداگانه برای هر service، موارد جدید را پیدا و ثبت می‌کند.

برای اینکه API Catalog بتواند ارتباط بین serviceها را درست نشان دهد، serviceها باید headerهای tracing استاندارد W3C مثل traceparent را در درخواست‌های ورودی و خروجی منتقل کنند.

Discovery Mode یا Workspace Mode؟

مورد	Discovery Mode	Workspace Mode
راه‌اندازی	یک بار deploy می‌شود و agent ثبت serviceها را انجام می‌دهد.	اول Postman را پیکربندی می‌کنید، بعد deploy انجام می‌شود.
مناسب برای	microserviceهای زیاد و onboarding کم‌تنظیمات.	کنترل جداگانه برای هر service و تیم‌های Postman-first.
serviceهای جدید	هنگام deploy خودکار پیدا می‌شوند.	باید جداگانه پیکربندی شوند.
ورودی‌های لازم	API key و cluster name.	Workspace ID و system environment ID.

پیش‌نیازهای Discovery Mode

• Postman API key با دسترسی‌های لازم.
• Kubernetes cluster نسخه 1.19+.
• پیکربندی kubectl برای cluster شما.

Deploy کردن Insights Agent در Discovery Mode

1. namespace و secret مربوط به API key را بسازید:

kubectl create namespace postman-insights-namespace

kubectl create secret generic postman-agent-secrets   --namespace postman-insights-namespace   --from-literal=postman-api-key=<YOUR_POSTMAN_API_KEY>

2. manifest پایه postman-insights-agent-daemonset.yaml را از Postman دریافت کنید.
3. در بخش args مقدار --discovery-mode را اضافه کنید:

args:
- kube
- run
- --discovery-mode

4. نام cluster را در بخش env وارد کنید. این نام باید پایدار و یکتا باشد:

env:
- name: POSTMAN_INSIGHTS_CLUSTER_NAME
  value: "<YOUR_CLUSTER_NAME>"

5. API key را از Secret بخوانید:

env:
- name: POSTMAN_INSIGHTS_CLUSTER_NAME
  value: "<YOUR_CLUSTER_NAME>"
- name: POSTMAN_INSIGHTS_API_KEY
  valueFrom:
    secretKeyRef:
      name: postman-agent-secrets
      key: postman-api-key

6. manifest را اعمال کنید:

kubectl apply -f postman-insights-agent-daemonset.yaml

7. بررسی کنید podهای agent روی nodeها اجرا شده باشند:

kubectl get pods -n postman-insights-namespace
kubectl logs -n postman-insights-namespace -l name=postman-insights-agent --tail=50

کامل کردن onboarding در Postman

از Home وارد API Catalog > Service Discovery > Postman Insights Catalog شوید. سپس service و environment مورد نظر را انتخاب کنید تا وارد API Catalog شود. API key باید متعلق به کاربری باشد که به workspace مقصد دسترسی write دارد.

محدود کردن discovery به namespaceهای خاص

به صورت پیش‌فرض agent بیشتر namespaceها را بررسی می‌کند و namespaceهای سیستمی را کنار می‌گذارد. اگر فقط چند namespace مشخص را می‌خواهید، در args از --include-namespaces استفاده کنید:

args:
- kube
- run
- --discovery-mode
- --include-namespaces=production,staging

وصل کردن requestها بین serviceها

برای اینکه graph وابستگی serviceها کامل شود، برنامه‌های شما باید headerهای W3C tracing را منتقل کنند. اگر outbound callها header traceparent را نفرستند، service پایین‌دستی در همان trace دیده نمی‌شود و graph ناقص می‌ماند.

فرمت traceparent

فرمت header به این شکل است:

version-trace_id-parent_id-flags

نمونه:

00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01

• trace_id: شناسه ۳۲ کاراکتری hex برای کل trace.
• parent_id: شناسه ۱۶ کاراکتری hex برای span والد.
• flags: دو کاراکتر hex، مثلا 01 برای sampled.

الگوی ساده propagation

در هر زبان برنامه‌نویسی، الگو تقریبا یکسان است: هنگام ورود request، traceparent را بخوانید؛ trace ID را نگه دارید؛ span ID جدید بسازید؛ و در هر outbound HTTP request دوباره traceparent را تنظیم کنید.

on_request(request):
  header = request.headers["traceparent"]
  if header is valid W3C traceparent:
    trace_id = parsed.trace_id
    parent_span_id = parsed.parent_id
  else:
    trace_id = new_random_trace_id()
    parent_span_id = null
  my_span_id = new_random_span_id()

before_send_outbound_http(client_request):
  ctx = current_request_context()
  client_request.headers["traceparent"] = format_traceparent(
    version = "00",
    trace_id = ctx.trace_id,
    parent_id = ctx.my_span_id,
    flags = ctx.flags
  )

گزینه‌های عملی

• OpenTelemetry: روش پیشنهادی برای انتقال خودکار traceparent و tracestate.
• API gateway/proxy: مطمئن شوید trace context را حفظ یا inject می‌کنند.
• Message queue و background job: برای کارهای غیر HTTP هم trace ID را در metadata پیام منتقل کنید.

منبع آموزشی: Postman Docs، بازنویسی و ساده‌سازی‌شده برای کاربران فارسی‌زبان.