Contributing to Models

Understanding the internals of Meshery’s logical object model

Meshery’s internal object model is designed to provide a consistent and extensible way of capturing and characterizing the resources under Meshery’s management and the capabilities Meshery has at its disposal. Meshery Models serve as the unit of packaging for the object models that define a registered capability or a type of managed infrastructure and their relationships, and details specifics of how to manage them.Models often represent infrastructure and application technologies, however, they are also capable of defining other types of entities like annotations, like shapes (infrastructure ambiguous components). Models are used to define the capabilities of Meshery. See Models to learn more about models as a logical concept.

Each model includes a set of entities (in the form of definitions) that Meshery can manage. Models are defined and versioned using on the Model Schema. The schema defines the structure of the model, including the entities it contains, their relationships, and the properties they have. The schema also defines the version of the model and the version of the schema itself. See Registry to learn more about Meshery’s internal registry and how to use it.

Figure: Model Entity Classification

Meshery Entities and their Lifecycle

This section aids in your understanding of the vernacular of Meshery’s internal object model and discusses the difference beteween schemas, definitions, declarations, and instances. The lifecycle of Meshery entities (components, relationships, policies) is represented by the following terms, which are used to describe the various stages of their lifecycle.

Schema

Schema (static) : the skeletal structure representing a logical view of the size, shape, characteristics of a construct.

The schema represents the skeletal structure of an entity and provides a logical view of its size, shape, and characteristics. It defines the expected properties and attributes of the entity. The schema serves as a blueprint or template for creating instances of the entity. It is a static representation that defines the structure and properties but does not contain specific configuration values.

Schema example

#Component schema excerpt

{
"$id": "https://schemas.meshery.io/component.json",
  "$schema": "<http://json-schema.org/draft-07/schema#>",
"description": "Components are the atomic units for designing infrastructure. Learn more at <https://docs.meshery.io/concepts/components>",
"required": [
"apiVersion",
"kind",
"schema",
"model"
],
"additionalProperties": false,
"type": "object",
"properties": {
"apiVersion": {
"type": "string",
"description": "API Version of the component."
},
"kind": {
"type": "string",
"description": "Kind of the component."
.
.
.

See github.com/meshery/schemas for more details.

Definition

Definition (static) : An implementation of the Schema containing an outline of the specific attributes of a given, unconfigured entity.

A definition is an implementation of the schema. It contains specific configurations and values for the entity at hand. The definition provides the actual configuration details for a specific instance of the entity. It is static because it is created based on the schema but does not change once created. The definition is used to instantiate declarations of the entity.

Definition example

a generic, unconfigured Kubernetes Pod.

Declaration

Declaration (static) : - A configured entity with detailed intentions of a given Definition.

Declaration example

NGINX container as a Kubernetes Pod with port 443 and SSL termination.

Instance

Instance (dynamic) : A realized entity (deployed/discovered); An instantiation of the declaration.

An instance represents a realized entity. An instance is a dynamic representation that corresponds to a deployed or discovered instantiation of a declaration. An instance is created based on its corresponding definition and represents an actual running or deployed version of the entity within the environment.

Instance example

NGINX-as234z2 pod running in a cluster as a Kubernetes Pod with port 443 and SSL termination.

Instructions for creating a new Model

Creating Models Quick Start

See the quick start for a no fluff guide to creating your first Meshery model.

All of Meshery’s Models, Components, and Relationships can be found in the Meshery Integrations spreadsheet. This spreadsheet is the source of truth for the definition of Meshery’s models. On a daily schedule, the contents of the Meshery Integrations spreadsheet is refreshed.

Model Source Code

See examples of Models defined in JSON in meshery/meshery.

To add or update a model, follow these steps:

1. Create a Model Definition. Open the Meshery Integrations spreadsheet. Create a new row (or comment to suggest a new row) to capture the specific details of your model. As you fill-in model details, referernce each column’s notes and comments as instructions and an explanation of their purpose.
2. Generate Components. Once you have entered values into the required columns, either execute step 2.a. or 2.b.
3. Execute the following command to generate components for your model.

`$ mesheryctl registry generate --spreadsheet-id "1DZHnzxYWOlJ69Oguz4LkRVTFM79kC2tuvdwizOJmeMw" --spreadsheet-cred “$"`

1. Ask a maintainer to invoke the Model Generator workflow.
2. Enhance Component details. While the default shape for new components is a circle, each component should be considered for its best-fit shape.
3. Review and familiarize with the available set of predefined relationship types. Refer to the Cytoscape node types for a list of possible shapes.
4. Propose a specific shape, best-suited to visually represent the Component. Example - Deployment as a pentagon.
5. Proposee a specific icon, best-suited to visually represent the Component. Example - DaemonSet as a skull icon.

Using Meshery CLI with the Registry (models)

Create new and list existing models by using mesheryctl registry to interact with the Meshery Registry and the Meshery Integrations spreadsheet.

Instructions for creating a new Component

See the Contributing to Components for detailed instructions.

Instructions for creating a new Relationship

See the Contributing to Relationships for detailed instructions.

Generating Models does not require Meshery Server

Meshery Server is not required to generate models. The Meshery CLI can be used to generate models. Model and Component generation logic is MeshKit. mesheryctl and Meshery Server both utilize MeshKit’s libraries for ongoing programmatic generation of models and components.

Next Steps

The Meshery team is currently working on the following:

• Extending the model to support additional entities
• Improving the tooling for working with models
• Defining relationships between components and embedding those policies within models

We encourage you to get involved in the development of Meshery Models and to share your feedback.

Meshery Models are extensible

Meshery Models are designed to be extensible, allowing you to define new components as needed. If you have an idea for a new component, please create one and share it with the Meshery community.

Suggested Reading

• Build & Release (CI) - Details of Meshery's build and release strategy.
• Contributing to Meshery Adapters - How to contribute to Meshery Adapters
• Contributing to Meshery CLI - How to contribute to Meshery Command Line Interface.
• Contributing to Meshery's End-to-End Tests using Cypress - How to contribute to End-to-End Tests using Cypress.
• Contributing to Meshery Docker Extension - How to contribute to Meshery Docker Extension
• Contributing to Meshery Docs - How to contribute to Meshery Docs.
• How to write MeshKit compatible errors - How to declare errors in Meshery components.
• Contributing to Meshery using git - How to contribute to Meshery using git
• Meshery CLI Contributing Guidelines - Design principles and code conventions.
• Contributing to Model Components - How to contribute to Meshery Model Components
• Contributing to Model Relationships - How to contribute to Meshery Models Relationships, Policies...
• Contributing to Models Quick Start - A no-fluff guide to creating your own Meshery Models quickly.
• Contributing to Meshery Policies - How to contribute to Meshery Policies
• Contributing to Meshery Server Events - Guide is to help backend contributors send server events using Golang.
• Contributing to Meshery UI - Notification Center - How to contribute to the Notification Center in Meshery's web-based UI.
• Contributing to Meshery UI - Sistent - How to contribute to the Meshery's web-based UI using sistent design system.
• Contributing to Meshery's End-to-End Tests - How to contribute to End-to-End Tests using Playwright.
• Contributing to Meshery UI - How to contribute to Meshery UI (web-based user interface).
• Contributing to Meshery Server - How to contribute to Meshery Server
• Setting up Meshery Development Environment on Windows - How to set up Meshery Development Environment on Windows
• End-to-End Test Status - Status reports of Meshery's various test results.