Contributing to Models

Understanding the internals of Meshery’s logical object model

Meshery uses a logical object model to describe the infrastructure and capabilities it manages in a consistent and extensible way.

What Are Meshery Models?

At the core of this system are Meshery Models — packages that define a specific type of infrastructure, application, or capability. These models include:

• Components: Individual parts of a system (e.g., services, databases).
• Relationships: How those parts interact.
• Metadata: Visual and behavioral traits, such as icons or capabilities.

Models can describe traditional technologies (like Kubernetes workloads), or more abstract entities (like annotations or diagrams).

Learn more: What are Meshery Models?

What Is the Model Schema?

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.

 {
"$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."
.
.
.

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.

Declaration

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

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.

Capabilities

Capabilities: Capabilities are used to describe the operations that a model supports.

Models use capabilities to describe the operations which they support, such as styling, configurations, interactions, and runtime behavior. Entities may define a broad array of capabilities, which are in turn dynamically interpreted by Meshery for full lifecycle management.

To simplify the assignment of these capabilities, Meshery organizes these capabilities into reusable and assignable sets, such as:

• Default Set: A foundational set covering configuration (Workload Configuration, Labels and Annotations), UI interaction (Styling, Change Shape, Compound Drag and Drop), and component introspection (Relationships, Json Schema).
• Shapes: Visual components with layout and appearance-related capabilities. Includes Styling, Change Shape, Compound Drag and Drop, and Body Text.
• Comment: Annotation-like elements with light interaction. Similar to Shapes, but focused on non-functional overlays.
• Ghost: Lightweight visual components with minimal styling. Typically lacks body text or complex interactions.
• Shapes without Text: Variant of Shapes, omitting Body Text to support simpler block structures.
• Component with Logging and Terminal Session Support: Extends the Default set with operational capabilities like Performance Test, Interactive Terminal, and Stream Logs.
• Container Alias: Alias components that simulate real workloads, combining configuration, view, and operational capabilities.

Individual Capabilities

 {
"$id": "https://schemas.meshery.io/capability.json",
"$schema": "http://json-schema.org/draft-07/schema#",
"description": "Meshery manages entities in accordance with their specific capabilities. This field explicitly identifies those capabilities largely by what actions a given component supports; e.g. metric-scrape, sub-interface, and so on. This field is extensible. Entities may define a broad array of capabilities, which are in-turn dynamically interpretted by Meshery for full lifecycle management.",
"additionalProperties": false,
"type": "object",
"required": 
.
...
.
"kind": {
"description": "Top-level categorization of the capability",
"additionalProperties": false,
"anyOf": [
  {
    "const": "action",
    "description": "For capabilities related to executing actions on entities. Example: initiate log streaming on a Pod. Example: initiate deployment of a component."
  },
  {
    "const": "mutate",
    "description": "For capabilities related to mutating an entity. Example: the ability to change the configuration of a component."
  },
  .
  .
  .

Importing and Creating Models

Models can be created from scratch or imported using either the Meshery UI or the Meshery CLI.
To learn more, see the detailed guides on Importing Models and Creating Models.

Use Create if you’re starting from scratch. Use Import if you already have model definitions (e.g., JSON, CSV, tar).

Model Generation from Kubernetes Custom Resource Definitions (CRDs)

When generating models from Kubernetes Custom Resource Definitions (CRDs), Meshery automatically parses the CRD specifications to create components. During model creation, you can optionally specify a group filter based on the spec.group field from CRDs to control which CRDs are included when generating components for that model.

How CRD Filtering Works

During model generation, you as the user can specify a group filter value that will be matched against the spec.group field of CRDs. This user-specified filter allows you to selectively include only CRDs that belong to a specific Kubernetes API group in your model, ensuring logical organization of related components.

Example: In the CRD below, the spec.group field has the value cloudquota.cnrm.cloud.google.com. When creating a model, you would explicitly specify cloudquota.cnrm.cloud.google.com as the group filter value (e.g., in the model definition spreadsheet or via the UI). Meshery will then include only CRDs matching this API group when generating components for that model.

apiVersion: apiextensions.k8s.io/v1
kind: CustomResourceDefinition
metadata:
  annotations:
    cnrm.cloud.google.com/version: 1.140.0
  labels:
    cnrm.cloud.google.com/managed-by-kcc: "true"
    cnrm.cloud.google.com/system: "true"
  name: apiquotaadjustersettings.cloudquota.cnrm.cloud.google.com
spec:
  group: cloudquota.cnrm.cloud.google.com  # API group used for filtering
  names:
    categories:
    - gcp
    kind: APIQuotaAdjusterSettings
    plural: apiquotaadjustersettings
  scope: Namespaced
  versions:
  - name: v1beta1
    schema:
      openAPIV3Schema:
        properties:
          apiVersion:
            type: string
          kind:
            type: string
          # ... additional schema definition

Component Generation Behavior

When Meshery processes CRDs:

1. Parsing: Each CRD is parsed to extract its schema and specifications
2. Filtering (Optional): If a group filter is specified, only CRDs with a matching spec.group value are processed
3. Component Creation: A component definition is generated for each CRD, including its kind, version, and schema
4. Model Assignment: Generated components are assigned to the target model
5. Registration: The components are registered in Meshery’s Registry under their respective model
6. Enrichment: Components inherit default properties from their model and can be further customized

This user-controlled filtering capability allows you to organize related Kubernetes custom resources together, making them easier to discover, manage, and use within Meshery designs. For example, to create a model containing all Google Config Connector CRDs for a specific GCP service, you would explicitly specify their common API group value (e.g., cloudquota.cnrm.cloud.google.com) as the group filter when defining the model.

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!