# File Discovery

## File

### Description

Grey Matter Control discovers service instances from a JSON or YAML file on disk. It will update clusters stored in the Greymatter API at startup and whenever the file changes.

### Usage

To use file type discovery, set the following environment variables:

```bash
GM_CONTROL_CMD=file
GM_CONTROL_FILE_FILENAME={}
GM_CONTROL_FILE_FORMAT={}
```

| Environment Variable       | Description                                    | Type     | Default | Required |
| -------------------------- | ---------------------------------------------- | -------- | ------- | -------- |
| `GM_CONTROL_FILE_FILENAME` | Filename of mounted file to discover instances | `string` |         | `true`   |
| `GM_CONTROL_FILE_FORMAT`   | File type, one of `json` or `yaml`             | `string` | `json`  | `false`  |

### File Specifications

The file should be of the form (yaml):

```yaml
- cluster: cluster-name
  instances:
    - host: hostname
      port: port
      metadata:
        - key: optional
          value: metadata
- cluster: cluster-name
  instances:
    - host: hostname
      port: port
...
```

or, as json:

```javascript
[
  {
    "cluster": "cluster-name",
    "instances": [
      {
        "host": "hostname",
        "port": <port>,
        "metadata": [
          { "key": "optional", "value": "metadata" }
        ]
      }
    ]
  }
]
```

> Note: when updating the file, care should be taken to make the modification atomic. In practice, this means writing the updated file to a temporary location and then moving/renaming the file to the watched path. Alternatively, the watched path may be a symbolic link that is replaced with a reference to the updated file.

#### Command Line

To use the command line, run gm-control with `gm-control file <global-flags> --filename={} --format={}`.

**Help**

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