# Istio Discovery Guide

This guide provides a basic overview of how to configure Grey Matter Catalog to retrieve service information from an [Istio](https://istio.io/) mesh control plane.

## Prerequisites

1. An existing Grey Matter deployment following our [Install on Kubernetes](https://greymatter.gitbook.io/grey-matter-documentation/1.7-beta/installation/installation-kubernetes) guide.
2. An Istio deployment installed in the same Kubernetes cluster in the `istio-system` namespace, following one of the [Istio Installation Guides](https://istio.io/latest/docs/setup/install/).
3. [Istio's Bookinfo application](https://istio.io/latest/docs/examples/bookinfo/) deployed in the same Kubernetes cluster, but in a separate `istio-services` namespace. See below for more details on why a separate namespace is required and how to perform this custom installation.
4. [greymatter CLI](https://greymatter.gitbook.io/grey-matter-documentation/1.7-beta/installation/commands-cli) set up to connect to Grey Matter Catalog.

{% hint style="info" %}
**Deploying Istio's Bookinfo application**

This guide requires that Istio services be deployed in a separate Kubernetes namespace from the Grey Matter deployment. The namespace for the Bookinfo application will use Istio's [automatic sidecar injection](https://istio.io/latest/docs/setup/additional-setup/sidecar-injection/#automatic-sidecar-injection) setting. Separating Istio and Grey Matter services into different namespaces will prevent namespace collisions.

The following commands should be substituted for the ones encountered in the Bookinfo instructions:

```bash
kubectl label namespace istio-services istio-injection=enabled
kubectl apply -f samples/bookinfo/platform/kube/bookinfo.yaml -n istio-services
```

{% endhint %}

## Overview

1. Configure a connection to the Istio control plane
2. Configure service entries for tracking instances in the Istio mesh

## Steps

### 1. Configure a connection to the Istio control plane

Control plane connections are tracked in Catalog using mesh configuration objects. The following example is a simple configuration object that specifies the address to Istio's control plane service. Save the following in a `mesh.json` file:

```javascript
{
  "mesh_id": "istio-mesh-example",
  "mesh_type": "istio",
  "name": "Istio Example Mesh",
  "sessions": {
    "default": {
      "url": "istiod.istio-system.svc:15010"
    }
  }
}
```

Use the greymatter CLI to create the configuration object in Catalog:

```bash
greymatter create catalog-mesh < mesh.json
```

After creating a configuration object, Catalog responds with a summary including a status of each configured control plane connection, a map of instance counts, and mesh summary metadata. Note that the `session_statuses.default` session is marked as `"Pending"`.

```javascript
{
  "mesh_id": "istio-mesh-example",
  "configuration": {
    "mesh_id": "istio-mesh-example",
    "mesh_type": "istio",
    "name": "Istio Example Mesh",
    "sessions": {
      "default": {
        "url": "istiod.istio-system.svc:15010"
      }
    },
    "labels": {},
    "external_links": []
  },
  "session_statuses": {
    "default": "Pending"
  },
  "instance_counts": {},
  "metadata": {
    "owners": [],
    "capabilities": [],
    "service_count": 0,
    "service_stable_count": 0,
    "service_warning_count": 0,
    "service_down_count": 0,
    "instance_count": 0
  }
}
```

To retrieve an updated status on the control plane connection, run:

```bash
greymatter get catalog-mesh istio-mesh-example
```

If Catalog was able to connect to the Istio control plane, the mesh summary response should resemble the following:

```javascript
{
  "mesh_id": "istio-mesh-example",
  "configuration": {
    "mesh_id": "istio-mesh-example",
    "mesh_type": "istio",
    "name": "Istio Example Mesh",
    "sessions": {
      "default": {
        "url": "istiod.istio-system.svc:15010"
      }
    },
    "labels": {},
    "external_links": []
  },
  "session_statuses": {
    "default": "OK"
  },
  "instance_counts": {
    "details-v1:9080": 1,
    "istio-egressgateway:15443": 1,
    "istio-egressgateway:8080": 1,
    "istio-egressgateway:8443": 1,
    "istio-ingressgateway:15021": 1,
    "istio-ingressgateway:15443": 1,
    "istio-ingressgateway:31400": 1,
    "istio-ingressgateway:8080": 1,
    "istio-ingressgateway:8443": 1,
    "productpage-v1:9080": 1,
    "ratings-v1:9080": 1,
    "reviews-v1:9080": 1,
    "reviews-v2:9080": 1,
    "reviews-v3:9080": 1
  },
  "metadata": {
    "owners": [],
    "capabilities": [],
    "service_count": 0,
    "service_stable_count": 0,
    "service_warning_count": 0,
    "service_down_count": 0,
    "instance_count": 0
  }
}
```

The `instance_counts` field should be populated by `host:port` pairs each with their own instance count, indicating that Catalog was able to discover a number of instances (i.e. [Kubernetes pods](https://kubernetes.io/docs/concepts/workloads/pods/)) for the service.

Each `host:port` pair refers to an individual [Kubernetes deployment](https://kubernetes.io/docs/concepts/workloads/controllers/deployment/). If you want to organize this collection by [Kubernetes service](https://kubernetes.io/docs/concepts/services-networking/service/) instead, run the following command to edit the `istio-mesh-example` configuration (ensure your `$EDITOR` environment variable is set):

```bash
greymatter edit catalog-mesh istio-mesh-example
```

Edit the configuration so that `labels` has the following:

```javascript
{
  ...
  "labels": {
    "group_by_k8s_service": "true" // note this is a string label
  }
}
```

The greymatter CLI should respond with another `"Pending"` status for the `default` session. To retrieve the updated state of the mesh object from Catalog, run:

```bash
greymatter get catalog-mesh istio-mesh-example
```

You should see the following under `instance_counts`. Note that the `reviews:9080` Kubernetes service has 3 instances, whereas the previous setting showed 3 distinct Kubernetes deployments (i.e. `reviews-v1:9080`, `reviews-v2:9080`, and `reviews-v3:9080`).

```javascript
{
  ...
  "instance_counts": {
    "details:9080": 1,
    "istio-egressgateway:15443": 1,
    "istio-egressgateway:8080": 1,
    "istio-egressgateway:8443": 1,
    "istio-ingressgateway:15021": 1,
    "istio-ingressgateway:15443": 1,
    "istio-ingressgateway:31400": 1,
    "istio-ingressgateway:8080": 1,
    "istio-ingressgateway:8443": 1,
    "productpage:9080": 1,
    "ratings:9080": 1,
    "reviews:9080": 3
  },
  ...
}
```

### 2. Configure service entries for tracking instances in the Istio mesh

Services are tracked in Catalog using service configuration objects that reference mesh configuration objects. The following example is a simple service object that references `istio-mesh-example`. Save the following in a `reviews.json` file:

```javascript
{
  "mesh_id": "istio-mesh-example",
  "service_id": "reviews:9080",
  "name": "Reviews",
  "minInstances": 1,
  "maxInstances": 3
}
```

Use the greymatter CLI to create the service configuration object in Catalog:

```bash
greymatter create catalog-service < reviews.json
```

After creating a service configuration object, Catalog responds with a summary that includes the configuration, additional discovered data, and individual service instances. Note that each instance contains a `metadata` object that includes a `k8s_namespace`, `k8s_deployment`, and `k8s_service` for identifying which resource is being referenced in your Kubernetes cluster.

```javascript
{
  "service_id": "reviews:9080",
  "mesh_id": "istio-mesh-example",
  "name": "Reviews",
  "version": "",
  "description": "",
  "owner": "",
  "owner_url": "",
  "api_endpoint": "",
  "api_spec_endpoint": "",
  "capability": "",
  "runtime": "GO",
  "documentation": "",
  "prometheus_job": "reviews:9080",
  "min_instances": 1,
  "max_instances": 3,
  "enable_instance_metrics": false,
  "enable_historical_metrics": false,
  "business_impact": "low",
  "external_links": [],
  "mesh_type": "istio",
  "localities": [],
  "instances": [
    {
      "instance_id": "5c4cf820faaff06eaa19243c4b322362",
      "session": "default",
      "locality": "",
      "metadata": {
        "health_status": 0,
        "health_status_desc": "UNKNOWN",
        "istio_cluster": "outbound|9080||reviews.istio-services.svc.cluster.local",
        "k8s_deployment": "reviews-v2",
        "k8s_namespace": "istio-services",
        "k8s_service": "reviews"
      }
    },
    {
      "instance_id": "a7fb0d4aa029abe189f93cf6b6d03ee3",
      "session": "default",
      "locality": "",
      "metadata": {
        "health_status": 0,
        "health_status_desc": "UNKNOWN",
        "istio_cluster": "outbound|9080||reviews.istio-services.svc.cluster.local",
        "k8s_deployment": "reviews-v1",
        "k8s_namespace": "istio-services",
        "k8s_service": "reviews"
      }
    },
    {
      "instance_id": "c0e09925989960827fca906707977f9a",
      "session": "default",
      "locality": "",
      "metadata": {
        "health_status": 0,
        "health_status_desc": "UNKNOWN",
        "istio_cluster": "outbound|9080||reviews.istio-services.svc.cluster.local",
        "k8s_deployment": "reviews-v3",
        "k8s_namespace": "istio-services",
        "k8s_service": "reviews"
      }
    }
  ],
  "metadata": {},
  "status": "stable"
}
```

To retrieve the service summary object again, run the following:

```bash
greymatter get catalog-service reviews:9080 --catalog.mesh=istio-mesh-example
```

## Questions

{% hint style="success" %}
**Need help with your installation?**

Create an account at [Grey Matter Support](https://support.greymatter.io/support/home) to reach our team.
{% endhint %}