ECS (EC2)

Overview

Deploy the ARMO ECS agent to your Amazon ECS cluster running on EC2 instances to enable runtime security monitoring. The deployment uses an AWS CloudFormation stack that creates two components:

• ECS Agent: A daemon service that runs on every EC2 instance in your cluster, using eBPF for runtime threat detection. It monitors processes, file operations, and network activity at the kernel level.
• ECS Operator: A single-instance service that provides cluster-wide visibility by collecting metadata about all ECS services, tasks, and container instances.

Deployment typically completes in under 15 minutes.

Prerequisites

• An active ECS cluster running on EC2 launch type (not Fargate)
• Your ARMO Account ID (Customer GUID) and Access Key, available from the ARMO Platform
• AWS CLI installed and configured (only required for manual installation)
• IAM permissions to create CloudFormation stacks, IAM roles, ECS services, and task definitions

🚧

The URLs used in this guide (cloud.armosec.io for the platform and https://api.armosec.io for the API) are the default ARMO environment endpoints. Verify the correct platform and API URLs for your environment before proceeding.

Installation

There are two ways to deploy the ARMO ECS agent. The recommended approach is through the ARMO Platform UI, which generates a ready-to-use CloudFormation link with all parameters pre-filled. Alternatively, advanced users who are familiar with AWS CloudFormation can deploy the stack manually using the AWS CLI or AWS Console.

Option A: Install via ARMO Platform (Recommended)

This is the easiest way to install. The ARMO Platform generates a CloudFormation stack link with all the correct values already filled in for your cluster.

1. Log in to the ARMO Platform.
2. Navigate to the Accounts page from the left sidebar.
3. Click Connect Amazon ECS cluster.

4. In the connection dialog, paste the full Cluster ARN (Amazon Resource Name) for the ECS cluster you want to connect. You can find this in the AWS Console under your cluster's details page.

   A cluster ARN looks like this:

   arn:aws:ecs:us-east-1:123456789012:cluster/my-cluster

5. Click Launch stack. This opens the AWS CloudFormation console with all required parameters pre-filled, including your ARMO credentials, cluster name, region, and container image versions.

6. In the AWS CloudFormation console, review the parameters and click Create stack.
7. Return to the ARMO Platform and click Verify Installation to confirm the cluster was connected successfully.

Option B: Install Manually via AWS CLI

🚧

Before you begin: You must first create the ECS cluster instance in the ARMO Platform. Go to the Accounts page, click Connect Amazon ECS, and register your cluster. This is needed for pulling the agent images and for the ECS agent to report back to the platform.

If you prefer to deploy from the command line, you can create the CloudFormation stack using the AWS CLI. You will need to provide the required parameters manually.

The CloudFormation template is available at: https://armo-cadr-prod.s3.us-east-1.amazonaws.com/armo-ecs-agent-stack.yaml

aws cloudformation create-stack \
  --stack-name armo-ecs-agent \
  --template-url https://armo-cadr-prod.s3.us-east-1.amazonaws.com/armo-ecs-agent-stack.yaml \
  --parameters \
    ParameterKey=Region,ParameterValue=<YOUR_AWS_REGION> \
    ParameterKey=EcsClusterName,ParameterValue=<YOUR_CLUSTER_NAME> \
    ParameterKey=CustomerGuid,ParameterValue=<YOUR_ARMO_CUSTOMER_GUID> \
    ParameterKey=AccessKey,ParameterValue=<YOUR_ARMO_ACCESS_KEY> \
    ParameterKey=ApiUrl,ParameterValue=<ARMO_API_URL> \
    ParameterKey=EcsAgentImage,ParameterValue=<AGENT_IMAGE> \
    ParameterKey=EcsOperatorImage,ParameterValue=<OPERATOR_IMAGE> \
  --capabilities CAPABILITY_NAMED_IAM \
  --region <YOUR_AWS_REGION>

Replace the placeholder values:

🚧

The --capabilities CAPABILITY_NAMED_IAM flag is required because the stack creates named IAM roles for the ECS tasks.

To optionally enable CloudWatch logging, add the CloudWatchLogsGroupName parameter:

    ParameterKey=CloudWatchLogsGroupName,ParameterValue=/ecs/armo-agent

Wait for the stack to complete:

aws cloudformation wait stack-create-complete \
  --stack-name armo-ecs-agent \
  --region <YOUR_AWS_REGION>

Option C: Install Manually via AWS Console

🚧

Before you begin: You must first create the ECS cluster instance in the ARMO Platform. See the note in Option B above.

1. Open the AWS CloudFormation Console.
2. Click Create stack > With new resources (standard).
3. Under Specify template, select Upload a template file and upload the ARMO CloudFormation template.
4. Fill in the stack name (e.g., armo-ecs-agent) and the required parameters listed in the table above.
5. On the review page, check the box to acknowledge that CloudFormation will create IAM resources with custom names.
6. Click Create stack and wait for the status to reach CREATE_COMPLETE.

What Gets Deployed

The CloudFormation stack creates IAM roles (prefixed with armo- and suffixed with your stack name), and two ECS services: armo-ecs-agent, a daemon service that runs one agent task on every EC2 instance for eBPF-based runtime monitoring, and armo-ecs-operator, a single-instance service that provides cluster-wide visibility and reports metadata to the ARMO backend.

Verification

After the stack has been created, verify the deployment:

# Check that both services are running
aws ecs describe-services \
  --cluster <YOUR_CLUSTER_NAME> \
  --services armo-ecs-agent armo-ecs-operator \
  --region <YOUR_AWS_REGION>

Confirm that both services show status: ACTIVE and have running tasks matching your expected count (one ECS agent per EC2 instance, one operator total).

In the ARMO Platform:

• Your cluster should appear in the Accounts page
• Agent health status shows as connected
• Security findings begin appearing within a few minutes

Troubleshooting

Agent tasks not starting

Check that your EC2 instances have enough available memory. The ECS agent requires 1024 MiB and the operator requires 1024 MiB with 512 CPU units. Verify that the container images can be pulled by checking the task execution role permissions.

Operator not reporting to ARMO

Verify that the CustomerGuid, AccessKey, and ApiUrl values are correct. The operator needs outbound network access to communicate with the ARMO backend.

Stack creation fails with IAM error

Ensure you included the --capabilities CAPABILITY_NAMED_IAM flag when creating the stack. The template creates IAM roles with custom names.

View Logs

If you enabled CloudWatch logging during installation, view logs with:

# ECS agent logs
aws logs tail <YOUR_LOG_GROUP_NAME> \
  --log-stream-name-prefix armo \
  --follow

# Operator logs
aws logs tail <YOUR_LOG_GROUP_NAME> \
  --log-stream-name-prefix ecs \
  --follow

Updating the Agent

To update the ARMO agent to a newer version, update the CloudFormation stack with the new image parameters:

aws cloudformation update-stack \
  --stack-name armo-ecs-agent \
  --use-previous-template \
  --parameters \
    ParameterKey=Region,UsePreviousValue=true \
    ParameterKey=EcsClusterName,UsePreviousValue=true \
    ParameterKey=CustomerGuid,UsePreviousValue=true \
    ParameterKey=AccessKey,UsePreviousValue=true \
    ParameterKey=ApiUrl,UsePreviousValue=true \
    ParameterKey=EcsAgentImage,ParameterValue=<NEW_AGENT_IMAGE> \
    ParameterKey=EcsOperatorImage,ParameterValue=<NEW_OPERATOR_IMAGE> \
  --capabilities CAPABILITY_NAMED_IAM \
  --region <YOUR_AWS_REGION>

Uninstalling

To remove the ARMO agent, delete the CloudFormation stack:

aws cloudformation delete-stack \
  --stack-name armo-ecs-agent \
  --region <YOUR_AWS_REGION>

This removes all IAM roles, task definitions, and ECS services created by the stack.

Next Steps

• Configure security policies and detection rules in the ARMO Platform
• Set up alert notifications (Slack, PagerDuty, email)
• Review and tune initial security findings
• Connect additional ECS clusters or Kubernetes clusters