Importing a Design

Learn how to import designs from various sources and formats, including Kubernetes manifests, Helm charts, Docker Compose files, and more.
Tags:
Categories:

Kanvas acts as a powerful bridge, enabling you to import your existing application and infrastructure configurations from a wide variety of standard formats. It transforms these configurations into visual, editable, deployable, and shareable designs. This guide covers how to import designs, the supported formats, and important considerations.

There are multiple ways to import a design.

1. From Kanvas:

The most direct method is to click the hamburger menu (☰) in the top-left corner, then select the “Import” button in the Kanvas toolbar.

File Import Process

2. From Layer5 Cloud:

Navigate to the My Designs page and click the “Import” button.

Cloud Import Process

3. Using Drag and Drop:

You can drag a file from your local computer directly onto the Kanvas canvas to import a design.

Drag and Drop Import

4. Via GitHub Integration:

For a more advanced, repository-based workflow, you can establish a persistent connection between your GitHub account and Meshery. This allows you to browse your repositories and import multiple designs directly.

Learn more about GitHub integration.

Kanvas supports a diverse set of infrastructure types and packaging formats. The following sections provide detailed requirements and instructions for each.

Importing from a Kubernetes manifest is the most direct way to bring your existing configurations into Kanvas. This method is suitable for any standard .yaml or .yml file that conforms to the Kubernetes API specification, as well as for projects managed by Kustomize.

1. Importing Plain Kubernetes Manifests: If you have Kubernetes configurations available as standard manifest files, you can import them directly.

  • Supported Packaging Formats: A standard .yaml or .yml file containing one or more Kubernetes resource definitions.

2. Importing a Kustomize Project: If you manage your Kubernetes configurations with Kustomize, a popular template-free tool for customization, you can import your entire project.

A key requirement when importing a Kustomize project is that you must provide the entire project directory, not just the kustomization.yaml file. This is because the kustomization.yaml file only contains instructions and references to other base manifest files. To correctly render the final configuration, Kanvas needs access to all of these related files.

  • Supported Packaging Formats: A .zip archive containing the complete Kustomize project directory, including the kustomization.yaml file and all of its referenced resources.

Helm is the standard package manager for Kubernetes. Importing a Helm chart into Kanvas allows you to visualize, manage, and customize complex applications. To ensure a successful import, you must provide the complete packaged chart. Importing individual chart files like Chart.yaml or values.yaml is not supported.

  • Supported Packaging Formats:
    • Chart Archive (.tgz, .tar, or .tar.gz): The standard gzipped tarball format for distributing Helm charts.
    • OCI Artifact: A modern packaging standard. When exported as a file for upload, this can be imported via an oci:// URI from a container registry.

This import method provides a convenient bridge for developers looking to migrate their applications from a local Docker-based environment to Kubernetes. Kanvas will parse your docker-compose.yaml file and automatically translate your services into their equivalent Kubernetes resources.

  • Supported Packaging Formats: A standard .yaml or .yml file. For best compatibility, ensure your Compose file includes a version key (e.g., version: '3.8') at the top level.

This is Meshery’s native format and provides a lossless way to save and import your designs. It preserves all of an application’s component configurations as well as the visual layout, annotations, and metadata from the Kanvas designer.

  • Supported Packaging Formats:
    • YAML File (.yml): The standard, human-readable file generated when you export a design.
    • OCI Artifact: Meshery Designs can also be packaged as OCI artifacts, allowing them to be versioned and distributed via container registries.

Each supported file will be imported as a separate, new design. For example, if you drag three different Kubernetes manifest files onto Kanvas, three distinct designs will be created.

The “File Upload” dialog is designed to process one file or package at a time. If you select multiple files in your operating system’s file browser, only the last file in the selection will be processed for import. To import from multiple files, please import them individually.

No. When a file is imported, it is converted into a native Meshery Design. The original source file is not stored and cannot be downloaded later. The export function will generate a new file based on the current state of your design.

For more details, see the Exporting Designs guide.

When you choose to merge a new design into an existing one, Meshery first creates a separate design from your imported file before performing the merge. You can find this newly created design on your My Designs page.

Yes. File Upload and URL Import are simple, one-time actions for importing a single design. In contrast, the GitHub Integration creates a deep, persistent connection to your GitHub account.

It requires you to authorize the Meshery GitHub App, which then allows you to browse your repositories and select designs directly from the Meshery UI. Most importantly, this integration can enable a GitOps workflow by adding a GitHub Action to your repository that provides visual snapshots of design changes in your pull requests.

There is no strict limit on the file size itself (e.g., in MB). However, there are limits on the number of components a design can contain, which is determined by your current subscription plan. Free accounts are limited to 100 components.

If you attempt to import a design that contains more components than your plan allows, the import will fail with a message stating that the component limit has been exceeded.

Learn more about plans.

Last modified July 11, 2025: Update content/en/kanvas/getting-started/import-designs.md (c98b04bb)

Related Videos

Recent Discussions on Kanvas