# instance discovery

## Automatic

{% hint style="success" %}
One key benefit to a service mesh is the dynamic handling of ephemeral service nodes. These nodes have neither consistent IP addresses nor consistent numbers of instances as services are spun up and down. The `gm-control-api` server, in conjunction with Grey Matter Control, can handle these ephemeral services automatically.‌
{% endhint %}

The ability to automatically populate instances of a particular microservice comes from the `cluster` object. In particular, the `name` field in the `cluster` object determines which nodes will be pulled out of the mesh and populated in the `instances` array. In the example below, the name is `catalog`. This means that all services that announce as catalog in service discovery, will be found and populated into the instances array after creation.‌

Create the following object:

```javascript
{
  "zone_key": "default-zone",
  "cluster_key": "catalog-proxy",
  "name": "catalog",
  "instances": [],
  "circuit_breakers": {
    "max_connections": 500,
    "max_requests": 500
  },
  "outlier_detection": null,
  "health_checks": []
}
```

It will be populated in the mesh as:

```javascript
{
    "cluster_key": "catalog-proxy",
    "zone_key": "default-zone",
    "name": "catalog",
    "secret": {
        "secret_key": "",
        "secret_name": "",
        "secret_validation_name": "",
        "subject_names": null,
        "ecdh_curves": null,
        "set_current_client_cert_details": { "uri": false },
        "checksum": ""
    },
    "instances": [
        {
            "host": "10.128.2.183",
            "port": 9080,
            "metadata": [
                {
                    "key": "pod-template-hash",
                    "value": "2000163809"
                },
                {
                    "key": "gm_k8s_host_ip",
                    "value": "10.0.2.132"
                },
                {
                    "key": "gm_k8s_node_name",
                    "value": "ip-10-0-2-132.ec2.internal"
                }
            ]
        },
        {
            "host": "10.128.2.140",
            "port": 9080,
            "metadata": [
                {
                    "key": "pod-template-hash",
                    "value": "475497808"
                },
                {
                    "key": "gm_k8s_host_ip",
                    "value": "10.0.2.82"
                },
                {
                    "key": "gm_k8s_node_name",
                    "value": "ip-10-0-2-82.ec2.internal"
                }
            ]
        }
    ],
    "circuit_breakers": {
        "max_connections": 500,
        "max_pending_requests": null,
        "max_retries": null,
        "max_requests": 500
        },
    "outlier_detection": null,
    "health_checks": [],
    "checksum": "2b6d2a8a6886eb30574f16480b0f99b90e11484d9ddb10fb7970c3ce37d945ab"}
```

‌ Even though the object was created with no `instances`, they were discovered from the mesh and populated. Now any service that needs to talk to `catalog`, can link to this `cluster` and address all live instances.‌