User guide

Core concepts

Tonomi Platform is a model-driven platform. As such, it comes with a way to define entities and relationships in a way that is independent from underlying implementation. This section will explain core elements of the model.

Throughout this guide, you will encounter sidebars labeled “Ops corner” and “Dev corner”, which provide additional points of reference by drawing analogies from operations and development, respectively. Information in these sidebars is completely optional and can be safely skipped.

Components and instances

The cornerstone of the domain model is the notion of a configuration component, or simply a component. A component is a logical unit of configuration.

Some components can be fully autonomic and self-managed. For instance, high-level concepts such as “service” or an “application” can be represented by components.

Other components have external dependencies and cannot be used their own. Such components are meant to be run together with others as part of larger deployment.

It is not uncommon for a Tonomi Platform implementation to model the whole system as a single component and then refactor it out into multiple connected components over time.

There are two types of components in Tonomi Platform — built-in and custom. Built-in components are generally used by the component developers to create custom ones and therefore out of scope for this guide.

See also

For details on how to use built-in components, see Manifest developer’s guide.

Custom components are the one specific to the organization. They are registered by the component developers in the component catalog and accessible through the portal.

Component catalog can contain multiple revisions of the same component, which can be thought of as different versions or flavors of the same configuration component. They can be provided for convenience or to limit the range of permitted configurations.

See also

For more information on revisions, see Revisions.

Multiple copies of the same component or a component revision can be running at the same time. A copy of a running component is called a component instance or simply an instance. Different instances may have different configuration, runtime state, dependencies, resources etc.

The portal provides dashboards to see all instances and their properties, either for a given component, or across multiple components. Additionally, it keeps an log of events associated with every instance throughout its lifecycle.

The portal provides an ability to request a new instance of a given component. Most components provide a way of configuring themselves, and some would not launch without some input from the user. In this case, the portal will render a form so that the user can provide the necessary configuration.

See also

For more information on launching instances, see Advanced launch.

There’s also an ability to reconfigure a particular running instance providing it with another configuration parameters or even with another manifest version. The Reconfigure dialog is similar to Advanced launch except the former can be called for already running instances only. When reconfiguring to another manifest version the user is responsible for keeping the new and old manifest versions in consistency. The reconfiguration is available for both 1.x and 2.0 manifest types although it isn’t possible to switch among them for running instances.

Each instance has a status, as reported by the Control Fabric.

The portal has accepted a request to create the instance and waiting for the controller to acknowledge the new control plan. If instances are spending exceedingly long times in Requested state, it may signify controller or network connectivity problems.
This is a new instance and Control Fabric is orchestrating the services to build out its environment. Depending on the component, this can take from seconds for simple components to hours for complex systems that require multiple downstream dependencies. In this state, instance usually reports intermediate status in the Activity Log.
The instance is running and reporting no errors.

The instance is busy executing a task. This is usually a result of one of the three things events:

  • Instance is reacting to an event which requires its immediate undivided attention.
  • Instance is reacting to a change in control plan initiated by the operator.
  • Instance is executing an ad-hoc command from an operator.

With few exceptions, an instance in this state is busy and cannot respond to requests immediately. In this state, instance usually reports the reason for being busy and intermediate status in the Activity Log.

The instance is experiencing an exceptional situation which requires attention from the operator. This is often due to an error downstream or a component implementation issue. Instance usually reports technical details of the error in the Activity Log.

Interfaces and dependencies

Most of the time, a system under management is best described by multiple components that depend on each other in a certain way. In Tonomi Platform, a component developer does not need to describe every component that it needs to launch a new instance — instead, they can declare a dependency and rely on the platform to satisfy the dependency based on the environment policies.

In order to achieve the separation between the capability and its implementation, Tonomi Platform introduces the notion of the interface. Interface is a special-form contract that is required by the consumer component or provided by the service component. Interfaces are used to exchange information between different components, and only through interfaces such exchange is possible.

