ecs

Grey Matter Fabric supports service discovery from AWS ECS deployments. See the Grey Matter Control AWS ECS discovery setup documentation for how to configure this with Grey Matter Control.

AWS ECS Deployment

See the AWS ECS documentation for information on why and how to use ECS. Grey Matter Control can discover tasks from ECS deployments using launch type EC2.

Note: Grey Matter is not compatible with ECS Fargate.

ECS deployments configure services through ECS task definitions. The Grey Matter control plane will discover running tasks with a specific dockerLabel and determine the instance information based on the task Network Mode

ECS Services and Tasks

ECS Services are configured by ECS task definitions.

The Grey Matter Control plane will poll the specified clusters for running ECS containers with a specific dockerLabel. These containers are defined as a part of the ECS task definition. See the Grey Matter Control setup ECS task specifications for the format of this dockerLabel.

An example ECS Task set up for discovery by Grey Matter Control (using its default configuration) is here.

ECS Task Network Modes

The Control server determines the instances of each ECS task container based on its Network Mode. The network mode of any task container to be discovered by Grey Matter Control must be one of bridge (default), host, or awsvpc.

For tasks with Network Mode bridge, instance hosts are determined using the EC2 Instance IP of the EC2 on which the task is running, and ports are determined by the hostPort of the ECS task Network Bindings.

For tasks with Network Mode host, instance hosts are determined using the EC2 Instance IP of the EC2 on which the task is running, and ports are determined by the port specified for the container in the docker label.

For tasks with Network Mode awsvpc, instance hosts are determined using the Network Interfaces private IPv4 addresses, and ports are determined by the container port specified in the container definition port mappings.

Example Task

The ECS Task definition below is properly setup to be discovered by the gm-control server.

{
  "family": "gm-example-task",
  "executionRoleArn": "{YOUR-EXECUTION-ROLE}",
  "containerDefinitions": [
    {
      "name": "service",
      "image": "docker.greymatter.io/internal/example-service:latest",
      "cpu": 128,
      "memoryReservation": 128,
      "portMappings": [
        {
          "containerPort": 3000,
          "hostPort": 3000,
          "protocol": "tcp"
        }
      ],
      "repositoryCredentials": {
        "credentialsParameter": "{YOUR-CREDENTIALS-SECRET-ARN}"
      },
      "essential": true
    },
    {
      "name": "proxy",
      "image": "docker.greymatter.io/release/gm-proxy:1.2.1",
      "cpu": 128,
      "dockerLabels": {
        "gm-cluster": "example-service:8080"
    },
      "memoryReservation": 128,
      "portMappings": [
        {
          "containerPort": 8080,
          "hostPort": 8080,
          "protocol": "tcp"
        }
      ],
      "repositoryCredentials": {
        "credentialsParameter": "{YOUR-CREDENTIALS-SECRET-ARN}"
      },
      "essential": true,
      "environment": [
        {
            "name": "PROXY_REST_DYNAMIC",
            "value": "true"
        },
        {
            "name": "XDS_PORT",
            "value": "50001"
        },
      ]
    }
  ]
}

The ECS service definition below is set up to run with the above task definition to be discovered by gm-control.

{
    "cluster": "final-cluster",
    "serviceName": "example-service",
    "taskDefinition": "gm-example-task",
    "loadBalancers": [
        {
            "targetGroupArn": "{YOUR-TARGET-GROUP-ARN}",
            "containerName": "proxy",
            "containerPort": 8080
        }
    ],
    "desiredCount": 1,
    "role": "ecsServiceRole"
}