KubeCon Workshop: Publish a Design and Build a Custom Model

Path A uses the Kanvas extension on https://playground.meshery.io for both labs.

• Lab 1: you build the Deployment and Service visually in Kanvas Designer, then Validate and Publish To Catalog.
• Lab 2: you open the Registry’s Create Model wizard in the Playground, mark the model as visual annotation only, and upload the KubeCon logos. You then pin the component in Kanvas Designer and drop it onto your Lab 1 design.

You work in the browser. You do not need mesheryctl on Path A.

Path B uses only Meshery UI and/or mesheryctl. It does not use the Kanvas extension.

• Lab 1: you import a ready-made Kubernetes manifest (a Deployment and a Service) from the Designs page or with mesheryctl design import, then Validate and publish from Meshery UI.
• Lab 2: you scaffold, package, and import the KubeCon logo model with mesheryctl (or import the ready-made archive in the Registry), then add that component to your Lab 1 design by editing the design in the Design Configurator or by updating the design file.

You will point mesheryctl at the Playground before the Path B labs.

1. Open Kanvas Designer. Go to https://playground.meshery.io/extension/meshmap and choose the Designer tab.
2. Create and name the design. Start a new design and name it kubecon-<your-handle>-design, for example kubecon-octocat-design. The save indicator beside the name is a cloud with a tick when the design is saved. Kanvas saves automatically about 3 seconds after you stop editing.
3. Add a Deployment. From the Kubernetes model, drag a Deployment onto the canvas. Open its configuration form, give it a name, and set the container image to meshery/meshery-milestone:latest. That image is a small Nginx app; Docker Hub currently publishes it under the latest tag only. Add a label such as app: kubecon-<your-handle>.
4. Add a Service. Drag a Service onto the canvas. In its configuration form, set the selector to the same app: kubecon-<your-handle> value so the Service targets the Deployment, and set port and targetPort to 80.
5. Connect them. Tap the Service, pick a relationship type from the edge picker, and drag to the Deployment. Kanvas highlights compatible targets.
6. Validate. Run Validate and fix anything it reports. Validate checks every component against its schema and does not contact a cluster. The count in the result comes from the design, so it includes components whose definitions could not be fetched; a clean result does not guarantee every component was checked.
7. Confirm it is saved. Check the save indicator shows a cloud with a tick.
8. Publish to the Catalog. Open Details for the design: click the info (“i”) button, or choose Details from the File menu, or go to Configuration > Designs and open the design’s Design Information. Fill in Type, Technology, Description and Caveats (for example: Type “Workload”, Technology “Kubernetes”, a one-sentence description of your Deployment and Service). Click Publish to Catalog.

Download the ready-made manifest first: kubecon-design.yaml. It defines a Deployment that uses meshery/meshery-milestone:latest and a Service that selects it on port 80. You can edit the resource names and the app: kubecon-demo label to include your handle before you import, or leave them as they are and just give the design a unique name.

If you will use mesheryctl in this lab or in Lab 2, point it at the Playground once, before you import anything. Signing in to the Playground in your browser does not configure mesheryctl.

mesheryctl system context create playground --url https://playground.meshery.io --set
mesheryctl system token create playground-token -f ~/.meshery/playground-auth.json --set
mesheryctl system login
chmod 600 ~/.meshery/playground-auth.json
mesheryctl system context view

The token file is separate so signing in does not overwrite the token your other contexts use. Confirm mesheryctl system context view shows the Playground endpoint before you import or delete anything.

Import the manifest as a design

Use the UI, or mesheryctl, or both.

Meshery UI

1. Go to Configuration > Designs, or open https://playground.meshery.io/configuration/designs.
2. Click Import Design.
3. Enter the Design Name kubecon-<your-handle>-design, for example kubecon-octocat-design.
4. Choose File Upload, then pick kubecon-design.yaml from your computer.
5. Click Import. Importing does not deploy anything.

mesheryctl

mesheryctl design import -f kubecon-design.yaml -n kubecon-<your-handle>-design

-f is a local path or a direct URL. -n names the design; without it, mesheryctl uses the file name. -s is optional because Meshery Server detects the format. If you pass it, use -s "Kubernetes Manifest" (the value is case-insensitive). Confirm the import:

mesheryctl design list
mesheryctl design view kubecon-<your-handle>-design

mesheryctl design view prints YAML by default. Use -o json if you want JSON.

Optional: build the design in the Design Configurator

Instead of importing the manifest, you can create the design from forms in Meshery UI (still without Kanvas):

1. Go to Configuration > Designs and click Create Design. The Design Configurator opens at /configuration/designs/configurator.
2. Enter the Design Name kubecon-<your-handle>-design.
3. In Select Category, choose Orchestration & Management. In Select Model, choose Kubernetes.
4. Expand the Deployment form, set the container image to meshery/meshery-milestone:latest, and add a label such as app: kubecon-<your-handle>.
5. Expand the Service form, set the selector to that same label, and set port and targetPort to 80.
6. Click the Save Design as New File icon. The design appears on the Designs page.

