upwindctl ECS Command

Overview

The upwindctl ecs command is a CLI tool that automates the process of patching ECS task definitions to inject the Upwind Tracer into your containerized applications. This tool simplifies the deployment of Upwind monitoring by automatically modifying task definition files to include the necessary configuration for the Upwind Tracer sidecar container.

Use Cases

The upwindctl ecs patch command is particularly useful when:

• You manage ECS task definitions using Infrastructure as Code (IaC) tools like Terraform or CloudFormation
• You need to patch multiple task definitions consistently
• You want to automate the process of adding Upwind monitoring to existing ECS tasks
• You need to update task definitions with the latest Upwind Tracer image

Prerequisites

• upwindctl CLI: Install upwindctl

• Task Definition File: Have your ECS task definition file ready in JSON format, or know the ARN of an existing task definition

• AWS credentials: Required to patch a task definition by ARN, to use --register, and to run upwindctl ecs instrument. upwindctl uses the standard AWS credential chain. The identity needs these permissions:

  • Patch by ARN: ecs:DescribeTaskDefinition
  • --register: ecs:RegisterTaskDefinition, plus iam:PassRole on the task role and execution role of the task definition
  • instrument: ecs:DescribeServices, ecs:DescribeTaskDefinition, ecs:RegisterTaskDefinition, ecs:UpdateService and iam:PassRole as above

• Docker (optional): If you want to automatically detect the entrypoint and command from container images using Docker inspect

Command Reference

upwindctl ecs

The main command for ECS operations.

upwindctl ecs [flags]

Aliases: ecs, e

upwindctl ecs patch

The patch command patches task definition and injects Upwind Tracer to selected containers.
The output is a new task definition file with the Upwind Tracer injected.

The taskdef argument can be:

• Path to a task definition JSON file
• ARN (e.g., arn:aws:ecs:us-east-1:123456789012:task-definition/my-task:1)
• "-" to read from stdin

upwindctl ecs patch <taskdef> [flags]

Aliases: patch, p

Flags

Flag	Type	Description	Default
--container	string	Container name to patch. Can be specified multiple times to patch multiple containers. If not specified, all containers will be patched.	All containers
--tracer-image	string	Image to use for the Upwind Tracer sidecar	public.ecr.aws/upwindsecurity/images/tracer:0.10.2
--api-host	string	Cluster Manager address the Upwind Tracer reports to, for example upwind-cluster-manager.upwind-<your-cluster-name>.private:8082. Sets UPWIND_TRACER_API_HOST on the patched containers.	Not set
--api-security	boolean	Enable API security reporting. Sets UPWIND_TRACER_EXTENDED_SYSCALLS and UPWIND_TRACER_REPORT_API_CATALOG to true on the patched containers.	false
--register	boolean	Register new task definition revision after patching. The command then prints the ARN of the new revision as {"arn": "..."} instead of the task definition.	false
--output	string	Output format. Only json is supported.	json

upwindctl ecs instrument

The instrument command patches the task definition of an existing ECS service, registers the patched task definition as a new revision, and updates the service to use it. It patches every container in the task definition.

upwindctl ecs instrument --cluster <cluster-name> --service <service-name> [flags]

Aliases: instrument, i

Flags

Flag	Type	Description	Default
--cluster	string	Name of the ECS cluster that runs the service
--service	string	Name of the ECS service to instrument
--tracer-image	string	Image to use for the Upwind Tracer sidecar	public.ecr.aws/upwindsecurity/images/tracer:0.10.2
--api-host	string	Cluster Manager address the Upwind Tracer reports to. Sets UPWIND_TRACER_API_HOST on the patched containers.	Not set
--api-security	boolean	Enable API security reporting	false

Usage Examples

Basic Usage

Patch a task definition file and output the modified JSON:

upwindctl ecs patch ./task_definition.json

Patch from ARN

Fetch and patch a task definition from AWS using its ARN:

upwindctl ecs patch arn:aws:ecs:us-east-1:123456789012:task-definition/my-task:1

Patch from stdin

Read task definition from stdin and output the patched version:

cat task_definition.json | upwindctl ecs patch -

Patch Specific Containers

Patch only specific containers in a task definition:

upwindctl ecs patch ./task_definition.json \
  --container app-container \
  --container worker-container

Specify Custom Tracer Image

Use a specific version of the Upwind Tracer image:

upwindctl ecs patch ./task_definition.json \
  --tracer-image public.ecr.aws/upwindsecurity/images/tracer:0.10.2

Save to File

Save the patched task definition to a new file:

upwindctl ecs patch ./task_definition.json > patched_task_definition.json

Integration with Infrastructure as Code

Terraform

You can use upwindctl with Terraform to automatically patch task definitions. Terraform reads the patched container definitions while it plans, so run upwindctl from an external data source or before terraform plan:

Using external data source

The external data source only accepts a JSON object with string values, so jq returns the patched container definitions as a single JSON string:

