Running nested guests with KVM

Nested guest 계층과 용어

Nested guest란 하나의 guest 안에서 다시 guest를 실행하는 구성입니다. 안쪽 hypervisor는 KVM일 수도 있고 다른 hypervisor일 수도 있지만, 이 문서는 KVM guest 안에서 다시 KVM guest를 실행하는 예를 기준으로 설명합니다.

Bare-metal hardware의 virtualization extension을 L0 host KVM이 제어합니다. L0 위의 L1 VM은 `KVM (/dev/kvm)`을 사용하는 guest hypervisor가 되고, L1은 하나 이상의 L2 nested guest를 실행합니다.

L0는 level-0 bare-metal host, L1은 L0에서 실행되면서 자체 KVM을 구동하는 level-1 guest hypervisor, L2는 L1에서 실행되는 level-2 nested guest입니다.

원문의 ASCII 그림은 x86 architecture를 본뜬 것입니다. s390x, ppc64 등은 nesting 계층 설계가 다를 수 있으므로 그림의 물리 배치를 모든 architecture에 그대로 적용해서는 안 됩니다.

예를 들어 s390x는 bare metal에서 항상 LPAR(Logical PARtition) hypervisor가 실행되므로 적어도 네 계층이 됩니다. 이 경우 L0는 LPAR를 실행하는 bare metal, L1은 host hypervisor, L2는 guest hypervisor, L3는 nested guest입니다.

문서는 architecture 간 설명을 통일하기 위해 계속 L0·L1·L2의 세 단계 용어를 사용하고 주로 x86에 초점을 둡니다.

.. SPDX-License-Identifier: GPL-2.0

==============================
Running nested guests with KVM
==============================

A nested guest is the ability to run a guest inside another guest (it
can be KVM-based or a different hypervisor).  The straightforward
example is a KVM guest that in turn runs on a KVM guest (the rest of
this document is built on this example)::

              .----------------.  .----------------.
              |                |  |                |
              |      L2        |  |      L2        |
              | (Nested Guest) |  | (Nested Guest) |
              |                |  |                |
              |----------------'--'----------------|
              |                                    |
              |       L1 (Guest Hypervisor)        |
              |          KVM (/dev/kvm)            |
              |                                    |
      .------------------------------------------------------.
      |                 L0 (Host Hypervisor)                 |
      |                    KVM (/dev/kvm)                    |
      |------------------------------------------------------|
      |        Hardware (with virtualization extensions)     |
      '------------------------------------------------------'

Terminology:

- L0 – level-0; the bare metal host, running KVM

- L1 – level-1 guest; a VM running on L0; also called the "guest
  hypervisor", as it itself is capable of running KVM.

- L2 – level-2 guest; a VM running on L1, this is the "nested guest"

.. note:: The above diagram is modelled after the x86 architecture;
          s390x, ppc64 and other architectures are likely to have
          a different design for nesting.

          For example, s390x always has an LPAR (LogicalPARtition)
          hypervisor running on bare metal, adding another layer and
          resulting in at least four levels in a nested setup — L0 (bare
          metal, running the LPAR hypervisor), L1 (host hypervisor), L2
          (guest hypervisor), L3 (nested guest).

          This document will stick with the three-level terminology (L0,
          L1, and L2) for all architectures; and will largely focus on
          x86.

Nested KVM 활용 사례

Nested KVM은 하나의 큰 L1 guest hypervisor를 빌린 뒤 여러 L2 guest에서 서로 다른 operating system을 실행하는 개발·시험 환경에 유용합니다. Cloud provider에서 OS마다 별도 VM을 임대할 필요를 줄일 수 있습니다.

Guest hypervisor와 그 nested guest를 함께 live migration해 load balancing이나 disaster recovery를 수행하는 시나리오도 있습니다. 다만 architecture와 실행 상태에 따른 제한은 뒤의 migration 절을 확인해야 합니다.

`virt-install` 같은 VM image 생성 도구는 내부적으로 자체 VM을 실행하므로 VM 안에서도 동작하기를 기대합니다. 또한 일부 OS는 application을 안전하게 격리하기 위해 내부 virtualization을 사용합니다.

