# Marathon Discovery

## DC/OS Marathon

### Description

Grey Matter Control discovers service instances from the Marathon API using application labels.

### Usage

To use marathon discovery, set the following environment variables:

```bash
# required
GM_CONTROL_CMD=marathon
GM_CONTROL_MARATHON_DCOS_TOML_FILE={}
# optional
GM_CONTROL_MARATHON_GROUP_PREFIX={}
GM_CONTROL_MARATHON_SELECTOR={}
GM_CONTROL_MARATHON_CLUSTER_LABEL={}
GM_CONTROL_MARATHON_DCOS_URL={}
GM_CONTROL_MARATHON_DCOS_ACS_TOKEN={}
GM_CONTROL_MARATHON_DCOS_INSECURE={}
GM_CONTROL_MARATHON_DCOS_REQUEST_TIMEOUT={}
```

Either `GM_CONTROL_MARATHON_DCOS_TOML_FILE` must be set **or** both `GM_CONTROL_MARATHON_DCOS_URL` and `GM_CONTROL_MARATHON_DCOS_ACS_TOKEN` must be set.

| Environment Variable                       | Description                                                               | Type      | Default      | Required                               |
| ------------------------------------------ | ------------------------------------------------------------------------- | --------- | ------------ | -------------------------------------- |
| `GM_CONTROL_MARATHON_GROUP_PREFIX`         | `group` prefix naming applications to expose                              | `string`  | (all groups) | `false`                                |
| `GM_CONTROL_MARATHON_SELECTOR`             | Label selector for filtering applications                                 | `string`  |              | `false`                                |
| `GM_CONTROL_MARATHON_CLUSTER_LABEL`        | Name of Marathon `label` specifying which cluster a Mesos task belongs to | `string`  | `gm_cluster` | `false`                                |
| `GM_CONTROL_MARATHON_DCOS_TOML_FILE`       | Path to a DC/OS CLI dcos.toml configuration file                          | `string`  |              | `true` if following two vars are unset |
| `GM_CONTROL_MARATHON_DCOS_URL`             | The public master IP of your DC/OS installation                           | `string`  |              | `false` unless dcos.toml-file unset    |
| `GM_CONTROL_MARATHON_DCOS_ACS_TOKEN`       | ACS Token for authenticating DC/OS requests                               | `string`  |              | `false` unless dcos.toml-file unset    |
| `GM_CONTROL_MARATHON_DCOS_INSECURE`        | If true, do not verify DC/OS SSL certificates                             | `boolean` | `false`      | `false`                                |
| `GM_CONTROL_MARATHON_DCOS_REQUEST_TIMEOUT` | Timeout in seconds for DC/OS requests                                     | `int`     | `5s`         | `false`                                |

#### Application Specifications

Marathon applications with the label specified in `GM_CONTROL_MARATHON_SELECTOR` will be polled for discovery by Grey Matter Control. The default value is empty, so all applications will be polled. Applications will be linked to api clusters with the label specified in `GM_CONTROL_MARATHON_CLUSTER_LABEL` and its value.

Instances are generated for tasks with host equal to the task host. Each task is examined for service ports. The first exposed TCP port is used. If no ports are exposed, the task is ignored. All application labels besides the cluster label are captured as instance metadata.

#### Command Line

To use the command line, run gm-control with

```bash
gm-control marathon <global-flags> --dcos.toml-file={}
```

**Help**

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