Create Models

The scaffold workflow is the most direct way to hand-author a model - especially an annotation-only model (a curated set of icons used purely for visual diagramming). Unlike the CSV and Spreadsheet workflows, it does not require forking meshery/meshery or a Google Spreadsheet credential; it produces model files locally, packages them as an OCI image, and registers them into a running Meshery Server.

1. Scaffold the model

Generate the folder structure with mesheryctl model init:

This creates:

2. Edit model.json

Open digitalocean-icons/v0.1.0/model.json and set the model's identity and appearance:

• category.name and subCategory - e.g. Platform / Cloud Provider.
• registrant.kind - e.g. meshery.
• description - a short summary of what the model provides.
• metadata.svgColor and metadata.svgWhite - the model's display icon, as an inline SVG string (strip any <?xml ...?> header and collapse the SVG to a single line).
• metadata.isAnnotation - set to true for an annotation-only (visual diagramming) model.

3. Add one component per capability

model init drops a single sample component under components/. Add one JSON file per component (delete the sample if unused). For each component set:

• displayName - the human-readable name shown in the UI (e.g. DO Logo Icon Blue).
• component.kind - the unique identifier for the component (e.g. do-logo-icon-blue).
• styles.svgColor and styles.svgWhite - the component's inline SVG.
• metadata.isAnnotation - true for annotation components.

4. Package the model as an OCI image

This writes an OCI artifact named <model>-<version>.tar (e.g. digitalocean-icons-v0-1-0.tar) to your current directory.

5. Register the model into a Meshery Server

Import the packaged artifact (or the model directory) into your connected Meshery Server. This step requires a running server and an authenticated mesheryctl context (see mesheryctl system login):

Verify the result:

See Importing Models for the full set of import sources and Push or Pull a Model Image for packaging details.

1. Understanding the Template Directory

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

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:

The --directory flag takes the path to the folder that contains Models.csv and Components.csv (Relationships.csv is optional). This path is CSV-driven and does not require a Google Spreadsheet credential.

4. Locating Generated Files

After successful generation, your model's files will be created in the repository's models/ directory. You can find these files at meshery/models/[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:

The value passed to --spreadsheet-cred is the base64-encoded contents of the service-account JSON (the string itself), not a file path and not GOOGLE_APPLICATION_CREDENTIALS. Pass it as --spreadsheet-cred "$SHEET_CRED".

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

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/models/[YOUR_MODEL_NAME]