Installing the Agent on AWS

The Instana agent can be installed on AWS Virtual Machines to either:

  1. Monitor applications running on those Virtual Machines, or

  2. Collect data from AWS APIs like CloudWatch, S3 and X-Ray (see the full list of supported AWS APIs)

In both cases, the installation method we advise is based on our One-Liner.

It is also possible to have the AWS API data fetched via an Instana agent running outside of AWS.

DEPRECATED: In the past, we have made available an Amazon Machine Image (AMI) with a pre-installed Instana agent. However, we firmly believe that you should select the Operative System to use based on what is best to run your applications, and then install the Instana agent on it to monitor them; as a result, the Instana agent AMI is deprecated and will not be updated any longer.

Install the Instana agent to monitor AWS API data

User data is an AWS feature that allows to specify scripts to be executed by EC2 on a newly-created Virtual Machine while it is being provisioned for use. The Instana agent One-Liner works with User data effortlessly.

UserData script

The core of the User data script to run is found in the Management Portal of your tenant unit. From there, select “Install Agent”, and the following page will appear:

Agent Installation Screen in the Management Portal

Configure the “One-Liner” form to (1) “install silently” and to (2) “install and start as service”. Copy the resulting script and paste it in a text editor: you will need to add a few lines as shown below:

#!/bin/bash

curl -o setup_agent.sh https://setup.instana.io/agent && chmod 700 ./setup_agent.sh && sudo ./setup_agent.sh -a <redacted> -m aws -t dynamic -l <redacted> -s

The recommended instance type is a Current Generation General Purpose machine (for example, the m4.large).

Notice: The snippet above will install the agent in AWS mode. AWS mode is just INFRASTRUCTURE mode plus the automatic configuration of the AWS data collection. For more information about agent modes, see the Agent Mode documentation.

Which AMI should I use?

Anything that fits the general requirements for running the Instana Agent on Linux is fine. Other operating systems are not supported to use the Instana agent to fetch data from the AWS APIs.

A note on costs

Monitoring your AWS infrastructure will incur some additional costs into your AWS budget. Here is a rough estimate (assuming a m4.large instance):

  • EC2 Instance: $0.12 per hour * 24 hours = $2.88 per day
  • Discovery: Number of AWS supported services * (3 discover ticks per minute * 60 minutes * 24 hours) = 4320 * Number of AWS supported services calls to the AWS API
  • Cloud Watch Metrics: Number of AWS detected services * (1 request per minute * 60 minutes * 24 hours) * Number of metrics = 1440 * Number of AWS detected services calls to the AWS CloudWatch API * Number of metrics calls to the Cloud Watch API per day

An example

Let’s use Amazon RDS as an example with two PostgreSQL instances running. We’re currently monitoring 18 different metrics for this service, so:

  • EC2 Instance: $0.12 per hour * 24 hours makes a total $2.88 per day
  • RDS Costs: 1440 requests per day * 2 RDS instances * 18 metrics makes a total of 51,840 requests per day to the AWS CloudWatch API. The current price for the CloudWatch API is $0.01 per 1000 requests so it would make a total of $0.52 per day

IMPORTANT: Using User data to install the Instana Agent via cloud-init directives is not supported.

IMPORTANT: You should have exactly one Instana agent per AWS Region collecting data from the AWS APIs, as it will poll the Amazon APIs and incurr in the related costs. If you want to simply install the Instana agent via user data to monitor some applications deployed on AWS, rather than fetch data from the AWS APIs, refer to this documentation.

The INSTANA_AGENT_MODE environment variable will instruct the One-Liner to perform additional, AWS-specific steps like configuring the AWS Region and setting up the collection of data via the AWS APIs, provided that the EC2 Virtual Machine has the right IAM permissions configured.

The small shell script above can be used with the user data facilities of:

IAM Roles

