Skip to main content

Installation

Overview​

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

Prerequisites​

To successfully install the Upwind components on Amazon ECS, ensure the following prerequisites are met:

  1. Amazon ECS Cluster. Ensure you have an existing Amazon ECS cluster . If you need to create one, refer to the Getting started with Amazon ECS guide.

  2. Private Subnet with NAT Gateway. Ensure the Cluster Manager task has at least one private subnet configured with a NAT Gateway. This setup is essential to provide network services to the sensor components, enabling efficient and scalable monitoring of the cluster. For more information, consult the AWS documentation on configuring a VPC with private subnets and a NAT Gateway.

    info

    The Cluster Manager task does not receive a public IP address to prevent exposing services on the public internet. The NAT Gateway is necessary for secure communication with the Upwind platform via the public internet.

  3. Security Group Configuration. Ensure the security group assigned to the Cluster Manager task allows inbound traffic on port 8082 from all other tasks in the cluster.

    info

    By default, the Cluster Manager task utilizes the default security group for the VPC. For more information on specifying a custom security group, refer to the instructions below.

Install​

  1. Log in to the Upwind Management Console .

  2. Select the + (plus) symbol at the top of the screen and select Connect ECS cluster.

  3. Ensure that Fargate is selected under the ECS cluster type option.

  4. Choose the appropriate installation method for your environment from the available options.

  5. Under Sensor credentials, click Generate a new one to create a new client ID and client secret. Provide a name and click Generate. If you already have Sensor credentials, you may skip this step and select existing credentials from the list.

    warning

    The credentials can be viewed only once; if you choose to use existing credentials from the list, you must provide the client secret.

  6. Under ECS cluster, select the desired ECS cluster from the list.

    info

    If your cluster is not listed, ensure that your account is properly connected to Upwind. For more information on connecting your account, please refer to the Connect Cloud Account documentation.

  7. Follow the detailed steps corresponding to your chosen installation method:

  1. Create a new directory for your Terraform project and navigate to it in your terminal, or use an existing one if you would like to set up the Terraform module in an existing project:

    mkdir my-terraform-project && cd $_

  2. Inside your project directory, create a new file named main.tf to hold the Terraform configuration, or modify an existing main.tf if you are integrating with an existing project:

    touch main.tf

  3. Copy or download the code snippet from the Terraform setup section and paste it into main.tf.

  4. Before proceeding, ensure that your configuration settings are tailored to your environment. This includes network configurations and compatibility settings specific to your ECS cluster setup.

    Networking ConfigurationEnsure the subnets variable is set to the IDs of one or more private subnets with routes to the NAT Gateway.
    Cluster Manager ConfigurationEnsure that the security group configuration allows inbound traffic on ports 8082 and 8444. If necessary, create a security group and set the security_groups_cluster_manager variable to its ID (e.g., sg-123456789).
    Deployment MethodUpwind 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.

    Deployment Methods​

    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.3"
              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([
        {
          # 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.
        { /* ... */ }
      ])
    }

  5. Save the changes to your main.tf file.

  6. Run the following command to initialize Terraform within the project directory:

    terraform init

  7. Run the following command to apply the Terraform configuration and create the necessary resources:

    terraform apply

  8. Review the changes that Terraform plans to make and enter yes when prompted to confirm the changes. Terraform will provision the necessary infrastructure and resources in your AWS account to deploy the Upwind components, based on the provided configuration.

  9. Once the terraform apply command has successfully executed, the necessary infrastructure and resources should be provisioned within a few moments. A success message will appear in the console to indicate the successful installation of the Upwind components.

Test Connectivity​

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

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

Expected Output:

[
  {
    "ServiceName": "upwind-cluster-manager",
    "ServiceStatus": "ACTIVE",
    "DesiredCount": 1,
    "RunningCount": 1,
    "DeploymentStatuses": ["PRIMARY"],
    "DeploymentsCount": 1
  }
]
CheckDescription
ServiceStatusEnsure ServiceStatus is ACTIVE for both services.
DesiredCount and RunningCount for upwind-cluster-managerEnsure both counts are equal, typically set to 1.
DeploymentStatusesEnsure all deployments have PRIMARY status, and the DeploymentCount matches the expected number.

Troubleshooting​

If you encounter issues during deployment or operation, consult the Troubleshooting guide for solutions and best practices.