***
title: Insights Agent deployment modes for the API Catalog
updated: 2026-03-01T00:00:00.000Z
max-toc-depth: 2
----------------
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](/docs/api-catalog/connect/insights).
## Onboarding approaches
The agent supports two approaches for onboarding services:
| Approach | How it works | Best for |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| **Discovery Mode** | Deploy the agent first. It automatically discovers services from Kubernetes metadata and registers them with Postman. Continue onboarding in the Postman app. | Teams with many microservices who want zero-configuration onboarding, or who want new services picked up automatically. |
| **Workspace Mode** | Create a workspace and system environment in Postman, copy the generated IDs, then configure the agent with those IDs. | Teams who prefer to set up Postman first, or who want each agent instance to map to a specific workspace. |
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](/docs/api-catalog/connect/insights) 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.
The Postman API key must belong to a user with **write access** to target workspaces (workspace Admin or Super Admin). The agent creates and links applications on behalf of this user.
## 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.
```bash
postman-insights-agent kube run --discovery-mode [flags]
```
| Flag | Type | Default | Description |
| ---------------------- | --------- | ---------------------------- | ----------------------------------------------------------------------------------------------------------- |
| `--discovery-mode` | Bool | `false` | Enable automatic service discovery. Requires `POSTMAN_INSIGHTS_CLUSTER_NAME` env var. |
| `--include-namespaces` | string | *(empty — all non-excluded)* | Comma-separated namespaces to discover. When set, only pods in these namespaces are captured. |
| `--exclude-namespaces` | string | *(empty)* | Comma-separated namespaces to exclude, added to the [default exclusion list](#default-excluded-namespaces). |
| `--include-labels` | key=value | *(empty)* | Pods must match **all** of these labels to be captured. |
| `--exclude-labels` | key=value | *(empty)* | Pods matching **any** of these labels are skipped. |
| `--rate-limit` | float | `0` (system default) | Maximum requests per minute to capture. |
All flags can also be set using environment variables. CLI flags take precedence.
| Environment variable | Equivalent flag | Format |
| ------------------------------------- | ---------------------- | ---------------------------------------------------- |
| `POSTMAN_INSIGHTS_DISCOVERY_MODE` | `--discovery-mode` | `"true"` to enable |
| `POSTMAN_INSIGHTS_CLUSTER_NAME` | *(env var only)* | Cluster name string (**required** in discovery mode) |
| `POSTMAN_INSIGHTS_INCLUDE_NAMESPACES` | `--include-namespaces` | Comma-separated list |
| `POSTMAN_INSIGHTS_EXCLUDE_NAMESPACES` | `--exclude-namespaces` | Comma-separated list |
| `POSTMAN_INSIGHTS_INCLUDE_LABELS` | `--include-labels` | Comma-separated `key=value` pairs |
| `POSTMAN_INSIGHTS_EXCLUDE_LABELS` | `--exclude-labels` | Comma-separated `key=value` pairs |
**Example: discover only in specific namespaces**
```bash
postman-insights-agent kube run \
--discovery-mode \
--include-namespaces=production,staging
```
**Example: exclude pods by label**
```bash
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.
| Pod environment variable | Effect |
| --------------------------------------------------------------- | --------------------------------------------- |
| `POSTMAN_INSIGHTS_WORKSPACE_ID` + `POSTMAN_INSIGHTS_SYSTEM_ENV` | Pod uses the workspace-based onboarding flow. |
| `POSTMAN_INSIGHTS_PROJECT_ID` | Pod uses the legacy project-based flow. |
| *(neither set)* | Pod uses auto-discovery (default). |
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
```bash
postman-insights-agent kube inject \
-f \
--discovery-mode \
--cluster-name \
[--service-name ] \
[-o ]
```
| Flag | Type | Default | Description |
| ------------------ | ------ | ---------------- | --------------------------------------------------------------------------------------------- |
| `--discovery-mode` | Bool | `false` | Enable automatic service discovery. |
| `--cluster-name` | string | *(empty)* | Kubernetes cluster name (**required** with `--discovery-mode`). |
| `--service-name` | string | *(auto-derived)* | Override the auto-derived service name. |
| `-f`, `--file` | string | *(required)* | Path to the Kubernetes YAML file to inject. |
| `-o`, `--output` | string | *(stdout)* | Path to write the injected YAML. |
| `-s`, `--secret` | string | `"false"` | Generate a Kubernetes Secret for the API key (`"true"` to include in output, or a file path). |
**Example:**
```bash
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
By default the API key is embedded as a literal env var. Use `--secret` to reference it from a Kubernetes Secret named `postman-agent-secrets` (key: `postman-api-key`). Generate the Secret automatically with `--secret`, or create it separately with `postman-insights-agent kube secret`.
#### Workspace Mode
```bash
postman-insights-agent kube inject \
-f \
--workspace-id \
--system-env \
[-o ]
```
| Flag | Type | Default | Description |
| ---------------- | ------------- | --------- | -------------------------------------------------------------------------------------- |
| `--workspace-id` | string (UUID) | *(empty)* | Your Postman workspace ID. Mutually exclusive with `--project` and `--discovery-mode`. |
| `--system-env` | string (UUID) | *(empty)* | Your system environment ID. Required when `--workspace-id` is set. |
Exactly one of `--project` (legacy), `--workspace-id`, or `--discovery-mode` must be specified.
## 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.
`--exclude-namespaces` adds to the default exclusion list. It doesn't replace it.
#### 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:
```yaml
metadata:
annotations:
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.
| Controller type | Captured? |
| ------------------------------ | --------- |
| Deployment (using ReplicaSet) | Yes |
| StatefulSet | Yes |
| DaemonSet | Yes |
| Job | No |
| CronJob | No |
| Standalone pod (no controller) | No |
The DaemonSet automatically skips pods that already have the Postman Insights Agent sidecar container, preventing duplicate traffic capture when running alongside sidecar-injected deployments.
## 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):
| Priority | Source | Example |
| -------- | ----------------------------------------------------------------------------------- | ------------------------------------------------------------- |
| 1 | **Owner reference name** — For Deployments, the ReplicaSet hash suffix is stripped. | Pod `my-app-5d4b7c8f9a-x2k4j` → `my-app` |
| 2 | **`app.kubernetes.io/name` label** | `app.kubernetes.io/name: payment-service` → `payment-service` |
| 3 | **`app` label** | `app: checkout` → `checkout` |
| 4 | **Pod name prefix** — Last `-suffix` segment is stripped from the pod name. | `api-gateway-7f8c9` → `api-gateway` |
### Overriding the service name
Set `POSTMAN_INSIGHTS_SERVICE_NAME` in the pod spec to override the auto-derived name:
```yaml
env:
- name: POSTMAN_INSIGHTS_SERVICE_NAME
value: "custom-namespace/custom-name"
```
For sidecar deployments, use the `--service-name` flag with `kube inject`:
```bash
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.
This TTL only applies to auto-discovered services that have not yet been onboarded. Services using Workspace Mode or hybrid per-pod IDs are not affected.
## Environment variables reference
| Variable | Applies to | Description |
| ------------------------------------- | ------------------ | ------------------------------------------------------------------------------------------------------------------ |
| `POSTMAN_INSIGHTS_API_KEY` | All | Postman API key for authentication. Also accepts `POSTMAN_API_KEY` as a fallback. |
| `POSTMAN_INSIGHTS_DISCOVERY_MODE` | DaemonSet, Sidecar | Set to `"true"` to enable Discovery Mode. Prefer using the `--discovery-mode` flag in `args` for visibility. |
| `POSTMAN_INSIGHTS_CLUSTER_NAME` | DaemonSet, Sidecar | Kubernetes cluster name (**required** in Discovery Mode). Builds unique service slug `cluster/namespace/workload`. |
| `POSTMAN_INSIGHTS_SERVICE_NAME` | Sidecar | Override the auto-derived service name. |
| `POSTMAN_INSIGHTS_INCLUDE_NAMESPACES` | DaemonSet | Comma-separated namespaces to include (Discovery Mode). |
| `POSTMAN_INSIGHTS_EXCLUDE_NAMESPACES` | DaemonSet | Comma-separated namespaces to exclude, added to defaults (Discovery Mode). |
| `POSTMAN_INSIGHTS_INCLUDE_LABELS` | DaemonSet | Comma-separated `key=value` pairs. Pods must match **all** labels. |
| `POSTMAN_INSIGHTS_EXCLUDE_LABELS` | DaemonSet | Comma-separated `key=value` pairs. Pods matching **any** label are excluded. |
| `POSTMAN_INSIGHTS_WORKSPACE_ID` | DaemonSet, Sidecar | Postman workspace ID (Workspace Mode, or hybrid mode in DaemonSet). |
| `POSTMAN_INSIGHTS_SYSTEM_ENV` | DaemonSet, Sidecar | System environment ID. Required when workspace ID is set. |
| `POSTMAN_INSIGHTS_PROJECT_ID` | DaemonSet | Per-pod legacy project ID (hybrid mode). Routes the pod to the legacy project flow. |
| `POSTMAN_INSIGHTS_WORKLOAD_NAME` | Sidecar | Workload name. Auto-derived from the Deployment name by `kube inject`. |
| `POSTMAN_INSIGHTS_WORKLOAD_TYPE` | Sidecar | Workload type (for example, `Deployment`). Auto-derived by `kube inject`. |
| `POSTMAN_INSIGHTS_LABELS` | Sidecar | JSON-encoded map of workload labels. Auto-derived by `kube inject`. |
| `POSTMAN_K8S_NAMESPACE` | Sidecar | Pod namespace. Auto-set by `kube inject` using the Kubernetes downward API. |
CLI flags always take precedence over environment variables.
## CLI flags reference
### `kube run` (DaemonSet) — Discovery Mode flags
| Flag | Type | Default | Description |
| ---------------------- | --------- | --------- | ----------------------------------------------------------------------------- |
| `--discovery-mode` | Bool | `false` | Enable automatic service discovery. Requires `POSTMAN_INSIGHTS_CLUSTER_NAME`. |
| `--include-namespaces` | string | *(empty)* | Comma-separated namespaces to include. |
| `--exclude-namespaces` | string | *(empty)* | Comma-separated namespaces to exclude (added to defaults). |
| `--include-labels` | key=value | *(empty)* | Labels that pods must have to be captured. |
| `--exclude-labels` | key=value | *(empty)* | Labels that exclude pods from capture. |
### `kube inject` (Sidecar) — Onboarding mode flags
Exactly one of `--project`, `--workspace-id`, or `--discovery-mode` must be specified.
| Flag | Type | Default | Description |
| ------------------ | ------------- | ---------------- | --------------------------------------------------------------------------------- |
| `--discovery-mode` | Bool | `false` | Enable automatic service discovery. |
| `--cluster-name` | string | *(empty)* | Cluster name (**required** with `--discovery-mode`). |
| `--workspace-id` | string (UUID) | *(empty)* | Postman workspace ID. Mutually exclusive with `--project` and `--discovery-mode`. |
| `--system-env` | string (UUID) | *(empty)* | System environment ID. Required when `--workspace-id` is set. |
| `--service-name` | string | *(auto-derived)* | Override the auto-derived service name. |
| `-f`, `--file` | string | *(required)* | Path to the Kubernetes YAML to inject. |
| `-o`, `--output` | string | *(stdout)* | Path to write the injected YAML. |
| `-s`, `--secret` | string | `"false"` | Generate a Secret for the API key. |
## 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](#default-excluded-namespaces)? 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:
```yaml
metadata:
annotations:
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).
```bash
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.
```bash
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](#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.