Skip to main content

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: Download and install the upwindctl tool:

    curl -fsSL https://get.upwind.io/upwindctl.sh | bash

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

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

Installation​

Download upwindctl​

You can download and install upwindctl using the installation script:

curl -fsSL https://get.upwind.io/upwindctl.sh | bash

This will download the latest version of upwindctl and install it to your local system.

Verify Installation​

Verify that upwindctl is installed correctly:

upwindctl version

Command Reference​

upwindctl ecs​

The main command for ECS operations.

upwindctl ecs [flags]

Aliases: ecs, e

upwindctl ecs patch​

Patches an ECS task definition file to inject the Upwind Tracer sidecar container.

upwindctl ecs patch [flags]

Aliases: patch, p

Flags​

FlagTypeDescriptionDefault
--taskdefstringPath to the task definition file, ARN (e.g., arn:aws:ecs:us-east-1:123456789012:task-definition/my-task:1), or - to read from stdinRequired
--containerstringContainer name to patch. Can be specified multiple times to patch multiple containers. If not specified, all containers will be patched.All containers
--sensorimagestringImage to use for the Upwind Tracer sidecarpublic.ecr.aws/upwindsecurity/images/tracer:0.5.0
--dockerinspectbooleanUse Docker inspect to automatically detect the entrypoint and command from the container imagetrue

Usage Examples​

Basic Usage​

Patch a task definition file and output the modified JSON:

upwindctl ecs patch --taskdef ./task_definition.json

Patch from ARN​

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

upwindctl ecs patch --taskdef 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 --taskdef -

Patch Specific Containers​

Patch only specific containers in a task definition:

upwindctl ecs patch \
  --taskdef ./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 \
  --taskdef ./task_definition.json \
  --sensorimage public.ecr.aws/upwindsecurity/images/tracer:0.4.0

Disable Docker Inspect​

Disable automatic entrypoint detection via Docker inspect:

upwindctl ecs patch \
  --taskdef ./task_definition.json \
  --dockerinspect=false

Save to File​

Save the patched task definition to a new file:

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

Integration with Infrastructure as Code​

Terraform​

You can use upwindctl with Terraform to automatically patch task definitions:

resource "null_resource" "patch_task_definition" {
  provisioner "local-exec" {
    command = <<-EOT
      upwindctl ecs patch \
        --taskdef ./task_definition.json \
        > ./patched_task_definition.json
    EOT
  }

  triggers = {
    task_definition_hash = filemd5("./task_definition.json")
  }
}

resource "aws_ecs_task_definition" "app" {
  family                = "my-app"
  container_definitions = file("./patched_task_definition.json")

  depends_on = [null_resource.patch_task_definition]
}

CI/CD Pipeline​

Integrate upwindctl into your CI/CD pipeline:

name: Patch and Deploy ECS Task Definition

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      - name: Install upwindctl
        run: curl -fsSL https://get.upwind.io/upwindctl.sh | bash

      - name: Patch task definition
        run: |
          upwindctl ecs patch \
            --taskdef ./task_definition.json \
            --container my-app \
            > patched_task_definition.json

      - name: Deploy to ECS
        run: |
          aws ecs register-task-definition \
            --cli-input-json file://patched_task_definition.json

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.5.0",
  "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:

  • If Docker inspect is enabled, it 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:

sudo chmod +x /usr/local/bin/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. Try disabling Docker inspect: --dockerinspect=false
  4. Manually specify the command as additional arguments

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​

Support​

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