# AWS ECS Discovery

## AWS ECS

### Description

Grey Matter Control discovers service instances from AWS ECS services using ECS task container dockerLabels. This collector requires AWS access credentials to utilize the AWS APIs.

### Usage

To use aws ecs discovery, set the following environment variables:

```bash
# required
GM_CONTROL_CMD=ecs
GM_CONTROL_XDS_ENABLE_REST=true
GM_CONTROL_ECS_AWS_ACCESS_KEY_ID={}
GM_CONTROL_ECS_AWS_SECRET_ACCESS_KEY={}
GM_CONTROL_ECS_AWS_REGION={}
GM_CONTROL_ECS_CLUSTERS={}
# optional
GM_CONTROL_ECS_CLUSTER_TAG={}
```

| Environment Variable                   | Description                                                                         | Type     | Default      | Required |
| -------------------------------------- | ----------------------------------------------------------------------------------- | -------- | ------------ | -------- |
| `GM_CONTROL_ECS_AWS_ACCESS_KEY_ID`     | AWS Access Key to access ECS Clusters                                               | `string` |              | `true`   |
| `GM_CONTROL_ECS_AWS_SECRET_ACCESS_KEY` | Corresponding AWS Secret Access Key                                                 | `string` |              | `true`   |
| `GM_CONTROL_ECS_AWS_REGION`            | The AWS region in which ECS clusters are running                                    | `string` |              | `true`   |
| `GM_CONTROL_ECS_CLUSTERS`              | A comma separated list of names of the ECS clusters from which to discover services | `true`   |              | `true`   |
| `GM_CONTROL_ECS_CLUSTER_TAG`           | The key value of the dockerLabel indicating which ECS service tasks to discover     | `string` | `gm-cluster` | `false`  |

### REST Support and Grey Matter Sidecars

When using AWS ECS discovery type, the global environment variable `GM_CONTROL_XDS_ENABLE_REST` **must** be set to true. This configures Grey Matter Control to use REST instead of gRPC for communication with Grey Matter sidecars, which is required in ECS.

The following environment variables are also **required to be set on all Grey Matter sidecars** running in an ECS deployment:

* `PROXY_REST_DYNAMIC=true`
* `XDS_PORT=50001`

### ECS Clusters

The particular ECS deployment may be any number of clusters and not all may need to be scraped to find services. Set `GM_CONTROL_ECS_CLUSTERS` to specify which ECS clusters to discover from. This value is required, but it can be left empty to specify for the Grey Matter Control server to search all clusters.

### ECS Task Specifications

Grey Matter Control will discover ECS service tasks from the specified clusters based on their [container definition `dockerLabels`](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/task_definition_parameters.html#container_definition_labels). Any ecs task running a service in a container to be discovered by the Control server **must** have dockerLabel of the form:

```bash
"dockerLabels": {"<ecs-cluster-tag>": "<cluster-name>:<port>" }
```

The value of `<ecs-cluster-tag>` is specified by the `GM_CONTROL_ECS_CLUSTER_TAG` environment variable. The default value is `gm-cluster`.

#### Command Line

To use the command line, run gm-control with `gm-control ecs <global-flags> --aws.access-key-id={} --aws.secret-access-key={} --aws.region={} --clusters={}`.

**Help**

For help or to list available options for ecs discovery using the cli, run `gm-control ecs --help`.