Install Postman Insights Agent as a DaemonSet

Install the Postman Insights Agent as a DaemonSet if you want to install it in multiple services at once, for example, across your entire organization by your DevOps or platform team.

This installation is a three-part process consisting of:

1. Installing the Insights Agent as a DaemonSet in a Kubernetes cluster.
2. Onboarding your service as environment variables.
3. Activating Repro Mode, to enable you to reproduce errors on real user data.

You can also set up alerts to get notifications about your errors.

Requirements

• Edit permissions for the Kubernetes deployment.
• Postman Workspace Admin or Editor role.
• Linux environment. The agent and the user’s service should be running in a Linux environment.
• Insights project. See Get started with Postman Insights to learn more.

Install the agent in the Kubernetes cluster

To install the Insights agent as a DaemonSet in your Kubernetes cluster, do the following:

1. Download the postman-insights-agent-daemonset.yaml manifest file.

2. Apply the manifest file to your cluster by running the following command:

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

   This sets up the following resources in your cluster:

   Resource type	Resource
   Namespace	postman-insights-namespace
   Service Account	postman-insights-service-account
   Cluster Role	postman-insights-read-only-role
   Cluster Role Binding	postman-insights-view-all-resources-binding
   DaemonSet	postman-insights-agent

3. Wait for all the pods assigned to the DaemonSet to start up. You can check the status of the DaemonSet by running the following command:

   $
   kubectl get daemonsets -n postman-insights-namespace postman-insights-agent

   The number of desired and ready pods should be equal.

   

Onboard your service to Insights

To continue onboarding your service, you’ll collect your project ID and API key and move on to adding the required environment variables to your Kubernetes deployment.

Get your project ID

Go to the Diagnostics tab to locate your project ID string, formatted as svc_xxxxxxxxxx. Copy and keep it for the next steps.

Get your Postman API key

Get or create a new API key. For more information, see Generate and use Postman API keys. Keep the API key for the next steps.

Manage and store the API Key

You need to provide the API key as an environment variable to the containers. You can either add it directly in the deployment YAML file or use one of the following methods:

• Kubernetes ConfigMap
• Kubernetes Secrets
• AWS Secrets Manager
• HashiCorp Vault
• Other secret management tools

When using these options, make sure the container has the necessary permissions to access the secret from your secrets manager and that the secret is accessible from within the container. The following examples show how to use Kubernetes ConfigMap and Secrets to store the API key.

Learn more about DaemonSet security considerations.

Add environment variables to your deployment

You can add environment variables by defining them directly or by using a ConfigMap.

Do the following:

1. Set the following two environment variables per service:

   Environment variable	Description
   POSTMAN_INSIGHTS_PROJECT_ID	Your Insights project ID from the Postman app.
   POSTMAN_INSIGHTS_API_KEY	Your AWS Secret ARN of Postman API Key, which will be used to send traffic data from your service.

   You can use these optional environment variables:

   Environment variable	Description
   POSTMAN_INSIGHTS_DISABLE_REPRO_MODE	Turn off Repro Mode for a specific service.
   POSTMAN_INSIGHTS_AGENT_RATE_LIMIT	Service-specific rate limit. The Insights Agent drops traffic after reaching this limit.

2. Based on the following options, decide how to use Kubernetes ConfigMap and Secrets to store the API key.

   • Option 1: Define environment variables directly
   • Option 2: Define environment variables using a ConfigMap
   • Option 3: Define environment variables using both ConfigMap and Secrets

Option 1: Define environment variables directly

To add an environment variable to a Kubernetes deployment from a config file, you typically define it in a YAML manifest under the env section of the container spec.

1
...
2
spec:
3
  ...
4
  template:
5
    ...
6
    spec:
7
      containers:
8
        - name: my-container
9
          image: my-image
10
          env:
11
            - name: POSTMAN_INSIGHTS_PROJECT_ID
12
              value: "svc_xxxxxxxxxx"
13
            - name: POSTMAN_INSIGHTS_API_KEY
14
              value: "PMAK_xxxxxxxxxx"
15
  ...
16
...

Option 2: Define environment variables using a ConfigMap

If you want to manage environment variables through a ConfigMap, do the following:

1. Define the ConfigMap:

   1
   apiVersion: v1
   2
   kind: ConfigMap
   3
   metadata:
   4
     name: deployment-service-config
   5
   data:
   6
     POSTMAN_INSIGHTS_PROJECT_ID: "svc_xxxxxxxxxx"
   7
     POSTMAN_INSIGHTS_API_KEY: "PMAK_xxxxxxxx"

2. Reference the ConfigMap in the deployment:

   1
   ...
   2
   spec:
   3
     ...
   4
     template:
   5
       ...
   6
       spec:
   7
         containers:
   8
           - name: deployment-service
   9
             image: deployment-service-image
   10
             envFrom:
   11
               - configMapRef:
   12
                   name: deployment-service-config
   13
     ...
   14
   ...

This imports all key-value pairs from the deployment-service-config as environment variables into the container.

Option 3: Define environment variables using both ConfigMap and Secrets

If you want to store the API Key in secrets (for security concerns) and the Service ID in Config Map, do the following:

1. Define the ConfigMap:

   1
   apiVersion: v1
   2
   kind: ConfigMap
   3
   metadata:
   4
     name: deployment-service-config
   5
   data:
   6
     POSTMAN_INSIGHTS_PROJECT_ID: "svc_xxxxxxxxxx"

2. Define the secret:

   • Encode your API key.

     $
     echo -n "<your_api_key>" | base64
     $
     # Output: UE1BSy1hc2RmZ2hqa2wtcXdlcnR5dTU0MzIx

   • Create secret.yaml.

     1
     apiVersion: v1
     2
     kind: Secret
     3
     metadata:
     4
       name: deployment-service-secret
     5
     type: Opaque
     6
     data:
     7
       POSTMAN_INSIGHTS_API_KEY: "encoded API key"

3. Reference both ConfigMap and Secret in the deployment:

   1
   ...
   2
   spec:
   3
     ...
   4
     template:
   5
       ...
   6
       spec:
   7
         containers:
   8
           - name: deployment-service
   9
             image: deployment-service-image
   10
             envFrom:
   11
               - configMapRef:
   12
                   name: deployment-service-config
   13
               - secretRef:
   14
                   name: deployment-service-secret
   15
     ...
   16
   ...

After you add the environment variables, the deployment restarts, and new pods are created. The Insights Agent, running as a DaemonSet, begins monitoring traffic from your services.

Wait for the Insights Agent to collect traffic

After Insights detects traffic from the Insights Agent, you’ll get automatically redirected to the Overview page. The Insights Agent needs 5-8 minutes to use AI to generate endpoints.

If you’re only seeing health checks, your traffic may be affected. If you’re not seeing what you expect after 10 minutes, see Diagnose and troubleshoot Insights Agent errors.

Activate Repro Mode

In a DaemonSet setup, agent-level Repro Mode can be controlled both at the DaemonSet level and at the individual service level. For Repro Mode to work for a service, you need to activate it at both the agent and service levels.

To turn on Repro Mode, go to your Insights project and click Settings. Then, toggle on Activate Repro Mode.

Learn more about debugging with Repro Mode.

Set up alerts

Insights alerts notify you about your errors in real time, so you can act on them immediately. In your Insights project’s Alerts tab, you can adjust error rate thresholds, find and view problematic endpoints, mute or unmute alerts globally for specific endpoints, and integrate your alerts with Slack. Learn more about configuring and using alerts.