Create Models

Meshery offers two primary ways to bring models into your system: Create and Import.

  • Import is ideal when you already have a model definition file (e.g., JSON, CSV) and simply want to bring it into Meshery.
  • Create is the recommended approach if you’re starting fresh — it guides you through building a model step by step using an intuitive UI wizard.

This section walks you through the Create workflow — perfect for users who want full control over naming, styling, and categorizing their models while sourcing CRDs from GitHub or ArtifactHub.

Tip: If you don’t have any files yet, start with Create. You can always export or re-import your model later.

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

Step 1: Open the Model Generation Interface

Go to the Registry section in the Meshery UI. Click the create button to start creating a new model.

registry generate model

Step 2: Set Up Your Model Name

Enter the following names for your model:

  • Model Name: This is the unique, system identifier. Use lowercase letters and hyphens only (no spaces).
    Example: cert-manager
  • Display Name: This is the friendly name displayed in the UI. It can include spaces and uppercase letters.
    Example: Cert Manager
registry generate model name

Step 3: Set Model Categorization

Select the appropriate Category and Subcategory from the dropdowns. If your model doesn't match any available category, choose Uncategorized to ensure it can be easily located later.

registry generate model categorization

Step 4: Configure Model Styling

Customize your model's appearance:

  • Logos: Upload separate images for dark and light themes.
  • Colors: Define the primary and secondary colors for your model's visual elements.
  • Icon Shape: Choose a shape for the model’s icon as displayed in the UI.

Note: If you don't provide custom styling, Meshery's default values will be used.

registry generate model styling

Step 5: Provide the Source Location

Specify the source for your model by entering one of the following URL types:

  • GitHub Repository:
    Enter a URL using the following format: git://github.com/[organization]/[repository]/[branch]/path/to/crds
    Example: git://github.com/cert-manager/cert-manager/master/deploy/crds
  • ArtifactHub Package:
    Enter a URL in this format: https://artifacthub.io/packages/search?ts_query_web={model-name}

Need a Source URL?

Check the sourceURL column in the Meshery Integration Sheet and try one of the listed sources.
registry generate model source selection

Step 6: Additional Settings

  • Immediate Registration: Enable this option to register your model instantly, making it available in your Meshery instance right away.
  • Visual Annotation Only: Mark this option if your model is intended solely for visual diagramming rather than infrastructure management.
registry generate model additional settings

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.

Step 7: Finalize and Create Your Model

Review your model details. If everything looks good, click "Generate" to create your model.

Meshery will process the provided source URL, extract the necessary information, and create the model based on the specified details.

If you want to make any changes before generation, you can go back to the previous steps using the navigation buttons and edit the details as needed.

registry generate model generate

Step 8: Check Model Generation Status

Once the model is successfully generated, a confirmation message will appear. You'll be able to view the model along with its components and relationships directly in the Registry page.

If any issues occur, Meshery will display an error message detailing what went wrong so you can correct it and try again.

A notification will also appear in the Notification Center to confirm whether the operation succeeded or failed, providing additional context if needed.

Note on Deletion

Once a model is generated, it cannot be deleted from the Meshery UI. If you no longer wish to use it, you may mark it as ignored instead.

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 component - interact with and update Meshery Server
- mesheryctl relationships - interact with and update Meshery Server

Suggested Reading