Insights Agent deployment modes for the API Catalog

This reference covers all deployment modes, configuration options, filtering behavior, and troubleshooting for the Postman Insights Agent.

Just want to get running? See the Connect with the API Catalog using Postman Insights Agent.

Onboarding approaches

The agent supports two approaches for onboarding services:

Both approaches are available across DaemonSet and Sidecar deployment models.

Get started with Discovery Mode

Deploy the agent with --discovery-mode and a cluster name. The agent handles service registration automatically. See Connect with the API Catalog using Postman Insights Agent for step-by-step instructions.

Get started with Workspace Mode

To get started, you need your workspace ID and system environment ID from the Postman app. In Postman, from Home, click API Catalog > Integrated Services. Select the service and copy the IDs from the bottom of the page.

Next, deploy the agent with those IDs:

1. Open the Postman app and create (or select) a workspace.
2. Create a system environment and copy the workspace ID and system environment ID.
3. Deploy the agent using --workspace-id and --system-env with either the DaemonSet or Sidecar mode below.

Both IDs must be valid UUIDs (for example, 550e8400-e29b-41d4-a716-446655440000). You can copy them directly from the Postman app.

Deployment modes

DaemonSet (kube run)

Deploys one agent pod per node. The agent watches pod events cluster-wide and captures traffic from all eligible pods on each node. Recommended for cluster-wide coverage.

Discovery Mode

A single API key covers the entire cluster. The agent watches for pod events and automatically starts capturing traffic for eligible pods.

$
postman-insights-agent kube run --discovery-mode [flags]

All flags can also be set using environment variables. CLI flags take precedence.

Example: discover only in specific namespaces

$
postman-insights-agent kube run \
>
  --discovery-mode \
>
  --include-namespaces=production,staging

Example: exclude pods by label

$
postman-insights-agent kube run \
>
  --discovery-mode \
>
  --exclude-labels=team=infrastructure

Workspace Mode

In Workspace Mode, each monitored pod is associated with a specific Postman workspace and system environment. The DaemonSet reads POSTMAN_INSIGHTS_WORKSPACE_ID and POSTMAN_INSIGHTS_SYSTEM_ENV from each target pod’s environment and starts capturing traffic for that service.

Hybrid mode

In DaemonSet Discovery Mode, pods that already have explicit service IDs in their environment are routed to their respective flow instead of auto-discovery. This allows gradual adoption alongside existing per-pod configurations.

The pod’s own POSTMAN_INSIGHTS_API_KEY is used if set. Otherwise, the DaemonSet-level key is the fallback.

Sidecar

Sidecar injects the agent as an additional container into an existing deployment YAML. Use this when you want per-deployment control rather than cluster-wide coverage.

Discovery Mode

$
postman-insights-agent kube inject \
>
  -f <deployment.yaml> \
>
  --discovery-mode \
>
  --cluster-name <cluster> \
>
  [--service-name <name>] \
>
  [-o <output.yaml>]

Example:

$
postman-insights-agent kube inject \
>
  -f deployment.yaml \
>
  --discovery-mode \
>
  --cluster-name "production-cluster" \
>
  --service-name "my-namespace/my-service" \
>
  --secret \
>
  -o injected-deployment.yaml

The injected sidecar includes:

• Args — apidump --discovery-mode (plus --service-name if provided)
• Env vars — POSTMAN_INSIGHTS_API_KEY, POSTMAN_INSIGHTS_CLUSTER_NAME, POSTMAN_INSIGHTS_WORKLOAD_NAME, POSTMAN_INSIGHTS_WORKLOAD_TYPE, POSTMAN_INSIGHTS_LABELS, and standard Kubernetes downward API fields
• Resources — 200m CPU / 500Mi memory
• Security — NET_RAW capability for packet capture

Workspace Mode

$
postman-insights-agent kube inject \
>
  -f <deployment.yaml> \
>
  --workspace-id <YOUR_WORKSPACE_ID> \
>
  --system-env <YOUR_SYSTEM_ENV_ID> \
>
  [-o <output.yaml>]

Pod filtering

In DaemonSet Discovery Mode, the agent applies a multi-layer filtering pipeline to decide which pods to capture. A pod must pass every layer.

Layer 0 — Self-exclusion

The agent’s own pod is always excluded to prevent feedback loops.

Layer 1 — Namespace filtering

System and infrastructure namespaces are excluded by default. Customize with --include-namespaces and --exclude-namespaces.

The rules are applied in the following order:

1. If the pod’s namespace is in the exclude list, then skip.
2. If --include-namespaces is set and the namespace isn’t in the list, then skip.
3. Otherwise, pass.

Default excluded namespaces

The Insights Agent skips namespaces that belong to infrastructure or platform tooling — anything that isn’t your application traffic. This includes Kubernetes system namespaces (kube-system, kube-public), cloud-provider-managed namespaces (GKE, EKS), service meshes, ingress controllers, networking plugins, certificate and secrets management, monitoring and observability stacks, security and policy engines, GitOps and CI/CD tooling, autoscalers, storage operators, and serverless runtimes. The postman-insights-namespace where the agent itself runs is also excluded.

If one of your application namespaces shares a name with a namespace in the exclusion list, use --include-namespaces to explicitly include it.

Layer 2 — Label and annotation filtering

