Connect with the API Catalog using Postman Insights Agent

The Postman Insights Agent monitors your Kubernetes services and automatically populates your API Catalog. The recommended way to get started is Discovery Mode — deploy the agent once and it finds and registers your services automatically, with no per-service configuration needed.

Prerequisites

• A Postman API key with required permissions
• Kubernetes cluster v1.19+
• kubectl configured for your cluster

Deploy with Discovery Mode

1. Create the namespace and API key secret. The agent authenticates with Postman using your API key. Store it as a Kubernetes Secret so it never appears in plain text in the manifest:

   $
   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. Download the base DaemonSet manifest, postman-insights-agent-daemonset.yaml.

3. Edit the manifest for Discovery Mode. The downloaded manifest requires three changes before it works with Discovery Mode. Open the file and apply the following edits:

   • Enable Discovery Mode. Find the args section and add --discovery-mode:

     1
     args:
     2
     - kube
     3
     - run
     4
     - --discovery-mode
     --discovery-mode and --repro-mode serve different purposes and are not alternatives. Keep any other flags in args that your deployment already uses. Just add --discovery-mode to enable service discovery.

   • Set your cluster name. Discovery Mode requires a unique cluster name to identify your services across environments. Add it to the env section:

     1
     env:
     2
     - name: POSTMAN_INSIGHTS_CLUSTER_NAME
     3
     value: "<YOUR_CLUSTER_NAME>"      # e.g. "production" or "us-east-staging"
     The cluster name is combined with the namespace and workload name to build a unique service identifier (cluster/namespace/workload). Choose a name that is stable and unique. Changing it later will cause services to appear as new entries.

   • Wire the API key. Reference the Secret you created in Step 1. Add this to the env section alongside the cluster name:

     1
     env:
     2
     - name: POSTMAN_INSIGHTS_CLUSTER_NAME
     3
     value: "<YOUR_CLUSTER_NAME>"
     4
     - name: POSTMAN_INSIGHTS_API_KEY
     5
     valueFrom:
     6
         secretKeyRef:
     7
         name: postman-agent-secrets
     8
         key: postman-api-key

     After all three changes, the relevant part of your manifest should look like this:

     1
     containers:
     2
     - name: postman-insights-agent
     3
     image: public.ecr.aws/postman/postman-insights-agent:latest
     4
     args:
     5
     - kube
     6
     - run
     7
     - --discovery-mode
     8
     env:
     9
     - name: POSTMAN_INSIGHTS_CLUSTER_NAME
     10
         value: "<YOUR_CLUSTER_NAME>"
     11
     - name: POSTMAN_INSIGHTS_API_KEY
     12
         valueFrom:
     13
         secretKeyRef:
     14
             name: postman-agent-secrets
     15
             key: postman-api-key
     16
     - name: POSTMAN_INSIGHTS_K8S_NODE
     17
         valueFrom:
     18
         fieldRef:
     19
             fieldPath: spec.nodeName
     20
     - name: POSTMAN_INSIGHTS_CRI_ENDPOINT
     21
         value: /var/run/containerd/containerd.sock

4. Apply the manifest.

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

5. Verify the deployment.

   Check that the agent pods are running on each node:

   $
   kubectl get pods -n postman-insights-namespace

   Then, inspect the logs to confirm services are being discovered:

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

   You can expect to see log lines indicating pods are being discovered and services are being registered with Postman. If pods aren’t appearing, see Troubleshooting.

6. Complete onboarding in Postman. From Home, click API Catalog > Service Discovery > Postman Insights Catalog. Then, select the service and the environment to integrate into API Catalog.

   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.

   Discovered services have a traffic capture window. If a service isn’t onboarded in the Postman app within that window, the agent pauses capture for that service. Completing onboarding lifts the restriction. See Traffic TTL for details.

Optional: Limit discovery to specific namespaces

By default, the agent discovers pods in all namespaces except a built-in exclusion list (for example, Kubernetes system, monitoring, GitOps tools). To capture only specific namespaces, add --include-namespaces to the args section in the manifest:

1
args:
2
- kube
3
- run
4
- --discovery-mode
5
- --include-namespaces=production,staging

For the full list of filtering options — namespace exclusions, label filtering, per-pod opt-out — see the Pod Filtering reference.

Choosing an approach

For sidecar injection, Workspace Mode instructions, advanced filtering, environment variable reference, and troubleshooting, see Insights Agent deployment modes.