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.

Model Entity Classification 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 can be found in the Meshery Integrations spreadsheet. This spreadsheet serves as the source of truth for the definition of Meshery’s models and is refreshed daily.

Model Source Code

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

Prerequisites:

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.

1. Understanding the Template Directory

Inside your forked Meshery repository, you'll find the templates-csvs directory containing three essential CSV files:

mesheryctl/templates/templates-csvs/
├── models.csv # Define model metadata and core properties
├── components.csv # Specify individual components and their characteristics
└── relationships.csv # Define how components interact and connect

2. Customizing Your Model

Creating your model involves modifying these CSV files to match your specific requirements. When making changes, you have two valuable references at your disposal: the existing entries in the CSV files serve as practical examples, while the integration spreadsheet provides comprehensive documentation of all possible fields and their purposes.

3. Generating Your Model

Once you've customized your CSV files, you can generate your model using a single command. Ensure you're in the root directory of your forked Meshery repository, as this maintains the correct file path relationships:

mesheryctl registry generate --directory templates-csvs --model "YOUR_MODEL_NAME"

4. Locating Generated Files

After successful generation, your model's files will be created in the Meshery server's model directory. You can find these files at meshery/server/meshmodel/[YOUR_MODEL_NAME]/. Take time to review these generated files to ensure they accurately reflect your intended model structure.

5. Troubleshooting

If you encounter issues during the generation process, you can use these diagnostic approaches to identify and resolve problems:

  • Examine the detailed error logs at ~/.meshery/logs/registry/ to understand specific generation issues.
  • Review your CSV files for proper formatting, ensuring all required columns are present and correctly populated.
  • Confirm you're executing the command from the root of your forked Meshery repository.

Setting Up Your Environment

Before you begin working with the Integration Spreadsheet, you'll need to complete several important setup steps:

1. Spreadsheet Preparation

Start by creating your own copy of the Meshery Integration Sheet:

  1. Visit the Meshery Integration Sheet
  2. Make a copy using File > Make a copy
  3. Look at the URL of your new spreadsheet and note the ID (the long string between /d/ and /edit)

2. Google Cloud Configuration

Set up your Google Cloud environment with these steps:

  1. Create a new Google Cloud Project or select an existing one
  2. Enable the Google Sheets API for your project
  3. Create service account credentials

3. Credential Configuration

Set up your credentials in your local environment:

base64 -w 0 /path/to/your-service-account-creds.json
echo 'export SHEET_CRED="[paste-base64-output-here]"' >> ~/.bashrc
source ~/.bashrc

4. Spreadsheet Access Configuration

  1. Open your copied spreadsheet
  2. Click "Share" in the top right
  3. Add your service account email (ends with @developer.gserviceaccount.com)
  4. Grant "Editor" permissions
  5. Publish the spreadsheet:
    • File > Share > Publish to web
    • Select "Comma-separated values (.csv)"
    • Click "Publish"

Working with the Integration Spreadsheet

Once your environment is set up, you can begin working with the spreadsheet:

1. Adding Your Model

The integration spreadsheet contains existing model definitions that serve as practical examples. You can either create a new entry following the patterns in existing rows, or practice by generating an existing model first to understand the process. Each row represents a complete model definition, use them as reference for creating a new row.

2. Generating the Model

Use mesheryctl to generate your models. Make sure to run the command inside your forked meshery/meshery repo

mesheryctl registry generate --spreadsheet-id "YOUR_SPREADSHEET_ID" --spreadsheet-cred "$SHEET_CRED" --model "YOUR_MODEL_NAME"

The command will:

  • Read your spreadsheet data
  • Validate the model definition
  • Generate the model files
  • For error logs your can checkout ~/.meshery/logs/registry/

3. Verification

The model will be generated in meshery/server/meshmodels/[YOUR_MODEL_NAME]

Using Meshery CLI with the Meshery Registry and Meshery Models

Meshery CLI has a set of commands that pertain to the lifecycle management of models:
- mesheryctl registry - interact with and update spreadsheets
- mesheryctl models - interact with and update Meshery Server
- mesheryctl components - interact with and update Meshery Server
- mesheryctl relationships - interact with and update Meshery Server

The URL Import feature allows you to generate models in Meshery by providing URLs to source repositories or package registries. Here's how to use it:

1. Access the Model Generation Interface

Navigate to Registry in the Meshery UI. Click the "Generate" button to begin creating a new model. In the Upload Method dialog, select "URL Import" and click Next.

registry generate model

2. Provide Source Location

You can provide either a GitHub repository URL or an ArtifactHub package URL as your source:

