Kumori Components

In general terms, a service is specified by its interface. The term microservice refers to a service with very focused functionality. Thus, in essence, a microservice is specified also by its interface, as it is just a service.

Service/Microservice interfaces

What we refer to as a service interface is in reality the set of communication channels it exposes to the external world.

In Kumori we distinguish between two kinds of communication channels: client and server shannels. Client channels represent dependencies a service has on other services. Strictly speaking, client channels may be ignored when speciying a service from the point of view of the service’s clients themselves as the set of dependencies can be seen as an implementtion detail of the service.

However, within Kumori’s service model, client channels play an important role in the service discovery mechanism, aiding to specify the topology of services.

Server channels represent endpoints through which we can request functionality from a service. Strictly speaking, besides specifying the service channels of a service, we should also represent the protocols such an endpoint supports. However, in this version of our platform, we do not go beyond using labels to represent those protocols, without getting any deeper into compatibilities or semantics. Having said that, the tools of the model may check simple compatibility by comparing labels (not done in our current version).

Server channel specifications must also provide the port number a server program needs to bind to to accept incoming communications from its clients.

Thus, in Kumori, a service/microservice interface specification can be simply represented like so:

branch

The model also defines an additional type of channel: the duplex channel. A duplex channel brings together the features of both client and server channels, usually in conjunction with full connectors in a topology.

microservice implementation: Components

A microservice interface specification provides a good deal of information. However it is not enough to actually activate the microservice. Kumori Platform is a platform that manages service deployments, which means it needs to know enough about its implementation to set activities in motion.

In Kumori Platform a microservice is represented by a set of executions of a Kumori Component, all of them equally configured, except for the fact that each one posesses a distinct ID (its instance ID), and, potentially (but intimately related to its ID) a different persistent store (when configured to hava such a store).

In order to activate a Component and convert it into a microservice, Kumori Platform needs to be provided with the specification of the component, consisting of these parts:

  • A Configuration section, composed also of subsections

    • A Parameter subsection, listing what configuration data is available.

    • A Resource subsection, listing what resources (secrets, volumes) a component instance may make use of.

    • A Resilience subsection, mostly equal to 0.

    • A Scale subsection, when not empty, it contains a qos spec, and also an hsize spec.

  • A Channel section, specifying the microservice interface we explained earlier on.

when including a `scale: hsize: ` spec, the number of instances in any role using the component must be compatible with the spec. If, e.g., the spec is a concrete number, that MUST be the number of instances to be deployed. Any other number of instances will give rise to an error.

In addition, Components MUST provide extra information pertaining to their needs when ran

  • A code section, where the actual image implementing the component is specified. Besides the image, a code section also maps parts of the running component (microservice) configuration to content that can be placed in files and environment variables so that code running can access its configured parameters. The section also permits specifying the size each contaniner needs. In Kumori we refer to this aspect as the vertical size of a component. It is expected that his vertical size be a computed value derived from other characteristics represented in the scale subsection of the configuration (mainly, que qos field)

  • A profile section, characterizing the code in terms of features it needs of the underlying hardware (cpu threads, GPUs,…​)

  • A size section, where the amount of machine resources given to the running instance of a component are specified (bandwidth,…​).

The code of a component can access the lifecycle API of Kumori to be notified of several events on which it can act. Among them, configuration changes as well as certain membership changes are of potential interest to a Component implementation.

As of the current version, notifications of changes in configuration are carried out by changes in the underlying files (i.e., /kumori/config.json) used to deposit such information. Processes in a component can subscribe to be signaled by such changes when they occur, and can, thus, receive them without needing to be restarted.
When configuration changes affect environment variables, the only way running processes within a component can capture them is by restarting them.

A component code must be implemented as a Docker image, and the component specification must include at least a hub and tag where to retrieve it from. It is advisable to also provide the sha digest of the image.

When the image registry is private, it is necessary to also provide some credentials to access it. Credentials are a kind of resource in our platform, and should be provided on deployment. We strongly advise against providing a credentials reference hardcoded in the credentials field for the image as this would make the component spec potentially non-portable among different kumori clusters.

Components

A component is one of the basic elements of Kumori’s service model. It represents basic information needed to start the activity of an instance of a microservice. As a basic element of Kumori Platform, it is defined through its own manifest.

The manifest essentially contains each one of the aspects needed to completely define a component as seen above, except for the actual content of the code image, which is supposed to reside within some docker hub.

Formal representation of a Component in Kumori Platform

As presented in section Manifest in Kumori: the CUE language, a Component’s manifest has a common part with the manifests of any other element of our model, which we will not explore any further, and a description field, containing all the specific parts of a Component’s definition.

The general structure of a component’s manifest is as folows.

srv: {...}
config: {...}
size: {...}
code: {...}

That is, a Component specification has four sections, defined by their own structures. We are going to explain the format and purpose of each one.