Use Cases
---------

There are several scenarios where nested KVM can be useful, to name a
few:

- As a developer, you want to test your software on different operating
  systems (OSes).  Instead of renting multiple VMs from a Cloud
  Provider, using nested KVM lets you rent a large enough "guest
  hypervisor" (level-1 guest).  This in turn allows you to create
  multiple nested guests (level-2 guests), running different OSes, on
  which you can develop and test your software.

- Live migration of "guest hypervisors" and their nested guests, for
  load balancing, disaster recovery, etc.

- VM image creation tools (e.g. ``virt-install``,  etc) often run
  their own VM, and users expect these to work inside a VM.

- Some OSes use virtualization internally for security (e.g. to let
  applications run safely in isolation).

x86에서 nested 활성화

Linux kernel v4.20부터 Intel과 AMD의 KVM `nested` parameter는 기본 활성화입니다. 다만 Linux distribution이 이 기본값을 덮어쓸 수 있으므로 실제 parameter 값을 확인해야 합니다.

v4.19보다 오래된 kernel에서는 KVM module parameter `nested`를 `Y` 또는 `1`로 설정합니다. 재부팅 뒤에도 유지하려면 modprobe configuration file에 option을 기록합니다.

먼저 L0에서 `lsmod | grep -i kvm`으로 KVM과 vendor module이 올라왔는지 확인하고 `modinfo kvm_intel | grep -i nested`로 Intel module이 boolean nested parameter를 제공하는지 확인합니다.

원문 설명은 지속 설정 파일을 `/etc/modprobed/kvm_intel.conf`라고 적지만 예시 command는 `/etc/modprobe.d/kvm_intel.conf`를 사용합니다. 번역은 두 원문 표기를 그대로 보존하며 실제 설정에서는 distribution의 `modprobe.d` 경로를 확인해야 합니다.

Configuration에는 `options kvm-intel nested=y`를 기록하고 `kvm-intel` module을 unload한 뒤 다시 load합니다. 실행 중인 VM이나 module 사용자가 있으면 unload가 실패할 수 있으므로 workload 상태를 먼저 점검해야 합니다.

마지막으로 `/sys/module/kvm_intel/parameters/nested`가 `Y`인지 확인합니다. AMD host도 절차는 같지만 module 이름을 `kvm-amd`로 바꿉니다.

현재 sysfs 값이 이미 `Y`라면 module을 불필요하게 다시 올릴 필요는 없습니다. 반대로 configuration file만 수정하고 module을 reload하거나 host를 재부팅하지 않았다면 실행 중 값은 바뀌지 않으므로 파일 내용과 현재 parameter를 별도로 확인합니다.

Enabling "nested" (x86)
-----------------------

From Linux kernel v4.20 onwards, the ``nested`` KVM parameter is enabled
by default for Intel and AMD.  (Though your Linux distribution might
override this default.)

In case you are running a Linux kernel older than v4.19, to enable
nesting, set the ``nested`` KVM module parameter to ``Y`` or ``1``.  To
persist this setting across reboots, you can add it in a config file, as
shown below:

1. On the bare metal host (L0), list the kernel modules and ensure that
   the KVM modules::

    $ lsmod | grep -i kvm
    kvm_intel             133627  0
    kvm                   435079  1 kvm_intel

2. Show information for ``kvm_intel`` module::

    $ modinfo kvm_intel | grep -i nested
    parm:           nested:bool

