Use Grey Matter Catalog

Learn how to use Grey Matter Catalog.

Grey Matter Catalog is one of Grey Matter's core microservices. It provides additional metadata about services to the Grey Matter dashboard. Catalog can be leveraged as an API to develop further visualizations of a service mesh.

Catalog works as follows:

  1. It connects to Grey Matter Control to retrieve discovered services.

  2. It combines discovered services with user driven configuration.

  3. It creates summarized metadata about services running within a service mesh.

This guide will help you update service entries in the Grey Matter Catalog so you can track service instances in your network.

Prerequisites

  • Unix environment

  • Decipher account

  • Running instance of the Grey Matter Catalog server

Note: in this tutorial, we will refer to the server host as catalog-api and its default port 8080.

Step 1: Review service entry fields

You can add service entries to Grey Matter Catalog to let you track the status of service instances in your network. Each entry you add should include the following fields.

Entry

Description

clusterName

The unique cluster name assigned to the service within a mesh.

zoneName

The zone to which the service belongs (this generally will be default-zone).

name

A display name for the catalog entry.

version

The version of the deployed service.

owner

A tag specifying an organization, company, department, etc. to whom the service belongs.

capability

A tag specifying the service's capability.

documentation

A URL specifying the service's documentation page.

minInstances

The minimum number of running instances of the service you can expect.

maxInstances

The maximum number of running instances of the service you can expect.

enableInstanceMetrics

Whether to permit access to metrics for the service's instances.

metricsPort

The port configured for the service's sidecar to expose its metrics.

enableHistoricalMetrics

Whether to permit access to historical metrics for the service.

prometheusJob

The name assigned to the service's corresponding Prometheus job for tracking its historical metrics.

Step 2: Add a zone for storing entries in the service catalog

Since each entry must be added to an existing zone configuration object (i.e. mesh) in the service catalog, your first step is to ensure a zone exists in the catalog. Run the following command in your terminal to check if a zone has already been pre-configured in your deployment:

curl http://catalog-api:8080/zones

If the JSON array in the printed response contains an object like the one below, make note of the zoneName value and continue on to Step 2. Otherwise, if it is empty, you'll need to manually configure a zone.

Zones are represented in the service catalog in this JSON format:

default-zone.json
default-zone.json
{
"serverAddress": "gm-control:50000",
"zoneName": "default-zone",
"requestCluster": "edge"
}

Copy the JSON object above into a new file with the name default-zone.json .

Note: _**_If you haven't deployed a Grey Matter Control service yet, you can leave the serverAddressas is. Otherwise, use the address to your deployed Control service.

Run the following command in your terminal in the same directory as the file:

curl -X POST http://catalog-api:8080/zones \
-d @default-zone.json \
--header "Content-Type: application/json"

If the request was successful, the following response should print out in your terminal:

{"added": "default-zone"}

Step 3: Add a new entry to the service catalog

Now that you've created the zone, you will make an HTTP request to add the following JSON-encoded entry to the service catalog:

example.json
example.json
{
"clusterName": "example",
"zoneName": "default-zone",
"name": "Example Service",
"version": "1.0",
"owner": "Decipher",
"capability": "Example",
"documentation": "/services/example/1.0/",
"maxInstances": 1,
"minInstances": 1,
"enableInstanceMetrics": true,
"metricsPort": 8081,
"enableHistoricalMetrics": true,
"prometheusJob": "example"
}

Copy the JSON object above into a new file with the name example.json . Ensure the zoneName value matches the name of the zone configured in Step 1.

Run the following command in your terminal in the same directory as the file:

curl -X POST http://catalog-api:8080/clusters \
-d @example.json \
--header "Content-Type: application/json"

If the request was successful, the following response should print out in your terminal:

{"added": "example"}

Step 4: View an existing entry in the service catalog

Now that you've added an entry to the service catalog, it should show up in the list of entries returned in the response from the following HTTP request:

curl http://catalog-api:8080/clusters/example

The response should be a JSON array that includes the entry.

Notice that there is an additional instances field in the entry with an array. If a service with the clusterName of "example" exists within your mesh and it currently has running instances, Catalog should've populated the instances array with a number of objects representing each running instance! Otherwise, the instancesarray returned with the entry should be empty.

Here is a sample response of the entry with a populatedinstances array:

[
{
"clusterName": "example",
"zoneName": "default-zone",
"name": "Example Service",
"version": "1.0",
"owner": "Decipher",
"capability": "Example",
"documentation": "/services/example/1.0/",
"maxInstances": 1,
"minInstances": 1,
"enableInstanceMetrics": true,
"metricsPort": 8081,
"enableHistoricalMetrics": true,
"prometheusJob": "example"
"instances": [
{
"name": "cee8014703400366094f6f2be882579d",
"startTime": 1548167565788
}
]
}
]

Step 5: Modify an existing entry in the service catalog

It would be rare in any deployment scenario to not have to make updates to an existing catalog entry. For example, you may need to enable or disable the ability to view metrics for a given service, or you may need to increase or decrease the maximum number of instances to expect for a given service.

Let's say you already have one running instance of your example service and you decide to scale up the service to three instances in your deployed environment. Since your example catalog entry has its maxInstances value set to 1, the Grey Matter Dashboard would display a warning for the example service since it has too many instances!

Go back to your example.json file from Step 1 and update the maxInstances field to 3. Then run the following command from your terminal to modify the example service in the catalog:

curl -X PUT http://catalog-api:8080/clusters/example \
-d @example.json \
--header "Content-Type: application/json"

If the request was successful, the following response should print out in your terminal:

{"replaced": "example"}

Step 6: Delete an existing entry from the service catalog

Now that you've learned how to add, view, and modify an entry in the service catalog, the last step in this tutorial is to delete the entry. Deleting the entry requires specifying both the clusterName as well as the zoneName of the entry in the HTTP request. Remember: The zoneName used must match the name of the zone configured in Step 1.

Run the following command from your terminal in order to remove the example service entry:

curl -X DELETE http://catalog-api:8080/clusters/example?zoneName=default-zone

If the request was successful, the following response should print out in your terminal:

{"deleted": "example"}

References

In this tutorial, we've shown you how to do basic operations defined in the Grey Matter Catalog API to manage entries in your service mesh. To learn more advanced operations such as viewing metrics for a given service instance or retrieving a summary of all known service entries, please refer to the API documentation available at the root of your deployed Catalog server.

Questions?

Need Help?

Create an account at Decipher Support to reach our team.