# Install Postman Insights Agent on AWS ECS

The Postman Insights Agent listens to the traffic arriving at the cluster service you want to monitor and automatically populates your Insights project with endpoints.

<Info class="iconless-callout">
  **Estimated time:** 10-minute setup, 5-minute wait
</Info>

After onboarding a service, you'll see your endpoints and their insights. Then, you can leverage the Insights' [Repro Mode](#activate-repro-mode) to debug your failing endpoints. You can also set up [alerts](#set-up-alerts) to get notifications about your errors.

## Requirements

Configuring ECS requires the following:

* Internet access for your service, to be able to communicate with the Insights backend services. For more information, see [Ensure internet access](#ensure-internet-access).
* AWS credentials at `~/.aws/credentials` with edit access to the ECS cluster, service, and task definition. For more information, see [Set up AWS ECS permissions](#set-up-aws-ecs-permissions).
* **Cluster ARN.** Go to the cluster in the AWS console and find the ARN in the cluster overview.
* **Service ARN.** The ARN of the service on which you want to install the Postman Insights Agent.
* **Insights project.** If you haven't already, create a new Insights project in your workspace. See [Get started with Postman Insights](/docs/insights/get-started/overview/) to learn more.

## Install the Postman Insights Agent

To install the Insights Agent, do the following:

1. From the **Setup** tab of your workspace, select **Start with ECS**.

   <img alt="Select your environment" src="https://assets.postman.com/postman-docs/v11/insights-environment-select-v.11.45.jpg" />

2. Run the following on your command line:

   ```bash
   bash -c "$(curl -L https://releases.observability.postman.com/scripts/install-postman-insights-agent.sh)"
   ```

Next, you'll configure your Insights Agent. Depending on the type of your deployment, select one of the following configuration options:

* If you're using Fargate, you can [configure the Insights Agent as a sidecar](#configure-the-insights-agent-as-a-sidecar) only.
* If you're using ECS on EC2 with awsvpc, you can install it as a [sidecar](#configure-the-insights-agent-as-a-sidecar) or as a [daemon service](#configure-the-insights-agent-as-a-daemon-service).
* If you're using ECS on EC2 with bridge networking, you can [configure the Insights Agent as a daemon service](#configure-the-insights-agent-as-a-daemon-service) only.

## Configure the Insights Agent as a sidecar

You'll add the sidecar using either the `ecs add` [subcommand](/docs/insights/reference/agent/ecs-add/) or, if you're on CloudFormation stack, the `ecs cf-fragment` [subcommand](/docs/insights/reference/agent/ecs-cf-fragment/).

<Info class="iconless-callout">
  If you're using ECS on EC2 with bridge networking, you'll need to attach the Insights Agent to the host network. See [Configure the Insights Agent as a daemon service](#configure-the-insights-agent-as-a-daemon-service).
</Info>

### Configure using ecs add

1. Prepare to run the install script. Check [Requirements](#requirements) for needed information.

2. On the Insights onboarding screen, click **Add API key** to copy and paste it with the next command.

   <Info class="iconless-callout">
     In the example command below, the angle brackets and the text between them are placeholders. The command you copy in the onboarding screen will contain your correct API key and project ID.
   </Info>

   ```bash
   POSTMAN_API_KEY=<add-your-api-key-here> postman-insights-agent ecs add \
   --project <projectId> \
   --cluster <ECS_cluster_ARN> \
   --profile <aws_profile_name> \
   --region <aws_region> \
   --service <ECS_service_ARN> \
   --task <task-name> \
   --repro-mode
   ```

   <Info class="iconless-callout">
     The `--repro-mode` flag allows the agent to send encrypted payload data for rerunning requests.
   </Info>

   Observe the deployment progress.

   <Info class="iconless-callout">
     The time it takes for the deployment to complete depends on the number of tasks running in a service. Therefore, while the process might take a while, the CLI runs until the deployment is finished because the processing is handled by AWS.
   </Info>

   See the help menu for further configuration.

   ```bash
   postman-insights-agent ecs --help
   ```

3. Return to Postman and observe an Insights Project populated for your services.

<Info class="iconless-callout">
  **Tip:** If you're not seeing your endpoints right away, traffic may be taking some time to collect. See the next section for more information.
</Info>

#### 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](/docs/insights/troubleshoot/overview/).

#### Activate Repro Mode

<Info class="iconless-callout">
  Only a Workspace Admin can enable the **Repro Mode**.
</Info>

To make API calls using real user data, you need to activate Repro Mode. Go to your Insights project and click [**Settings**](/docs/insights/reference/app/settings-tab/). Then, toggle on **Activate Repro Mode**.

<Info class="iconless-callout">
  **Default data redactions.** Postman Insights automatically redacts a set of sensitive values including authentication tokens. See the [full list](/docs/insights/data/redactions/). You can also add fields to redact ahead of turning on the feature.
</Info>

Learn more about [debugging with Repro Mode](/docs/insights/debug/).

#### 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](/docs/insights/reference/app/alerts-tab/).

### Configure using ecs cf-fragment

The `ecs cf-fragment` subcommand prints a CloudFormation fragment that can be included in an ECS cluster managed by a CloudFormation template.

To edit the CloudFormation template, do the following:

1. Go to the **Diagnostics** tab to locate your project ID string, formatted as *svc\_xxxxxxxxxx*. Copy it for the next step.

2. On your command line, run the `ecs cf-fragment` subcommand:

   ```bash
   POSTMAN_API_KEY=<your-api-key> postman-insights-agent ecs cf-fragment --project <project-id> --repro-mode
   ```

3. Edit the CloudFormation template that has the task definition for your service. Include the container definition output from the previous command in the task definition.

4. Edit the CloudFormation template for your service to use the new revision of the task definition.

The precise steps depend on your workflow for updating your CloudFormation templates. As an example, the steps below show how to do this using Application Composer in the AWS console.

To add the Insights Agent to a task definition in AWS Application Composer, do the following:

1. Go to your CloudFormation stack that has the task definition for your service. Then click **Update**.

2. Click the **Update stack** dropdown. You can choose either of two options. This example selects **Make a direct update**.

   <img alt="Update CloudFormation template" src="https://assets.postman.com/postman-docs/v11/insights-cf-fragment-update-v11.45.png" />

3. Select **Edit in Infrastructure Composer**, then click the **Edit in Infrastructure Composer** button.

   <img alt="Update stack" src="https://assets.postman.com/postman-docs/v11/insights-update-stack-v11.45.png" />

4. Enter **Template** mode.

   <img alt="Enter Template mode" src="https://assets.postman.com/postman-docs/v11/insights-template-mode-v11.45.png" />

5. Switch to **Template** mode and find the `ContainerDefinitions` section of the appropriate `TaskDefinition` resource. To add the Postman Insights Agent container definition, use the following command:

   ```bash
   POSTMAN_API_KEY=<your-api-key> postman-insights-agent ecs cf-fragment --project <project-id> --repro-mode
   ```

   <img alt="Add Insights Agent definition" src="https://assets.postman.com/postman-docs/v11/insights-add-agent-definition-v11.45.png" />

6. Validate the changes by clicking the **Validate** button.

7. Click **Create change set** to update the template.

8. Select an appropriate S3 bucket (optional), then click **Confirm and continue to CloudFormation**.

   <img alt="Update template" src="https://assets.postman.com/postman-docs/v11/insights-update-template-v11.45.png" />

9. Click **Next**.

   <img alt="Update stack confirm" src="https://assets.postman.com/postman-docs/v11/insights-update-stack-next-v.11.45.png" />

10. Click **Next** again to accept the existing set of parameter values.

    <img alt="Accept parameter values" src="https://assets.postman.com/postman-docs/v11/insights-accept-parameters-v11.45.png" />

11. In the **Stack failure options** dialog, click **Roll back all stack resources**, or the update may not succeed. Check **I acknowledge that AWS CloudFormation might create IAM resources.**, and click **Next**.

    <img alt="Stack failure options" src="https://assets.postman.com/postman-docs/v11/insights-stack-failure-options-v11.45.png" />

12. Review the changes and click **Submit**. It may take several minutes for the task definition to be updated.

If your service isn't configured to pick up the latest version of a task definition, you'll need to update the service manually.

To update a service with a new task definition revision in AWS Application Composer, do the following:

1. Go to the **Task definitions** page of the ECS console. Ensure you are in the appropriate AWS region, and select the task definition that you previously updated. Note its latest revision number.

2. Follow the previous steps for editing a task definition, except instead of adding the Insights Agent's container definition, update the task definition for your service.

3. Return to Postman and observe an Insights Project populated for your services.

<Info class="iconless-callout">
  **Tip:** If you're not seeing your endpoints right away, traffic may be taking some time to collect. See the next section for more information.
</Info>

#### 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](/docs/insights/troubleshoot/overview/).

#### Activate Repro Mode

<Info class="iconless-callout">
  Only a Workspace Admin can enable the **Repro Mode**.
</Info>

To make API calls using real user data, you need to activate Repro Mode. Go to your Insights project and click [**Settings**](/docs/insights/reference/app/settings-tab/). Then, toggle on **Activate Repro Mode**.

<Info class="iconless-callout">
  **Default data redactions.** Postman Insights automatically redacts a set of sensitive values including authentication tokens. See the [full list](/docs/insights/data/redactions/). You can also add fields to redact ahead of turning on the feature.
</Info>

Learn more about [debugging with Repro Mode](/docs/insights/debug/).

#### 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](/docs/insights/reference/app/alerts-tab/).

## Configure the Insights Agent as a daemon service

The following are instructions for attaching the Insights Agent to the host network in ECS. This option is necessary if you use ECS with bridge networking. If you'd like to install the Insights Agent as a sidecar instead, see [Configure the Insights Agent as a sidecar](#configure-the-insights-agent-as-a-sidecar).

You can add the Insights agent to an ECS cluster as a daemon service by using the `ecs task-def` [subcommand](/docs/insights/reference/agent/ecs-task-def/).

To create a new task definition, do the following:

1. Go to the **Task definitions** page of the ECS console. Ensure you are in the appropriate AWS region.

2. Select **Create new task definition > Create new task definition with JSON**.

   <img alt="Create a new task definition with JSON" src="https://assets.postman.com/postman-docs/v11/insights-task-definition-json-v11.45.png" />

3. On your command line, run the `ecs task-def` subcommand:

   ```bash
   POSTMAN_API_KEY=PMAK_xxxxxxxx_xxxxxxxx postman-insights-agent ecs task-def --project svc_xxxxxxxxxx --repro-mode
   ```

4. Replace the contents of the task definition with the output from the previous command.

   <img alt="Paste JSON" src="https://assets.postman.com/postman-docs/v11/insights-task-definition-json-paste-v11.45.png" />

5. Click **Create**. You can use the `postman-insights-agent` task definition to add the Postman Insights Agent to your ECS cluster.

To add the Insights Agent to your ECS cluster as a daemon service, do the following:

1. Go to the **Services** tab of your ECS cluster. Click **Create**.

   <img alt="Run new task" src="https://assets.postman.com/postman-docs/v11/insights-run-new-task-v11.45.png" />

2. In the **Task definition family** dropdown, select **postman-insights-agent**. Set service name to **postman-insights-agent**.

   <img alt="Set service name" src="https://assets.postman.com/postman-docs/v11/insights-set-service-name-v11.45.png" />

3. In the **Environment** dialog, select **Launch type**. Then select **EC2** from the **Launch type** dropdown list.

   <img alt="Select ECS as launch type" src="https://assets.postman.com/postman-docs/v11/insights-launch-type-v11.45.png" />

1) In the **Deployment configuration** dialog, set the **Service type** to **Daemon**.

<img alt="Configure ECS deployment" src="https://assets.postman.com/postman-docs/v11/insights-ecs-deployment-configuration-v11.45.png" />

1. At the bottom of the page, click **Create**.

2. Return to Postman and observe an Insights Project populated for your services.

<Info class="iconless-callout">
  **Tip:** If you're not seeing your endpoints right away, traffic may be taking some time to collect. See the next section for more information.
</Info>

### Wait for the Insights Agent to collect traffic

After Insights detects traffic from the Insights Agent, you'll get 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](/docs/insights/troubleshoot/overview/).

### Activate Repro Mode

<Info class="iconless-callout">
  Only a Workspace Admin can enable the **Repro Mode**.
</Info>

To make API calls using real user data, you need to activate Repro Mode. Go to your Insights project and click [**Settings**](/docs/insights/reference/app/settings-tab/). Then, toggle on **Activate Repro Mode**.

<Info class="iconless-callout">
  **Default data redactions.** Postman Insights automatically redacts a set of sensitive values including authentication tokens. See the [full list](/docs/insights/data/redactions/). You can also add fields to redact ahead of turning on the feature.
</Info>

Learn more about [debugging with Repro Mode](/docs/insights/debug/).

## More help with the ECS install

The following tasks help to set up your ECS install.

### Ensure internet access

Verify that your Fargate or EC2 task has a route to the internet.

#### Fargate tasks

To verify that your task has a route to the internet:

* When using a public subnet, you can assign a public IP address to the task ENI.
* When using a private subnet, the subnet can have a NAT gateway attached.

For more information, see [Amazon ECS task networking options for the Fargate launch type](https://docs.aws.amazon.com/AmazonECS/latest/userguide/fargate-task-networking.html).

#### EC2 tasks

Tasks must be launched in private subnets with NAT gateway. For more information, see [Amazon ECS task networking options for the EC2 launch type](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/task-networking.html).

### Set up AWS ECS permissions

Attach the following policy to your AWS profile.

```json
{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "ecs:UpdateService",
                "ecs:RegisterTaskDefinition",
                "ecs:DescribeServices",
                "ecs:TagResource",
                "ecs:DescribeTaskDefinition",
                "ecs:DescribeClusters"
                ],
            "Resource": "*"
        }
    ]
}
```

The Postman Insights Agent CLI needs the following permissions to install the Insights Agent in ECS. If the profile you selected is missing any of these permissions, the CLI displays an error message indicating which action it was attempting to perform.

The `AmazonECS_FullAccess` policy provided by Amazon is a superset of these actions. You could add the entire policy to ensure full permission.

| Action                           | Resource                                                                     | Purpose                                                                                             |
| -------------------------------- | ---------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- |
| `ec2:DescribeRegions`            | \*                                                                           | Find the list of AWS regions you have enabled. (If not present, it defaults to a precompiled list.) |
| `ecs:ListClusters`               | \*                                                                           | Find the available ECS clusters.                                                                    |
| `ecs:DescribeClusters`           | \*, or restricted to account like `arn:aws:ecs:::cluster/*`                  | Look up the names of the available ECS clusters.                                                    |
| `ecs:ListTaskDefinitionFamilies` | \*                                                                           | Find the available task definitions.                                                                |
| `ecs:DescribeTaskDefinition`     | \*                                                                           | Read the existing task definition in order to copy it.                                              |
| `ecs:RegisterTaskDefinition`     | \*                                                                           | Write a new version of the task definition.                                                         |
| `ecs:ListServices`               | \*                                                                           | Find the available services.                                                                        |
| `ecs:DescribeServices`           | \*, or restricted to your account, or restricted to the cluster you selected | Identify which services are using the task definition you selected.                                 |
| `ecs:UpdateService`              | \*, or restricted to your account, or restricted to the cluster you selected | Update and restart the service using the new task definition.                                       |
| `ecs:TagResource`                | \*, or restricted to your account, or restricted to the cluster you selected | Mark the service as having been updated by the Insights Agent.                                      |