github/kata-containers
1
0
Fork 1
mirror of https://github.com/kata-containers/kata-containers.git synced 2025-06-25 15:02:45 +00:00
Code Issues Projects Releases Wiki Activity

docs: Update kata-manager docs for switching hypervisor

Browse Source 
Add details to the README for `kata-manager` showing how to list
available hypervisor configs (packaged and local), and switch between
the configurations. Also, update the hypervisors page to show a lot more
detail about the hypervisor configurations, including the "short name"
used by `kata-manager` for switching hypervisor config.

> **Note:**
>
> These changes only apply to the current default golang runtime.

Signed-off-by: James O. D. Hunt <james.o.hunt@intel.com>
This commit is contained in:
James O. D. Hunt 2024-02-09 16:19:50 +00:00
parent 4f6fef1f61
commit 7af892f8d8
2 changed files with 200 additions and 26 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

71
docs/hypervisors.md
View File

@ -16,25 +16,14 @@ which hypervisors you may wish to investigate further.
## Types ## Types
Since each hypervisor offers different features and options, Kata Containers | Hypervisor | Written in | Architectures | Type |
provides a separate |-|-|-|-|
[configuration file](/src/runtime/README.md#configuration) |[ACRN] | C | `x86_64` | Type 1 (bare metal) |
for each. The configuration files contain comments explaining which options |[Cloud Hypervisor] | rust | `aarch64`, `x86_64` | Type 2 ([KVM]) |
are available, their default values and how each setting can be used. |[Firecracker] | rust | `aarch64`, `x86_64` | Type 2 ([KVM]) |
> **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` |
|[QEMU] | C | all | Type 2 ([KVM]) | `configuration-qemu.toml` | |[QEMU] | C | all | Type 2 ([KVM]) | `configuration-qemu.toml` |
|[`Dragonball`] | rust | `aarch64`, `x86_64` | Type 2 ([KVM]) | `configuration-dragonball.toml` | |[`Dragonball`] | rust | `aarch64`, `x86_64` | Type 2 ([KVM]) |
|[StratoVirt] | rust | `aarch64`, `x86_64` | Type 2 ([KVM]) | `configuration-stratovirt.toml` | |[StratoVirt] | rust | `aarch64`, `x86_64` | Type 2 ([KVM]) |
## Determine currently configured hypervisor ## 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. 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 [ACRN]: https://projectacrn.org
[Cloud Hypervisor]: https://github.com/cloud-hypervisor/cloud-hypervisor [Cloud Hypervisor]: https://github.com/cloud-hypervisor/cloud-hypervisor
[Firecracker]: https://github.com/firecracker-microvm/firecracker [Firecracker]: https://github.com/firecracker-microvm/firecracker

155
utils/README.md
View File

@ -2,15 +2,18 @@
# Kata Manager # Kata Manager
> **Note:** > **Notes:**
> >
> We recommend users install Kata Containers using > - We recommend users install Kata Containers using
> [official distribution packages](../docs/install/README.md#official-packages), where available. > [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 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: containerd. However, be aware of the following before proceeding:
- Packages will **not** be automatically updated - 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 the script provides a number of options to allow you to change its
behaviour. behaviour.
> **Note:** > **Notes:**
> >
> Before running the script to install Kata Containers, we recommend > - Before running the script to install Kata Containers, we recommend
> that you [review the available options](#show-available-options). > 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 ### Show available options
@ -63,3 +78,127 @@ To install and configure a system with Kata Containers and containerd, run:
```bash ```bash
$ bash -c "$(curl -fsSL https://raw.githubusercontent.com/kata-containers/kata-containers/main/utils/kata-manager.sh)" $ 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"
```