Fine-grained control at the individual pod level. It’s evaluated in the following order:

1. Opt-out annotation — the pod has postman.com/insights-disabled: "true", then skip.
2. Opt-in set to false — the pod has postman.com/insights-enabled: "false", then skip.
3. Exclude labels — the pod matches any key-value pair in --exclude-labels, then skip.
4. Include labels — --include-labels is set and the pod doesn’t match all pairs, then skip.

To opt out of a specific pod or deployment, add the annotation postman.com/insights-disabled: "true" to the pod spec or deployment spec:

1
metadata:
2
  annotations:
3
    postman.com/insights-disabled: "true"

Layer 3 — Controller type filtering

Only the pods managed by long-running workload controllers are captured. Ephemeral workloads are excluded.

Service name derivation

When a pod passes all filters, the agent derives a service name in the format {namespace}/{workload-name}.

The workload name is resolved using this fallback chain (first match wins):

Overriding the service name

Set POSTMAN_INSIGHTS_SERVICE_NAME in the pod spec to override the auto-derived name:

1
env:
2
- name: POSTMAN_INSIGHTS_SERVICE_NAME
3
  value: "custom-namespace/custom-name"

For sidecar deployments, use the --service-name flag with kube inject:

$
postman-insights-agent kube inject \
>
  -f deployment.yaml \
>
  --discovery-mode \
>
  --cluster-name "production-cluster" \
>
  --service-name "my-namespace/my-service" \
>
  -o injected-deployment.yaml

Discovery traffic TTL

When a service is discovered, the agent captures traffic for 24 hours to give you time to complete onboarding in the Postman app. This prevents unnecessary traffic from consuming your plan limits for services you haven’t intentionally onboarded. If the service isn’t onboarded within that window, the agent pauses capture for it automatically.

To resume capture, onboard the service in the Postman app. The restriction is lifted and capture resumes indefinitely.

Environment variables reference

CLI flags always take precedence over environment variables.

CLI flags reference

kube run (DaemonSet) — Discovery Mode flags

kube inject (Sidecar) — Onboarding mode flags

Exactly one of --project, --workspace-id, or --discovery-mode must be specified.

Troubleshooting

If you’re having issues with service discovery, here are some common questions and answers.

Why isn’t my pod being discovered?

Check each filtering layer in order:

1. Namespace — Is the pod in a default excluded namespace? Use --include-namespaces to explicitly include it.
2. Labels — Does the pod match an --exclude-labels pattern? Does it satisfy all --include-labels requirements?
3. Annotations — Does the pod have postman.com/insights-disabled: "true" or postman.com/insights-enabled: "false"?
4. Controller type — Is the pod managed by a Deployment, StatefulSet, or DaemonSet? Jobs, CronJobs, and standalone pods aren’t captured.

How do I opt a specific pod out of discovery?

Add the opt-out annotation to the pod template in the Deployment:

1
metadata:
2
  annotations:
3
    postman.com/insights-disabled: "true"

How do I limit discovery to specific namespaces?

Use --include-namespaces. Only pods in the listed namespaces are discovered (default exclusions still apply).

$
postman-insights-agent kube run \
>
  --discovery-mode \
>
  --include-namespaces=production,staging

How do I add namespaces to the exclusion list?

Use --exclude-namespaces. These are added to the built-in defaults — they do not replace them.

$
postman-insights-agent kube run \
>
  --discovery-mode \
>
  --exclude-namespaces=dev,sandbox

The derived service name is wrong. How do I fix it?

Set POSTMAN_INSIGHTS_SERVICE_NAME in the pod spec, or use the --service-name flag with kube inject for sidecar deployments.

Will traffic be captured twice if I run both a DaemonSet and a sidecar on the same pod?

No. The DaemonSet automatically detects pods that already have the Postman Insights Agent sidecar container and skips them. This is applied consistently across pod watch events, the initial pod scan, and periodic health-check reconciliation.

Why is the cluster name required?

The backend uses the cluster name together with the namespace and workload name to build a unique service slug (cluster/namespace/workload). Without it, services with the same namespace and workload name across different clusters would collide. The agent exits at startup with a clear error if the cluster name is missing.

What happens when a discovered service’s traffic TTL expires?

The agent gracefully stops capturing traffic for that service and marks it TrafficMonitoringEnded. To resume, onboard the service in the Postman app — the TTL restriction is then lifted.

Can I use Discovery Mode and Workspace Mode in the same cluster?

Yes. The DaemonSet skips pods that already have the agent sidecar, so there is no risk of capturing traffic twice. A Discovery Mode DaemonSet can safely run alongside sidecar-injected deployments using Workspace Mode.

Can I use per-pod workspace or project IDs alongside DaemonSet Discovery Mode?

Yes. Pods with POSTMAN_INSIGHTS_WORKSPACE_ID + POSTMAN_INSIGHTS_SYSTEM_ENV, or POSTMAN_INSIGHTS_PROJECT_ID set in their environment are routed to their respective flow instead of auto-discovery. See Hybrid mode for details.

I’m seeing “API Catalog is not enabled for this team”. What does this mean?

The API Catalog feature is not enabled for your Postman team. Contact your Postman team administrator to enable it, then redeploy the agent.

What happens if I set --workspace-id without --system-env?

The agent exits with an error. --system-env is required whenever --workspace-id is specified.