Skip to main content

Directory

The Directory is an implementation of the directory gRPC service. It is the service to find other services. Typically, every other Cogment service only needs to know the address of the Directory to access anything in Cogment.

A regular health check is done on non-permanent network services to make sure they remain available (i.e. network reachable). If a service fails the health check, it is automatically removed from the Directory. Non-permanent services have a limited lifetime in the directory; after a week, they will be removed.

The Directory works in tandem with the Cogment endpoints, in particular the ones with a discover host (refered as dicovery endpoints).

A Directory Client is also part of the Cogment CLI to access the Directory from the command line.

Command line

The Directory is a Cogment CLI service:

$ cogment services directory --port=9005

Options

port

The TCP port where to serve the directory gRPC service. This is where the users of the Directory connect to.

Can be specified as:

  • a command line option, e.g. --port,
  • an environment variable, e.g. COGMENT_DIRECTORY_PORT,
  • its default value is 9005.

grpc_reflection

Whether or not to enable gRPC reflection on the served directory endpoint.

Can be specified as:

  • a command line option, e.g. --grpc_reflection,
  • an environment variable, e.g. COGMENT_DIRECTORY_GRPC_REFLECTION=1,
  • by default, it is disabled.

Operation

At its most basic, the Directory contains services searchable by type and property, and returns endpoints where to reach the matched services.

Every registered service has a unique ID (it is unique among currently registered services). When registering a service, the ID of the new service is provided with a "secret" key (a string). This "secret" (in combination with the ID) is required to deregister the service. If a new service matches an existing one (i.e. an inquiry would match them), it is considered a duplicate. Duplicates are acceptable for non-permanent services. For permanent services (both the old and new services must be permanent), duplicates are not allowed; instead, an update of the old service is performed (i.e. the ID and secret are kept the same).

Every service is also associated with an authentication token. This token is provided by users when registering a new service, and it must be provided to inquire or deregister that service. For example, any inquiry can only find services that have the same authentication token as the one provided to the inquiry. Similarly for deregistering: a service cannot be deregistered without the appropriate authentication token. In closed environments, the authentication token can be left empty to facilitate directory management.

When inquiring services, the services returned are in increasing order of age (since registration). So the first is always the most recently registered service. Permanent services do not change their registration timestamp when updated.

Data

The Directory maintains the following data for each service:

  • service ID: This is a numerical (unsigned integer of 64 bits) value generated by the Directory and assigned to the service on registration. It is unique to that service as long as it is in the Directory. Although very unlikely, it is possible for this ID to be re-used after the service is deregistered.
  • endpoint: It consists of four distinct information:
    • protocol: The protocol (URL scheme) for the endpoint (grpc or cogment). The cogment protocol is not considered a "network" protocol and thus will not be checked for health (network connectivity).
    • host: The host for the endpoint (e.g. somewhere.com). For the grpc protocol this represents a TCP/IP network resource; it can be a network hostname or an IP address. For the cogment protocol it must be a registered name (see cogment endpoints) and typically does not represent a network resource.
    • port: The TCP port where the registered service is providing its services. This is required for grpc protocol hosts.
    • ssl requirement: Whether the service requires an encrypted SSL connection.
  • type: The type of service. This also determines how health checks are performed on the service.
    • client actor connection: Provides client actor grpc API service
    • trial lifecycle management: Provides lifecycle grpc API service
    • actor: Provides actor grpc API service
    • environment: Provides environment grpc API service
    • pre-hook: Provides pre-hook grpc API service
    • datalog: Provides datalog grpc API service
    • datastore: Provides datastore grpc API service
    • model registry: Provides model registry grpc API service
    • other: This type of service does not provide a grpc API service or it is not a globally defined type of service. Only a tcp connection will be tested for health checking.
  • permanent: This determines if the service should be kept in the directory regardless of health (network connectivity) or lifetime limits (a week). It also prevents duplication of the service in the directory (i.e. if a duplicate is registered, the service will just be updated with the new information, and keep the same ID and secret).
  • properties: This is a free form mapping of name and value strings. But Cogment may require properties of specific names for its operation, in particular for endpoint discovery). These special property names are prefixed with a double underscore (__), e.g. __implementation. Also, for proper use in Cogment, property names and values should be restricted to a limited character set (see ).
  • secret: This is a secret string that is generated by the Directory on registering a new service. It must be provided to deregister a service. There is no way to recover this value, so it must be recorded after registration.
  • authentication token: A string to authenticate users of the registered service. It is provided by the user for registration of a new service, and the same token must be provided to access (deregister or inquire) that service.