Validate and dry run

On the Designs page, open the action menu for your design:

1. Choose Validate Design. This checks the design against component schemas and does not contact a cluster. Fix anything it reports, then validate again.
2. Optionally choose Dry Run. Dry Run talks to a cluster and is not required to finish the lab.

There is no mesheryctl design validate or mesheryctl design check command. mesheryctl design evaluate runs relationship-evaluation policies and writes an evaluated design to a file; it is not a substitute for Validate Design and is not required in this lab.

Publish to the Catalog

The Designs table does not have a separate Publish action. Publish from Design Information:

1. On Configuration > Designs, open the action menu for your design and choose Design Information.
2. Fill in Type, Technology, Description and Caveats (for example: Type “Workload”, Technology “Kubernetes”, a one-sentence description of your Deployment and Service). Technology maps to the form’s compatibility field; pick at least one.
3. Click Publish to Catalog. You must be signed in, you must own the design, and you need the Publish Design permission.

There is no mesheryctl command that publishes a design to the Catalog.

Path A builds the model in the Playground Registry, then adds the component in Kanvas Designer. You do not need mesheryctl.

Open the Create Model wizard

1. Open the Registry: click your avatar in the top right and choose Registry, or go to Settings > Registry, or open https://playground.meshery.io/settings?settingsCategory=Registry&tab=Models.
2. On the Models tab, click Create Model. The modal title is Create Model.

Walk through the wizard

The stepper labels are Model Details, Model Categorization, Styling, Source, Additional Details, and Finalize Generation. Use Next to advance. Generate runs on the summary step and registers the model immediately. The wizard has no separate Immediate Registration toggle.

1. Model Details. Enter a unique Model Name such as kubecon-<your-handle>-logo (lowercase letters, digits, and hyphens only, no spaces) and a Model Display Name such as KubeCon Logo (<your-handle>).
2. Model Categorization. Choose a Category and Subcategory. If nothing fits, choose Uncategorized for both, so the model is easy to find later.
3. Styling. Upload kubecon-logo-color.svg as Logo (Light Theme) and kubecon-logo-white.svg as Logo (Dark Theme). The inputs accept .svg files only (the browser reports image/svg+xml). Optionally set Primary Color, Secondary Color, and Shape. If you leave colors and shape empty, Meshery uses its defaults. Light Theme maps to svgColor; Dark Theme maps to svgWhite.
4. Source. Choose GitHub or Artifact Hub, then enter a Model URL. This step is required: Next stays disabled until the source and a valid URL are set.
5. Additional Details. Check The components in this model are visual annotations only. The wizard’s help text and the generation summary call this option Visual Annotation Only.
6. Finalize Generation. Review the summary, including Visual Annotation Only: Yes, then click Generate. When it finishes, click Finish.

Import the ready-made KubeCon logo model

1. Stay on the Registry Models tab and click Import Model.
2. Choose File Import, pick kubecon-logo.tar.gz from your computer, and import it.
3. Confirm the model appears in the Registry. This fallback model is named kubecon-logo and is shared, so prefer a handle-specific model when you have one. The archive already has isAnnotation set to true and the SVGs inlined, with a single component whose kind and display name are kubecon-logo and KubeCon Logo.

Add the logo to your Lab 1 design in Kanvas

1. Reopen your design in Kanvas Designer at https://playground.meshery.io/extension/meshmap.
2. Find the component. Search the component list for KubeCon Logo or your model display name. Hover it and click the pin icon (Pin To Dock) so it sits in the dock at the bottom. If it does not appear, refresh the Kanvas tab and search again.
3. Drop it on the canvas. Drag the KubeCon Logo component onto the design near your Deployment and Service. It is annotation-only, so it is a visual label, not a workload.
4. Save. Wait for the cloud-with-a-tick save indicator.
5. Optional: update the Catalog request. If your Lab 1 publish request is still pending review, this save is enough; the submitted design updates automatically. If the design was already approved and is locked in the Catalog, clone it, add the logo to the clone, and publish the new design.

Path B builds the model with mesheryctl (or imports the ready-made archive in the Registry) and adds the component without Kanvas. If you did not already point mesheryctl at the Playground in Lab 1, do that first. Signing in to the Playground in your browser does not configure mesheryctl.

mesheryctl system context create playground --url https://playground.meshery.io --set
mesheryctl system token create playground-token -f ~/.meshery/playground-auth.json --set
mesheryctl system login
chmod 600 ~/.meshery/playground-auth.json
mesheryctl system context view

Confirm mesheryctl system context view shows the Playground endpoint before you import or delete anything.

Scaffold, edit, package and import

1. Scaffold the model. Pick a unique model name that includes your handle, using lowercase letters, digits and hyphens only:

   mesheryctl model init kubecon-<your-handle>-logo --version v0.1.0
   

   That creates kubecon-<your-handle>-logo/v0.1.0/, with model.json, a sample file under components/, and empty relationships/, connections/ and credentials/ directories.

