Contributing to Models Quick Start

Meshery Models are a way to represent the architecture of a system or application. Models are defined in JSON and can be used to visualize the components and relationships between them. This guide will walk you through the process of creating a new model.

Meshery Components are the building blocks of a model. Each component represents a different part of the system or application. Components can be anything from a database to a microservice to a server. Relationships define how components interact with each other. For example, a database component might have a relationship with a microservice component that represents the microservice’s dependency on the database.

Creating your first Meshery Model

The following instructions are a no-fluff guide to creating your own Meshery Models quickly. For more detailed information, see the Contributing to Models documentation.

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. You can find templates for these files 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.

Congratulations! You have successfully created a new model.

Contributing a Model Definition

  1. Fork the meshery/meshery.io repository.
  2. Create a new branch in your fork of the meshery/meshery.io repository.
  3. Add your model definition to the collections/_models directory.
  4. Create a pull request to the meshery/meshery.io repository.
  5. Once your pull request is merged, your model will be available in the next Meshery release.

Next Steps

Contributing to Models

See the full Contributing to Models documentation for a detailed understanding of models and the many ways in which you can customize them.

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