Install Upwind on Amazon ECS and AWS Fargate

Overview

This page provides instructions for installing the Upwind components in an ECS cluster using the AWS Fargate launch type.

Prerequisites

1. An existing Amazon ECS cluster . To deploy one, see Getting started with Amazon ECS .
2. Upwind Cluster Manager requires at least one private subnet with a NAT Gateway.
3. The security group for the cluster manager must allow inbound traffic on port 8082 from all other tasks in the cluster. By default, the cluster manager will use the default security group for the VPC.

Install

Step 1: Generate Credentials

note

This step is relevant only if you want to create new client credentials. If you already have client credentials, you can skip this step.

Select the + (plus) symbol at the top of the screen and select Connect ECS Cluster. Select Generate a new one to create a new client ID and client secret. Provide a name and select Generate. Alternatively, you can generate it in the Credentials page in the console. For more information review the documentation on Credentials.

After you have generated the secret, it will automatically be copied into step 3 and inserted into the UPWIND_CLIENT_ID and UPWIND_CLIENT_SECRET fields.

Step 2: Choose ECS Cluster

Select the ECS Cluster you would like to connect.

Step 3: Choose Installation Method

Select the appropriate installation method for your environment from the available options to install the Upwind Cluster Manager and deploy the Upwind Sensor.

Terraform (Recommended)

Step 3.1: Install the Upwind Cluster Manager

Copy the Terraform module code snippet from the Upwind Management Console and save it to a file named main.tf. Replace the placeholders with the appropriate values, either directly or by setting Terraform variables.

To install the Upwind Cluster Manager, run the following command:

terraform init && terraform apply

Step 3.2: Deploy the Upwind Sensor

Upwind provides two deployment methods: Sidecar Deployment and Embedded Deployment. Choose the method that best meets your needs and proceed with the instructions for your selected deployment method.

Sidecar Deployment

This approach allows monitoring of AWS Fargate containers without any modifications to the application container image.

Add the Upwind Sensor Sidecar Container

Add a new container definition for the Upwind Sensor sidecar container:

resource "aws_ecs_task_definition" "example" {
  #  ...

  container_definitions = jsonencode([
    #  { ... },

    {
        container  = {
          name      = "upwind-tracer"
          image     = "public.ecr.aws/upwindsecurity/images/tracer:0.1.1"
          essential = false
      }
    }
  ])
}

For each application container, set the following sections; environment, valuesFrom, entrypoint, command, and linuxParameters:

resource "aws_ecs_task_definition" "example" {
  container_definitions = jsonencode([
    {
      # Specify the UPWIND_TRACER_API_HOST environment variable
      # to set the report forwarding destination.
      environment = {
        "UPWIND_TRACER_API_HOST" = "upwind-cluster-manager.upwind-<cluster-name>.private:8082",
      }

      # Map the tracer's container image directory into your application image.
      volumesFrom = [
        {
          sourceContainer = "upwind-tracer"
          readOnly        = true
        }
      ]

      # Specify the entrypoint and command. If you already use an entrypoint,
      # move it to be the first argument for the command field.
      entrypoint = [
        "/var/lib/upwind/upwind-tracer"
      ]

      command = [
        "/path/to/command",
        "--arg1",
        "--arg2",
      ]

      # Add the SYS_PTRACE capability to allow the tracer to monitor the
      # processes and connections of applications within the container,
      # even if they are running under a non-root user.
      linuxParameters = {
        capabilities = {
          add = [
            "SYS_PTRACE"
          ],
        }
      }
    },

    #  Container definition for the Upwind Tracer sidecar.
    { /* ... */ }
  ])
}

Apply Changes

To update the task definition, run the following command:

terraform apply

Embedded Deployment

This approach integrates the Upwind Sensor binary directly into the application container image during the build process.

Add the Upwind Sensor to your Dockerfile

This step involves (a) adding a build stage, (b) copying the Upwind Sensor binary, and (c) setting up the entrypoint and command instructions.

Below is a simple example of a Dockerfile with these additions:

# syntax=docker/dockerfile:1

# (a) Add the Upwind Tracer image as a build stage.
FROM public.ecr.aws/upwindsecurity/images/tracer:0.1.1 AS upwind-tracer

# (b) Copy the Upwind Tracer binary from the build stage.
COPY --from=upwind-tracer /var/lib/upwind /var/lib/upwind

# (c) Set the default entrypoint to the Upwind Tracer.
ENTRYPOINT ["/var/lib/upwind/upwind-tracer"]

# (c) Set the default command to run your application.
CMD ["/path/to/your/app"]

Build and Push Image

After defining and creating your image, you need to push it to a container registry like Amazon ECR. Copy the example script from the Upwind console and save it to a file named build-push.sh. Replace the placeholders with the appropriate values, either directly or by setting environment variables.

To build and push the image, run the following command:

/path/to/build-push.sh

Update the Task Definition

Update the task definition of your application by modifying the container definition to use the new image with the embedded binary.

resource "aws_ecs_task_definition" "example" {
  #  ...

  container_definitions = jsonencode([
    {
        container  = {
          image     = "<IMAGE_URI>"
      }
    }
  ])
}

Apply Changes

To update the task definition, run the following command:

