Installing the host agent on Amazon Elastic Container Service (ECS)

To install the host agent into an Elastic Container Service (ECS) cluster that runs on Elastic Computing (EC2) by using ECS Daemon Scheduling, complete the steps to use either EC2 User Data or an ECS Task definition.

For Fargate on AWS ECS, see the Fargate monitoring documentation.

Deploying the host agent by using EC2 User Data

This is the preferred mechanism to deploy the host agent across your ECS on EC2 clusters.

The Launching an Amazon ECS Container Instance documentation shows how to use User Data on new EC2 instances that power your ECS on EC2 clusters.

The mechanisms that are described in Instana's Monitor AWS EC2 instances documentation applies to this use-case as well.

Deploying the host agent by using an ECS Task definition

Required fields

The following settings are required for Java® applications to be correctly monitored by Instana:

{
    "ipcMode": "host",
    "pidMode": "host",
    "privileged": true,
    "networkMode": "host",
    ...
}

Example

See the following example of JSON. You can modify the JSON file to meet your needs when you deploy the host agent.

Note: The fields that you need to modify are marked as <required>. You must set the <required> fields as strings.

{
    "ipcMode": "host",
    "executionRoleArn": null,
    "containerDefinitions": [
        {
            "dnsSearchDomains": null,
            "logConfiguration": {
                "logDriver": "json-file"
            },
            "entryPoint": null,
            "portMappings": [],
            "command": null,
            "linuxParameters": null,
            "environment": [
                {
                    "name": "INSTANA_AGENT_ENDPOINT",
                    "value": <required>
                },
                {
                    "name": "INSTANA_AGENT_ENDPOINT_PORT",
                    "value": <required>
                },
                {
                    "name": "INSTANA_AGENT_KEY",
                    "value": <required>
                }
            ],
            "ulimits": null,
            "dnsServers": null,
            "mountPoints": [
                {
                    "readOnly": false,
                    "containerPath": "/var/run",
                    "sourceVolume": "var_run"
                },
                {
                    "readOnly": false,
                    "containerPath": "/run",
                    "sourceVolume": "run"
                },
                {
                    "readOnly": false,
                    "containerPath": "/sys",
                    "sourceVolume": "sys"
                },
                {
                    "readOnly": false,
                    "containerPath": "/dev",
                    "sourceVolume": "dev"
                },
                {
                    "readOnly": false,
                    "containerPath": "/var/log",
                    "sourceVolume": "log"
                }
            ],
            "workingDirectory": null,
            "secrets": null,
            "dockerSecurityOptions": null,
            "memory": <required>,
            "volumesFrom": null,
            "image": <required: the image used to start your container. Up to 255 letters (uppercase and lowercase), numbers, hyphens, underscores, colons, periods, forward slashes, and number signs are allowed.>,
            "disableNetworking": null,
            "interactive": null,
            "healthCheck": null,
            "essential": true,
            "links": null,
            "hostname": null,
            "extraHosts": null,
            "pseudoTerminal": null,
            "user": null,
            "readonlyRootFilesystem": null,
            "dockerLabels": null,
            "systemControls": null,
            "privileged": true,
            "name": <required: the name of a container. Up to 255 letters (uppercase and lowercase), numbers, hyphens, and underscores are allowed.>,
            "repositoryCredentials": {
                "credentialsParameter": ""
            }
        }
    ],
    "placementConstraints": [],
    "memory": <required>,
    "taskRoleArn": "",
    "family": <required: specify a name for your task definition. Up to 255 letters (uppercase and lowercase), numbers, hyphens, and underscores are allowed.>,
    "pidMode": "host",
    "requiresCompatibilities": [
        "EC2"
    ],
    "networkMode": "host",
    "cpu": "<Required>",
    "volumes": [
        {
            "name": "dev",
            "host": {
                "sourcePath": "/dev"
            },
            "dockerVolumeConfiguration": null
        },
        {
            "name": "sys",
            "host": {
                "sourcePath": "/sys"
            },
            "dockerVolumeConfiguration": null
        },
        {
            "name": "var_run",
            "host": {
                "sourcePath": "/var/run"
            },
            "dockerVolumeConfiguration": null
        },
        {
            "name": "run",
            "host": {
                "sourcePath": "/run"
            },
            "dockerVolumeConfiguration": null
        },
        {
            "name": "log",
            "host": {
                "sourcePath": "/var/log"
            },
            "dockerVolumeConfiguration": null
        }
    ]
}

Checking the status of the host agent

After you install the host agent, you can check the status of the host agent in the Instana UI or on the host. For more information, see Checking the status of the host agent.

Monitor AWS EC2 instances

For more information about AWS EC2 monitoring, see the AWS EC2 documentation and blog post.

Troubleshooting agent deployment

If installing the agent is not successful at first, you can check log messages and troubleshooting tips. If this troubleshooting section does not answer the questions you have, contact the IBM Instana support team with information about your experience, so that we can help you and update our documentation accordingly.

For troubleshooting information that is general to all host agents, see Managing host agents / Troubleshooting.