data "external" "patched_task_definition" {
  program = ["bash", "-c", <<-EOT
    upwindctl ecs patch ./task_definition.json | \
    jq -c '{container_definitions: (.containerDefinitions | tojson)}'
  EOT
  ]
}

resource "aws_ecs_task_definition" "app" {
  family                   = "my-app"
  requires_compatibilities = ["FARGATE"]
  network_mode             = "awsvpc"
  cpu                      = 256
  memory                   = 512
  container_definitions    = data.external.patched_task_definition.result.container_definitions
}

Using a pre-patched file

Patch the task definition before you run Terraform, for example in an earlier pipeline step:

upwindctl ecs patch ./task_definition.json > ./patched_task_definition.json

Then read the patched container definitions from the file:

resource "aws_ecs_task_definition" "app" {
  family                   = "my-app"
  requires_compatibilities = ["FARGATE"]
  network_mode             = "awsvpc"
  cpu                      = 256
  memory                   = 512
  container_definitions    = jsonencode(jsondecode(file("./patched_task_definition.json")).containerDefinitions)
}

CI/CD Pipeline

Integrate upwindctl into your CI/CD pipeline:

GitHub Actions

name: Patch and Deploy ECS Task Definition

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    permissions:
      id-token: write
      contents: read
    steps:
      - uses: actions/checkout@v6

      - name: Configure AWS credentials
        uses: aws-actions/configure-aws-credentials@v6
        with:
          role-to-assume: arn:aws:iam::123456789012:role/my-deploy-role
          aws-region: us-east-1

      - name: Install upwindctl
        env:
          UPWINDCTL_NONINTERACTIVE: "yes"
        run: |
          curl -fsSL https://get.upwind.io/upwindctl.sh | bash
          echo "$HOME/.upwindctl" >> "$GITHUB_PATH"

      - name: Patch task definition and Register
        id: patch
        run: |
          TASK_DEFINITION_ARN=$(upwindctl ecs patch ./task_definition.json \
            --container my-app \
            --register | jq -r '.arn')
          echo "task-definition-arn=$TASK_DEFINITION_ARN" >> "$GITHUB_OUTPUT"

With --register, upwindctl prints the ARN of the new task definition revision, and the step saves it as the task-definition-arn output so later steps can deploy it, for example with aws ecs update-service --task-definition.

GitLab CI

stages:
  - build
  - deploy

patch-task-definition:
  stage: build
  image:
    name: amazon/aws-cli
    entrypoint: [""]
  variables:
    UPWINDCTL_NONINTERACTIVE: "yes"
  before_script:
    - curl -fsSL https://get.upwind.io/upwindctl.sh | bash
    - . "$HOME/.upwindctl/env"
  script:
    - upwindctl ecs patch ./task_definition.json --register

What the Command Does

When you run upwindctl ecs patch, the tool performs the following modifications to your task definition:

1. Adds Upwind Tracer Sidecar Container

If not already present, adds a new container definition for the Upwind Tracer:

{
  "name": "upwind-tracer",
  "image": "public.ecr.aws/upwindsecurity/images/tracer:0.10.2",
  "essential": false
}

2. Configures Volume Mounts

For each application container, adds a volume mount from the Upwind Tracer sidecar:

{
  "volumesFrom": [
    {
      "sourceContainer": "upwind-tracer",
      "readOnly": true
    }
  ]
}

3. Adds Linux Capabilities

Adds the SYS_PTRACE capability to allow the tracer to monitor processes:

{
  "linuxParameters": {
    "capabilities": {
      "add": ["SYS_PTRACE"]
    }
  }
}

4. Updates Entrypoint and Command

Modifies the container entrypoint to use the Upwind Tracer:

{
  "entrypoint": ["/var/lib/upwind/upwind-tracer"],
  "command": ["/original/entrypoint", "arg1", "arg2"]
}

The tool intelligently handles different scenarios:

• Automatically detects the original entrypoint and command from the container image
• If an entrypoint already exists, it moves it to the command field
• If both entrypoint and command exist, it preserves both in the correct order

Troubleshooting

Permission Denied

If you encounter permission errors when running upwindctl:

chmod +x "$HOME/.upwindctl/upwindctl"

Docker Inspect Fails

If Docker inspect fails to retrieve image information:

1. Ensure Docker is running: docker ps
2. Verify you have access to the container registry
3. Set entryPoint for the container in your task definition. upwindctl only looks up the image when the container has no entryPoint

Task Definition Not Found

If the tool cannot find your task definition:

1. Verify the file path is correct
2. Ensure the file is valid JSON
3. For ARNs, verify your AWS credentials are configured correctly

Invalid Task Definition Output

If the patched task definition is invalid:

1. Validate the original task definition format
2. Check that all required fields are present in the original file
3. Review the AWS ECS task definition schema documentation

Additional Resources

• Amazon ECS Task Definition Parameters
• Deploy the Upwind Tracer on Fargate

Support

If you encounter issues or need assistance with the upwindctl ecs command:

• Review the Troubleshooting guide
• Contact Upwind Support through the Management Console
• Check the Upwind Documentation