Skip to main content

Installation

Overview​

This topic provides instructions for installing the Upwind components in an ECS cluster using the Amazon EC2 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 ports 8082 and 8444 from the EC2 instances within 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.

  4. Linux Kernel Version for EC2 Instances. Ensure your cluster's EC2 instances are operating on a Linux kernel version 4 (such as Amazon Linux 2), and configure the sensor image to use the BCC flavor. For more information on Linux kernel compatibility, refer to the instructions below.

  5. Instance Metadata Service (IMDS) Configuration. Ensure the hop limit for the IMDS service is set to 2. For more information, consult the AWS documentation on configuring instance metadata options.

  6. Docker Version Requirements. Ensure the Docker version is v20.10.13 or newer to guarantee reliable metrics collection. This version is included in the Amazon ECS-optimized AMI 20220607 and newer.

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 EC2 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, which can be used to launch ENIs for the Cluster Manager service tasks.
    Cluster Manager ConfigurationEnsure that the security group configuration allows inbound traffic on ports 8082 and 8444. If the default security group for the VPC does not permit this traffic from one of the security groups applied to the instances in the cluster, create a security group that does. Set the security_groups_cluster_manager variable to the ID of this security group (e.g., sg-123456789).
    Linux Kernel CompatibilityEnsure that if the cluster EC2 instances are running on Linux kernel version 4 (for example, Amazon Linux 2), the image_sensor variable is set to:
    image_sensor = {
      registry   = "registry.upwind.io"
      repository = "images/agent"
      tag        = "0.96.0-bcc"
    }

  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-sensor upwind-cluster-manager \
  --query "services[*].{ \
      ServiceName:serviceName, \
      ServiceStatus:status, \
      DesiredCount:desiredCount, \
      RunningCount:runningCount, \
      DeploymentStatuses:deployments[*].status, \
      DeploymentsCount:length(deployments) \
  }" \
  --output json

Expected output:

[
  {
    "ServiceName": "upwind-sensor",
    "ServiceStatus": "ACTIVE",
    "DesiredCount": 1,
    "RunningCount": 1,
    "DeploymentStatuses": ["PRIMARY"],
    "DeploymentsCount": 1
  },
  {
    "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-sensorEnsure both counts are equal to the instance count, as it uses a daemon strategy.
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.