Interfaces may contain the following items:

  • Data, used by the downstream component to communicate important information to upstream components;
  • Commands, which provide synchronous procedural calls and are used to simplify execution of ad-hoc operating tasks and orchestration workflows.

A common use case for the interfaces is to separate the data that belongs to different runtime sources (e.g. load balancer configuration vs. application servers configuration in a component that represents an elastic pool of application servers). However, interfaces are also useful as namespaces, for instance, to separate user-level configuration from administrator level configuration.

Whenever an instance is launched or reconfigured, the portal will try to satisfy its downstream interfaces. (An interface is considered downstream if it used to receive data or executes commands on other components). If the portal cannot find matching services, it may try to provision a new instance of the requested service. If that’s not an option, it will display an error and cancel the operation. How exactly the dependencies are satisfied is controlled by the environment policies.

In runtime, a satisfied dependency is represented by a binding. Components whose interfaces are bound to each other can exchange information on these interfaces and in the direction specified in the interface definitions.

Consider an example. A component, representing an application pool, requires a database connection string as part of its downstream database configuration interface, is being requested by the user.

The portal might do one of the following things:
  • Use an environment property which contains the connection string to satisfy the dependency;
  • Bind the interface of the application pool to a database component which provides the connection string as part of its upstream interface;
  • Launch a new database and bind its yet-to-become-active upstream interface to the application pool.

In either case, if the value of connection string is changed at any point in time, the application pool component will receive an event and can adapt to the new value.

Assembling components together

There are two ways to create a brand new component. One is to create a plug-in to Tonomi Platform, which and looks and feels like a built-in. Because of the close ties of such components with the controller and potential impact on fabric operation, this option is currently reserved to Tonomi, Inc. personnel and a trusted network of partners. Another option is to use particular components that specialize in assembly: composites and workflows.

Composite components take a set of other components, either built-in or custom and arrange them together so they look and feel as a single component. Creating a three-tier application out of separate components responsible for each individual tier can be used as an example. A composite can specify precisely how the information should flow between the constituent components, as well as provide some simple data transformations.

Workflow components are frequently used together with composites in order to provide coordination for complex orchestration. For instance, a three-tier application can require setting maintenance mode on application servers, stopping the database server, updating the schema and then redeploying the application in parallel on multiple servers. Without a workflow in place to keep track of the stages, coordination of steps can become tricky.

Most of the components that you see in the component catalog are composites.


At this time, components must be wrapped in composites to be placed in the component catalog. Also, composites and workflows cannot be created through the web UI. For information on how to create your custom components using application manifests, see Manifest developer’s guide.

Environments and policies

Throughout this guide, we’ve repeatedly mentioned environment policies as a way to control how what components can and cannot do. It is time to dig into details.

This section will be most useful to those who want to create and manage their own environments.

The term “environment” can be misleading at times, since it used to signify two different, but related concepts. Most of the time “environment” means runtime environment, the actual set of resources, services and data available to the component instance — for example, servers, API endpoints and database connections for a web application. However, Tonomi Platform advances this notion further to cover setups with thousands of dynamically created environments, whether for the purposes of tenant separation, deployment staging, or self-service labs.

Within the context of Tonomi Platform, “environment” always means this design-time environment, unless explicitly specified otherwise. Such environments are defined in Tonomi Platform as a set of policies: rules that apply to every instance that is launched in the environment.

At this point in time, Tonomi Platform does not allow specifying arbitrary policies, instead providing a set of pre-built policies that address common use cases. New policies are being implemented as plug-ins that make their way into the core platform as the product evolves.

For the sake of example, policies that can be specified in the environment include:

  • Exposing a service endpoint to the instances running in given environment;
  • Providing environment variables and markers to the instances running in given environment;
  • Substituting a component within a composite with a binding to a shared service;
  • Substituting cloud servers with static ones and vice verse;
  • Specifying the hardware setup and images used by the cloud servers;
  • Specifying the SSH keys that are used to access the servers;
  • Overriding the commands invoked by the workflow components.

Additionally, Tonomi Platform allows setting up portal-wide access policies, which can be used to prohibit changing the environment settings.