Istio Discovery Guide

This guide provides a basic overview of how to configure Grey Matter Catalog to retrieve service information from an Istio mesh control plane.

Prerequisites

1. An existing Grey Matter deployment following our Install on Kubernetes guide.

2. An Istio deployment installed in the same Kubernetes cluster in the istio-system namespace, following one of the Istio Installation Guides.

3. Istio's Bookinfo application 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 set up to connect to Grey Matter Catalog.

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 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:

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

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:

{
  "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:

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".

{
  "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:

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:

{
  "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) for the service.

Each host:port pair refers to an individual Kubernetes deployment. If you want to organize this collection by Kubernetes service instead, run the following command to edit the istio-mesh-example configuration (ensure your $EDITOR environment variable is set):

greymatter edit catalog-mesh istio-mesh-example

Edit the configuration so that labels has the following:

{
  ...
  "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:

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).

{
  ...
  "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:

{
  "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:

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.

{
  "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:

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

Questions

Need help with your installation?

Create an account at Grey Matter Support to reach our team.