2. Edit model.json. Set metadata.isAnnotation to true. Set registrant.kind to meshery, give the model a short description, and paste the color SVG into metadata.svgColor and the white SVG into metadata.svgWhite. Strip any XML header (<?xml ... ?>) and collapse each SVG to a single line before pasting. Leave schemaVersion as models.meshery.io/v1beta2. If you set a category, Uncategorized is a safe choice.

3. Replace the sample component. In components/, keep a single JSON file (you can rename component.json to kubecon-logo.json). Set:

   • displayName to KubeCon Logo
   • component.kind to kubecon-logo
   • metadata.isAnnotation to true
   • styles.svgColor and styles.svgWhite to the same inlined SVGs
   • schemaVersion to components.meshery.io/v1beta1 (this wire format is the most widely accepted by current Meshery Servers)
   • the nested model.name to the same name you passed to model init

   You can delete the sample file under relationships/ if you do not need it. A model imports if it contains at least one valid component.

4. Package the model as an OCI archive:

   mesheryctl model build kubecon-<your-handle>-logo/v0.1.0
   

   This writes kubecon-<your-handle>-logo-v0-1-0.tar in your current directory.

5. Import it into the Playground:

   mesheryctl model import -f kubecon-<your-handle>-logo-v0-1-0.tar
   mesheryctl model view kubecon-<your-handle>-logo
   

   You can also import from the UI: avatar, then Registry, then Import Model, then File Import, and choose the .tar file. Either route registers the model in the shared Playground instance.

Add the logo to your Lab 1 design (without Kanvas)

Without Kanvas you will not see the logo on a canvas. You can still add the annotation component to the design document, save or update it, and confirm it with mesheryctl design view.

Preferred: add it in the Design Configurator

1. Go to Configuration > Designs, open the action menu for your Lab 1 design, and choose Edit. The Design Configurator opens at /configuration/designs/configurator?design_id=....
2. In Select Category, look for the category you gave the model (the ready-made archive uses Uncategorized). In Select Model, choose your KubeCon logo model.
3. Expand the KubeCon Logo component form, give it a name if prompted, and confirm it appears in the YAML editor next to the forms.
4. Click the Update Design icon (not Save Design as New File, unless you want a copy).

If the model does not appear in the category or model dropdowns, refresh the page and search again. Whether a just-imported annotation-only model always appears in the Design Configurator has not been verified in the Playground; if it does not, use the YAML path below.

YAML path: export, add a component, and update

1. Export the design. In Meshery UI, on the Designs page, choose Download and pick Meshery Design (yaml). Or run:

   mesheryctl design export kubecon-<your-handle>-design
   

   The default --type is current (the design as Meshery stores it now).

2. Open the exported YAML. It should have a top-level components: list and a schemaVersion such as designs.meshery.io/v1beta1. Append this component to that list. Replace the model name with your handle-specific model name, or use kubecon-logo if you imported the fallback archive. Generate a fresh UUID for id (for example with uuidgen):

   - id: 00000000-0000-0000-0000-000000000000
     schemaVersion: components.meshery.io/v1beta1
     version: v0.1.0
     displayName: KubeCon Logo
     format: JSON
     status: enabled
     model:
       schemaVersion: models.meshery.io/v1beta2
       version: v0.1.0
       name: kubecon-<your-handle>-logo
       displayName: KubeCon Logo
       status: enabled
       metadata:
         isAnnotation: true
       model:
         version: v0.1.0
     metadata:
       isAnnotation: true
     component:
       kind: kubecon-logo
       version: v0.1.0
       schema: ""
     configuration: {}
   

   This snippet matches the v1beta1 component shape used in published catalog designs and in the ready-made kubecon-logo model (schemaVersion, component.kind, nested model.name / model.version, and metadata.isAnnotation). It omits Kanvas-only styles.position fields. The Registry should supply the component’s SVG styling when the referenced model is registered. This exact append-and-update path has been checked against the schema and against Meshery source, but it has not been dry-run in the Playground.

3. Update the existing design: open it in the Design Configurator, paste the edited YAML into the editor, and click Update Design.

   mesheryctl design import always creates a new design (it posts to /api/pattern/import and does not update an existing ID). If you re-import the edited file, give it a new name, for example:

   mesheryctl design import -f kubecon-<your-handle>-design-with-logo.yaml -s "Meshery Design" -n kubecon-<your-handle>-design-with-logo
   

4. Confirm the logo component is in the design:

   mesheryctl design view kubecon-<your-handle>-design
   

5. Optional: update the Catalog request. If your Lab 1 publish request is still pending review, updating the same design is enough; the submitted request updates automatically. If you created a new design by re-importing, publish that new design. If the original design was already approved and is locked, clone it, add the logo to the clone, and publish the new design.