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 Projects with endpoints.

To use the Insights Agent with Amazon Elastic Container Service (ECS), complete the following steps. Then, you'll be automatically directed to the Endpoints tab.

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.
• 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.
• 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.

Install the Postman Insights Agent

To install the Insights Agent, do the following:

1. Select Insights in the sidebar and select + to create a new Insights Project.

   

   The onboarding workflow displays, listing the installation instructions and supported deployments.

2. Run the following on your command line:

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

3. In Postman, select AWS ECS.

   

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 only.
• If you're using ECS on EC2 with awsvpc, you can install it as a sidecar or as a daemon service.
• If you're using ECS on EC2 with bridge networking, you can configure the Insights Agent as a daemon service only.

Configure the Insights Agent as a sidecar

The sidecar is added using the ecs add subcommand or, if you're on CloudFormation stack, using ecs cf-fragment.

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 using ecs add

1. Prepare to run the install script. Check Requirements for needed information.

2. On the Insights onboarding screen, select Add API key, and then copy and paste the command on your command line.

   The command below is just an example. Your API key and project ID will be autopopulated.

   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>
   

   Observe the deployment progress.

   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 will run until the deployment is finished because the processing is handled by AWS.

   See the help menu for further configuration.

   postman-insights-agent ecs --help
   

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

   Your Insights Project can take a few minutes to populate.

You are ready to check your Insights Agent connection, curate your endpoints, and observe insights about your endpoints. You can also review any traffic errors.

Configure using ecs cf-fragment

The ecs cf-fragment command 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. On your command line, run the ecs cf-fragment subcommand:

   postman-insights-agent ecs cf-fragment --project svc_YYYYY
   

   You can find your project ID on the onboarding screen.

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

3. 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 select Update.

   

2. Select Edit in Application Composer, then select the Edit in Application Composer button.

   

3. Enter Template mode.

   

4. Find the ContainerDefinitions section of the appropriate TaskDefinition resource. Add the Postman Insights Agent container definition.

   

5. Select Update template. Select an appropriate S3 bucket, then select Confirm and continue to CloudFormation.

   

6. Select Next.

   

7. Select Next again to accept the existing set of parameter values.

   

8. In the Stack failure options dialog, select Roll back all stack resources, or the update may not succeed. Select Next.

   

9. Review the changes and select Submit. It may take a few 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 was updated above. Note its latest revision number.

   

2. Follow the steps above 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.

   Your Insights Project can take a few minutes to populate.

You are ready to customize your insights and debug your endpoints. You can also review any traffic errors if your endpoints aren't populating.

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.

You can add the Insights agent to an ECS cluster as a daemon service by using 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.

   

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

   postman-insights-agent ecs task-def --project svc_YYYYY
   

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

   

5. Select 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 Tasks tab of your ECS cluster. Select Run new task.

   

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

   

3. In the Deployment configuration dialog, configure the following settings:

   • Set the Application type to Service.
   • In the Family dropdown, choose postman-insights-agent.
   • Set the Service name to postman-insights-agent.
   • Set the Service type to Daemon.
   

4. At the bottom of the page, select Create.

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

   Your Insights Project can take a few minutes to populate.

You are ready to check your Insights Agent connection, curate your endpoints, and observe insights about your endpoints. You can also review any traffic errors.

Uninstall the Insights Agent

The Insights Agent installation modifies the task definition of your service to include the Insights Agent sidecar. To uninstall the Insights Agent, revert to the earlier version of your task definition. To completely uninstall the agent, you can delete the task definition that contains the Insights Agent sidecar.

Additional 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.

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.

Set up AWS ECS permissions

Attach the following policy to your AWS profile.

{
    "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 in order to install the Insights Agent in ECS. If the profile you selected lacks any of these permissions, the CLI output will show 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 as an easy way to ensure your permissions are sufficient, if they're not already.

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.