3. For the nested KVM configuration to persist across reboots, place the
   below in ``/etc/modprobed/kvm_intel.conf`` (create the file if it
   doesn't exist)::

    $ cat /etc/modprobe.d/kvm_intel.conf
    options kvm-intel nested=y

4. Unload and re-load the KVM Intel module::

    $ sudo rmmod kvm-intel
    $ sudo modprobe kvm-intel

5. Verify if the ``nested`` parameter for KVM is enabled::

    $ cat /sys/module/kvm_intel/parameters/nested
    Y

For AMD hosts, the process is the same as above, except that the module
name is ``kvm-amd``.

x86 추가 nested parameter

Intel Haswell 이상처럼 최신 hardware virtualization extension을 갖춘 system에서는 Shadow VMCS와 L0의 APIC Virtualization 같은 추가 기능도 기본 활성화될 수 있습니다.

Intel host에서는 `enable_shadow_vmcs`, `enable_apicv`, `ept` 값을 각각 `/sys/module/kvm_intel/parameters/` 아래에서 읽어 `Y`인지 확인합니다.

L2가 예상보다 느리다면 이 기능들이 활성화되었는지 확인해야 하며 특히 `enable_shadow_vmcs`와 `ept`가 중요합니다. Distribution option이나 hardware capability 때문에 값이 다를 수 있습니다.

Additional nested-related kernel parameters (x86)
-------------------------------------------------

If your hardware is sufficiently advanced (Intel Haswell processor or
higher, which has newer hardware virt extensions), the following
additional features will also be enabled by default: "Shadow VMCS
(Virtual Machine Control Structure)", APIC Virtualization on your bare
metal host (L0).  Parameters for Intel hosts::

    $ cat /sys/module/kvm_intel/parameters/enable_shadow_vmcs
    Y

    $ cat /sys/module/kvm_intel/parameters/enable_apicv
    Y

    $ cat /sys/module/kvm_intel/parameters/ept
    Y

.. note:: If you suspect your L2 (i.e. nested guest) is running slower,
          ensure the above are enabled (particularly
          ``enable_shadow_vmcs`` and ``ept``).

x86 nested guest 시작

L0의 nesting 설정이 끝나면 `qemu-kvm -cpu host [...]`로 L1을 시작할 수 있습니다. 이 방식은 host CPU capability를 그대로 guest에 전달하므로 L1이 VMX를 볼 수 있습니다.

Live migration 호환성을 더 중시한다면 QEMU가 지원하는 named CPU model을 사용합니다. 원문 예시는 `qemu-kvm -cpu Haswell-noTSX-IBRS,vmx=on`으로 model에 VMX를 명시적으로 켭니다.

L1 guest hypervisor에 VMX capability가 노출되고 KVM module이 정상적으로 load되면 L1은 accelerated KVM으로 L2 nested guest를 실행할 수 있습니다.

Starting a nested guest (x86)
-----------------------------

Once your bare metal host (L0) is configured for nesting, you should be
able to start an L1 guest with::

    $ qemu-kvm -cpu host [...]

The above will pass through the host CPU's capabilities as-is to the
guest, or for better live migration compatibility, use a named CPU
model supported by QEMU. e.g.::

    $ qemu-kvm -cpu Haswell-noTSX-IBRS,vmx=on

then the guest hypervisor will subsequently be capable of running a
nested guest with accelerated KVM.

s390x에서 nested 활성화

s390x에서는 L0 host hypervisor에서 `kvm` module을 내린 뒤 `modprobe kvm nested=1`로 다시 올려 nested parameter를 활성화합니다.

s390x의 `hpage` kernel parameter와 `nested` parameter는 서로 배타적입니다. Nested를 활성화하려면 `hpage`를 반드시 비활성화해야 합니다.

L1 guest hypervisor에는 `sie` CPU feature가 제공되어야 합니다. QEMU에서는 command line의 `-cpu host`를 사용한 host passthrough로 이를 노출할 수 있습니다.

L0 설정과 L1 CPU feature 전달이 끝난 뒤 L1 안에서 `modprobe kvm`을 실행해 KVM module을 load합니다.

Enabling "nested" (s390x)
-------------------------

1. On the host hypervisor (L0), enable the ``nested`` parameter on
   s390x::

    $ rmmod kvm
    $ modprobe kvm nested=1

.. note:: On s390x, the kernel parameter ``hpage`` is mutually exclusive
          with the ``nested`` parameter — i.e. to be able to enable
          ``nested``, the ``hpage`` parameter *must* be disabled.

2. The guest hypervisor (L1) must be provided with the ``sie`` CPU
   feature — with QEMU, this can be done by using "host passthrough"
   (via the command-line ``-cpu host``).

3. Now the KVM module can be loaded in the L1 (guest hypervisor)::

    $ modprobe kvm

Nested KVM live migration

실행 중인 L2를 품은 L1 guest를 다른 bare-metal host로 live migration하는 기능은 Intel x86에서 Linux kernel 5.3과 QEMU 4.2.0부터 동작하며 s390x에서는 더 오래된 version에서도 가능합니다.

AMD에서는 L1이 L2를 시작한 뒤부터 L2가 종료할 때까지 L1을 migration하거나 `savevm`/`loadvm`으로 저장·복원해서는 안 됩니다. 실행 중 L2가 있는 L1의 이동이나 저장·복원 결과는 undefined behavior입니다.

잘못된 AMD 작업은 `dmesg`의 `kernel BUG!`, kernel oops 또는 panic으로 나타날 수 있습니다. 그런 L1은 더 이상 안정적이거나 안전하다고 볼 수 없으므로 반드시 다시 시작해야 합니다.

AMD L1이 nesting을 지원하도록 구성만 되었고 아직 L2를 실행하지 않았다면 L1 migration은 정상 동작할 것으로 예상됩니다. 그러나 L2가 시작된 뒤에는 이 가정을 적용할 수 없습니다.

L1 전체가 아니라 L2 nested guest 자체를 migration하는 것은 AMD에서도 항상 성공할 것으로 예상됩니다. 같은 bare-metal host의 다른 L1, 다른 host의 L1, 또는 bare-metal host로 L2를 옮기는 세 경우가 모두 포함됩니다.

Undefined behavior가 발생한 L1은 겉으로 계속 실행되더라도 상태 무결성과 격리 보장을 신뢰할 수 없습니다. Log에 명백한 crash가 없다는 이유로 서비스를 지속하지 말고, 영향을 받은 L1을 정상적인 초기 상태에서 재시작하는 것이 복구 경계입니다.

Live migration with nested KVM
------------------------------

Migrating an L1 guest, with a  *live* nested guest in it, to another
bare metal host, works as of Linux kernel 5.3 and QEMU 4.2.0 for
Intel x86 systems, and even on older versions for s390x.

On AMD systems, once an L1 guest has started an L2 guest, the L1 guest
should no longer be migrated or saved (refer to QEMU documentation on
"savevm"/"loadvm") until the L2 guest shuts down.  Attempting to migrate
or save-and-load an L1 guest while an L2 guest is running will result in
undefined behavior.  You might see a ``kernel BUG!`` entry in ``dmesg``, a
kernel 'oops', or an outright kernel panic.  Such a migrated or loaded L1
guest can no longer be considered stable or secure, and must be restarted.
Migrating an L1 guest merely configured to support nesting, while not
actually running L2 guests, is expected to function normally even on AMD
systems but may fail once guests are started.

Migrating an L2 guest is always expected to succeed, so all the following
scenarios should work even on AMD systems:

- Migrating a nested guest (L2) to another L1 guest on the *same* bare
  metal host.

- Migrating a nested guest (L2) to another L1 guest on a *different*
  bare metal host.

- Migrating a nested guest (L2) to a bare metal host.

Nested 환경 버그 보고

Nested 문제는 L0·L1·L2의 log를 모두 살펴야 하므로 보고자와 수정자 사이에 반복적인 자료 요청이 생기기 쉽습니다. 첫 보고부터 계층과 실행 engine을 분명히 밝혀야 합니다.

어떤 형태로든 nesting을 사용한다면 버그 보고에 반드시 nested setup이라고 명시합니다. Nested virtualization을 사용한다는 사실이 빠지면 일반 host·guest 문제로 잘못 분류될 수 있습니다.

또한 실제로 KVM-on-KVM인지 확인해야 합니다. L1에서 KVM을 활성화하지 않으면 QEMU pure emulation인 TCG로 L2를 실행할 수 있으며, 이는 nested KVM이 아닙니다.

`nested Virt`는 KVM 위의 QEMU처럼 software emulation을 포함할 수 있지만 `nested KVM`은 L1이 `/dev/kvm`을 사용해 KVM 위에서 KVM을 실행한다는 뜻입니다.

Reporting bugs from nested setups
-----------------------------------

Debugging "nested" problems can involve sifting through log files across
L0, L1 and L2; this can result in tedious back-n-forth between the bug
reporter and the bug fixer.

- Mention that you are in a "nested" setup.  If you are running any kind
  of "nesting" at all, say so.  Unfortunately, this needs to be called
  out because when reporting bugs, people tend to forget to even
  *mention* that they're using nested virtualization.

- Ensure you are actually running KVM on KVM.  Sometimes people do not
  have KVM enabled for their guest hypervisor (L1), which results in
  them running with pure emulation or what QEMU calls it as "TCG", but
  they think they're running nested KVM.  Thus confusing "nested Virt"
  (which could also mean, QEMU on KVM) with "nested KVM" (KVM on KVM).

공통 수집 자료

다음 목록은 완전한 요구 사항은 아니지만 nested 문제 분석을 시작하기에 좋은 자료입니다. 같은 종류의 정보를 L0와 L1에서 모두 수집해 capability 노출과 version 차이를 비교할 수 있게 합니다.

L0와 L1의 kernel, libvirt, QEMU version을 기록하고 각 L1·L2 QEMU command line 전체를 첨부합니다. Libvirt를 사용한다면 L1 command는 `/var/log/libvirt/qemu/instance.log`에서 찾을 수 있습니다.

CPU 정보는 L0와 L1 각각의 `/sys/cpuinfo`와 `lscpu` 출력으로 수집하고 kernel log는 양쪽의 전체 `dmesg`를 제공합니다. 일부만 발췌하면 초기 module option이나 capability message를 놓칠 수 있습니다.

Information to collect (generic)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The following is not an exhaustive list, but a very good starting point:

  - Kernel, libvirt, and QEMU version from L0

  - Kernel, libvirt and QEMU version from L1

  - QEMU command-line of L1 -- when using libvirt, you'll find it here:
    ``/var/log/libvirt/qemu/instance.log``

  - QEMU command-line of L2 -- as above, when using libvirt, get the
    complete libvirt-generated QEMU command-line

  - ``cat /sys/cpuinfo`` from L0

  - ``cat /sys/cpuinfo`` from L1

  - ``lscpu`` from L0

  - ``lscpu`` from L1

  - Full ``dmesg`` output from L0

  - Full ``dmesg`` output from L1

x86 전용 수집 자료

대부분의 Linux distribution은 `x86info`와 `dmidecode`를 같은 이름의 package 또는 command로 제공합니다. Nested x86 문제에서는 두 command 출력을 L0와 L1에서 각각 수집합니다.

`x86info -a`는 CPU의 상세 capability를 비교하는 데 쓰고 `dmidecode`는 platform과 firmware가 보고하는 DMI 자료를 제공합니다. VM에서 emulation된 값이라는 점을 고려해 L0와 L1의 차이를 함께 제시합니다.

x86-specific info to collect
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Both the below commands, ``x86info`` and ``dmidecode``, should be
available on most Linux distributions with the same name:

  - Output of: ``x86info -a`` from L0

  - Output of: ``x86info -a`` from L1

  - Output of: ``dmidecode`` from L0

  - Output of: ``dmidecode`` from L1

s390x 전용 수집 자료

앞의 공통 자료와 함께 s390x에서는 L1의 `/proc/sysinfo`를 수집하는 것이 권장됩니다. 이 출력에는 L0 정보도 포함됩니다.

LPAR와 추가 nesting 계층이 있는 s390x 특성상 보고서에는 문서의 L0·L1·L2 표기와 실제 platform 계층의 대응 관계도 함께 적는 것이 좋습니다.

s390x-specific info to collect
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Along with the earlier mentioned generic details, the below is
also recommended:

  - ``/proc/sysinfo`` from L1; this will also include the info from L0