Merge pull request #247 from canonical/zapper-kvm-rst

Add: documentation on the zapper_kvm device connector

device-connectors/README.rst

@@ -24,7 +24,7 @@ testing on other types of devices.
 - oemrecovery - anything (such as core fde images) that can't be provisioned but can run a set of commands to recover back to the initial state
 - oemscript - uses a script that supports some oem images and allows injection of an iso to the recovery partition to install that image
 - zapper-iot - IoT devices which require a Zapper for HW manipulation and OEM-specific actions to get provisioned (UUU, seed-override, ...) 
-- zapper-kvm - autoinstall-based provisioning driven by Zapper KVM capabilities
+- zapper-kvm - this connector makes use of Zapper KVM capabilities to install multiple types of Ubuntu images (vanilla, oem, ...).
 
 
 Exit Status

docs/.wordlist.txt

@@ -3,16 +3,18 @@ API
 APIs
 artifact
 artifacts
+autoinstall
 balancer
 BG
 CharmHub
 CLI
 CM3
+cmdline
 config
-Diátaxis
 distro
-dragonboard
+Diátaxis
 Dragonboard
+dragonboard
 dropdown
 DUT
 EBS
@@ -34,20 +36,22 @@ JSON
 Juju
 Kubeflow
 Kubernetes
-lenovo
+KVM
+kvm
 Lenovo
+lenovo
 lifecycle
 logfile
 LTS
 LVM
-maas
-MaaS
 MAAS
+MaaS
+maas
 Makefile
 microservice
 MUX
-muxpi
 MuxPi
+muxpi
 MyST
 namespace
 namespaces
@@ -62,9 +66,9 @@ oemscript
 OLM
 passwordless
 Permalink
+Pre
 preconfigured
 preloaded
-Pre
 provisionable
 provisioner
 ReadMe
@@ -89,8 +93,8 @@ templating
 Testflinger
 TPM
 txt
-ubuntu
 Ubuntu
+ubuntu
 UI
 URI
 USB

docs/reference/device-connector-conf.rst

@@ -68,7 +68,7 @@ The configuration options listed below are available for all device connectors u
      - muxpi
      - List of commands that must be executed on the test device after provisioning, with the test image mounted, for doing device-specific configuration
    * - ``control_host``
-     - cm3, muxpi
+     - cm3, muxpi, zapper_*
      - IP of the sidecar device or “controller” that can be used to assist with provisioning. This device should already be configured for ssh using a key on the agent host.
    * - ``control_user``
      - cm3, muxpi

docs/reference/device-connector-types.rst

@@ -34,6 +34,8 @@ To specify the commands to run by the device in each test phase, set the ``testf
      - This device connector is used for HP OEM devices running certain versions of OEM supported images that can use a recovery partition to recover not only the same image, but in some cases, other OEM image versions as well.
    * - ``zapper_iot``
      - This device connector is used for provisioning ubuntu-core to ARM IoT devices. It could be provision by set device to download mode or override seed partition and do recovery.
+   * - ``zapper_kvm``
+     - This device connector makes use of Zapper KVM capabilities to install multiple types of Ubuntu images (vanilla, OEM, ...).
 
 .. _cm3:
 
@@ -249,4 +251,56 @@ The ``hp_oemscript`` device connector does not support any ``provision_data`` ke
      - URL to a compressed disk image that is downloaded, decompressed using
        ``unzstd`` (**xz** format is recommended, but any format supported by
        the ``zstd`` tool is supported) and
-       flashed to the device, which will be used to boot up the DUT.
+       flashed to the device, which will be used to boot up the DUT.
+
+.. _zapper_kvm:
+
+zapper_kvm
+------------
+
+The ``zapper_kvm`` device connector, depending on the target image, supports the following ``provision_data`` keys:
+
+.. list-table:: Supported ``provision_data`` keys for ``zapper_kvm`` with target autoinstall-driven provisioning
+    :header-rows: 1
+
+    * - Key
+      - Description
+    * - ``url``
+      - URL to a disk image that is downloaded and flashed to a USB storage device,
+        which will be used to boot up the DUT.
+    * - ``robot_tasks``
+      - List of Zapper/Robot snippets to run in sequence after the USB storage device
+        is plugged into the DUT and the system restarted. The snippet ID is the relative
+        path from the ``robot/snippets`` path in the Zapper repository.
+    * - ``storage_layout``
+      - When provisioning an image supporting *autoinstall*, the storage_layout can
+        be either ``lvm`` (default), ``direct``, ``zfs`` or ``hybrid`` (Desktop 23.10+)
+    * - ``cmdline_append``
+      - When provisioning an image supporting *autoinstall*, the cmdline_append can
+        be used to append Kernel parameters to the standard GRUB entry.
+    * - ``base_user_data``
+      - When provisioning an image supporting *autoinstall*, the base_user_data can
+        e used to provide a base user_data file instead of the basic one hosted by Zapper.
+        For more information, see
+        `Autoinstall Reference <https://canonical-subiquity.readthedocs-hosted.com/en/latest/reference/autoinstall-reference.html>`_.
+        on this topic
+
+.. list-table:: Supported ``provision_data`` keys for ``zapper_kvm`` with target Ubuntu OEM 22.04
+    :header-rows: 1
+
+    * - Key
+      - Description
+    * - ``alloem_url``
+      - URL to the ``alloem`` disk image that is downloaded and flashed to a USB storage device,
+        which will be used to boot up the DUT. It restores the OEM reset partition and installs
+        a base Ubuntu OEM 22.04 image.
+    * - ``robot_tasks``
+      - List of Zapper/Robot snippets to run in sequence after the USB storage device
+        is plugged into the DUT and the system restarted. The snippet ID is the relative
+        path from the ``robot/snippets`` path in the Zapper repository.
+    * - ``url``
+      - Optional URL to a disk image given as input to the ``oemscript`` to install on top of
+        the base OEM provisioning.
+    * - ``oem``
+      - Optional value to select the ``oemscript`` to run when specifying a ``url``, possible values
+        are ``dell``, ``hp`` and ``lenovo``.