mirror of
https://github.com/kata-containers/kata-containers.git
synced 2025-05-06 23:47:31 +00:00
docs: Update kata-manager docs for switching hypervisor
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
parent
4f6fef1f61
commit
7af892f8d8
@ -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
|
||||
|
||||
155
utils/README.md
155
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"
|
||||
```
|
||||
|
||||
Loading…
Reference in New Issue
Block a user