diff --git a/configs/cli.sidebar.json b/configs/cli.sidebar.json index 6bc05aba..732d0969 100644 --- a/configs/cli.sidebar.json +++ b/configs/cli.sidebar.json @@ -26,6 +26,10 @@ "title": "Building", "path": "/docs/cli/building" }, + { + "title": "Filesystem", + "path": "/docs/cli/filesystem" + }, { "title": "Running", "path": "/docs/cli/running" @@ -42,8 +46,12 @@ "summarize": true, "routes": [ { - "title": "`Kraftfile`", + "title": "Kraftfile (v0.6, latest)", "path": "/docs/cli/reference/kraftfile/latest" + }, + { + "title": "Kraftfile (v0.5)", + "path": "/docs/cli/reference/kraftfile/v0.5" } ] }, @@ -61,17 +69,9 @@ "title": "`kraft clean`", "path": "/docs/cli/reference/kraft/clean" }, - { - "title": "`kraft fetch`", - "path": "/docs/cli/reference/kraft/fetch" - }, { "title": "`kraft menu`", "path": "/docs/cli/reference/kraft/menu" - }, - { - "title": "`kraft prepare`", - "path": "/docs/cli/reference/kraft/prepare" } ] }, @@ -97,6 +97,10 @@ "title": "`kraft pkg push`", "path": "/docs/cli/reference/kraft/pkg/push" }, + { + "title": "`kraft pkg rm`", + "path": "/docs/cli/reference/kraft/pkg/rm" + }, { "title": "`kraft pkg source`", "path": "/docs/cli/reference/kraft/pkg/source" @@ -167,6 +171,50 @@ } ] }, + { + "title": "Kraft Cloud Commands", + "sort": false, + "open": true, + "summarize": true, + "routes": [ + { + "title": "`kraft cloud deploy`", + "path": "/docs/cli/reference/kraft/cloud/deploy" + }, + { + "title": "`kraft cloud img ls`", + "path": "/docs/cli/reference/kraft/cloud/img/ls" + }, + { + "title": "`kraft cloud inst create`", + "path": "/docs/cli/reference/kraft/cloud/instance/create" + }, + { + "title": "`kraft cloud inst delete`", + "path": "/docs/cli/reference/kraft/cloud/instance/delete" + }, + { + "title": "`kraft cloud inst logs`", + "path": "/docs/cli/reference/kraft/cloud/instance/logs" + }, + { + "title": "`kraft cloud inst ls`", + "path": "/docs/cli/reference/kraft/cloud/instance/ls" + }, + { + "title": "`kraft cloud inst start`", + "path": "/docs/cli/reference/kraft/cloud/instance/start" + }, + { + "title": "`kraft cloud inst status`", + "path": "/docs/cli/reference/kraft/cloud/instance/status" + }, + { + "title": "`kraft cloud inst stop`", + "path": "/docs/cli/reference/kraft/cloud/instance/stop" + } + ] + }, { "title": "Miscellaneous Commands", "sort": false, diff --git a/content/blog/2023-11-15-kraftkit-v0.7.0-released.mdx b/content/blog/2023-11-15-kraftkit-v0.7.0-released.mdx new file mode 100644 index 00000000..eb8444eb --- /dev/null +++ b/content/blog/2023-11-15-kraftkit-v0.7.0-released.mdx @@ -0,0 +1,379 @@ +--- +title: "KraftKit v0.7.0 Release" +description: | + A massive update to a unikernel developer's best friend. +publishedDate: 2023-11-15 +authors: +- Alexander Jung +- Cezar Craciunoiu +tags: +- release +- announcement +image: /images/kraftkit-v0.7.0.png +--- + +In the world of modern software development, it's crucial to stay ahead of the curve and embrace cutting-edge technologies. +Unikernels, which are specialized, single-address-space machine images that run a single application, have been gaining traction as a powerful approach to building lightweight, secure, and highly efficient software systems. + +Unikraft, an open-source project for building unikernels, has been at the forefront of this movement. +It offers developers a versatile and efficient framework to create unikernels for various use cases. +And today, we're thrilled to introduce KraftKit v0.7.0, a huge update to the companion command-line tool that makes Unikraft even more accessible and developer-friendly! + + +For the full changelog, check out [the release note on GitHub](https://github.com/unikraft/kraftkit/releases/tag/v0.7.0). + + +With a whole slew of new features and improvements, KraftKit v0.7.0 is a game-changer for unikernel development. +Let's dive into the exciting new features and improvements in this release: + + +## `Kraftfile` v0.6 Specification Update + +This release introduces a new `Kraftfile` specification which makes new adjustments to the user's workflow such that it is easier to run applications in binary compatibility mode and with a template. +At a high-level, the following adjustments are made to the specification: + +- A new top-level `runtime` element to be used for defining the user of an elfloader or existing pre-built unikernel image. + Similar to other component-type elements like `unikraft` and `libraries`, the `runtime` element is intended to allow for a short-hand and long-hand syntax where a `source`, `version` and set of `kconfig` options can be used to qualify the elfloader application. +- Abbreviations of the `specification`, `architecture` and `platform` element names such that can be used in short-hand syntax as `spec`, `arch` and `plat`, respectively. +- Top-level `volumes` element which is used for defining user-specified paths which are to be used during runtime of a unikernel. +- Top-level `rootfs` element which is used for defining the root filesystem of the user. + The provided implementation allows a user to serialize a filesystem from three new contexts: an existing CPIO archive (passthrough), a path to a directory, and a `Dockerfile` which is constructed via [BuildKit](https://github.com/moby/buildkit). +- Top-level `cmd` which is a string or list which represents the command-line argument to execute for the unikernel as a way to porclain the Kraftfile and the intended application usecase. + +Aside from these introductions to the v0.6 specification, the underlying parser is adjusted to handle reading both the specifications and defaulting to v0.6 as the latest. +These adjustments are subsequently implemented through the release. + + +### High-level `Kraftfile` v0.6 specification changes + +#### A. Introduction of short-hand syntaxes + +1. In addition to bumping the specification version to v0.6, the `specification` element can be abbreviated to `spec`: + + ```yaml + spec: v0.6 + ``` + +2. Within the list of `targets`, the `architecture` and `platform` attributes can be abbreviated to `arch` and `plat`, respectively, and be used interchangeably: + + ```yaml + targets: + - plat: qemu + arch: x86_64 + ``` + + ```yaml + targets: + - plat: qemu + architecture: x86_64 + ``` + + ```yaml + targets: + - platform: qemu + arch: x86_64 + ``` + +3. The list of targets can now accept an even shorter syntax where only the architecture and platform are desired in the list: + + ```yaml + targets: + - qemu/x86_64 + ``` + + This shorthand syntax can be mixed with full target elements: + + ```yaml + targets: + - qemu/x86_64 + - platform: qemu + architecture: arm64 + - plat: fc + arch: x86_64 + ``` + +#### C. Introduction of a `cmd` element for specifying program operation + +The `cmd` is array or string element which can be used for setting default arguments to be used during the instantiation of a new unikernel instance: + +1. Specified as an in-line array: + ```yaml + spec: v0.6 + + cmd: ["-c", "/nginx/conf/nginx.conf"] + ``` + +2. Specified as a multi-line array: + ```yaml + spec: v0.6 + + cmd: + - -c + - /nginx/conf/nginx.conf + ``` + +3. Specified as a string: + ```yaml + spec: v0.6 + + cmd: "-c /nginx/conf/nginx.conf" + ``` + +#### C. Introduction to `runtime` element for accessing pre-built images + +The `runtime` element is a new top-level element which has been designed to ease the declaration of a previously constructed unikernel image in the project. +In many cases, specifically instances where the user is writing in a high-level language such as Python or where they wish to use a pre-built Linux userpace image, the user does not care for wanting to build a unikernel image from scratch. +Instead, the goal is to leverage pre-built unikernel images which are distributed using the [OCI Package Manager](https://github.com/unikraft/kraftkit/pull/339). + +Similar to the top-level `unikraft` and `template` elements (see below), the `runtime` element can be specified using a short-hand syntax or a long-hand syntax for greater control or preference. + +1. In short-hand syntax, simply referencing the pre-built unikernel image is possible by declaring: + ```yaml + spec: v0.6 + + runtime: unikraft.org/nginx:latest + ``` + In the above example, the `runtime` element refers to an OCI archive for NGINX. + In a `kraft run` scenario, this is simply pulled and executed verbatim. + Paired with the ability to customize the `rootfs` element or `volumes` elemen, the `runtime` element becomes more pragmatic: + ```yaml + spec: v0.6 + + runtime: unikraft.org/nginx:latest + + rootfs: ./ + ``` + Or with a volume, which simply "overwrites" an existing directory already located within NGINX's root filesystem that is distributed as part of the OCI image: + ```yaml + spec: v0.6 + + runtime: unikraft.org/nginx:latest + + volumes: + - ./html:/nginx/html + ``` + In the above snippet, the user customizes only the directory which serves HTML with a path `./html` which is located on their host. + + Note that this usecase is not limited to a single application and applies to the ELF Loader application and customizing the loaded application which is part of a root filesystem: + ```yaml + spec: v0.6 + + # Default ELF Loader application + runtime: loaders.unikraft.org/default:latest + + # Path must contain the Linux ELF binary, e.g. at ./rootfs/helloworld + rootfs: ./rootfs + + cmd: ["/helloworld"] + ``` + or a high-level programming language such as python3: + ```yaml + spec: v0.6 + + runtime: unikraft.org/python3:latest + + rootfs: ./Dockerfile + + cmd: ["/main.py"] + ``` + In the above snippet, the user has created a `Dockerfile` which contains the necessary root filesystem and included their application at `/main.py`. + +2. The long-hand syntax allows specifically setting `source`, `version` and `kconfig` options which are requirements of the runtime: + ```yaml + spec: v0.6 + + runtime: + source: unikraft.org/nginx + version: latest + kconfig: + CONFIG_LIB9PFS: 'y' + ``` + In the above example, the a pre-built NGINX unikernel has been requested as the runtime with the explicit option of having the 9P Filesystem enabled. + +#### D. Fully realizing the `template` element + +There were several issues related to the `template` element, including the fact that it was not properly seeded, or transformed, from the `Kraftfile` into the application structure. +This has now been tested end-to-end and enables: + +1. Workflows where a user may wish to reference an existing application repository and make customizations, for example, with the [ELF Loader](https://github.com/unikraft/app-elfloader.git) application, making changes to the core configuration and adding additional targets: + ```yaml + spec: v0.6 + + template: https://github.com/unikraft/app-elfloader.git + + unikraft: + version: stable + kconfig: + CONFIG_LIBUKLIBPARAM: 'y' + CONFIG_LIBNOLIBC: 'y' + CONFIG_LIBNOLIBC_UKDEBUG_ASSERT: 'y' + CONFIG_LIBPOSIX_EVENT: 'y' + CONFIG_LIBPOSIX_FUTEX: 'y' + CONFIG_LIBPOSIX_MMAP: 'y' + CONFIG_LIBPOSIX_releaseOCESS: 'y' + CONFIG_LIBPOSIX_releaseOCESS_PIDS: 'y' + CONFIG_LIBPOSIX_releaseOCESS_MAX_PID: 31 + CONFIG_LIBPOSIX_releaseOCESS_CLONE: 'y' + CONFIG_LIBPOSIX_SOCKET: 'y' + CONFIG_LIBPOSIX_SYSINFO: 'y' + CONFIG_LIBPOSIX_TIME: 'y' + CONFIG_LIBPOSIX_USER: 'y' + CONFIG_LIBUKSIGNAL: 'y' + CONFIG_LIBSYSCALL_SHIM: 'y' + CONFIG_LIBVFSCORE_AUTOMOUNT_ROOTFS: 'y' + CONFIG_LIBVFSCORE_ROOTFS_INITRD: 'y' + CONFIG_LIBVFSCORE_ROOTFS: "initrd" + CONFIG_APPELFLOADER_VFSEXEC_EXECBIT: 'n' + + targets: + - plat: qemu + arch: x86_64 + kconfig: + CONFIG_VIRTIO_BUS: 'n' + - plat: firecracker + arch: x86_64 + ``` + +3. Similar to other component elements (e.g. `unikraft` and `libraries`), the `template` element can be expressed in a longer format: + ```yaml + spec: v0.6 + + template: + source: https://github.com/unikraft/app-elfloader.git + version: stable + ``` + +### New workflow scenarios + +The following workflow scenarios were used during testing. + +#### A. Using a pre-built unikernel and customizing the root filesystem + +Customizing the whole root filesystem is now possible by supplying either: + +1. A path representing a prebuilt CPIO archive file: + ```yaml + spec: v0.6 + + runtime: unikraft.org/nginx:latest + + rootfs: ./initramfs.cpio + ``` + +4. A directory which will be dynamically serialized into a CPIO archive: + ```yaml + spec: v0.6 + + runtime: unikraft.org/nginx:latest + + rootfs: ./rootfs/ + ``` + +5. Or, a `Dockerfile` which will be built via BuildKit and then serialized into a new CPIO archive: + ```yaml + spec: v0.6 + + runtime: unikraft.org/nginx:latest + + rootfs: ./Dockerfile + ``` + To use BuildKit, set the address within the new `buildkit_host` user setting, the new environmental variable `KRAFTKIT_BUILDKIT_HOST` or the command-line flag `--buildkit-host`. + This defaults to `unix:///run/buildkit/buildkitd.sock`. + + +#### B. Using a pre-built unikernel and mounting a path within the root filesystem + +1. Specifying via short-hand syntax a map between a directory on the host and a path within the instance: + ```yaml + spec: v0.6 + + runtime: unikraft.org/nginx:latest + + volumes: + - ./src:/nginx/html + ``` + +2. Using a more verbose (long-hand) syntax and mapping between the mount on the host and a path within the instance: + ```yaml + spec: v0.6 + + runtime: unikraft.org/nginx:latest + + volumes: + - source: ./src + destination: /nginx/html + ``` + + +## OCI Indexes and Multi-Platform Images + + +This contains breaking changes to the OCI package manager. +As a result, when you upgrade be sure to re-package and re-push your OCI images. + + +This large refactor reworks the OCI package manager to assume the use of the OCI image specification's index such that we can represent multiple manifests within a single canonical referencable name. +This means that we can build multiple unikernels with the same name. +This makes sense for multi-target projects which build the same application but target different hardware/platform vendors. + +The structure of the index can be found [here](https://github.com/opencontainers/image-spec/blob/main/image-index.md) and in this implementation we itemized each manifest in the index in the same way. +When we use the `Catalog` method now, we are able to query a remote registry based on the selected OS (platform) and architecture as well as any embedded KConfig options (if they are embedded). + +When packaging multiple targets of a single application, the resulting package will be listed for all unique targets: + +```console +kraft pkg ls --apps +``` +``` +TYPE NAME VERSION FORMAT DIGEST PLAT +app helloworld latest oci e8be0a9 qemu/x86_64 +app helloworld latest oci a6802f4 qemu/arm64 +``` + +Use cases include selecting appropriately based on the host's architecture as well as feature selection via embedded KConfig options. + +Notable additional improvements which are incorporated in this pull request include: +- Better offline mode in each package manager: all internal package managers were optimized to reduce instantiation time which makes a noticeable impact when using `kraft` in offline mode; +- Better outputs in `kraft pkg ls` which now has dynamic column data information; +- Better prompts in `kraft pkg` for selecting and packaging individual targets from an application project; +- `kraft pkg prune` has been renamed to `kraft pkg rm` and now works for all underlying implementations (per-manifest type for libraries and components, and directory and containerd for OCI packages); +- Better handling of insecure authenticated OCI registries; and, +- Natively selecting the host platform and architecture in `kraft pkg pull` when no additional flags are provided. + + +## A New Pre-built Community Image Catalog + +Following the ability to package multiple platform/architecture combinations now +using a single canonical OCI image reference, and to help ease using pre-built +unikernel applications, we're ecited to release a new community catalog of +pre-built unikernel images, ready to use. + + +See [the new open-source catalog on +GitHub](https://github.com/unikraft/catalog). + + +```console +kraft pkg ls --apps --update +``` + +## Dockerfile root filesystem creation via BuildKit + +This release includes the ability to construct root filesystems from new and existing `Dockerfile` definitions. +This is made possible by rearchitecting [the `initrd` package](https://pkg.go.dev/kraftkit.sh@v0.7.0/initrd) to support different input types. +When using a root filesystem which is ultimately serialized into a CPIO archive (including previously built CPIO archives which simply represent a no-op), these can be dynamically built. + +Using `Dockerfile` via BuildKit to build root filesystems offers several advantages in terms of efficiency, portability, and ease of management which were considered before implementation: + +1. **Reproducibility** + - A `Dockerfile` enables you to specify the exact steps needed to build your filesystem, making the build process reproducible. + - BuildKit's caching mechanisms enhance build efficiency by reusing layers when the dependencies and source code haven't changed, which speeds up the build process. + +2. **Portability** + - BuildKit supports multi-platform builds, enabling you to create filesystems for different architectures without changing the `Dockerfile`. + +3. **Ease of Use** + - A `Dockerfile` provides a user-friendly, human-readable format for defining the build steps, making it accessible to developers with varying levels of expertise. + - Leveraging the extensive Docker ecosystem and allowing the re-usse of many existing filesystems which speed up using unikernels + +To get started building `Dockerfile`s as part of your existing project, check out the updated documentation on [filesystem support in KraftKIt](/docs/cli/filesystem#building-and-packaging-a-static-initram-root-filesystem). diff --git a/content/docs/cli/filesystem.mdx b/content/docs/cli/filesystem.mdx new file mode 100644 index 00000000..69d4187a --- /dev/null +++ b/content/docs/cli/filesystem.mdx @@ -0,0 +1,358 @@ +--- +title: "Filesystems" +description: | + One important aspect of the lifecycle of a unikernel is access to a + filesystem, which provides the necessary files and resources required for your + application. +--- + +A filesystem serves as the underlying structure that allows an operating system to store, retrieve, and organize files on storage mediums. +Whether it's a traditional server or virtual machine, or a more specialized environment like a unikernel, the role of a filesystem remains the same: to enable the reading and writing of data. + + +## The Role of Filesystems in Unikernels + +At its core, the primary purpose of a filesystem in a unikernel is to provide a structured and efficient means of organizing and accessing data. +Unikernels, as single-address-space machine images tailored for specific applications, operate in highly specialized environments where resource constraints and performance optimization are paramount. +The filesystem in a unikernel must strike a delicate balance between providing necessary storage functionality and minimizing the footprint to adhere to the lightweight philosophy of unikernels. + +In addition to storage, filesystems in unikernels play a vital role in facilitating I/O operations, ensuring that applications can seamlessly interact with external data, network resources, and other system components. +As unikernels are designed for specific use cases, their filesystems often incorporate optimizations to cater to the unique requirements of the targeted applications, whether they be microservices, network appliances, or other specialized workloads. + +The choice and design of a filesystem for unikernels necessitates a thoughtful approach to address the distinct challenges posed by this model. +Considerations such as minimalism, performance, security, and compatibility with the unikernel's targeted application as well as the environment in which will operate are crucial in shaping the filesystem architecture. +The goal of this documentation is to explore these design considerations in depth, providing insights into how developers can tailor filesystem solutions in Unikraft to enhance the efficiency and functionality of unikernel-based applications. + +In this documentation, you will be guided in different approaches to building support for a filesystems, the different ways in which filesystems are used throughout the lifecycle of a unikernel (both at compile-time and at runtime), the ways for realising those filesystems, using them and populating (or seeding) filesystems to the unikernel application. +Ultimately, this will enable you to design and use one or many filesystems for your unikernel application appropriately. + + +## Root Filesystems + +The first consideration to make when approaching the customisation of the filesystem in general is to start with the root filesystem. +A root filesystem is a filesystem tree mounted at the root (`/`) directory and is a fundamental component of any operating system which provides the essential files, subdirectories, and resources required for the system to function. +Typically, it serves as the foundation upon which the operating system operates and runs applications. +For Unikraft, however, the use of a root filesystem is totally optional and depends on the specific requirements of your application. + +Thanks to Unikraft's highly modular structure, building a unikernel with root filesystem support is both trivial and left up to the application developer and ultimately the application use case. +Some unikernels may not require a filesystem at all if the application does not read or write any files. +In this case, neither the underlying filesystem subsystem (`vfscore`) or a root filesystem can are compiled into the unikernel binary. +For example, this may be use in lambda-type usecases. +However, many applications do need access to files, configuration data, a temporary file directory scratch pad (e.g. `/tmp`) or other have file-based resource needs. +In such cases, a root filesystem is essential. + + +### Classes of Root Filesystems + +Unikraft supports essentially two classes of root filesystems: initial ramdisks ("initrd" or "initram" for short) and external volumes. +Both classes can be implemented using different underlying driver formats depending on preference or requirements. +Additionally, their use of either is not mutually exclusive, making for highly versatile unikernel configurations. +These different configurations are shown in Figure 1 and are discussed in depth in the following sections: + +a. [Initial Ramdisk Filesystem (initramfs)](#initial-ramdisk-filesystem-initramfs) + +b. [Embedded Initial Ramdisk Filesystems (einitrds)](#embedded-initial-ramdisk-filesystems-einitrds) + +c. [External Volumes](#external-volumes) + +d. [Mixing and Matching Filesystems](#mixing-and-matching-filesystems) + + + + +#### Initial Ramdisk Filesystem (initramfs) + +Traditionally, initramfs is a temporary root filesystem used during the initial stages of the boot sequence of an operating system to to set up the environment before transitioning to the real root filesystem. +The initram is loaded into volatile memory (RAM) making it both ephemeral but also performant. +With Unikraft, however, it can be used as the permenant (though non-persistent) root filesystem during the lifecycle of a unikernel application. +This is a common approach with unikernels, and can be compared to the resulting filesystem which is generated after building a `Dockerfile` (see later [how to use a `Dockerfile` to generate a rootfs](#building-and-packaging-a-static-initram-root-filesystem)). + +Traditionally, the initram filesystem is provided as an external archive file and virtual machine monitors have specific options to allow setting the path to this archive file. +For example, with QEMU this is handled via the `-initrd` flag. This root filesystem configuration can be seen in [Figure 1 (a)](#classes-of-root-filesystems). + + +When instantiating a unikernel image with an external initramfs and when specifying an amount of memory, you must supply at least the size of the initramfs as minimum amount of memory because this file will be loaded directly into memory during boot time. +`kraft` will warn you if specify an amount of memory less than the size of the external initram archive. +If you do not specify an amount of memory, `kraft` will attempt to intelligently determine the minimum amount of memory necessary for instantiating the unikernel. + + +Initram is a simple and effective way of populating an initial tree of data as the root filesystem (also known as "seeding the root filesystem") to the unikernel during boottime and giving the application access to essential files for use during its runtime. +Throughout the lifecycle of the application, this root filesystem is held in memory (via [Unikraft's internal library `ramfs`](https://github.com/unikraft/unikraft/tree/staging/lib/ramfs)) and therefore it is not persistent. +A good example of use cases for such filesystems are static configuration files; e.g `/etc/resolv.conf` for dynamic name resolution (used in most standard libc's) or static configuration files used by your application (such as [NGINX's config files](https://github.com/unikraft/catalog/blob/main/library/nginx/1.15/rootfs/nginx/conf/nginx.conf)). +These files do not change often (or at all) once they are initially written and therefore make for good candidates to be placed within initramfs (or as embedded initramfs as you'll discover in the next section). + +Towards optimizing against a performance-oriented KPI, initramfs is a good choice since its underlying hardware implementation is backed by RAM. +The trade-off however is that this filesystem is delivered statically and will not change following the end-of-life of a unikernel (i.e. after a restart). +The contents of such a filesystem is often created and updated during the process of Continious Integration / Continious Delivery (CI/CD) wherein the files required by an application are built and packaged together (see how this is done in a [GitHub Actions workflow](/docs/getting-started/integrations/github-actions)) but requires the unikernel to be redeployed in order for those filesystem changes to be realized. + + +To use an initramfs in your unikernel, you must ensure it is built with the following additional KConfig options set in your `Kraftfile`: +```yaml +unikraft: + kconfig: + # For using an external initrd archive you will need + # to enable Unikraft's VFS subsystem: + CONFIG_LIBVFSCORE: 'y' + + # For any use of initrd you will need to enable: + CONFIG_LIBRAMFS: 'y' + + # For automatic mounting of the initramfs during boot. + # Note this configuration prevents the unikernel from + # using anything else other than initrd as the rootfs. + CONFIG_LIBVFSCORE_AUTOMOUNT_ROOTFS: 'y' + CONFIG_LIBVFSCORE_ROOTFS_INITRD: 'y' + CONFIG_LIBVFSCORE_ROOTFS: "initrd" + + # Alternatively, for dynamic mounting, wherein you + # configure mounting options at boot time via + # kernel command-line arguments: + CONFIG_LIBVFSCORE_FSTAB: 'y' +``` + + + +See below the list of supported initramfs archive formats. +In addition to the KConfig specified above, the relevant format's KConfig option will also need to be set. + +| Format | KConfig Option | Description | +|--------|------------------|-------------| +| `cpio` | `CONFIG_LIBCPIO` | CPIO (Copy-In, Copy-Out) archives are uncompressed or minimally compressed to keep them simple and efficient. This format is seamlessly integrated into KraftKit, meaning unless you specifically wish to use an alternative format, you need not worry about alternatives. | + +More formats, such as tarballs, are planned: [follow the GitHub Project board](https://github.com/orgs/unikraft/projects/24/views/13). + + + +#### Embedded Initial Ramdisk Filesystems (einitrds) + +Unikraft supports embedding the initram archive file within the kernel binary directly as shown in [Figure 1 (b)](#classes-of-root-filesystems). +This is often used when the coupling between the application and the initial root filesystem is particularly strong. +Naturally, the caveat of this approach is that if this filesystem requires updating, then the unikernel image needs to be re-built and redeployed. +However, in embedding an initial root filesystem into the kernel binary image, it frees up the original initram parameter which is typically supplied to a virtual machine monitor (e.g. QEMU's `-initrd` flag has become free to be used by another initramfs file). +This allows for a new possibility of mounting an external initram archive file to a subdirectory within this root filesystem. +This provides some degree of on-the-fly customization, where a second initramfs can be used to change the a portion of the unikernel's filesystem and therefore operation, without having to re-compile the unikernel binary image. +Since initramfs is intended for high-performance applications, both the einitrd and the dynamically supplied initrd will be stored in volatile RAM. + +There are several additional reasons why one may wish to embed the initram into the unikernel, including: + +- Wishing to enforce strict and static application required files are always present such that the unikernel binary can act in a standalone manner and is guaranteed runtime operation; +- Similarly, to prevent corruption or malicious intent by reducing the attack surface by removing the possibility of injecting a different initrd at boot time and embedding these into a single binary as opposed to a binary and an external initramfs archive file; or, +- To enforce strict performance guarantees when accessing certain files within the root filesystem which are non-persistent. + + +To use embedded initramfs in your unikernel, you must ensure it is built with the following additional KConfig options set in your `Kraftfile`: +```yaml +unikraft: + kconfig: + # For using embedded initrd you will need to enable + # Unikraft's VFS subsystem: + CONFIG_LIBVFSCORE: 'y' + + # For any use of einitrd you will need to enable: + CONFIG_LIBRAMFS: 'y' + CONFIG_LIBCPIO: 'y' + CONFIG_LIBVFSCORE_ROOTFS_EINITRD: 'y' + + # To force using the embedded initrd persistently + # you can set the automount flag: + CONFIG_LIBVFSCORE_AUTOMOUNT_ROOTFS: 'y' + + # Alternatively, for dynamic mounting, wherein you + # configure mounting options at boot time via + # kernel command-line arguments: + CONFIG_LIBVFSCORE_FSTAB: 'y' + + # If you've set `rootfs` to a directory or a Dockerfile, + # this will be the default location of its output. + CONFIG_LIBVFSCORE_ROOTFS_EINITRD_PATH: .unikraft/build/initramfs.cpio +``` + + + +#### External Volumes + +In contrast, the longevitiy of the initram makes it unsuitable for applications which rely on persistent storage, i.e. having made changes to a filesystem to be persisted after restarting the unikernel which is often necessary for database applications like Postgres or MongoDB, but great for stateless memory instensive systems like Redis or NGINX. + +In the context of storage and file systems, a volume typically refers to a partition or logical storage unit on a physical or virtual disk. +Volumes are usually formatted with a file system (e.g., NTFS, ext4) and can contain directories and files. +Unikraft also considers the use of a host path mapping as a type of volume (e.g. the use of [the 9P filesystem](https://github.com/unikraft/unikraft/tree/staging/lib/9pfs)). + +Traditionally, volumes are typically associated with long-term data storage, not just for boottime operations. +However, Unikraft supports using volumes as the root filesystem and supports different volume drivers, which are included at compile-time, shown in [Figure 1 (c)](#classes-of-root-filesystems), which enable you to attach external resources to the unikernel application at runtime. +Because of this ability, it is possible to mount a volume to the root path of the unikernel. + +There are number of reasons why you may wish to or not to mount an external volume as the root filesystem: + +- **Decreasing package size**: + Using a persistent volume to store larger files can be used to mitigate against packaging a unikernel with such files and reducing the transport and storage cost of the image. + Instead, the volume gets access to larger, locally stored artifacts which intended to be used. +- **Initialization (boot-time) performance**: + Loading artifacts into memory at boot can incur a performance penality. + Instead, the initialization of a volume driver to access an external filesystem can be faster. +- **Shared file resources**: + Multiple unikernel instances can utilize the same external volume. + Typically these volumes are read-only and the unikernel instances represent replicas where one unikernel instance may have read-write privileges. +- **When reading and writing to the volume is not performance critical**: + Whilst it is possible to use high-performance volume drivers with Unikraft, you cannot guarantee their performance (since they represent an external system) whereas you can with embedded initramfs since it is the same encapsulated system. +- **For bi-directional communication between host and the unikernel instance**: + This is often used during development of a unikernel when the filesystem is under-going rapid changes which require real-time reflection in the unikernel. + + +Configuration options per driver will vary, including their microlibrary name. +Regardless, to facilitate the use of a root filesystem you will need to at least enable`vfscore`: +```yaml +unikraft: + kconfig: + # For using volumes you will need to enable Unikraft's + # VFS subsystem: + CONFIG_LIBVFSCORE: 'y' + + # For automatic mounting of a specific volume + # driver during boot. Note this configuration + # prevents the unikernel from using anything else + # other than the selected driver. You must + # also set appropriate ROOTFS KConfig options. + # Refer to the driver's and vfscore's Config.uk + # for more information. + CONFIG_LIBVFSCORE_AUTOMOUNT_ROOTFS: 'y' + + # Alternatively, for dynamic mounting, wherein you + # configure mounting options at boot time via + # kernel command-line arguments: + CONFIG_LIBVFSCORE_FSTAB: 'y' +``` + + + +See below the list of supported volume drivers. +In addition to the KConfig specified above, the relevant driver's KConfig option will also need to be set. + +| Driver | KConfig option | Use case | +|--------|------------------|----------| +| `9pfs` | `CONFIG_LIBUK9P` | Bi-directional communication between a path on the host and a directory within the unikernel. Learn more about [the 9P (protocol)](https://en.wikipedia.org/wiki/9P_(protocol)). | + +More drivers are planned: [follow the GitHub Project board](https://github.com/orgs/unikraft/projects/24/views/13). + + +To use volume mounts in your unikernel, the `-v|--volume` flag accepts the source directory mapped to a path in the unikernel separated by a colon `:` delimiter, like so: + +```bash +kraft run -v ./rootfs:/ unikraft.org/nginx:latest +``` + +In the above example, relative directory `./rootfs` is mapped to the root of the unikernel instance located at `/`. + +Alternatively, for a reproducible setup, it is also possible to [set the list of volumes in the `Kraftfile`](/docs/cli/reference/kraftfile/latest#top-level-volumes-attribute). + + +#### Mixing and Matching Filesystems + +It is possible to mix-and-match or provide sub-paths by using multiple volumes, which is shown in [Figure 1 (d)](#classes-of-root-filesystems). +For example, supplying an initial root filesystem as a CPIO archive and then mounting only a sub-directory where you would like to see changes at runtime: + +```bash +kraft run --rootfs ./rootfs.cpio -v ./html:/nginx/html unikraft.org/nginx:latest +``` + +In the above example, an initial ramdisk is provided which supplies the unikernel with a root filesystem provided by the CPIO archive in the relative path `./rootfs.cpio` and we "overwrite" the contents in this filesystem at `/nginx/html` with the contents on the host at the relative directory at `./html`. +This allows you to dynamically change the served content by the NGINX instance. + + +Using pre-built unikernels [which are packaged as OCI images](/docs/cli/packaging#oci-based-packages) may come with a ready made initramfs which will automatically set a root filesystem. +This means that you may wish to only set a volume to "overwrite" a particular directory with the contents you wish to modify. +For example, with the NGINX image example supplied above, you need simply to run the following to incur dynamic changes to the served content: + +```bash +kraft run -v ./html:/nginx/html unikraft.org/nginx:latest +``` + + + +## Building and packaging a static initram root filesystem + +After enabling and building the support for [non-persistent root filesystem via initramfs](#initial-ramdisk-filesystem-initramfs) in your unikernel application, seeding this initial root filesystem can also be done in a number of ways with `kraft` and again depends on use case. +It can take on different underlying forms and serve distinct purposes in various computing environments. + +To supply a static initram archive as your root filesystem you can either use the `--rootfs` flag when packaging or running unikernels via `kraft`, e.g.: + +```bash +# Packaging a unikernel with static root filesystem archive +kraft pkg --rootfs ./rootfs.cpio --name unikraft.org/nginx:latest . + +# Running a unikernel with the supplied root filesystem archive +kraft run --rootfs ./rootfs.cpio unikraft.org/nginx:latest +``` + +Or you can set this in the [`Kraftfile` element for `rootfs`](/docs/cli/reference/kraftfile/latest#top-level-rootfs-attribute): + +```yaml ln={5} +spec: v0.6 + +runtime: unikraft.org/nginx:latest + +rootfs: ./rootfs +``` + +In the examples above, the supplied argument to "`rootfs`" (whether at the CLI or in a `Kraftfile`) can have an argument which is of three possible types which are intelligently determined by `kraft`: + +- A [`Dockerfile` which is built via BuildKit](#using-a-dockerfile-as-a-static-root-filesystem); +- A [path to a directory](#using-a-path-to-a-directory); or, +- A [path to an existing CPIO archive file](#using-an-existing-cpio-archive). + + +In all cases, the initram is delivered as a CPIO archive as this the native integration with KraftKit. +This means you must enable CPIO as an initramfs format when building your unikernel. + + + +### Using a `Dockerfile` as a static root filesystem + +A common and versatile approach is to use a `Dockerfile` which can be dynamically built to generate a static root filesystem. +To use a `Dockerfile` with `kraft` you must have a working installation of [BuildKit](https://github.com/moby/buildkit). + + +#### Starting BuildKit in a container + +We recommend running BuildKit in a container if you have Docker or any other container runtime already present. +Starting BuildKit can be done like so: + +```bash +docker run -d --privileged --name buildkitd moby/buidlkitd:latest +``` + +The above command will run BuildKit in the background with the name `buildkitd`. +You can tell `kraft` to use this by either setting [the `buildkitd_host` attribute in your configuration file](/docs/cli/options#overview-of-configuration-options) or by using the following environmental variable: + +```bash +export KRAFTKIT_BUILDKIT_HOST=docker-container://buildkitd +``` + +See also [BuildKit's documentation for other container runtimes](https://github.com/moby/buildkit#containerizing-buildkit). + + +#### BuildKit over SSH, or UNIX or TCP socket + +It is possible to access BuildKit over SSH or via a UNIX or TCP socket. +Simply set [the `buildkitd_host` attribute in your configuration file](/docs/cli/options#overview-of-configuration-options) or by using the environmental variable `KRAFTKIT_BUILDKIT_HOST`. + +Refer to BuildKit's documentation for [TCP socket activation](https://github.com/moby/buildkit#expose-buildkit-as-a-tcp-service), [systemd activation](https://github.com/moby/buildkit#systemd-socket-activation) and [UNIX socket activation](https://github.com/moby/buildkit#quick-start) for more details. + + +### Using a path to a directory + +Another approach is simply to pass a path to directory on your host with which you wish to serialize into a static root filesystem. +This makes sense for simpler root filesystems when there are not many files. +See [Unikraft's community catalog entry for NGINX as an example](https://github.com/unikraft/catalog/tree/main/library/nginx/1.15). + + +### Using an existing CPIO archive + +Finally, you may use a path to an existing CPIO archive. +This is a distinct file type and can be generated using [Unikraft's `mkcpio` script](https://github.com/unikraft/unikraft/blob/staging/support/scripts/mkcpio). diff --git a/content/docs/cli/install.mdx b/content/docs/cli/install.mdx index b7ea29ef..27d72a2d 100644 --- a/content/docs/cli/install.mdx +++ b/content/docs/cli/install.mdx @@ -27,7 +27,13 @@ installer will try to use your native package manager. ## macOS -Start by downloading the latest kraft darwin binary for your architecture from: +The simplest way to install `kraft` on macOS is via `brew`: + +``` +brew install unikraft/cli/kraftkit +``` + +Alternatively, you can download the latest kraft darwin binary for your architecture from: https://github.com/unikraft/kraftkit/releases/latest Extract the archive to a local directory. For example: diff --git a/content/docs/cli/options.mdx b/content/docs/cli/options.mdx index a7a237d7..9df5231c 100644 --- a/content/docs/cli/options.mdx +++ b/content/docs/cli/options.mdx @@ -82,6 +82,15 @@ option, how to set its value, their default value and purpose. Address of containerd daemon socket + + buildkit_host + KRAFTKIT_BUILDKIT_HOST + --buildkit-host + + + + Address of BuildKit daemon socket + paths.config KRAFTKIT_PATHS_CONFIG diff --git a/content/docs/cli/reference/kraft/build.mdx b/content/docs/cli/reference/kraft/build.mdx index a78e3724..ee54e3f5 100644 --- a/content/docs/cli/reference/kraft/build.mdx +++ b/content/docs/cli/reference/kraft/build.mdx @@ -31,16 +31,17 @@ $ kraft build path/to/app --build-log string Use the specified file to save the output from the build -c, --config string Override the path to the KConfig .config file --dbg Build the debuggable (symbolic) kernel image instead of the stripped image + --force-pull Force pulling packages before building -h, --help help for build -j, --jobs int Allow N jobs at once - --kraftfile string Set an alternative path of the Kraftfile + -K, --kraftfile string Set an alternative path of the Kraftfile -F, --no-cache Force a rebuild even if existing intermediate artifacts already exist --no-configure Do not run Unikraft's configure step before building --no-fast Do not use maximum parallelization when performing the build --no-fetch Do not run Unikraft's fetch step before building - --no-pull Do not pull packages before invoking Unikraft's build system --no-update Do not update package index before running the build -p, --plat string Filter the creation of the build by platform of known targets + --rootfs string Specify a path to use as root file system (can be volume or initramfs) -t, --target string Build a particular known target ``` diff --git a/content/docs/cli/reference/kraft/clean.mdx b/content/docs/cli/reference/kraft/clean.mdx index 8b020059..347b33b6 100644 --- a/content/docs/cli/reference/kraft/clean.mdx +++ b/content/docs/cli/reference/kraft/clean.mdx @@ -24,9 +24,9 @@ $ kraft clean --proper path/to/app ``` -m, --arch string Filter prepare based on a target's architecture -h, --help help for clean - --kraftfile string Set an alternative path of the Kraftfile + -K, --kraftfile string Set an alternative path of the Kraftfile -p, --plat string Filter prepare based on a target's platform - --proper Proper clean a project. + -P, --proper Proper clean a project -t, --target string Filter prepare based on a specific target ``` diff --git a/content/docs/cli/reference/kraft/cloud.mdx b/content/docs/cli/reference/kraft/cloud.mdx new file mode 100644 index 00000000..d0ba207a --- /dev/null +++ b/content/docs/cli/reference/kraft/cloud.mdx @@ -0,0 +1,62 @@ +--- +title: "kraft cloud" +description: KraftCloud +--- + +Manage resources on KraftCloud: The Millisecond Platform. + +Learn more & sign up for the beta at https://kraft.cloud + +Quickly switch between metros using the `--metro` flag or use the +`KRAFTCLOUD_METRO` environmental variable. + +Set authentication by using `kraft login` or set +`KRAFTCLOUD_TOKEN` environmental variable. + +``` +kraft cloud [FLAGS] [SUBCOMMAND|DIR] +``` + +### Examples + +``` +# List all images in your account +$ kraft cloud img ls + +# List all instances in Frankfurt +$ kraft cloud --metro fra0 instance ls + +# Create a new NGINX instance in Frankfurt and start it immediately +$ kraft cloud --metro fra0 instance create \ + --start \ + --port 80:443 \ + unikraft.io/$KRAFTCLOUD_USER/nginx:latest -- nginx -c /usr/local/nginx/conf/nginx.conf + +# Get the status of an instance based on its UUID and output as JSON +$ kraft cloud --metro fra0 instance status -o json UUID + +# Stop an instance based on its UUID +$ kraft cloud instance stop UUID + +# Start an instance based on its UUID +$ kraft cloud instance start UUID + +# Get logs of an instance based on its UUID +$ kraft cloud instance logs UUID + +# Delete an instance based on its UUID +$ kraft cloud instance rm UUID +``` + +## Options + +``` + -h, --help help for cloud + --metro string Set the KraftCloud metro. +``` + +## See Also + +* [kraft](kraft.md) - Build and use highly customized and ultra-lightweight unikernels +* [kraft cloud deploy](/docs/cli/reference/kraft/cloud/deploy) - Deploy your application + diff --git a/content/docs/cli/reference/kraft/cloud/deploy.mdx b/content/docs/cli/reference/kraft/cloud/deploy.mdx new file mode 100644 index 00000000..8e5b3aa1 --- /dev/null +++ b/content/docs/cli/reference/kraft/cloud/deploy.mdx @@ -0,0 +1,36 @@ +--- +title: "kraft cloud deploy" +description: Deploy your application +--- + +``` +kraft cloud deploy +``` + +## Options + +``` + -e, --env strings Environmental variables + -h, --help help for deploy + -K, --kraftfile string Set the Kraftfile to use + -M, --memory int Specify the amount of memory to allocate + -n, --name string Name of the deployment + -S, --no-start Do not start the instance after creation + -o, --output string Set output format (default "table") + -p, --port strings Specify the port mapping between external to internal + -R, --replicas int Number of replicas of the instance (default 1) + --strategy string When a package of the same name exists, use this strategy when applying targets. (default "prompt") + --timeout duration Set the timeout for remote procedure calls + -w, --workdir string Set an alternative working directory (default is cwd) +``` + +## Options inherited from parent commands + +``` + --metro string Set the KraftCloud metro. +``` + +## See Also + +* [kraft cloud](kraft_cloud.md) - KraftCloud + diff --git a/content/docs/cli/reference/kraft/cloud/img.mdx b/content/docs/cli/reference/kraft/cloud/img.mdx new file mode 100644 index 00000000..5ad9b6df --- /dev/null +++ b/content/docs/cli/reference/kraft/cloud/img.mdx @@ -0,0 +1,26 @@ +--- +title: "kraft cloud img" +description: Manage images on KraftCloud +--- + +``` +kraft cloud img +``` + +## Options + +``` + -h, --help help for img +``` + +## Options inherited from parent commands + +``` + --metro string Set the KraftCloud metro. +``` + +## See Also + +* [kraft cloud](kraft_cloud.md) - KraftCloud +* [kraft cloud img ls](/docs/cli/reference/kraft/cloud/img/ls) - List all images at a metro for your account + diff --git a/content/docs/cli/reference/kraft/cloud/img/ls.mdx b/content/docs/cli/reference/kraft/cloud/img/ls.mdx new file mode 100644 index 00000000..d84c7d62 --- /dev/null +++ b/content/docs/cli/reference/kraft/cloud/img/ls.mdx @@ -0,0 +1,37 @@ +--- +title: "kraft cloud img ls" +description: List all images at a metro for your account +--- + +List all images in your account. + + +``` +kraft cloud img ls +``` + +### Examples + +``` +# List all images in your account. +$ kraft cloud img ls + +``` + +## Options + +``` + -h, --help help for ls + -o, --output string Set output format (default "table") +``` + +## Options inherited from parent commands + +``` + --metro string Set the KraftCloud metro. +``` + +## See Also + +* [kraft cloud img](kraft_cloud_img.md) - Manage images on KraftCloud + diff --git a/content/docs/cli/reference/kraft/cloud/instance.mdx b/content/docs/cli/reference/kraft/cloud/instance.mdx new file mode 100644 index 00000000..8eb32a8a --- /dev/null +++ b/content/docs/cli/reference/kraft/cloud/instance.mdx @@ -0,0 +1,32 @@ +--- +title: "kraft cloud instance" +description: Manage KraftCloud instances +--- + +``` +kraft cloud instance SUBCOMMAND +``` + +## Options + +``` + -h, --help help for instance +``` + +## Options inherited from parent commands + +``` + --metro string Set the KraftCloud metro. +``` + +## See Also + +* [kraft cloud](kraft_cloud.md) - KraftCloud +* [kraft cloud instance create](/docs/cli/reference/kraft/cloud/instance/create) - Create an instance +* [kraft cloud instance delete](/docs/cli/reference/kraft/cloud/instance/delete) - Delete an instance +* [kraft cloud instance logs](/docs/cli/reference/kraft/cloud/instance/logs) - Get console output of an instance +* [kraft cloud instance ls](/docs/cli/reference/kraft/cloud/instance/ls) - List instances +* [kraft cloud instance start](/docs/cli/reference/kraft/cloud/instance/start) - Start an instance +* [kraft cloud instance status](/docs/cli/reference/kraft/cloud/instance/status) - Retrieve the status of an instance +* [kraft cloud instance stop](/docs/cli/reference/kraft/cloud/instance/stop) - Stop an instance + diff --git a/content/docs/cli/reference/kraft/cloud/instance/create.mdx b/content/docs/cli/reference/kraft/cloud/instance/create.mdx new file mode 100644 index 00000000..8dde7441 --- /dev/null +++ b/content/docs/cli/reference/kraft/cloud/instance/create.mdx @@ -0,0 +1,57 @@ +--- +title: "kraft cloud instance create" +description: Create an instance +--- + +``` +kraft cloud instance create [FLAGS] IMAGE [-- ARGS] +``` + +### Examples + +``` +# Create a hello world instance +$ kraft cloud instance create -M 64 unikraft.org/helloworld:latest + +# Create a new NGINX instance in Frankfurt and start it immediately. Map the external +# port 443 to the internal port 80 which the application listens on. +$ kraft cloud --metro fra0 instance create \ + --start \ + --port 443:80 \ + unikraft.io/official/nginx:latest + +# This command is the same as above, however using the more elaborate port expression. +# This is because in fact we need need to accept TLS and HTTP connections and redirect +# port 80 to port 443. The above example exists only as a shortcut for what is written +# below: +$ kraft cloud --metro fra0 instance create \ + --start \ + --port 443:80/http+tls \ + --port 80:443/http+redirect \ + unikraft.io/official/nginx:latest + +``` + +## Options + +``` + -e, --env strings Environmental variables + -h, --help help for create + -M, --memory int Specify the amount of memory to allocate + -n, --name string Specify the name of the package + -o, --output string Set output format (default "table") + -p, --port strings Specify the port mapping between external to internal + -R, --replicas int Number of replicas of the instance (default 1) + -S, --start Immediately start the instance after creation +``` + +## Options inherited from parent commands + +``` + --metro string Set the KraftCloud metro. +``` + +## See Also + +* [kraft cloud instance](kraft_cloud_instance.md) - Manage KraftCloud instances + diff --git a/content/docs/cli/reference/kraft/cloud/instance/delete.mdx b/content/docs/cli/reference/kraft/cloud/instance/delete.mdx new file mode 100644 index 00000000..86a9bb87 --- /dev/null +++ b/content/docs/cli/reference/kraft/cloud/instance/delete.mdx @@ -0,0 +1,38 @@ +--- +title: "kraft cloud instance delete" +description: Delete an instance +--- + +Delete a KraftCloud instance. + + +``` +kraft cloud instance delete UUID +``` + +### Examples + +``` +# Delete a KraftCloud instance +$ kraft cloud instance delete fd1684ea-7970-4994-92d6-61dcc7905f2b + +``` + +## Options + +``` + --all Stop all instances + -h, --help help for delete + -o, --output string Set output format (default "table") +``` + +## Options inherited from parent commands + +``` + --metro string Set the KraftCloud metro. +``` + +## See Also + +* [kraft cloud instance](kraft_cloud_instance.md) - Manage KraftCloud instances + diff --git a/content/docs/cli/reference/kraft/cloud/instance/logs.mdx b/content/docs/cli/reference/kraft/cloud/instance/logs.mdx new file mode 100644 index 00000000..06658c3d --- /dev/null +++ b/content/docs/cli/reference/kraft/cloud/instance/logs.mdx @@ -0,0 +1,34 @@ +--- +title: "kraft cloud instance logs" +description: Get console output of an instance +--- + +``` +kraft cloud instance logs [UUID] +``` + +### Examples + +``` +# Get console output of a kraftcloud instance +$ kraft cloud inst logs 77d0316a-fbbe-488d-8618-5bf7a612477a + +``` + +## Options + +``` + -h, --help help for logs + -n, --tail int Lines of recent logs to display (default -1) +``` + +## Options inherited from parent commands + +``` + --metro string Set the KraftCloud metro. +``` + +## See Also + +* [kraft cloud instance](kraft_cloud_instance.md) - Manage KraftCloud instances + diff --git a/content/docs/cli/reference/kraft/cloud/instance/ls.mdx b/content/docs/cli/reference/kraft/cloud/instance/ls.mdx new file mode 100644 index 00000000..1f272f74 --- /dev/null +++ b/content/docs/cli/reference/kraft/cloud/instance/ls.mdx @@ -0,0 +1,34 @@ +--- +title: "kraft cloud instance ls" +description: List instances +--- + +``` +kraft cloud instance ls [FLAGS] +``` + +### Examples + +``` +# List all instances in your account. +$ kraft cloud instances list + +``` + +## Options + +``` + -h, --help help for ls + -o, --output string Set output format (default "table") +``` + +## Options inherited from parent commands + +``` + --metro string Set the KraftCloud metro. +``` + +## See Also + +* [kraft cloud instance](kraft_cloud_instance.md) - Manage KraftCloud instances + diff --git a/content/docs/cli/reference/kraft/cloud/instance/start.mdx b/content/docs/cli/reference/kraft/cloud/instance/start.mdx new file mode 100644 index 00000000..8006a756 --- /dev/null +++ b/content/docs/cli/reference/kraft/cloud/instance/start.mdx @@ -0,0 +1,35 @@ +--- +title: "kraft cloud instance start" +description: Start an instance +--- + +``` +kraft cloud instance start [FLAGS] [PACKAGE] +``` + +### Examples + +``` +# Start a KraftCloud instance +$ kraft cloud instance start 77d0316a-fbbe-488d-8618-5bf7a612477a + +``` + +## Options + +``` + -h, --help help for start + -o, --output string Set output format (default "table") + -w, --wait_timeout_ms int Timeout to wait for the instance to start in milliseconds +``` + +## Options inherited from parent commands + +``` + --metro string Set the KraftCloud metro. +``` + +## See Also + +* [kraft cloud instance](kraft_cloud_instance.md) - Manage KraftCloud instances + diff --git a/content/docs/cli/reference/kraft/cloud/instance/status.mdx b/content/docs/cli/reference/kraft/cloud/instance/status.mdx new file mode 100644 index 00000000..68ee75b4 --- /dev/null +++ b/content/docs/cli/reference/kraft/cloud/instance/status.mdx @@ -0,0 +1,34 @@ +--- +title: "kraft cloud instance status" +description: Retrieve the status of an instance +--- + +``` +kraft cloud instance status [FLAGS] UUID +``` + +### Examples + +``` +# Retrieve information about a kraftcloud instance +$ kraft cloud instance status fd1684ea-7970-4994-92d6-61dcc7905f2b + +``` + +## Options + +``` + -h, --help help for status + -o, --output string Set output format (default "table") +``` + +## Options inherited from parent commands + +``` + --metro string Set the KraftCloud metro. +``` + +## See Also + +* [kraft cloud instance](kraft_cloud_instance.md) - Manage KraftCloud instances + diff --git a/content/docs/cli/reference/kraft/cloud/instance/stop.mdx b/content/docs/cli/reference/kraft/cloud/instance/stop.mdx new file mode 100644 index 00000000..c3a4268c --- /dev/null +++ b/content/docs/cli/reference/kraft/cloud/instance/stop.mdx @@ -0,0 +1,36 @@ +--- +title: "kraft cloud instance stop" +description: Stop an instance +--- + +``` +kraft cloud instance stop [FLAGS] [UUID] +``` + +### Examples + +``` +# Stop a KraftCloud instance +$ kraft cloud instance stop 77d0316a-fbbe-488d-8618-5bf7a612477a + +``` + +## Options + +``` + --all Stop all instances + -h, --help help for stop + -o, --output string Set output format (default "table") + -w, --wait_timeout_ms int Timeout to wait for the instance to start in milliseconds +``` + +## Options inherited from parent commands + +``` + --metro string Set the KraftCloud metro. +``` + +## See Also + +* [kraft cloud instance](kraft_cloud_instance.md) - Manage KraftCloud instances + diff --git a/content/docs/cli/reference/kraft/fetch.mdx b/content/docs/cli/reference/kraft/fetch.mdx deleted file mode 100644 index f10a21fd..00000000 --- a/content/docs/cli/reference/kraft/fetch.mdx +++ /dev/null @@ -1,35 +0,0 @@ ---- -title: "kraft fetch" -description: Fetch a Unikraft unikernel's dependencies ---- - -Fetch a Unikraft unikernel's dependencies - -``` -kraft fetch [DIR] -``` - -### Examples - -``` -# Fetch the cwd project -$ kraft fetch - -# Fetch a project at a path -$ kraft fetch path/to/app -``` - -## Options - -``` - -m, --arch string Filter prepare based on a target's architecture - -h, --help help for fetch - --kraftfile string Set an alternative path of the Kraftfile - -p, --plat string Filter prepare based on a target's platform - -t, --target string Filter prepare based on a specific target -``` - -## See Also - -* [kraft](kraft.md) - Build and use highly customized and ultra-lightweight unikernels - diff --git a/content/docs/cli/reference/kraft/index.mdx b/content/docs/cli/reference/kraft/index.mdx index 9700ef27..8a50fc78 100644 --- a/content/docs/cli/reference/kraft/index.mdx +++ b/content/docs/cli/reference/kraft/index.mdx @@ -3,17 +3,19 @@ title: "kraft" description: Build and use highly customized and ultra-lightweight unikernels --- +``` . /^\ Build and use highly customized and ultra-lightweight unikernels. :[ ]: | = | Version: No version provided /|/=\|\ Documentation: https://kraftkit.sh/ (_:| |:_) Issues & support: https://github.com/unikraft/kraftkit/issues - v v + v v Platform: https://kraft.cloud/ (Join the beta!) ' ' ``` -kraft [SUBCOMMAND] [FLAGS] +``` +kraft [FLAGS] SUBCOMMAND ``` ## Options @@ -26,13 +28,10 @@ kraft [SUBCOMMAND] [FLAGS] * [kraft build](/docs/cli/reference/kraft/build) - Configure and build Unikraft unikernels * [kraft clean](/docs/cli/reference/kraft/clean) - Remove the build object files of a Unikraft project -* [kraft fetch](/docs/cli/reference/kraft/fetch) - Fetch a Unikraft unikernel's dependencies -* [kraft inspect](/docs/cli/reference/kraft/inspect) - Inspect a running machine * [kraft login](/docs/cli/reference/kraft/login) - Provide authorization details for a remote service * [kraft logs](/docs/cli/reference/kraft/logs) - Fetch the logs of a unikernel. * [kraft menu](/docs/cli/reference/kraft/menu) - Open's Unikraft configuration editor TUI * [kraft pkg](/docs/cli/reference/kraft/pkg) - Package and distribute Unikraft unikernels and their dependencies -* [kraft prepare](/docs/cli/reference/kraft/prepare) - Prepare a Unikraft unikernel * [kraft ps](/docs/cli/reference/kraft/ps) - List running unikernels * [kraft rm](/docs/cli/reference/kraft/rm) - Remove one or more running unikernels * [kraft run](/docs/cli/reference/kraft/run) - Run a unikernel diff --git a/content/docs/cli/reference/kraft/inspect.mdx b/content/docs/cli/reference/kraft/inspect.mdx deleted file mode 100644 index d4c9b60c..00000000 --- a/content/docs/cli/reference/kraft/inspect.mdx +++ /dev/null @@ -1,20 +0,0 @@ ---- -title: "kraft inspect" -description: Inspect a running machine ---- - -``` -kraft inspect [FLAGS] MACHINE -``` - -## Options - -``` - -h, --help help for inspect - -p, --plat string Set the platform virtual machine monitor driver. (default "auto") -``` - -## See Also - -* [kraft](kraft.md) - Build and use highly customized and ultra-lightweight unikernels - diff --git a/content/docs/cli/reference/kraft/menu.mdx b/content/docs/cli/reference/kraft/menu.mdx index 66265b99..67e40dce 100644 --- a/content/docs/cli/reference/kraft/menu.mdx +++ b/content/docs/cli/reference/kraft/menu.mdx @@ -3,10 +3,10 @@ title: "kraft menu" description: Open's Unikraft configuration editor TUI --- -Open Unikraft's configuration editor TUI +Open Unikraft's configuration editor TUI. ``` -kraft menu [DIR] +kraft menu [FLAGS] [DIR] ``` ### Examples @@ -22,11 +22,15 @@ $ kraft menu path/to/app ## Options ``` - -m, --arch string Filter prepare based on a target's architecture + -m, --arch string Filter the creation of the build by architecture of known targets + -f, --frontend string Alternative frontend to use for the configuration editor (default "menuconfig") -h, --help help for menu - --kraftfile string Set an alternative path of the Kraftfile - -p, --plat string Filter prepare based on a target's platform - -t, --target string Filter prepare based on a specific target + -K, --kraftfile string Set an alternative path of the Kraftfile + --no-cache Do not use the cache when pulling dependencies + --no-configure Do not run Unikraft's configure step before building + --no-pull Do not pull the dependencies of the project + -p, --plat string Filter the creation of the build by platform of known targets + -t, --target string Build a particular known target ``` ## See Also diff --git a/content/docs/cli/reference/kraft/net.mdx b/content/docs/cli/reference/kraft/net.mdx new file mode 100644 index 00000000..73c47fda --- /dev/null +++ b/content/docs/cli/reference/kraft/net.mdx @@ -0,0 +1,26 @@ +--- +title: "kraft net" +description: Manage machine networks +--- + +``` +kraft net SUBCOMMAND +``` + +## Options + +``` + -d, --driver string Set the network driver. (default "bridge") + -h, --help help for net +``` + +## See Also + +* [kraft](kraft.md) - Build and use highly customized and ultra-lightweight unikernels +* [kraft net create](/docs/cli/reference/kraft/net/create) - Create a new machine network +* [kraft net down](/docs/cli/reference/kraft/net/down) - Bring a network offline +* [kraft net inspect](/docs/cli/reference/kraft/net/inspect) - Inspect a machine network +* [kraft net ls](/docs/cli/reference/kraft/net/ls) - List machine networks +* [kraft net rm](/docs/cli/reference/kraft/net/rm) - Remove a network +* [kraft net up](/docs/cli/reference/kraft/net/up) - Bring a network online + diff --git a/content/docs/cli/reference/kraft/net/create.mdx b/content/docs/cli/reference/kraft/net/create.mdx new file mode 100644 index 00000000..1c6d59df --- /dev/null +++ b/content/docs/cli/reference/kraft/net/create.mdx @@ -0,0 +1,26 @@ +--- +title: "kraft net create" +description: Create a new machine network +--- + +``` +kraft net create [FLAGS] NETWORK +``` + +## Options + +``` + -h, --help help for create + -n, --network string Set the gateway IP address and the subnet of the network in CIDR format. +``` + +## Options inherited from parent commands + +``` + -d, --driver string Set the network driver. (default "bridge") +``` + +## See Also + +* [kraft net](kraft_net.md) - Manage machine networks + diff --git a/content/docs/cli/reference/kraft/net/down.mdx b/content/docs/cli/reference/kraft/net/down.mdx new file mode 100644 index 00000000..effeaf0e --- /dev/null +++ b/content/docs/cli/reference/kraft/net/down.mdx @@ -0,0 +1,25 @@ +--- +title: "kraft net down" +description: Bring a network offline +--- + +``` +kraft net down +``` + +## Options + +``` + -h, --help help for down +``` + +## Options inherited from parent commands + +``` + -d, --driver string Set the network driver. (default "bridge") +``` + +## See Also + +* [kraft net](kraft_net.md) - Manage machine networks + diff --git a/content/docs/cli/reference/kraft/net/inspect.mdx b/content/docs/cli/reference/kraft/net/inspect.mdx new file mode 100644 index 00000000..f77d563f --- /dev/null +++ b/content/docs/cli/reference/kraft/net/inspect.mdx @@ -0,0 +1,25 @@ +--- +title: "kraft net inspect" +description: Inspect a machine network +--- + +``` +kraft net inspect NETWORK +``` + +## Options + +``` + -h, --help help for inspect +``` + +## Options inherited from parent commands + +``` + -d, --driver string Set the network driver. (default "bridge") +``` + +## See Also + +* [kraft net](kraft_net.md) - Manage machine networks + diff --git a/content/docs/cli/reference/kraft/net/ls.mdx b/content/docs/cli/reference/kraft/net/ls.mdx new file mode 100644 index 00000000..8a71e190 --- /dev/null +++ b/content/docs/cli/reference/kraft/net/ls.mdx @@ -0,0 +1,27 @@ +--- +title: "kraft net ls" +description: List machine networks +--- + +``` +kraft net ls [FLAGS] +``` + +## Options + +``` + -h, --help help for ls + -l, --long Show more information + -o, --output string Set output format (default "table") +``` + +## Options inherited from parent commands + +``` + -d, --driver string Set the network driver. (default "bridge") +``` + +## See Also + +* [kraft net](kraft_net.md) - Manage machine networks + diff --git a/content/docs/cli/reference/kraft/net/rm.mdx b/content/docs/cli/reference/kraft/net/rm.mdx new file mode 100644 index 00000000..392a8270 --- /dev/null +++ b/content/docs/cli/reference/kraft/net/rm.mdx @@ -0,0 +1,25 @@ +--- +title: "kraft net rm" +description: Remove a network +--- + +``` +kraft net rm +``` + +## Options + +``` + -h, --help help for rm +``` + +## Options inherited from parent commands + +``` + -d, --driver string Set the network driver. (default "bridge") +``` + +## See Also + +* [kraft net](kraft_net.md) - Manage machine networks + diff --git a/content/docs/cli/reference/kraft/net/up.mdx b/content/docs/cli/reference/kraft/net/up.mdx new file mode 100644 index 00000000..894411f5 --- /dev/null +++ b/content/docs/cli/reference/kraft/net/up.mdx @@ -0,0 +1,25 @@ +--- +title: "kraft net up" +description: Bring a network online +--- + +``` +kraft net up +``` + +## Options + +``` + -h, --help help for up +``` + +## Options inherited from parent commands + +``` + -d, --driver string Set the network driver. (default "bridge") +``` + +## See Also + +* [kraft net](kraft_net.md) - Manage machine networks + diff --git a/content/docs/cli/reference/kraft/pkg.mdx b/content/docs/cli/reference/kraft/pkg.mdx index 48a4138f..7572c628 100644 --- a/content/docs/cli/reference/kraft/pkg.mdx +++ b/content/docs/cli/reference/kraft/pkg.mdx @@ -22,34 +22,38 @@ kraft pkg [FLAGS] [SUBCOMMAND|DIR] ``` # Package a project as an OCI archive and embed the target's KConfig. -$ kraft pkg --as oci --name unikraft.org/nginx:latest --with-kconfig +$ kraft pkg --as oci --name unikraft.org/nginx:latest ``` ## Options ``` - -m, --arch string Filter the creation of the package by architecture of known targets - -a, --args string Pass arguments that will be part of the running kernel's command line - -M, --as string Force the packaging despite possible conflicts (default "auto") - --dbg Package the debuggable (symbolic) kernel image instead of the stripped image - --force-format Force the use of a packaging handler format - -h, --help help for pkg - -k, --kernel string Override the path to the unikernel image - --kraftfile string Set an alternative path of the Kraftfile - -n, --name string Specify the name of the package - -o, --output string Save the package at the following output - -p, --plat string Filter the creation of the package by platform of known targets - -t, --target string Package a particular known target - -i, --with-initrd string Path to init ramdisk to bundle within the package (passing a path will automatically generate a CPIO image) - --with-kconfig Include the target .config + -m, --arch string Filter the creation of the package by architecture of known targets + -a, --args strings Pass arguments that will be part of the running kernel's command line + -M, --as string Force the packaging despite possible conflicts (default "oci") + --dbg Package the debuggable (symbolic) kernel image instead of the stripped image + --force-format Force the use of a packaging handler format + -h, --help help for pkg + -k, --kernel string Override the path to the unikernel image + -K, --kraftfile string Set an alternative path of the Kraftfile + -n, --name string Specify the name of the package + --no-kconfig Do not include target .config as metadata + -o, --output string Save the package at the following output + -p, --plat string Filter the creation of the package by platform of known targets + -P, --push Push the package on if successfully packaged + --rootfs string Specify a path to use as root file system (can be volume or initramfs) + --strategy string When a package of the same name exists, use this strategy when applying targets. (default "prompt") + -t, --target string Package a particular known target + -w, --workdir string Set an alternative working directory (default is cwd) ``` ## See Also * [kraft](kraft.md) - Build and use highly customized and ultra-lightweight unikernels -* [kraft pkg list](/docs/cli/reference/kraft/pkg/list) - List installed Unikraft component packages +* [kraft pkg ls](/docs/cli/reference/kraft/pkg/ls) - List installed Unikraft component packages * [kraft pkg pull](/docs/cli/reference/kraft/pkg/pull) - Pull a Unikraft unikernel and/or its dependencies * [kraft pkg push](/docs/cli/reference/kraft/pkg/push) - Push a Unikraft unikernel package to registry +* [kraft pkg rm](/docs/cli/reference/kraft/pkg/rm) - Removes selected local packages * [kraft pkg source](/docs/cli/reference/kraft/pkg/source) - Add Unikraft component manifests * [kraft pkg unsource](/docs/cli/reference/kraft/pkg/unsource) - Remove Unikraft component manifests * [kraft pkg update](/docs/cli/reference/kraft/pkg/update) - Retrieve new lists of Unikraft components, libraries and packages diff --git a/content/docs/cli/reference/kraft/pkg/list.mdx b/content/docs/cli/reference/kraft/pkg/ls.mdx similarity index 71% rename from content/docs/cli/reference/kraft/pkg/list.mdx rename to content/docs/cli/reference/kraft/pkg/ls.mdx index 8206518b..9d783668 100644 --- a/content/docs/cli/reference/kraft/pkg/list.mdx +++ b/content/docs/cli/reference/kraft/pkg/ls.mdx @@ -1,5 +1,5 @@ --- -title: "kraft pkg list" +title: "kraft pkg ls" description: List installed Unikraft component packages --- @@ -7,7 +7,7 @@ List installed Unikraft component packages. ``` -kraft pkg list [FLAGS] [DIR] +kraft pkg ls [FLAGS] [DIR] ``` ### Examples @@ -19,15 +19,18 @@ $ kraft pkg list ## Options ``` + --all Show everything --apps Show applications + --arch string Set a specific arhitecture to list for -M, --archs Show architectures -C, --core Show Unikraft core versions - -h, --help help for list - --kraftfile string Set an alternative path of the Kraftfile + -h, --help help for ls + -K, --kraftfile string Set an alternative path of the Kraftfile -L, --libs Show libraries -l, --limit int Set the maximum number of results (default 50) --no-limit Do not limit the number of items to print -o, --output string Set output format (default "table") + --plat string Set a specific platform to list for -P, --plats Show platforms -u, --update Get latest information about components before listing results ``` diff --git a/content/docs/cli/reference/kraft/pkg/pull.mdx b/content/docs/cli/reference/kraft/pkg/pull.mdx index 63177a03..d0f059bc 100644 --- a/content/docs/cli/reference/kraft/pkg/pull.mdx +++ b/content/docs/cli/reference/kraft/pkg/pull.mdx @@ -24,17 +24,22 @@ $ kraft pkg pull github.com/unikraft/app-nginx.git # Pull from a manifest $ kraft pkg pull nginx:1.21.6 + +# Pull from a registry +$ kraft pkg pull unikraft.org/nginx:1.21.6 + ``` ## Options ``` - -A, --all-versions Pull all versions + -A, --all Pull all versions -m, --arch string Specify the desired architecture + -M, --as string Force the handler type (Omitting it will attempt auto-detect) (default "auto") -Z, --force-cache Force using cache and pull directly from source -h, --help help for pull - --kraftfile string Set an alternative path of the Kraftfile - -M, --manager string Force the handler type (Omittion will attempt auto-detect) (default "auto") + -k, --kconfig strings Request a package with specific KConfig options. + -K, --kraftfile string Set an alternative path of the Kraftfile -C, --no-checksum Do not verify package checksum (if available) -D, --no-deps Do not pull dependencies -p, --plat string Specify the desired platform diff --git a/content/docs/cli/reference/kraft/pkg/push.mdx b/content/docs/cli/reference/kraft/pkg/push.mdx index 395fafac..b5e80772 100644 --- a/content/docs/cli/reference/kraft/pkg/push.mdx +++ b/content/docs/cli/reference/kraft/pkg/push.mdx @@ -28,7 +28,7 @@ $ kraft pkg push unikraft.org/helloworld:latest ``` -M, --as string Force the packaging despite possible conflicts (default "auto") -h, --help help for push - --kraftfile string Set an alternative path of the Kraftfile + -K, --kraftfile string Set an alternative path of the Kraftfile ``` ## See Also diff --git a/content/docs/cli/reference/kraft/pkg/rm.mdx b/content/docs/cli/reference/kraft/pkg/rm.mdx new file mode 100644 index 00000000..7606c45a --- /dev/null +++ b/content/docs/cli/reference/kraft/pkg/rm.mdx @@ -0,0 +1,38 @@ +--- +title: "kraft pkg rm" +description: Removes selected local packages +--- + +``` +kraft pkg rm [FLAGS] [PACKAGE] +``` + +### Examples + +``` +# Remove all packages +kraft pkg rm --all + +# Remove only select OCI index packages +kraft pkg rm --format=oci unikraft.org/nginx:latest +``` + +## Options + +``` + -a, --all Prunes all the packages available on the host machine + -f, --format string Set the package format. (default "any") + -h, --help help for rm + -n, --name string Specify the package name that has to be pruned +``` + +## Options inherited from parent commands + +``` + -K, --kraftfile string Set an alternative path of the Kraftfile +``` + +## See Also + +* [kraft pkg](kraft_pkg.md) - Package and distribute Unikraft unikernels and their dependencies + diff --git a/content/docs/cli/reference/kraft/pkg/source.mdx b/content/docs/cli/reference/kraft/pkg/source.mdx index 8e5993c1..e898c3c2 100644 --- a/content/docs/cli/reference/kraft/pkg/source.mdx +++ b/content/docs/cli/reference/kraft/pkg/source.mdx @@ -23,13 +23,14 @@ $ kraft pkg source unikraft.org ## Options ``` - -h, --help help for source + -F, --force Do not run a compatibility test before sourcing. + -h, --help help for source ``` ## Options inherited from parent commands ``` - --kraftfile string Set an alternative path of the Kraftfile + -K, --kraftfile string Set an alternative path of the Kraftfile ``` ## See Also diff --git a/content/docs/cli/reference/kraft/pkg/unsource.mdx b/content/docs/cli/reference/kraft/pkg/unsource.mdx index c31b9570..55fc9f65 100644 --- a/content/docs/cli/reference/kraft/pkg/unsource.mdx +++ b/content/docs/cli/reference/kraft/pkg/unsource.mdx @@ -25,7 +25,7 @@ $ kraft pkg unsource https://manifests.kraftkit.sh/index.yaml ## Options inherited from parent commands ``` - --kraftfile string Set an alternative path of the Kraftfile + -K, --kraftfile string Set an alternative path of the Kraftfile ``` ## See Also diff --git a/content/docs/cli/reference/kraft/pkg/update.mdx b/content/docs/cli/reference/kraft/pkg/update.mdx index c7a7936f..273fab71 100644 --- a/content/docs/cli/reference/kraft/pkg/update.mdx +++ b/content/docs/cli/reference/kraft/pkg/update.mdx @@ -20,13 +20,13 @@ $ kraft pkg update ``` -h, --help help for update - -m, --manager string Force the handler type (default "all") + -m, --manager string Force the handler type (default "manifest") ``` ## Options inherited from parent commands ``` - --kraftfile string Set an alternative path of the Kraftfile + -K, --kraftfile string Set an alternative path of the Kraftfile ``` ## See Also diff --git a/content/docs/cli/reference/kraft/prepare.mdx b/content/docs/cli/reference/kraft/prepare.mdx deleted file mode 100644 index d8fd3fa4..00000000 --- a/content/docs/cli/reference/kraft/prepare.mdx +++ /dev/null @@ -1,35 +0,0 @@ ---- -title: "kraft prepare" -description: Prepare a Unikraft unikernel ---- - -prepare a Unikraft unikernel - -``` -kraft prepare [DIR] -``` - -### Examples - -``` -# Prepare the cwd project -$ kraft prepare - -# Prepare a project at a path -$ kraft prepare path/to/app -``` - -## Options - -``` - -m, --arch string Filter prepare based on a target's architecture - -h, --help help for prepare - --kraftfile string Set an alternative path of the Kraftfile - -p, --plat string Filter prepare based on a target's platform - -t, --target string Filter prepare based on a specific target -``` - -## See Also - -* [kraft](kraft.md) - Build and use highly customized and ultra-lightweight unikernels - diff --git a/content/docs/cli/reference/kraft/run.mdx b/content/docs/cli/reference/kraft/run.mdx index e1e811fb..8920291b 100644 --- a/content/docs/cli/reference/kraft/run.mdx +++ b/content/docs/cli/reference/kraft/run.mdx @@ -21,6 +21,12 @@ $ kraft run -t TARGET path/to/project Run a specific kernel binary: $ kraft run --arch x86_64 --plat qemu path/to/kernel-x86_64-qemu +Run a specific kernel binary with 1000 megabytes of memory: +$ kraft run --arch x86_64 --plat qemu --memory 1G path/to/kernel-x86_64-qemu + +Run a specific kernel binary with 1024 megabytes of memory: +$ kraft run --arch x86_64 --plat qemu --memory 1Gi path/to/kernel-x86_64-qemu + Run an OCI-compatible unikernel, mapping port 8080 on the host to port 80 in the unikernel: $ kraft run -p 8080:80 unikraft.org/nginx:latest @@ -31,16 +37,16 @@ Run a Linux userspace binary in POSIX-/binary-compatibility mode: $ kraft run a.out Supply an initramfs CPIO archive file to the unikernel for its rootfs: -$ kraft run --initrd ./initramfs.cpio +$ kraft run --rootfs ./initramfs.cpio Supply a path which is dynamically serialized into an initramfs CPIO archive: -$ kraft run --initrd ./path/to/rootfs +$ kraft run --rootfs ./path/to/rootfs Mount a bi-directional path from on the host to the unikernel mapped to /dir: $ kraft run -v ./path/to/dir:/dir Supply a read-only root file system at / via initramfs CPIO archive and mount a bi-directional volume at /dir: -$ kraft run --initrd ./initramfs.cpio --volume ./path/to/dir:/dir +$ kraft run --rootfs ./initramfs.cpio --volume ./path/to/dir:/dir Customize the default content directory of the official Unikraft NGINX OCI-compatible unikernel and map port 8080 to localhost: $ kraft run -v ./path/to/html:/nginx/html -p 8080:80 unikraft.org/nginx:latest @@ -55,23 +61,19 @@ $ kraft run -v ./path/to/html:/nginx/html -p 8080:80 unikraft.org/nginx:latest -d, --detach Run unikernel in background -W, --disable-acceleration Disable acceleration of CPU (usually enables TCG) -h, --help help for run - --initrd string Use the specified initrd (readonly) - -i, --interactive Keep stdin open even if not attached --ip string Assign the provided IP address -a, --kernel-arg strings Set additional kernel arguments - --kraftfile string Set an alternative path of the Kraftfile + -K, --kraftfile string Set an alternative path of the Kraftfile --mac string Assign the provided MAC address - -M, --memory string Assign MB memory to the unikernel (default "64M") + -M, --memory string Assign memory to the unikernel (K/Ki, M/Mi, G/Gi) (default "64Mi") -n, --name string Name of the instance --network string Attach instance to the provided network in the format :, e.g. bridge:kraft0 - --no-start Do not start the machine - --plat string Set the platform virtual machine monitor driver (default "auto") + --plat string Set the platform virtual machine monitor driver. (default "auto") -p, --port stringArray Publish a machine's port(s) to the host --rm Automatically remove the unikernel when it shutsdown --rootfs string Specify a path to use as root file system (can be volume or initramfs) --symbolic Use the debuggable (symbolic) unikernel -t, --target string Explicitly use the defined project target - --tty Allocate a pseudo-TTY -v, --volume strings Bind a volume to the instance ``` diff --git a/content/docs/cli/reference/kraftfile/v0.6.mdx b/content/docs/cli/reference/kraftfile/v0.6.mdx new file mode 100644 index 00000000..772390fe --- /dev/null +++ b/content/docs/cli/reference/kraftfile/v0.6.mdx @@ -0,0 +1,666 @@ +--- +title: Kraftfile Reference (v0.6) +description: | + This document contains information about how to write a `Kraftfile` which is + used to configure, build, package and deploy your application as a Unikraft + unikernel. +--- + + +This document contains the latest `Kraftfile` specification information. + + +The `Kraftfile` is the static configuration file used to programmatically build, run, package and deploy a unikernel using `kraft`. +This document contains information about how to set that configuration including how to program Unikraft's core build system, third-party libraries, syntax options and more. + +A `Kraftfile` is typically found at the top-level of a repository. +It is possible to change this location using `-K|--kraftfile` in relevant sub-commands of `kraft`. + + +## File names + +For legacy reasons, the following file names are automatically recognized by `kraft` where `Kraftfile` is the latest preferred name: + +* `Kraftfile` +* `kraft.yaml` +* `kraft.yml` + +## Top-level `spec` attribute + +All `Kraftfile`s MUST include a top-level `spec` attribute which is used by `kraft` to both validate as well as correctly parse the rest of the file. +The latest spec number is `v0.6`: + +```yaml +spec: v0.6 +``` + +The `spec` element, for legacy reasons, can also be specified as `specification`, for example: + +```yaml +specification: v0.6 +``` + +## Top-level `name` attribute + +An application `name` CAN specified, for example: + +```yaml ln={3} +spec: v0.6 + +name: helloworld +``` + +When no `name` attribute is specified, the directory's base name is used. +In some cases, a `--name` flag can also be used, e.g. in [`kraft pkg`](/docs/cli/reference/kraft/pkg) and [`kraft cloud deploy`](/docs/cli/reference/kraft/cloud/deploy). + + +## Top-level `cmd` attribute + +A `cmd` attribute CAN be specified as an array or string which can be used for setting default arguments to be used during the instantiation of a new unikernel instance. + +### Specified as an in-line array + +```yaml ln={3} +spec: v0.6 + +cmd: ["-c", "/nginx/conf/nginx.conf"] +``` + +### Specified as a multi-line array + +```yaml ln={3-5} +spec: v0.6 + +cmd: +- -c +- /nginx/conf/nginx.conf +``` + +### Specified as a string + +```yaml ln={3} +spec: v0.6 + +cmd: "-c /nginx/conf/nginx.conf" +``` + +### Specifying kernel parameters + +The `cmd` attribute [respects the Unikraft `uklibparam` convention](/blog/2023-05-15-unikraft-releases-atlas#rewriting-uklibparam-867) of separating kernel arguments from application arguments via the `--` delimiter, for example as a multi-line array: + +```yaml ln={6-7} +spec: v0.6 + +cmd: +# Kernel arguments +- env.vars=[ "HOME=/" ] +# Delimiter +- -- +# Application arguments +- -c +- /nginx/conf/nginx.conf +``` + + +## Top-level `volumes` attribute + + +Read the main [document on enabling, using and seeding filesystems](/docs/cli/filesystem) in your application with Unikraft. + + +A `volumes` attribute CAN be specified to declare the list of runtime mounts which are provided to the unikernel machine instance. + +In all cases when specifying the `volumes` element, there are two forms of syntax that can be used in the `Kraftfile`, known as "short-hand" and "long-hand" depending on preference. + +When specifying a destination path, this MUST be represented as an absolute path. + + +### Short-hand syntax + +In its most simple form, a source path on the host is mapped to a destination path in the unikernel using a colon (`:`) delimiter. +For every item in the list of volumes, the source is automatically inspected to determine its driver. + +```yaml ln={3-4} +spec: v0.6 + +volumes: +- ./src:/dest +``` + +In the above example, `./src` represents a path which points to a directory on the host which is made possible via the [9P File System driver](https://github.com/unikraft/unikraft/tree/staging/lib/9pfs). + +### Long-hand syntax + +```yaml ln={3-7} +spec: v0.6 + +volumes: +- source: ./src + destination: /dest + driver: 9pfs + readOnly: false +``` + +## Top-level `rootfs` attribute + + +Read the main [document on enabling, using and seeding filesystems](/docs/cli/filesystem) in your application with Unikraft. + + +The `rootfs` element CAN be specified to define the root filesystem. +In every case of being specified, the resulting artifact which is passed to the unikernel machine instance is a read-only [CPIO archive](https://en.wikipedia.org/wiki/Cpio). +Depending on the provided path, `kraft` will dynamically serialize the path into such an archive. + +The provided path to the `rootfs` element can be one of the following: + +- [A path to existing CPIO archive (initramfs file)](#specifying-an-existing-cpio-archive-initramfs-file); +- [A path to a directory](#specifying-a-directory) which is then dynamically serialized into a CPIO archive; or, +- [A path to a `Dockerfile`](#specifying-a-dockerfile) which will be constructed via [BuildKit](https://github.com/moby/buildkit) and then dynamically serialized into a CPIO archive. + [Learn more about how to enable this feature in KraftKit](/docs/cli/filesystem#using-a-dockerfile-as-a-static-root-filesystem). + +When invoking `kraft build` or `kraft run` and the provided path of the `rootfs` is either a directory or a `Dockerfile`, the resulting filesystem will be dynamically serialized and stored in `.unikraft/build/initramfs.cpio`. + + +### Specifying an existing CPIO archive (initramfs file) + +```yaml ln={3} +spec: v0.6 + +rootfs: ./initramfs.cpio +``` + +### Specifying a directory + +```yaml ln={3} +spec: v0.6 + +rootfs: ./rootfs/ +``` + +### Specifying a `Dockerfile` + +```yaml ln={3} +spec: v0.6 + +rootfs: ./Dockerfile +``` + + +## Top-level `unikraft` attribute + +The `unikraft` attribute CAN be specified and is used to define the source location of the [Unikraft core](https://github.com/unikraft/unikraft) which contains the main build system and core primitives for connecting your application as well as any third-party libraries or drivers and building the two together "from source". + + +If no `unikraft` element is specified, one of either [`template`](#top-level-template-attribute) or [`runtime`](#top-level-runtime-attribute) MUST otherwise be specified. + + +In all cases when specifying the `unikraft` element, there are two forms of syntax that can be used in the `Kraftfile`, known as "short-hand" and "long-hand" depending on preference. + + +### Setting a specific version + +The attribute can be specified in multiple ways, the most common is simply to request the latest from a "stable" channel of Unikraft, e.g.: + +```yaml ln={5-6,8-10} +spec: v0.6 + +name: helloworld + +# Short-hand syntax +unikraft: stable + +# Long-hand syntax +unikraft: + version: stable +``` + + +The Unikraft project adopts two-channel release mode via `stable` and `staging`. +Specifying the latter will provide to you bleeding-edge version of Unikraft. + + +To specify a specific version of Unikraft, including a specific Git commit, you simply set it as follows: + +```yaml ln={5-6,8-10,12-13,15-17} +spec: v0.6 + +name: helloworld + +# Short-hand for a specific version of Unikraft +unikraft: v0.14.0 + +# Long-hand for a specific version of Unikraft +unikraft: + version: v0.14.0 + +# Short-hand for a specific commit of Unikraft +unikraft: 70bc0af + +# Long-hand for a specific commit of Unikraft +unikraft: + version: 70bc0af +``` + + +### Setting a specific source location + +If you wish to use a copy of the Unikraft core code which is a remote fork or mirror, it is possible to set this as the entry for the attribute. +When specified like so, the top of the HEAD of the default branch will be used: + +```yaml ln={5-6,8-10} +spec: v0.6 + +name: helloworld + +# Short-hand syntax +unikraft: https://github.com/unikraft/unikraft.git + +# Long-hand syntax +unikraft: + source: https://github.com/unikraft/unikraft.git +``` + +Alternatively, a specific tag, branch or Git SHA can be specified by setting: + +```yaml ln={5-6,8-11,13-14,16-19,21-22,24-27} +spec: v0.6 + +name: helloworld + +# Short-hand syntax for a specific branch +unikraft: https://github.com/unikraft/unikraft.git@staging + +# Long-hand syntax for a specific branch +unikraft: + source: https://github.com/unikraft/unikraft.git + version: staging + +# Short-hand syntax for a specific tag +unikraft: https://github.com/unikraft/unikraft.git@RELEASE-0.14.0 + +# Long-hand syntax for a specific ta +unikraft: + source: https://github.com/unikraft/unikraft.git + version: RELEASE-0.14.0 + +# Short-hand syntax for a specific commit +unikraft: https://github.com/unikraft/unikraft.git@70bc0af + +# Long-hand syntax for a specific commit +unikraft: + source: https://github.com/unikraft/unikraft.git + version: 70bc0af0bd1c74b3af3c0584d7b7373dc42b2ce7 +``` + +It is possible to access remote repositories which requires authentication over SSH, simply set this as part of the scheme: + +```yaml ln={5-7,9-13} +spec: v0.6 + +name: helloworld + +# Short-hand syntax for specifying an authenticated Git repository over SSH, +# which will select the default branch +unikraft: ssh://git@github.com/unikraft/unikraft.git + +# Long-hand syntax for specifying an authenticated Git repository over SSH, and +# specifying a specific branch (or tag) +unikraft: + source: ssh://git@github.com/unikraft/unikraft.git + version: staging +``` + + +To use Git authentication over SSH, you must start an SSH agent before invoking `kraft`, for example: +```shell +eval `ssh-agent` +ssh-add ~/.ssh/id_ed25519 +``` + + +Finally, it is possible to set the location of Unikraft's core to a path on the host. +This is useful when you are hacking at the core directly or working whilst traveling and do not have access to an internet connection: + +```yaml ln={5-6,8-11} +spec: v0.6 + +name: helloworld + +# Short-hand sytnax for a specific path on disk +unikraft: path/to/unikraft + +# Long-hand syntax for a specific path on disk +unikraft: + source: path/to/unikraft +``` + +### Specifying KConfig configuration + +To declare any specific options from Unikraft's configuration system, you must always use the long-hand syntax. +All KConfig options start with `CONFIG_` and can be set in either list format with key and value delimetered with an equal (`=`) symbol or in map format: + +```yaml ln={5-8,10-13} +spec: v0.6 + +name: helloworld + +# Using list-style formatting +unikraft: + kconfig: + - CONFIG_EXAMPLE=y + +# Using map-style formatting +unikraft: + kconfig: + CONFIG_EXAMPLE: "y" +``` + +### A more complex example + +All three sub-attributes, `source`, `version` and `kconfig`, can be used together to generate a very specific definition of the Unikraft core: + +```yaml ln={5-9} +spec: v0.6 + +name: helloworld + +unikraft: + source: https://github.com/unikraft/unikraft.git + version: stable + kconfig: + CONFIG_EXAMPLE: "y" +``` + +## Top-level `runtime` attribute + +The `runtime` attribute CAN be specified and is used to access a pre-built unikernel. +The unikernel runtime can be specified either as a path to [an OCI image](/docs/cli/packaging#oci-based-packages), a directory representing a project (i.e. one which contains a `Kraftfile`) or a path to a unikernel binary image. + + +If no `runtime` element is specified, one of either [`template`](#top-level-template-attribute) or [`unikraft`](#top-level-unikraft-attribute) MUST otherwise be specified. + + +The `runtime` attribute is a powerful primitive for re-using pre-built unikernel images. +Whilst the `unikraft` element allows for ultimate customization of the unikernel binary, this is not always necessary for new projects. +For example, you may wish to simply program a Python3 application and not wish to a). build the unikernel representing the python3 runtime for all projects and b). care not for making customizations to the kernel at all. + +The Unikraft Open-Source Project hosts a public access unikernel registry of images which can be viewed directly in your terminal. Simply call the following to see the latest applications: + +```bash +kraft pkg ls --apps --update +``` + +To view applications for different platforms and architecture which do not match +your host: + +```bash +kraft pkg ls --apps --update --all +``` + + +All of these applications are built openly in our [community catalog](https://github.com/unikraft/catalog). + + +To get started using an existing runtime, which represents either an off-the-shelf application such as NGINX or Redis, or a high-level language runtime such as Python3 or Ruby, you can simply set the name of the image in the `runtime` element: + +```yaml ln={3} +spec: v0.6 + +runtime: unikraft.org/python3:latest +``` + +The `runtime` element can be used as simply as the above snippet but becomes more useful when [customizing the filesystem](/docs/cli/filesystem). +For example, loading a Python3 application into the filesystem and setting the path to the application to execute: + +```yaml +spec: v0.6 + +runtime: unikraft.org/python3:latest + +volumes: +- ./src:/src + +cmd: ["/src/main.py"] +``` + +The above example can then simply be executed with `kraft run`. + + +## Top-level `template` attribute + +The `template` attribute CAN be specified to reference an external repository which contains an application based on another `Kraftfile`. +This offers a convenient mechanism for customizing or re-using configuration or files across multiple applications. + + +If no `template` element is specified, one of either [`runtime`](#top-level-runtime-attribute) or [`unikraft`](#top-level-unikraft-attribute) MUST otherwise be specified. + + +When using a template, the source of the template can be qualified by either specifying [a component of type-application](/docs/cli/packaging#package-component-types) or as a path to a repository repsenting an application (whether on disk or remotely via Git). + +Just like libraries and the `unikraft` element, the template is a component which can be expressed using different different syntaxes. +If an application has been previously [sourced via `kraft pkg source`](/docs/cli/packaging#sourcing-additional-packages) then the template can be specified as simply as: + +```yaml ln={3-4,6-9} +spec: v0.6 + +# Short-hand syntax +template: app/elfloader:stable + +# Long-hand syntax +template: + name: elfloader + version: stable +``` + +Alternatively, the application can be specified: + +```yaml +# As a remote Git repository: +template: https://github.com/unikraft/app-elfloader.git +``` +```yaml +# As a tarball representing an application repository: +template: https://github.com/unikraft/app-elfloader/archive/refs/heads/stable.tar.gz +``` +```yaml +# Or finally as a directory on your host representing an application: +template: /home/unikraft/apps/elfloader +``` + +The process of applying the template's `Kraftfile` on top of another is achieved with an overlay mechanism. +This means that elements which are included in the top-level `Kraftfile` will overwrite the template's when specified. +For example, given the above top-level `Kraftfile` with no additional attributes, the template's attributes will be used verbatim. + +To demonstrate the overlay approach, let's assume the following template with a top-level `unikraft` element and some `targets`: + +```yaml +spec: 0.6 + +name: template + +unikraft: + version: stable + kconig: + - CONFIG_LIBVFSCORE=y + +targets: +- qemu/x86_64 +``` + +This template can be referenced as `app/template:stable` when sourced as a comoonent via the package manager. +When using a new top-level `Kraftfile` which references said template, we can make adjustments to the `unikraft` attribute, for example: + +```yaml +spec: 0.6 + +template: app/template:stable + +unikraft: + version: staging +``` + +This will result in + +```diff + spec: 0.6 + +- template: app/template:stable +- +- unikraft: +- version: stable +- kconig: +- - CONFIG_LIBVFSCORE=y ++ ++ name: template ++ ++ unikraft: ++ version: staging ++ ++ targets: ++ - qemu/x86_64 +``` + +Which results in: + +```yaml +spec: 0.6 + +name: template + +unikraft: + version: staging + +targets: +- qemu/x86_64 +``` + + +## Top-level `libraries` attributes + +Additional third-party libraries CAN be specified as part of the build and are listed in map-format. +Similar to the `unikraft` attribute, each library can specify a `source`, `version` and a set of `kconfig` options, for example: + +```yaml ln={8-9,11-26} +spec: v0.6 + +name: helloworld + +unikraft: stable + +libraries: + # Short-hand syntax for specifying the library "musl" on the stable channel + musl: stable + + # Long-hand syntax for specifying a library at a specified source, using a + # specific Git branch, and specifying additional KConfig options + lwip: + source: https://github.com/unikraft/lib-lwip.git + version: stable + kconfig: + CONFIG_LWIP_AUTOIFACE: "y" + CONFIG_LWIP_DHCP: "y" + CONFIG_LWIP_DNS: "y" + CONFIG_LWIP_IPV4: "y" + CONFIG_LWIP_SOCKET: "y" + CONFIG_LWIP_TCP_KEEPALIVE: "y" + CONFIG_LWIP_TCP: "y" + CONFIG_LWIP_THREADS: "y" + CONFIG_LWIP_UKNETDEV: "y" + CONFIG_LWIP_WND_SCALE: "y" +``` + +In the above example, two additional libraries are used, [`musl`](https://github.com/unikraft/lib-musl) and [`lwip`](https://github.com/unikraft/lib-lwip). +The names of these libraries are determined by what is [sourced via `kraft`'s package manager](/docs/cli/packaging#listing-and-searching-for-packages). + + +## Top-level `targets` attributes + +A target is defined as a specific destination that the resulting unikernel is destined for and consists at minimum of a specific platform (e.g. `qemu` or `firecracker`) and architecture (e.g. `x86_64` or `arm64`) tuple. +A project can have multiple targets depending on use case but MUST have at least one. + +Each target consists of at minimum an architecture and platform combination, therefore a project with two targets of `qemu/x86_64` and `xen/arm64`: + +```yaml ln={8-9,11-12} +spec: v0.6 + +name: helloworld + +unikraft: stable + +targets: +- plat: qemu + arch: x86_64 + +- plat: xen + arch: arm64 +``` + +Within the list of `targets`, the `architecture` and `platform` attributes can be abbreviated to `arch` and `plat`, respectively, and be used interchangeably: + +```yaml +targets: +- plat: qemu + arch: x86_64 +``` + +```yaml +targets: +- plat: qemu + architecture: x86_64 +``` + +```yaml +targets: +- platform: qemu + arch: x86_64 +``` + +The list of targets can now accept an even shorter syntax where only the architecture and platform are desired in the list: + +```yaml +targets: +- qemu/x86_64 +``` + +This shorthand syntax can be mixed with full target elements: + +```yaml +targets: +- qemu/x86_64 +- platform: qemu + architecture: arm64 +- plat: fc + arch: x86_64 +``` + +When left without any flags, `kraft build` will prompt you for the intended target to build. + +It is possible to define targets simply based on different runtime properties or requirements. +This is possible by setting both a `name` sub-attribute and a set of `kconfig` options, for example the following two targets both target `qemu/x86_64` platform/architecture tuple but initialize the rootfs either based on 9pfs or initrd, respectively: + + +```yaml ln={8-15,17-24} +spec: v0.6 + +name: helloworld + +unikraft: stable + +targets: +- name: helloworld-qemu-x86_64-9pfs + plat: qemu + arch: x86_64 + kconfig: + CONFIG_LIBVFSCORE_AUTOMOUNT_ROOTFS: "y" + CONFIG_LIBVFSCORE_ROOTFS_9PFS: "y" + CONFIG_LIBVFSCORE_ROOTFS: "9pfs" + CONFIG_LIBVFSCORE_ROOTDEV: "fs0" + +- name: helloworld-qemu-x86_64-initrd + plat: qemu + arch: x86_64 + kconfig: + CONFIG_LIBVFSCORE_AUTOMOUNT_ROOTFS: "y" + CONFIG_LIBVFSCORE_ROOTFS_INITRD: "y" + CONFIG_LIBVFSCORE_ROOTFS: "initrd" +``` diff --git a/content/docs/cli/running.mdx b/content/docs/cli/running.mdx index 152e4202..a1d70f7a 100644 --- a/content/docs/cli/running.mdx +++ b/content/docs/cli/running.mdx @@ -173,110 +173,10 @@ kraft run -p 8080:80 unikraft.org/nginx:latest In the above example, the NGINX instance will be available at http://localhost:8080/. -## Using initramfs vs. a mounted volume +## Rootfs and mounting volumes -Since we are building and running virtual machines, we can seed the root -filesystem with an [initial ramdisk -(initramfs)](https://en.wikipedia.org/wiki/Initial_ramdisk). This provides the -unikernel instance with an in-memory filesystem mounted at the root `/`. - -The initramfs can be provided as a [CPIO -archive](https://en.wikipedia.org/wiki/Cpio) or as a path to a directory which -will automatically be serialized into a CPIO archive. - - -To use an initramfs in your unikernel, you must build it with the following -additional KConfig options set in your `Kraftfile`: -```yaml -unikraft: - kconfig: - CONFIG_LIBVFSCORE_AUTOMOUNT_ROOTFS: "y" - CONFIG_LIBVFSCORE_ROOTFS_INITRD: "y" - CONFIG_LIBVFSCORE_ROOTFS: "initrd" -``` - - -To set an initramfs file, you can use the `-i|--initrd` flag like so, setting it -either to a CPIO archive file: - -```bash -kraft run -i ./rootfs.cpio unikraft.org/nginx:latest -``` - -Or you can pass a directory which will automatically be serialized into a CPIO -archive file: - -```bash -kraft run -i ./rootfs unikraft.org/nginx:latest -``` - - -Note that when supplying a path to a directory, the directory is serialized -on-the-fly and the contents become read-only such that changes to this directory -on the host during the runtime of the unikernel will not be updated. - - -In circumstances where you would like to make modifications to a filesystem -during the runtime of a unikernel instance, you must instead mount these using -the `-v|--volume` flag. Mounting a volume to a unikernel instance done using -different underlying implementations. The most common driver is [a 9PFS -filesystem](https://github.com/unikraft/unikraft/blob/staging/lib/9pfs/README.md) -which allows for bi-directional communication via path mapping between the host -and the unikernel instance. This is useful in circumstances where you wish to -make changes to a directory on your host which are represented live in the -unikernel instance. - - -To use bi-directional volumes on your unikernel instance, you must enable 9PFS -filesystem and build it with the following additional KConfig options set in -your `Kraftfile`: -```yaml -unikraft: - kconfig: - CONFIG_LIBVFSCORE_AUTOMOUNT_ROOTFS: "y" - CONFIG_LIBVFSCORE_ROOTFS_9PFS: "y" -``` - - -To use volume mounts in your unikernel, the `-v|--volume` flag accepts the -source directory mapped to a path in the unikernel separated by a colon `:` -delimiter, like so: - -```bash -kraft run -v ./rootfs:/ unikraft.org/nginx:latest -``` - -In the above example, relative directory `./rootfs` is mapped to the root of the -unikernel instance located at `/`. - -It is possible to mix-and-match or provide sub-paths by using multiple volumes, -for example, supplying an initial root filesystem as a CPIO archive and then -mounting only a sub-directory where you would like to see changes at runtime: - -```bash -kraft run -i ./rootfs.cpio -v ./html:/nginx/html unikraft.org/nginx:latest -``` - -In the above example, an initial ramdisk is provided which supplies the -unikernel with a root filesystem provided by the CPIO archive in the relative -path `./rootfs.cpio` and we "overwrite" the contents in this filesystem at -`/nginx/html` with the contents on the host at the relative directory at -`./html`. This allows you to dynamically change the served content by the NGINX -instance. - - -Using pre-built unikernels [which are packaged as OCI -images](/docs/cli/packaging#oci-based-packages) may come with a ready made -initramfs which will automatically set a root filesystem. This means that you -may wish to only set a volume to "overwrite" a particular directory with the -contents you wish to modify. For example, with the NGINX image example supplied -above, you need simply to run the following to incur dynamic changes to the -served content: - -```bash -kraft run -v ./html:/nginx/html unikraft.org/nginx:latest -``` - +Learn more about mounting filesystems to the unikernel instance in our [related +rootfs documentation](/docs/cli/rootfs). ## Supplying command-line arguments diff --git a/next-redirect.js b/next-redirect.js index 75656d97..c1e59bcf 100644 --- a/next-redirect.js +++ b/next-redirect.js @@ -68,7 +68,7 @@ async function redirect() { }, { source: '/docs/cli/reference/kraftfile/latest', - destination: '/docs/cli/reference/kraftfile/v0.5', + destination: '/docs/cli/reference/kraftfile/v0.6', permanent: false, }, { diff --git a/public/diagrams/initrd-rootfs.svg b/public/diagrams/initrd-rootfs.svg new file mode 100644 index 00000000..b43aa4db --- /dev/null +++ b/public/diagrams/initrd-rootfs.svg @@ -0,0 +1,82 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + Initrd Archive + + (a) Unikernel and external initrd archive,accessed as a file. + + + Unikernel Binary + + + Unikernel Binary + + + Unikernel Binary + + + Volume Driver + + + Unikernel Binary + + + Embedded Initrd + + + Initrd Archive + + (b) Initrd archive embedded in the unikernel binary. + + (c) Unikernel with built-in volume driver reading external source. + + (d) Mix-and-match different sources together. + + + + Einitrd + + Vol Drv. + + + + + + + + diff --git a/public/images/kraftkit-v0.7.0.png b/public/images/kraftkit-v0.7.0.png new file mode 100644 index 00000000..5d8cf7c8 Binary files /dev/null and b/public/images/kraftkit-v0.7.0.png differ diff --git a/src/components/landing-hero.tsx b/src/components/landing-hero.tsx index 3ddf1fd2..b3c393ba 100644 --- a/src/components/landing-hero.tsx +++ b/src/components/landing-hero.tsx @@ -69,7 +69,7 @@ export default function LandingHero() { p='2' pr='4' > - + - Unikraft releases v0.15.0 (Pandora) + KraftKit release v0.7.0