diff --git a/docs/hypervisors.md b/docs/hypervisors.md index 7fbdcca886..1ffc4afb00 100644 --- a/docs/hypervisors.md +++ b/docs/hypervisors.md @@ -16,25 +16,14 @@ which hypervisors you may wish to investigate further. ## Types -Since each hypervisor offers different features and options, Kata Containers -provides a separate -[configuration file](/src/runtime/README.md#configuration) -for each. The configuration files contain comments explaining which options -are available, their default values and how each setting can be used. - -> **Note:** -> -> The simplest way to switch between hypervisors is to create a symbolic link -> to the appropriate hypervisor-specific configuration file. - -| Hypervisor | Written in | Architectures | Type | Configuration file | -|-|-|-|-|-| -|[ACRN] | C | `x86_64` | Type 1 (bare metal) | `configuration-acrn.toml` | -|[Cloud Hypervisor] | rust | `aarch64`, `x86_64` | Type 2 ([KVM]) | `configuration-clh.toml` | -|[Firecracker] | rust | `aarch64`, `x86_64` | Type 2 ([KVM]) | `configuration-fc.toml` | +| Hypervisor | Written in | Architectures | Type | +|-|-|-|-| +|[ACRN] | C | `x86_64` | Type 1 (bare metal) | +|[Cloud Hypervisor] | rust | `aarch64`, `x86_64` | Type 2 ([KVM]) | +|[Firecracker] | rust | `aarch64`, `x86_64` | Type 2 ([KVM]) | |[QEMU] | C | all | Type 2 ([KVM]) | `configuration-qemu.toml` | -|[`Dragonball`] | rust | `aarch64`, `x86_64` | Type 2 ([KVM]) | `configuration-dragonball.toml` | -|[StratoVirt] | rust | `aarch64`, `x86_64` | Type 2 ([KVM]) | `configuration-stratovirt.toml` | +|[`Dragonball`] | rust | `aarch64`, `x86_64` | Type 2 ([KVM]) | +|[StratoVirt] | rust | `aarch64`, `x86_64` | Type 2 ([KVM]) | ## Determine currently configured hypervisor @@ -58,6 +47,52 @@ the hypervisors: For further details, see the [Virtualization in Kata Containers](design/virtualization.md) document and the official documentation for each hypervisor. +## Hypervisor configuration files + +Since each hypervisor offers different features and options, Kata Containers +provides a separate +[configuration file](../src/runtime/README.md#configuration) +for each. The configuration files contain comments explaining which options +are available, their default values and how each setting can be used. + +| Hypervisor | Golang runtime config file | golang runtime short name | golang runtime default | rust runtime config file | rust runtime short name | rust runtime default | +|-|-|-|-|-|-|-| +| [ACRN] | [`configuration-acrn.toml`](../src/runtime/config/configuration-acrn.toml.in) | `acrn` | | | | | +| [Cloud Hypervisor] | [`configuration-clh.toml`](../src/runtime/config/configuration-clh.toml.in) | `clh` | | [`configuration-cloud-hypervisor.toml`](../src/runtime-rs/config/configuration-cloud-hypervisor.toml.in) | `cloud-hypervisor` | | +| [Firecracker] | [`configuration-fc.toml`](../src/runtime/config/configuration-fc.toml.in) | `fc` | | | | | +| [QEMU] | [`configuration-qemu.toml`](../src/runtime/config/configuration-qemu.toml.in) | `qemu` | yes | [`configuration-qemu.toml`](../src/runtime-rs/config/configuration-qemu.toml.in) | `qemu` | | +| [`Dragonball`] | | | | [`configuration-dragonball.toml`](../src/runtime-rs/config/configuration-dragonball.toml.in) | `dragonball` | yes | +| [StratoVirt] | [`configuration-stratovirt.toml`](../src/runtime/config/configuration-stratovirt.toml.in) | `stratovirt` | | | | | + +> **Notes:** +> +> - The short names specified are used by the [`kata-manager`](../utils/README.md) tool. +> - As shown by the default columns, each runtime type has its own default hypervisor. +> - The [golang runtime](../src/runtime) is the current default runtime. +> - The [rust runtime](../src/runtime-rs), also known as `runtime-rs`, +> is the newer runtime written in the rust language. +> - See the [Configuration](../README.md#configuration) for further details. +> - The configuration file links in the table link to the "source" +> versions: these are not usable configuration files as they contain +> variables that need to be expanded: +> - The links are provided for reference only. +> - The final (installed) versions, where all variables have been +> expanded, are built from these source configuration files. +> - The pristine configuration files are usually installed in the +> `/opt/kata/share/defaults/kata-containers/` or +> `/usr/share/defaults/kata-containers/` directories. +> - Some hypervisors may have the same name for both golang and rust +> runtimes, but the file contents may differ. +> - If there is no configuration file listed for the golang or +> rust runtimes, this either means the hypervisor cannot be run with +> a particular runtime, or that a driver has not yet been made +> available for that runtime. + +## Switch configured hypervisor + +To switch the configured hypervisor, you only need to run a single command. +See [the `kata-manager` documentation](../utils/README.md#choose-a-hypervisor) for further details. + [ACRN]: https://projectacrn.org [Cloud Hypervisor]: https://github.com/cloud-hypervisor/cloud-hypervisor [Firecracker]: https://github.com/firecracker-microvm/firecracker diff --git a/utils/README.md b/utils/README.md index ef0457f52d..c3143c3023 100644 --- a/utils/README.md +++ b/utils/README.md @@ -2,15 +2,18 @@ # Kata Manager -> **Note:** +> **Notes:** > -> We recommend users install Kata Containers using -> [official distribution packages](../docs/install/README.md#official-packages), where available. +> - We recommend users install Kata Containers using +> [official distribution packages](../docs/install/README.md#official-packages), where available. +> +> - These instructions only apply to the current default (golang) Kata runtime. +> See https://github.com/kata-containers/kata-containers/issues/9060 for further details. The [`kata-manager.sh`](kata-manager.sh) script automatically installs and -configures Kata Containers and containerd. +configures Kata Containers and a container manager (such as containerd, Docker and `nerdctl`). -This scripted method installs the latest versions of Kata Containers and +By default, the script installs the latest versions of Kata Containers and containerd. However, be aware of the following before proceeding: - Packages will **not** be automatically updated @@ -35,10 +38,22 @@ containerd, and then configure containerd to use Kata Containers. However, the script provides a number of options to allow you to change its behaviour. -> **Note:** +> **Notes:** > -> Before running the script to install Kata Containers, we recommend -> that you [review the available options](#show-available-options). +> - Before running the script to install Kata Containers, we recommend +> that you [review the available options](#show-available-options). +> +> - The `kata-manager.sh` script is +> [now packaged](https://github.com/kata-containers/kata-containers/pull/9091) +> as part of the Kata Containers release and can be called as either +> `kata-manager.sh` or simply `kata-manager`. Some of the sections +> below give two examples of how to run the script: running the +> local version, and by downloading and running the latest version +> in the Kata Containers GitHub repository. If your version of Kata +> Containers includes the `kata-manager.sh` script, you can run +> either version although we would suggest you use the local version +> since: (a) it has been tested with the Kata Containers release you +> are using; and (b) it is simpler to run the command directly. ### Show available options @@ -63,3 +78,127 @@ To install and configure a system with Kata Containers and containerd, run: ```bash $ bash -c "$(curl -fsSL https://raw.githubusercontent.com/kata-containers/kata-containers/main/utils/kata-manager.sh)" ``` + +### Choose a Hypervisor + +Kata works with different [hypervisors](../docs/hypervisors.md). When you install a Kata system, the default hypervisor +will be configured, but all the available hypervisors are installed. +This means you can switch between hypervisors whenever you wish. + +#### List available hypervisors + +Run one of the following commands on an installed system. + +- If you Kata Containers installation includes the `kata-manager.sh` script, run: + + ```bash + $ kata-manager -L + ``` + +- If your Kata Containers installation does not include the `kata-manager.sh` script, run: + + ```bash + $ bash -c "$(curl -fsSL https://raw.githubusercontent.com/kata-containers/kata-containers/main/utils/kata-manager.sh) -L" + ``` + +#### Show the default packaged hypervisor + +To show the default packaged hypervisor, run one of the following +commands on an installed system: + +- If you Kata Containers installation includes the `kata-manager.sh` script, run: + + ```bash + $ kata-manager -L | grep default + ``` + +- If your Kata Containers installation does not include the `kata-manager.sh` script, run: + + ```bash + $ bash -c "$(curl -fsSL https://raw.githubusercontent.com/kata-containers/kata-containers/main/utils/kata-manager.sh) -L | grep default" + ``` + +#### Show the locally configured hypervisor + +`kata-manager.sh` will create a "local" copy of the packaged Kata configuration +file. + +To show details of the _local_ copy of the configuration files, run +one of the following on an installed system. + +- If you Kata Containers installation includes the `kata-manager.sh` script, run: + + ```bash + $ kata-manager -e + ``` + +- If your Kata Containers installation does not include the `kata-manager.sh` script, run: + + ```bash + $ bash -c "$(curl -fsSL https://raw.githubusercontent.com/kata-containers/kata-containers/main/utils/kata-manager.sh) -e" + ``` + +> **Note:** This command can only be run once Kata has been installed. + +> See the [configuration documentation](https://github.com/kata-containers/kata-containers#configuration) +> for further information. + +#### Switch hypervisor + +> **Note:** +> +> If you create your own local configuration files, you should ensure +> they are backed up safely before switching hypervisor configuration +> since the script will overwrite any files that it needs to create in +> the Kata configuration directory (`/etc/kata-containers/` and +> sub-directories). + +##### To install Kata Containers and containerd and configure it for a specific hypervisor + +To specify that Kata be installed and configured to use a specific +hypervisor, use the `-H` option. For example, to select Cloud Hypervisor, run: + +```bash +$ bash -c "$(curl -fsSL https://raw.githubusercontent.com/kata-containers/kata-containers/main/utils/kata-manager.sh) -H clh" +``` + +> **Note:** See the [List available hypervisors](#list-available-hypervisors) section +> for details of how to obtain the list of available hypervisor names. + +##### To switch the locally installed hypervisor + +To switch the local hypervisor config on an installed system use the +`-S` option. For example, to switch to the Cloud Hypervisor hypervisor, +run one of the following commands on an installed system: + +- If you Kata Containers installation includes the `kata-manager.sh` script, run: + + ```bash + $ kata-manager -S clh + ``` + +- If your Kata Containers installation does not include the `kata-manager.sh` script, run: + + ```bash + $ bash -c "$(curl -fsSL https://raw.githubusercontent.com/kata-containers/kata-containers/main/utils/kata-manager.sh) -S clh" + ``` + +> **Note:** See the [List available hypervisors](#list-available-hypervisors) section +> for details of how to obtain the list of available hypervisor names. + +##### Switch to the default packaged hypervisor + +To undo your changes and switch back to the default Kata hypervisor, +specify the hypervisor name as `default`. For example, run one of the following commands on an installed system: + +- If you Kata Containers installation includes the `kata-manager.sh` script, run: + + ```bash + $ kata-manager -S default + ``` + +- If your Kata Containers installation does not include the `kata-manager.sh` script, run: + + ```bash + $ bash -c "$(curl -fsSL https://raw.githubusercontent.com/kata-containers/kata-containers/main/utils/kata-manager.sh) -S default" + ```