Contributing to Model Components
In Meshery, a Components is a fundamental building block used to represent and define the infrastructure under management. Each component provides granular and specific support for your infrastructure and applications. Once registered with Meshery Server (in the Registry), components are available for inclusion in Designs that you create. Components can be created and published by anyone, allowing you to share you custom extensions with the community.
Overview of Steps to Create Components
Prework:
Development:
Postwork:
Prework
1. Understand Model Generation and Packaging
Prerequisite Reading
Components are defined and packaged in context of a Model. Be sure to first read and understand how models are created and packaged before attempting to create a new component. Without a model defined first, they component will be homeless.2. Customize Component Form-based Representation
Each component has any number of customizable properties in the form of metadata. The metadata provides additional details about the component, enhancing its capabilities. Metadata can be attached to components to customize their behavior. The metadata can be used to define the componentβs behavior, appearance, and interactions with other components.
Customize Component Form-based Representation
Components optionally have a UI schema, which is a JSON object that describes how a form should be rendered. It can be passed to JSON forms and is categorized into controls or layouts. The UI schema object follows the form field hierarchyβs tree structure and defines how each property should be rendered. For example, it can specify the order of controls, their visibility, and the layout.
Some UI schema elements have an options property that allows for further configuration of the rendering result. These configuration options are often renderer specific and need to be looked up. Some commonly used options include:
ui:order
: An array of field names in the order in which they should appear
ui:widget
: The name of an alternative widget to use for the field
ui:field
: The name of a custom field
classNames
: The class names to put on the component
Meshery UI uses the react-jsonschema-form
library to render forms. See the RJSF documentation for more information.
Customize Component Visual Representation
Meshery contributors who want to customize the visual representation of a Meshery component can do so by modifying the componentβs metadata. This metadata includes fields for specifying the componentβs:
- SVG: The SVG file used to represent the component visually.
- Primary Color: The primary color used for the component in hex format.
- Secondary Color: The secondary color used for the component in hex format.
- Shape: The basic shape of the component, such as a circle or square.
- isAnnotation: A boolean value that indicates whether the component is an annotation or is semantically meaningful.
Example Component Metadata
"metadata": {
"capabilities": "",
"defaultData": "",
"genealogy": "",
"isAnnotation": false,
"isCustomResource": false,
"isModelAnnotation": "FALSE",
"isNamespaced": false,
"logoURL": "Created by Meshery Authors",
"model": "kubernetes",
"modelDisplayName": "Kubernetes",
"primaryColor": "#326CE5",
"secondaryColor": "#7aa1f0",
"shape": "round-rectangle",
"shapePolygonPoints": "",
"status": "enabled",
"styleOverrides": "{\"height\":\"22px\", \"width\":\"22px\", \"x\":\"8.5\", \"y\":\"7.5\"}",
"styles": "{\"height\":\"22px\", \"width\":\"22px\", \"x\":\"8.5\", \"y\":\"7.5\"}",
"subCategory": "",
"svgColor": "\u003csvg width=\"90\" height=\"90\" viewBox=\"0 0 90 90\" fill=\"none\" xmlns=\"http://www.w3.org/2000/svg\"\u003e\n\u003cpath fill-rule=\"evenodd\" clip-rule=\"evenodd\" d=\"M41.0114 45.015C51.699 45.015 60.363 36.3512 60.363 25.6637C60.363 14.9763 51.699 6.3125 41.0114 6.3125C30.3239 6.3125 21.6599 14.9763 21.6599 25.6637C21.6599 36.3512 30.3239 45.015 41.0114 45.015ZM26.9841 46.0338C27.3733 45.9771 27.7668 46.0783 28.0996 46.2881C31.5844 48.484 36.0555 49.8036 40.931 49.8036C45.8346 49.8036 50.3289 48.4688 53.8223 46.2502C54.148 46.0434 54.5325 45.9405 54.9151 45.9897C64.2686 47.1911 71.4966 55.1832 71.4966 64.8635V72.3594C71.4966 78.7567 66.3106 83.9428 59.9132 83.9428H22.308C15.9107 83.9428 10.7246 78.7567 10.7246 72.3594V64.8635C10.7246 55.2946 17.7872 47.3752 26.9841 46.0338Z\" fill=\"#326CE5\"/\u003e\n\u003cpath fill-rule=\"evenodd\" clip-rule=\"evenodd\" d=\"M72.0356 82.4937C73.7201 80.3512 74.7249 77.649 74.7249 74.7122V64.0123C74.7249 55.9577 70.1245 48.9776 63.408 45.5561C72.7393 47.0963 79.8167 54.6562 79.7238 63.5783V72.0106C79.7238 76.766 76.5504 80.8211 72.0356 82.4937ZM63.6189 25.6633C63.6189 30.5769 62.1331 35.1434 59.5862 38.9381C66.2233 36.7133 71.0055 30.4442 71.0055 23.0581C71.0055 13.8103 63.5088 6.31348 54.261 6.31348C54.0822 6.31348 53.904 6.31628 53.7266 6.32184C59.7194 10.6542 63.6189 17.7034 63.6189 25.6633Z\" fill=\"#326CE5\"/\u003e\n\u003c/svg\u003e\n",
"svgComplete": "",
"svgWhite": "\u003csvg width=\"90\" height=\"90\" viewBox=\"0 0 90 90\" fill=\"none\" xmlns=\"http://www.w3.org/2000/svg\"\u003e\n\u003cpath fill-rule=\"evenodd\" clip-rule=\"evenodd\" d=\"M41.0114 45.015C51.699 45.015 60.363 36.3512 60.363 25.6637C60.363 14.9763 51.699 6.3125 41.0114 6.3125C30.3239 6.3125 21.6599 14.9763 21.6599 25.6637C21.6599 36.3512 30.3239 45.015 41.0114 45.015ZM26.9841 46.0338C27.3733 45.9771 27.7668 46.0783 28.0996 46.2881C31.5844 48.484 36.0555 49.8036 40.931 49.8036C45.8346 49.8036 50.3289 48.4688 53.8223 46.2502C54.148 46.0434 54.5325 45.9405 54.9151 45.9897C64.2686 47.1911 71.4966 55.1832 71.4966 64.8635V72.3594C71.4966 78.7567 66.3106 83.9428 59.9132 83.9428H22.308C15.9107 83.9428 10.7246 78.7567 10.7246 72.3594V64.8635C10.7246 55.2946 17.7872 47.3752 26.9841 46.0338Z\" fill=\"white\"/\u003e\n\u003cpath fill-rule=\"evenodd\" clip-rule=\"evenodd\" d=\"M72.0356 82.4937C73.7201 80.3512 74.7249 77.649 74.7249 74.7122V64.0123C74.7249 55.9577 70.1245 48.9776 63.408 45.5561C72.7393 47.0963 79.8167 54.6562 79.7238 63.5783V72.0106C79.7238 76.766 76.5504 80.8211 72.0356 82.4937ZM63.6189 25.6633C63.6189 30.5769 62.1331 35.1434 59.5862 38.9381C66.2233 36.7133 71.0055 30.4442 71.0055 23.0581C71.0055 13.8103 63.5088 6.31348 54.261 6.31348C54.0822 6.31348 53.904 6.31628 53.7266 6.32184C59.7194 10.6542 63.6189 17.7034 63.6189 25.6633Z\" fill=\"white\"/\u003e\n\u003c/svg\u003e\n"
},
Contributors can also override these settings for individual components if needed. For example, if a component has a different SVG color than its model, you can specify a custom SVG color for that component.
Component icons will be written to the /meshmodel/components/<model-name>/icon/...
directory upon registration.
Development
3. Create a Component Definition as a JSON file
Create a relationship definition as a JSON file, placing this new definition file into its respective model folder (see Contributing to Models). Relationship definition files are commonly named relationships.yaml
as a convention, however, this name is not required. A model may include any number of relationship definitions. Include the following attributes in your relationship definition:
kind
: The genre of component (e.g.,Pod
).model
: The model to which the component belongs (e.g.,kubernetes
).version
: The version of the component definition (e.g.,v1.0.0
).description
: A characterization of the component, its purpose and behavior.
Use Existing Components as Examples
Browse the existing components in the Meshery repository to find examples of how to existing component, using them as a template.Postwork
4. Component Authoring Best Practices and Considerations
General
- Use camelCasing as the formatting convention.
- Increment the component definition using the
version
property with each change published.
5. Contribute your component to the Meshery project
Submit a pull request to the Meshery repository with your new component definition, so that all users can benefit from the component(s) you have defined.
Keeping your component definition in a separate file allows for easier management and review of the component(s) you have defined.
Keeping your custom Components private
Alternatively, if you would like to keep the component definition private, you can bundle your component(s) in a custom model, import the custom model into your Meshery deployment. Your private component definition(s) will be registered in your Meshery Server's registry and available for use within your Meshery deployment.Suggested Reading
- Build & Release (CI) - Details of Meshery's build and release strategy.
- Contributing to Meshery Adapters - How to contribute to Meshery Adapters
- Contributing to Meshery CLI - How to contribute to Meshery Command Line Interface.
- Contributing to Meshery's End-to-End Tests using Cypress - How to contribute to End-to-End Tests using Cypress.
- Contributing to Meshery Docker Extension - How to contribute to Meshery Docker Extension
- Contributing to Meshery Docs - How to contribute to Meshery Docs.
- How to write MeshKit compatible errors - How to declare errors in Meshery components.
- Contributing to Meshery using git - How to contribute to Meshery using git
- Meshery CLI Contributing Guidelines - Design principles and code conventions.
- Contributing to Model Relationships - How to contribute to Meshery Models Relationships, Policies...
- Contributing to Models - How to contribute to Meshery Models, Components, Relationships, Policies...
- Contributing to Meshery Policies - How to contribute to Meshery Policies
- Contributing to Meshery Server Events - Guide is to help backend contributors send server events using Golang.
- Contributing to Meshery UI - Notification Center - How to contribute to the Notification Center in Meshery's web-based UI.
- Contributing to Meshery UI - Sistent - How to contribute to the Meshery's web-based UI using sistent design system.
- Contributing to Meshery's End-to-End Tests - How to contribute to End-to-End Tests using Playwright.
- Contributing to Meshery UI - How to contribute to Meshery UI (web-based user interface).
- Contributing to Meshery Server - How to contribute to Meshery Server
- Setting up Meshery Development Environment on Windows - How to set up Meshery Development Environment on Windows