terraform apply

AWS CloudFormation

Step 3.1: Install the Upwind Cluster Manager

Create a New Stack

1. Open the AWS CloudFormation console .
2. Click on Create stack.
3. Select With new resources (standard) for a completely new stack.

Specify Template

1. Choose Choose an existing template.
2. Select Amazon S3 URL for the template source.
3. Enter the following URL:

https://s3.amazonaws.com/get.upwind.io/cfn/templates/ecs-fargate/cluster-manager-task-0.1.0.yaml

4. Click on Next.

Specify Stack Details

1. Provide a Stack name. Use the pattern of <CLUSTER_NAME>-upwind-cluster-manager as this must be unique within the region.
2. Fill in any required parameters that the template specifies, such as cluster name, client credentials, and network configuration.

note

If the default security group for the VPC does not allow inbound traffic on port 8082, create a security group that does and set it as the ClusterManagerSecurityGroup stack parameter.

3. Click on Next.

Configure Stack Options

1. Configure additional options like tags, IAM role permissions, and advanced settings.
2. Click on Next.

Review and Create

1. Review all the settings and parameters. Check the Capabilities section and acknowledge that the template may create IAM resources, if applicable.
2. Click on Submit.

Step 3.2: Deploy the Upwind Sensor

Upwind provides two deployment methods: Sidecar Deployment and Embedded Deployment. Choose the method that best meets your needs and proceed with the instructions for your selected deployment method.

Sidecar Deployment

This approach allows monitoring of AWS Fargate containers without any modifications to the application container image.

Add the Upwind Sensor Sidecar Container

1. Open the Amazon ECS console .
2. Select Task Definitions from the left navigation pane, then choose the task definition you want to use.
3. Select the latest revision from the list.
4. Click on the Create new revision dropdown and select Create new revision.
5. Below the list of containers, click on Add container.
6. For each application container, set the following sections:
   • Under Environment variables, specify the UPWIND_TRACER_API_HOST environment variable to set the report forwarding destination:
     • Key: UPWIND_TRACER_API_HOST, Value: upwind-cluster-manager.upwind-<CLUSTER_NAME>.private:8082
   • Under Startup dependency ordering, set the upwind-tracer dependency to ensure the application container starts only after the Upwind Sensor sidecar container successfully starts.
     • Container name: upwind-tracer
     • Condition: Complete
   • Under Docker configuration, specify the entrypoint and command for the container. If you already use an entrypoint, move it to be the first argument for the command field.
     • Entrypoint: /var/lib/upwind/upwind-tracer
     • Command: /path/to/command,--arg1,--arg2
   • Under Storage, map the tracer's container volume into the cluster manager container:
     • Click on Add volume from under Volumes from.
     • Set the Container to your application container.
     • Set the Source container to upwind-tracer.
     • Check the Read only checkbox.
7. Click on Create to save the new revision.

Apply Changes

8. Update your services to use the new task definition revision created in the previous step.

Embedded Deployment

This approach integrates the Upwind Sensor binary directly into the application container image during the build process.

Add the Upwind Sensor to your Dockerfile

This step involves (a) adding a build stage, (b) copying the Upwind Sensor binary, and (c) setting up the entrypoint and command instructions.

Below is a simple example of a Dockerfile with these additions:

# syntax=docker/dockerfile:1

# (a) Add the Upwind Tracer image as a build stage.
FROM public.ecr.aws/upwindsecurity/images/tracer:0.1.1 AS upwind-tracer

# (b) Copy the Upwind Tracer binary from the build stage.
COPY --from=upwind-tracer /var/lib/upwind /var/lib/upwind

# (c) Set the default entrypoint to the Upwind Tracer.
ENTRYPOINT ["/var/lib/upwind/upwind-tracer"]

# (c) Set the default command to run your application.
CMD ["/path/to/your/app"]

Build and Push Image

After defining and creating your image, you need to push it to a container registry like Amazon ECR. Copy the example script from the Upwind Management Console and save it to a file named build-push.sh. Replace the placeholders with the appropriate values, either directly or by setting environment variables.

To build and push the image, run the following command:

/path/to/build-push.sh

Update the Task Definition

Update the task definition of your application by modifying the container definition to use the new image with the embedded binary.

1. Open the Amazon ECS console .
2. Select Task Definitions from the left navigation pane, then choose the task definition you want to use.
3. Select the latest revision from the list.
4. Click on the Create new revision dropdown and select Create new revision.
5. Update the Image URI in the Container details section.
6. Click on Create to save the new revision.

Apply Changes

7. Update your services to use the new task definition revision created in the previous step.

Test Connectivity

To verify the connectivity of your ECS cluster, run the following command:

aws ecs describe-services \
  --cluster [your-cluster-name] \
  --services upwind-sensor upwind-cluster-manager

Expected Output:

• Ensure ServiceStatus is ACTIVE for the upwind-cluster-manager service.
• Ensure DesiredCount and RunningCount are equal, typically set to 1, for the upwind-cluster-manager service.
• Ensure DeploymentStatuses are PRIMARY for all deployments, and DeploymentCount match.

Troubleshooting

If you encounter any issues during the installation process, please click the chat button for live connection with an expert from Upwind.