Overview

Using Meshery Designs to Manage Your Infrastructure

Meshery is a versatile platform designed to streamline the lifecycle, configuration, and performance management of infrastructure across Kubernetes clusters.

Designs in Meshery

Meshery employs the concept of Designs as a fundamental construct for managing infrastructure. Designs provide a structured way to organize and deploy various components of your infrastructure. To do so, Meshery utilizes a declarative approach to infrastructure management, similar to Kubernetes manifests. Meshery Designs are written in YAML and are validated against a schema.

Importing Existing Infrastructure and Applications

Meshery facilitates the import of infrastructure in multiple formats, including Kubernetes manifests, Helm Charts, and Docker Compose files. Import existing infrastructure definitions by directly from filesystem, via URL, or import directly from a GitHub repository.

  • Kubernetes Manifest
  • Meshery Design
  • Helm Charts
  • Docker Compose

See Importing Designs for more information.

Meshery Internals Provisioning Process

When a request is made to provision a design, it undergoes the following stages:

1. Import of Referenced Designs

A Design may reference any number of other Designs, in essence, a Design may import any number of other Designs. As an editor of a Design, you can make reference to another Design, while following principles of reusing and DRY (Do Not Repeat Yourself). Any referenced Design will subsequently be imported during the provisioning moment. To reference another design, do so by adding the following annotation

type: $(#use \)
in your Design file. The referenced design will be expanded from the source.

2. Identification

Meshery relies on components registered in its Registry. Only registered models and components can be managed with Meshery. Every registered model records the registrant that registered it - a connected Kubernetes cluster, Artifact Hub, GitHub, Meshery itself, or a deployed Meshery Adapter.

3. Validation

Components in the design are validated against the schema, ensuring consistency, similar to Kubernetes object validation but tailored for Designs.

4. Dependency Detection and Resolution

Deployment order comes from what the design declares. A component's dependsOn entries name other components of the same design, and each entry becomes an edge of the graph provisioning walks. Before anything is deployed, Meshery rejects a design whose dependencies name a component the design does not contain, name a component whose name is shared by more than one component, or form a cycle. The registrant plays no part in this: it decides who fulfills a component and what can be installed on the component's behalf, not what a component depends on.

Installing what a component needs before applying it - its Operators and CRDs - is that separate, registrant-specific behavior, and what Meshery is able to install depends on the source of the model:

  • Artifact Hub: Uses Helm Go client for Kubernetes Operator and CRD deployment via ApplyHelmChart().
  • Kubernetes YAML: Direct application with Kubernetes Go client (no auto-dependency handling).

This behavior is determined by the component’s host type:

if connection.Kind == "artifacthub" ➜ Helm Go client used
if connection.Kind == "kubernetes" ➜ Kubernetes Go client used

5. Provisioning

A Directed Acyclic Graph (DAG) generated in the previous step is processed. Dependent components are processed sequentially, while others are processed in parallel. Meshery intelligently handles the deployment order to ensure successful deployment.

A component is deployed only once every component it declares a dependency on has been deployed successfully. If one of those fails to apply, the component that depends on it is withheld rather than deployed, and is reported as such along with the dependency that failed; components that declared no dependency on the failed one are unaffected.

Each component is fulfilled by whoever registered its model: Meshery Server applies the component itself when that registrant is only a source of definitions, and delegates over gRPC to a Meshery Adapter when the registrant advertises a network endpoint. One design can use both paths in a single deployment. See Deployment Engine for both paths in full, and for what withholding does when a component's own prerequisites fail, when several clusters are selected, and when a design is undeployed.

Auto-Deployment of CRDs and Operators

Meshery automates the deployment of Custom Resource Definitions (CRDs) and operators based on the source from which a particular component was registered. By default, Meshery automatically deploys components that are sourced from Artifact Hub (utilizing Helm Charts). Support for OCI registries is expected in the near future.

Understanding CRDs and Why Deployment Order Matters

What is a CRD?

Custom Resource Definitions (CRDs) extend Kubernetes to support new resource types (e.g., VirtualService, Gateway). A CRD must be installed before any resource of that type is deployed, or you’ll encounter errors like “no matches for kind…”.

Why does Meshery only auto-deploy CRDs for ArtifactHub?

Helm Charts (used by ArtifactHub) are bundled with CRDs and operators, making it safe for Meshery to auto-deploy them via Helm Go client.

In contrast, Kubernetes YAML files may be minimal or incomplete. Meshery cannot assume what dependencies you intended. Therefore, Meshery avoids auto-deployment to prevent accidental conflicts or errors.

User Responsibility (for non-ArtifactHub components):

If you use Kubernetes YAML, ensure that all required CRDs and operators are included. Meshery will apply the YAML as-is using the Kubernetes Go client, but will not auto-deploy missing dependencies for you.

Related Reading