{"id":13495976,"url":"https://github.com/kuasar-io/kuasar","last_synced_at":"2025-03-28T17:34:31.701Z","repository":{"id":153410434,"uuid":"520314738","full_name":"kuasar-io/kuasar","owner":"kuasar-io","description":"A multi-sandbox container runtime that provides cloud-native, all-scenario multiple sandbox container solutions.","archived":false,"fork":false,"pushed_at":"2024-08-19T09:11:44.000Z","size":1340,"stargazers_count":1223,"open_issues_count":16,"forks_count":85,"subscribers_count":22,"default_branch":"main","last_synced_at":"2024-08-19T10:51:42.723Z","etag":null,"topics":["cloud-hypervisor","cloud-native","cncf","containerd","containers","cri","docker","microvm","oci","quark","rust","sandbox","wasmedge","webassembly"],"latest_commit_sha":null,"homepage":"https://kuasar.io","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/kuasar-io.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG/CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":"CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":"ROADMAP.md","authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-08-02T01:40:23.000Z","updated_at":"2024-08-16T22:06:02.000Z","dependencies_parsed_at":null,"dependency_job_id":"f8023e44-3d2e-4e06-bdda-ffcc34b21fca","html_url":"https://github.com/kuasar-io/kuasar","commit_stats":null,"previous_names":[],"tags_count":13,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kuasar-io%2Fkuasar","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kuasar-io%2Fkuasar/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kuasar-io%2Fkuasar/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kuasar-io%2Fkuasar/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kuasar-io","download_url":"https://codeload.github.com/kuasar-io/kuasar/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":222402848,"owners_count":16978747,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cloud-hypervisor","cloud-native","cncf","containerd","containers","cri","docker","microvm","oci","quark","rust","sandbox","wasmedge","webassembly"],"created_at":"2024-07-31T19:01:40.321Z","updated_at":"2024-10-31T11:30:35.228Z","avatar_url":"https://github.com/kuasar-io.png","language":"Rust","funding_links":[],"categories":["Rust","文章","webassembly","Runtimes \u0026 Platforms"],"sub_categories":[],"readme":"![](docs/images/logo.png)\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://github.com/kuasar-io/kuasar/actions/workflows/ci.yml\"\u003e\n    \u003cimg alt=\"GitHub Workflow Status\" src=\"https://github.com/kuasar-io/kuasar/actions/workflows/ci.yml/badge.svg?branch=main\"\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://cloud-native.slack.com/archives/C052JRURD8V\"\u003e\n    \u003cimg src=\"https://img.shields.io/badge/slack-join_chat-brightgreen.svg\" alt=\"chat\" /\u003e\n  \u003c/a\u003e\n  \u003cimg src=\"https://img.shields.io/badge/rustc-stable+-green.svg\" alt=\"supported rustc stable\" /\u003e\n  \u003ca href=\"https://github.com/kuasar-io/kuasar/blob/main/LICENSE\"\u003e\n    \u003cimg alt=\"GitHub\" src=\"https://img.shields.io/github/license/kuasar-io/kuasar?color=427ece\u0026label=License\u0026style=flat-square\"\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://github.com/kuasar-io/kuasar/graphs/contributors\"\u003e\n    \u003cimg alt=\"GitHub contributors\" src=\"https://img.shields.io/github/contributors/kuasar-io/kuasar?label=Contributors\u0026style=flat-square\"\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://app.fossa.com/projects/git%2Bgithub.com%2Fkuasar-io%2Fkuasar?ref=badge_shield\"\u003e\n    \u003cimg alt=\"FOSSA Status\" src=\"https://app.fossa.com/api/projects/git%2Bgithub.com%2Fkuasar-io%2Fkuasar.svg?type=shield\"\u003e\n  \u003c/a\u003e\n\u003c/p\u003e\n\nKuasar is an efficient container runtime that provides cloud-native, all-scenario container solutions by supporting multiple sandbox techniques. Written in Rust, it offers a standard sandbox abstraction based on the sandbox API. Additionally, Kuasar provides an optimized framework to accelerate container startup and reduce unnecessary overheads.\n\n# Supported Sandboxes\n\n| Sandboxer  | Sandbox          | Status          |\n|------------|------------------|-----------------|\n| MicroVM    | Cloud Hypervisor | Supported       |\n|            | QEMU             | Supported       |\n|            | Firecracker      | Planned in 2024 |\n|            | StratoVirt       | Supported       |\n| Wasm       | WasmEdge         | Supported       |\n|            | Wasmtime         | Supported       |\n|            | Wasmer           | Planned in 2024 |\n| App Kernel | gVisor           | Planned in 2024 |\n|            | Quark            | Supported       |\n| runC       | runC             | Supported       |\n# Why Kuasar?\n\nIn the container world, a sandbox is a technique used to separate container processes from each other, and from the operating system itself. After the introduction of the [Sandbox API](https://github.com/containerd/containerd/issues/4131), sandbox has become the first-class citizen in containerd. With more and more sandbox techniques available in the container world, a management service called \"sandboxer\" is expected to be proposed.\n\nKuasar supports various types of sandboxers, making it possible for users to select the most appropriate sandboxer for each application, according to application requirements.\n\nCompared with other container runtimes, Kuasar has the following advantages:\n\n+ **Unified Sandbox Abstraction**: The sandbox is a first-class citizen in Kuasar as the Kuasar is entirely built upon the Sandbox API, which was previewed by the containerd community in October 2022. Kuasar fully utilizes the advantages of the Sandbox API, providing a unified way for sandbox access and management, and improving sandbox O\u0026M efficiency.\n+ **Multi-Sandbox Colocation**: Kuasar has built-in support for mainstream sandboxes, allowing multiple types of sandboxes to run on a single node. Kuasar is able to balance user's demands for security isolation, fast startup, and standardization, and enables a serverless node resource pool to meet various cloud-native scenario requirements.\n+ **Optimized Framework**: Optimization has been done in Kuasar via removing all pause containers and replacing shim processes by a single resident sandboxer process, bringing about a 1:N process management model, which has a better performance than the current 1:1 shim v2 process model. The benchmark test results showed that Kuasar's sandbox startup speed 2x, while the resource overhead for management was reduced by 99%. More details please refer to [Performance](#performance).\n+ **Open and Neutral**: Kuasar is committed to building an open and compatible multi-sandbox technology ecosystem. Thanks to the Sandbox API, it is more convenient and time-saving to integrate sandbox technologies. Kuasar keeps an open and neutral attitude towards sandbox technologies, therefore all sandbox technologies are welcome. Currently, the Kuasar project is collaborating with open-source communities and projects such as WasmEdge, openEuler and QuarkContainers.\n\n# Kuasar Architecture\n\n![arch](docs/images/arch.png)\n\nSandboxers in Kuasar use their own isolation techniques for the containers, and they are also external plugins of containerd built on the new sandbox plugin mechanism. A discussion about the sandboxer plugin has been raised in this [Containerd issue](https://github.com/containerd/containerd/issues/7739), with a community meeting record and slides attached in this [comment](https://github.com/containerd/containerd/issues/7739#issuecomment-1384797825). Now this feature has been put into 2.0 milestone.\n\nCurrently, Kuasar provides three types of sandboxers - **MicroVM Sandboxer**, **App Kernel Sandboxer** and **Wasm Sandboxer** - all of which have been proven to be secure isolation techniques in a multi-tenant environment. The general architecture of a sandboxer consists of two modules: one that implements the Sandbox API to manage the sandbox's lifecycle, and the other that implements the Task API to handle operations related to containers.\n\nAdditionally, Kuasar is also a platform under active development, and we welcome more sandboxers can be built on top of it, such as Runc sandboxer.\n\n## MicroVM Sandboxer\n\nIn the microVM sandbox scenario, the VM process provides complete virtual machines and Linux kernels based on open-source VMMs such as [Cloud Hypervisor](https://www.cloudhypervisor.org/), [StratoVirt](https://gitee.com/openeuler/stratovirt), [Firecracker](https://firecracker-microvm.github.io/) and [QEMU](https://www.qemu.org/). **All of these vm must be running on virtualization-enabled node, otherwise, it won't work!**. Hence, the `vmm-sandboxer` of MicroVM sandboxer is responsible for launching VMs and calling APIs, and the `vmm-task`, as the init process in VMs, plays the role of running container processes. The container IO can be exported via vsock or uds.\n\nThe microVM sandboxer avoids the necessity of running shim process on the host, bringing about a cleaner and more manageable architecture with only one process per pod.\n\n![vmm](docs/images/vmm-arch.png)\n\n*Please note that only Cloud Hypervisor, StratoVirt and QEMU are supported currently.*\n\n## App Kernel Sandboxer\n\nThe app kernel sandbox launches a KVM virtual machine and a guest kernel, without any application-level hypervisor or Linux kernel. This allows for customized optimization to speed up startup procedure, reduce memory overheads, and improve IO and network performance. Examples of such app kernel sandboxes include [gVisor](https://gvisor.dev/) and [Quark](https://github.com/QuarkContainer/Quark).\n\nQuark is an application kernel sandbox that utilizes its own hypervisor named `QVisor` and a customized kernel called `QKernel`. With customized modifications to these components, Quark can achieve significant performance.\n\nThe `quark-sandboxer` of app kernel sandboxer starts `Qvisor` and an app kernel named `Qkernel`. Whenever containerd needs to start a container in the sandbox, the `quark-task` in `QVisor` will call `Qkernel` to launch a new container. All containers within the same pod will be running within the same process.\n\n![quark](docs/images/quark-arch.png)\n\n*Please note that only Quark is currently supported.*\n\n## Wasm Sandboxer\n\nThe wasm sandbox, such as [WasmEdge](https://wasmedge.org/) or [Wasmtime](https://wasmtime.dev/), is incredibly lightweight, but it may have constraints for some applications at present. The `wasm-sandboxer` and `wasm-task` launch containers within a WebAssembly runtime. Whenever containerd needs to start a container in the sandbox, the `wasm-task` will fork a new process, start a new WasmEdge runtime, and run the Wasm code inside it. All containers within the same pod will share the same Namespace/Cgroup resources with the `wasm-task` process.\n![wasm](docs/images/wasm-arch.png)\n\n## Runc Sandboxer\n\nExcept secure containers, Kuasar also has provide the ability for [runC](https://github.com/opencontainers/runc) containers. In order to generate a seperate namespace, a slight process is created by the `runc-sandboxer` through double folked and then becomes the PID 1. Based on this namespace, the `runc-task` can create the container process and join the namespace. If the container need a private namespace, it will unshare a new namespace for itself.\n\n![wasm](docs/images/runc-arch.png)\n\n# Performance\n\nThe performance of Kuasar is measured by two metrics:\n\n+ End-to-End containers startup time.\n+ Process memory consumption to run containers.\n\nWe used the Cloud Hypervisor in the benchmark test and tested the startup time of 100 PODs under both serial and parallel scenario. The result demonstrates that Kuasar outperforms open-source [Kata-containers](https://github.com/kata-containers/kata-containers) in terms of both startup speed and memory consumption.\n\nFor detailed test scripts, test data, and results, please refer to the [benchmark test](tests/benchmark/Benchmark.md). \n\n# Quick Start\n\n## Prerequisites\n\n### 1. OS\nThe minimum versions of Linux distributions supported by Kuasar are *Ubuntu 22.04* or *CentOS 8* or openEuler 23.03. \n\nPlease also note that Quark requires a Linux kernel version \u003e= 5.15.\n\n### 2. Sandbox\n\n+ MicroVM: To launch a microVM-based sandbox, a hypervisor must be installed on the **virtualization-enabled** host. \n  + It is recommended to install Cloud Hypervisor by default. You can find Cloud Hypervisor installation instructions [here](https://github.com/cloud-hypervisor/cloud-hypervisor/blob/main/docs/building.md).\n  + If you want to run kuasar with iSulad container engine and StratoVirt hypervisor, you can refer to this guide [how-to-run-kuasar-with-isulad-and-stratovirt](docs/vmm/how-to-run-kuasar-with-isulad-and-stratovirt.md).\n+ Quark: To use Quark, please refer to the installation instructions [here](docs/quark/README.md).\n+ WasmEdge: To start WebAssembly sandboxes, you need to install WasmEdge v0.13.5. Instructions for installing WasmEdge can be found in [install-a-specific-version-of-wasmedge](https://wasmedge.org/docs/start/install/#install-a-specific-version-of-wasmedge).\n\n### 3. containerd\n\nKuasar sandboxers are external plugins of containerd, so both containerd and its CRI plugin are required in order to manage the sandboxes and containers.\n\nWe offer two ways to interact Kuasar with containerd:\n\n+ **EXPERIMENTAL in containerd 2.0 milestone**: If you desire the full experience of Kuasar, please install [containerd under kuasar-io organization](docs/containerd.md). Rest assured that our containerd is built based on the official v1.7.0, so there is no need to worry about missing any functionalities.\n\n+ If the compatibility is a real concern, you need to install official containerd v1.7.0 with an extra [kuasar-shim](shim) for request forwarding, see [here](docs/shim/README.md). However, it's possible that this way may be deprecated in the future as containerd 2.0 evolves.\n\n### 4. crictl\n\nSince Kuasar is built on top of the Sandbox API, which has already been integrated into the CRI of containerd, it makes sense to experience Kuasar from the CRI level.\n\n`crictl` is a debug CLI for CRI. To install it, please see [here](https://github.com/kubernetes-sigs/cri-tools/blob/master/docs/crictl.md#install-crictl)\n\n### 5. virtiofsd\n\nMicroVMs like Cloud Hypervisor needs a virtiofs daemon to share the directories on the host. Please refer to [virtiofsd guide](https://gitlab.com/virtio-fs/virtiofsd).\n\n## Build from source\n\nRust 1.67 or higher version is required to compile Kuasar. Build it with root user:\n\n```shell\ngit clone https://github.com/kuasar-io/kuasar.git\ncd kuasar\nmake all\nmake install\n```\n\n\u003e Tips: `make all` build command will download the Rust and Golang packages from the internet network, so you need to provide the `http_proxy` and `https_proxy` environments for the `make all` command.\n\u003e\n\u003e If a self-signed certificate is used in the `make all` build command execution environment, you may encounter SSL issues with downloading resources from https URL failed. Therefore, you need to provide a CA-signed certificate and copy it into the root directory of the Kuasar project, then rename it as \"proxy.crt\". In this way, our build script will use the \"proxy.crt\" certificate to access the https URLs of Rust and Golang installation packages.\n\n## Start Kuasar\n\nLaunch the sandboxers by the following commands:\n\n+ For vmm: `nohup vmm-sandboxer --listen /run/vmm-sandboxer.sock --dir /run/kuasar-vmm \u0026`\n+ For quark: `nohup quark-sandboxer --listen /run/quark-sandboxer.sock --dir /var/lib/kuasar-quark \u0026`\n+ For wasm: `nohup wasm-sandboxer --listen /run/wasm-sandboxer.sock --dir /run/kuasar-wasm \u0026`\n+ For runc: `nohup runc-sandboxer --listen /run/runc-sandboxer.sock --dir /run/kuasar-runc \u0026`\n\n## Start Container\n\nSince Kuasar is a low-level container runtime, all interactions should be done via CRI in containerd, such as crictl or Kubernetes. We use crictl as examples:\n\n+ For vmm, quark or runc, run the following scripts:\n\n  `examples/run_example_container.sh kuasar-vmm`, `examples/run_example_container.sh kuasar-quark` or `examples/run_example_container.sh kuasar-runc`\n\n+ For wasm: Wasm container needs its own container image so our script has to build and import the container image at first.\n\n  `examples/run_example_wasm_container.sh`\n\n# Contact\n\nIf you have questions, feel free to reach out to us in the following ways:\n\n- [mailing list](https://groups.google.com/forum/#!forum/kuasar)\n- [slack](https://cloud-native.slack.com/archives/C052JRURD8V) | [Join](https://slack.cncf.io/)\n\n# Contributing\n\nIf you're interested in being a contributor and want to get involved in developing the Kuasar code, please see [CONTRIBUTING](CONTRIBUTING.md) for details on submitting patches and the contribution workflow.\n\n# License\n\nKuasar is under the Apache 2.0 license. See the [LICENSE](LICENSE) file for details.\n\nKuasar documentation is under the [CC-BY-4.0 license](https://creativecommons.org/licenses/by/4.0/legalcode).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkuasar-io%2Fkuasar","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkuasar-io%2Fkuasar","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkuasar-io%2Fkuasar/lists"}