Cloud (DIY): ECS task JSON

For teams that manage ECS task definitions directly (aws ecs register-task-definition, the AWS console, custom CLI tooling, CDK) without Terraform. You bring the ECS cluster, two IAM roles, a security group, and an AWS Secrets Manager secret holding the enrollment token. The drawer snippet is just the task definition itself.

When to pick this

• You already have an ECS cluster you want to drop a single agent task into.
• You manage IAM and networking through your own pipeline (CDK, hand-written CloudFormation, console) and the Terraform module’s “one block creates 25 things” pattern does not fit.
• You want to read every resource the deploy creates before any of them exist.

Prerequisites

Complete Pre-flight first. The drawer gives you a JSON task definition; to register and run it you also need:

• An ECS cluster (Fargate-capable; the task definition declares --launch-type FARGATE).
• A VPC + subnet with internet access (same rules as Fargate elsewhere).
• A security group permitting egress 443 + DNS, no inbound.
• An AWS Secrets Manager secret holding the enrollment token.
• An ECS execution role with the execution-role policy plus the AWS-managed AmazonECSTaskExecutionRolePolicy.
• An ECS task role with the discovery policy.

Walkthrough

1. Create the secret

aws secretsmanager create-secret \
  --region us-east-2 \
  --name argus-agent/enrollment-token \
  --secret-string 'argus_et_<your-token-here>'
# capture the returned ARN; you reference it twice below

2. Create the two IAM roles

Save the ECS trust policy as trust-ecs.json, the execution-role policy as exec-policy.json (placeholders substituted), and the discovery policy as discovery-policy.json.

# Execution role
aws iam create-role \
  --role-name argus-agent-exec \
  --assume-role-policy-document file://trust-ecs.json
aws iam attach-role-policy \
  --role-name argus-agent-exec \
  --policy-arn arn:aws:iam::aws:policy/service-role/AmazonECSTaskExecutionRolePolicy
aws iam put-role-policy \
  --role-name argus-agent-exec \
  --policy-name argus-agent-exec-extras \
  --policy-document file://exec-policy.json

# Task role
aws iam create-role \
  --role-name argus-agent-task \
  --assume-role-policy-document file://trust-ecs.json
aws iam put-role-policy \
  --role-name argus-agent-task \
  --policy-name argus-discovery-read \
  --policy-document file://discovery-policy.json

Capture the two role ARNs returned by create-role.

3. Create the security group

SG=$(aws ec2 create-security-group \
  --region us-east-2 \
  --group-name argus-agent-sg \
  --description "Argus agent egress only" \
  --vpc-id vpc-xxxxxxxxxxxxxxxxx \
  --query 'GroupId' --output text)
aws ec2 revoke-security-group-egress --group-id $SG --protocol -1 --port -1 --cidr 0.0.0.0/0
aws ec2 authorize-security-group-egress --group-id $SG --protocol tcp --port 443 --cidr 0.0.0.0/0
aws ec2 authorize-security-group-egress --group-id $SG --protocol tcp --port 53 --cidr 0.0.0.0/0
aws ec2 authorize-security-group-egress --group-id $SG --protocol udp --port 53 --cidr 0.0.0.0/0

4. Save the task definition

Copy the snippet from the drawer’s Cloud (DIY) > ECS task JSON tab into task.json and substitute the four placeholders:

task.json

{
  "family": "argus-agent",
  "networkMode": "awsvpc",
  "requiresCompatibilities": ["FARGATE"],
  "cpu": "512",
  "memory": "1024",
  "executionRoleArn": "<INSERT_EXECUTION_ROLE_ARN>",
  "taskRoleArn": "<INSERT_TASK_ROLE_ARN>",
  "containerDefinitions": [
    {
      "name": "argus-agent",
      "image": "ghcr.io/argusdspm/argus-agent:stable",
      "essential": true,
      "environment": [
        {"name": "ARGUS_BACKEND_URL", "value": "https://api.argusdspm.com"},
        {"name": "CLOUD_PROVIDER", "value": "aws"},
        {"name": "ENROLLMENT_POOL", "value": "baseline"}
      ],
      "secrets": [
        {"name": "ENROLLMENT_TOKEN", "valueFrom": "<INSERT_TOKEN_SECRET_ARN>"}
      ],
      "logConfiguration": {
        "logDriver": "awslogs",
        "options": {
          "awslogs-group": "/ecs/argus-agent",
          "awslogs-region": "<INSERT_REGION>",
          "awslogs-stream-prefix": "agent",
          "awslogs-create-group": "true"
        }
      }
    }
  ]
}

Substitute <INSERT_EXECUTION_ROLE_ARN> and <INSERT_TASK_ROLE_ARN> from step 2, <INSERT_TOKEN_SECRET_ARN> from step 1, and <INSERT_REGION> with your deploy region (must match the region of the secret, the log group, and the cluster).

Common pitfall

awslogs-create-group: "true" auto-creates the log group on first write, but only if the execution-role policy allows logs:CreateLogGroup on a matching ARN pattern. The <LOG_GROUP_ARN_PATTERN> in the policy must reference the same log group name as awslogs-group here. Mismatch surfaces as AccessDeniedException: not authorized to perform: logs:CreateLogGroup.

5. Register and run

aws ecs register-task-definition \
  --region us-east-2 \
  --cli-input-json file://task.json

aws ecs run-task \
  --region us-east-2 \
  --cluster <YOUR_CLUSTER> \
  --task-definition argus-agent \
  --launch-type FARGATE \
  --network-configuration "awsvpcConfiguration={subnets=[subnet-xxxxxxxxxxxxxxxxx],securityGroups=[$SG],assignPublicIp=ENABLED}"

For long-running operation use aws ecs create-service instead of run-task to get automatic restart on container exit.

Verify

aws ecs list-tasks --cluster <YOUR_CLUSTER> --query 'taskArns'

aws ecs describe-tasks \
  --cluster <YOUR_CLUSTER> \
  --tasks <task-id> \
  --query 'tasks[0].[lastStatus,containers[0].lastStatus]' --output text
# expect: RUNNING RUNNING

aws logs tail /ecs/argus-agent --follow

See Verifying connection.

Teardown

# Stop the running task (the service form needs delete-service first).
aws ecs stop-task --cluster <YOUR_CLUSTER> --task <task-id>

# Deregister the task definition.
aws ecs deregister-task-definition --task-definition argus-agent:1

# Delete the supporting resources.
aws iam delete-role-policy --role-name argus-agent-task --policy-name argus-discovery-read
aws iam delete-role --role-name argus-agent-task
aws iam detach-role-policy --role-name argus-agent-exec \
  --policy-arn arn:aws:iam::aws:policy/service-role/AmazonECSTaskExecutionRolePolicy
aws iam delete-role-policy --role-name argus-agent-exec --policy-name argus-agent-exec-extras
aws iam delete-role --role-name argus-agent-exec

aws secretsmanager delete-secret --secret-id argus-agent/enrollment-token --force-delete-without-recovery
aws logs delete-log-group --log-group-name /ecs/argus-agent
aws ec2 delete-security-group --group-id $SG

If you created the cluster just for this deploy, also aws ecs delete-cluster --cluster <YOUR_CLUSTER>.