The following IAM role configurations assigned to the EC2 Virtual Machine running the Instana agent, will allow the Instana agent to discover and monitor your AWS resources:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Action": [
        "elasticbeanstalk:DescribeEnvironments",
        "elasticbeanstalk:ListTagsForResource",
        "elasticbeanstalk:DescribeInstancesHealth",
        "dynamodb:ListTables",
        "dynamodb:DescribeTable",
        "dynamodb:ListTagsOfResource",
        "rds:DescribeDBInstances",
        "rds:DescribeEvents",
        "rds:ListTagsForResource",
        "sqs:ListQueues",
        "sqs:GetQueueAttributes",
        "sqs:ListQueueTags",
        "elasticache:ListTagsForResource",
        "elasticache:DescribeCacheClusters",
        "elasticache:DescribeEvents",
        "elasticloadbalancing:DescribeLoadBalancers",
        "elasticloadbalancing:DescribeTags",
        "elasticmapreduce:ListClusters",
        "elasticmapreduce:DescribeCluster",
        "es:ListDomainNames",
        "es:DescribeElasticsearchDomain",
        "es:ListTags",
        "ec2:DescribeInstances",
        "ec2:DescribeTags",
        "ec2:DescribeVolumes",
        "kinesis:ListStreams",
        "kinesis:DescribeStream",
        "kinesis:ListTagsForStream",
        "lambda:ListTags",
        "lambda:ListFunctions",
        "lambda:ListEventSourceMappings",
        "lambda:GetFunctionConfiguration",
        "mq:ListBrokers",
        "mq:DescribeBroker",
        "s3:GetBucketTagging",
        "s3:ListAllMyBuckets",
        "s3:GetBucketLocation",
        "s3:GetBucketPolicyStatus",
        "xray:BatchGetTraces",
        "xray:GetTraceSummaries",
        "tag:GetResources"
      ],
      "Effect": "Allow",
      "Resource": "*"
    },
    {
      "Action": [
        "cloudwatch:GetMetricStatistics",
        "cloudwatch:GetMetricData",
        "cloudwatch:ListMetrics"
      ],
      "Effect": "Allow",
      "Resource": "*"
    }
  ]
}

This role needs to be able to perform the AssumeRole action, so, make sure to edit the Trust Relationship with something like the following:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "Service": "ec2.amazonaws.com"
      },
      "Action": "sts:AssumeRole"
    }
  ]
}

X-Ray setup

If you want Instana to collect X-Ray tracing data for the X-Ray Technical Preview, the steps are similar as shown in the UserData script section, but with some significant differences.

The core of the script to run as User data is found in the Management Portal of your tenant unit. From there, select “Install Agent”. Configure the “One-Liner” form to install silently (do not select the “install and start as service” option). Copy the pre-configured script and paste it in a text editor: you will need to add a few lines as shown below:

#!/bin/bash

export INSTANA_AGENT_MODE=aws

curl -o setup_agent.sh https://setup.instana.io/agent && chmod 700 ./setup_agent.sh && sudo ./setup_agent.sh -a <redacted> -t dynamic -l <redacted>

echo 'export XRAY_TRACING_ENABLED=true' >> /opt/instana/agent/bin/setenv

systemctl start instana-agent

(Notice: the last line assumes Systemd as init system. In case of a SysVinit-based system, replace systemctl start instana-agent with service instana-agent start.)

Installation in a Kubernetes cluster running in AWS

If you want to install the Instana agent on a Kubenetes cluster running on AWS (either installed and managed by you, or using Amazon Elastic Kubernetes Service), you should install the Instana agent as a Daemonset.

However, the Instana agents deployed as daemonset should not be the ones pulling the data from the supported AWS APIs. We advise to install a dedicated EC2 VM running the agent to collect the data about the usage of AWS services using the User data method.

Installation outside your AWS infrastructure

You can also dedicate any agent running outside of your AWS infrastructure. For this you will need to specify the following environment variables:

  • The region you want to monitor:

    INSTANA_AWS_REGION_CONFIG=
  • The credentials to access AWS resources. Please note that these credentials should belong to a user which is allowed to access the resources already described in the IAM Roles section.

    AWS_ACCESS_KEY_ID=
    AWS_SECRET_ACCESS_KEY=
  • If you’re using AWS X-Ray tracing in your applications, you can configure Instana to integrate the traces. You just need to define the following variable:

    XRAY_TRACING_ENABLED=true

The simplest way to configure these variables is to append them to the /opt/instana/agent/bin/setenv file.

Installation inside your AWS infrastructure with our AWS AMI

DEPRECATION NOTICE: The AMI-based way of providing EC2 Virtual Machines with the Instana Agent pre-installed is deprecated: the Instana agent AMI will not be further updated. It is discouraged to keep using the Instana agent AMI. We will keep the current version of the Instana agent AMI available to customer that have access to it to prevent issues with their AWS settings. However, the Instana agent AMI will not be made available to new customers going forward.

We are deprecating the Instana agent AMI because you should be in full control of the Operative Systems running on your virtualized infrastructure. Giving you control over which AMI to use, you can enjoy in a timely manner any security update published by the AMI provider, and adhere to your IT policies and update processes.

The suggested migration path is to use the user data method to install the Instana agent on newly-provisioned EC2 Virtual Machines. We have worked on our installation process so that is extremely easy to have the same functionalities the Instana agent AMI used to provided, but none of the drawbacks.