For GitHub repositories:
Enter a URL in the format: git://github.com/[organization or username]/[repository]/[branch]/path/to/crds
For example: git://github.com/cert-manager/cert-manager/master/deploy/crds

For ArtifactHub packages:
Enter a URL in the format: https://artifacthub.io/packages/search?ts_query_web={model-name}

Pro tip: Check the sourceURL column in the Meshery Integration Sheet and try one of the listed sources.

registry generate model source selection

3. Configure Model Details

Enter the required information for your model:

  • Model Name: Should be in lowercase with hyphens. For example, cert-manager.
  • Display Name: How you want your model to be named. For example, Cert Manager.
registry generate model name

4. Set Model Categorization

Choose appropriate category and subcategory for your model from the dropdown menus. If your model doesn't fit existing categories, select "Uncategorized". This helps organize models in the registry and makes them easier to find.

registry generate model categorization

5. Configure Model Styling

Customize your model's appearance:

  • Upload logos for both dark and light themes
  • Set primary and secondary colors for visual elements
  • Select a shape for the model's icon in the UI

Note: If you don't provide custom styling, Meshery's default values will be used. You can change these later in the model definition.

registry generate model styling

6. Additional Settings

Before finishing, you can:

  • Choose to register the model immediately for instant availability in Meshery instance.
  • Specify if the model is for visual annotation only

Visual Annotation Models

When a model is marked for visual annotation only, it means the model will be used purely for visualization and diagramming purposes within Meshery's interface, rather than for actual infrastructure management.
registry generate model additional settings

After completing these steps, click "Finish" to generate your model. Once generated, you can find your model in the Registry section (if you checked "Register Model Immediately") else it'll download the generated model in an archive, ready for use in your Meshery environment.

The CSV Import feature allows you to generate models in Meshery by providing template CSV files that define your model structure, components, and relationships. Here's a comprehensive guide on how to use this feature:

1. Access the Model Generation Interface

Navigate to Registry in the Meshery UI. Click the "Generate" button to begin creating a new model. In the Upload Method dialog, select "URL Import" and click Next.

registry generate model CSV Import Initial Screen

2. Prepare Your CSV Files

You'll need three essential CSV files to define your model. CSV templates can be found in the Meshery repository. Each file serves a specific purpose:

  • models.csv: Defines your model's core metadata, including name, version, and general properties
  • components.csv: Describes the individual components that make up your model
  • relationships.csv: Specifies how different components interact and connect with each other

Pro tip: Look at existing models in the Meshery Integration Sheet to understand how to structure your CSV files effectively.

3. Upload Models, Components, and Relationships CSV

Model CSV Upload Component CSV Upload Relationship CSV Upload

6. Model Registration

In the final step, you can choose to register your model immediately in your Meshery instance. This makes the model available for immediate use after generation.

Model Registration Options

After completing these steps and successfully generating your model, you can find it in the Registry section if you chose to register it immediately. Otherwise, you'll receive a downloaded archive containing your generated model files.

Importing Generated Models

The generated model can be importing using both Mesheryctl and Meshery UI. Read Importing Models for detailed instructions on how to import models.

Post Model Generation

During model generation, corresponding components are created. Next step is to enrich these component details and define their capabilities and relationships.

  1. Enrich Component Details When a Component is initially generated, a new Component definition is created with default properties (e.g. colors, icons, capabilities, etc.), some of which are inherited from their respective Model.

    • 1.1. Customize Shapes and Colors

      • Default shape for new components is a circle
      • Consider enriching components’ details based on what they represent
      • Reference Cytoscape node types for possible shapes
      • Example: Use a pentagon shape to represent a Deployment
      • Know more about components shapes and colors

    • 1.2. Customize Icons

      • Components inherit the icon (colored and white SVGs) of their respective Model by default
      • Propose specific icons best suited to visually represent each component
      • Example: Use a skull icon for a DaemonSet

    • 1.3. Review Capabilities

      • Review and confirm assigned capabilities
      • Modify capabilities as needed

    See the Contributing to Components for detailed instructions.

  2. Identify Relationships

    • 2.1. Review Available Types Review and familiarize yourself with the predefined relationship kinds, types, and subtypes. See “Relationships logical concepts”

    • 2.2. Map Component Relationships

      • Identify appropriate relationships for your new components
      • Consider how components relate to others within the same model
      • Consider relationships with components in other models

    • 2.3. Create Definitions Codify the relationships you have identified into a Relationship Definition

    See the Contributing to Relationships for detailed instructions.

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