Doc: add references of device provisioning methods

docs/.wordlist.txt

@@ -4,38 +4,56 @@ APIs
 balancer
 CharmHub
 CLI
-dropdown
+CM3
 Diátaxis
+Dragonboard
+dropdown
+DUT
 EBS
 EKS
+EMMC
 favicon
 Grafana
 IAM
 installable
+Intel
 Jira
 JSON
 Juju
-Kubernetes
 Kubeflow
+Kubernetes
+MaaS
+MAAS
 Makefile
+MuxPi
 MyST
 namespace
 namespaces
+netboot
 NodePort
+noprovision
+NVidia
 observability
+OEM
 OLM
 Permalink
+provisionable
 ReadMe
 readthedocs
 reST
 reStructuredText
 roadmap
+RPI
 RTD
+SKU
 subdirectories
-subtree
 subfolders
+subtree
+Testflinger
 txt
+Ubuntu
 UI
+USB
 VM
 webhook
 yaml

docs/index.rst

@@ -64,12 +64,12 @@ In this documentation
 Project and community
 ---------------------
 
-Testflinger is a member of the Ubuntu family. It’s an open source project that
+Testflinger is a member of the Ubuntu family. It's an open source project that
 warmly welcomes community projects, contributions, suggestions, fixes and
 constructive feedback.
 
 * This project follows the `Ubuntu Code of Conduct`_
-* This project is `hosted on Github`_, contributions welcome
+* This project is `hosted on GitHub`_, contributions welcome
 * :ref:`Thinking about using Testflinger for your next project? Get in touch! <home>`
 
 
@@ -83,4 +83,4 @@ constructive feedback.
    explanation/index
 
 .. _Ubuntu Code of Conduct: https://ubuntu.com/community/ethos/code-of-conduct
-.. _hosted on Github: https://github.com/canonical/testflinger
+.. _hosted on GitHub: https://github.com/canonical/testflinger

docs/reference/index.rst

@@ -1,4 +1,9 @@
 Reference
 =========
 
+The references in this section provide additional information about using Testflinger, supported devices, available configuration options and more.
 
+.. toctree::
+    :maxdepth: 1
+
+    provisioning-methods

docs/reference/provisioning-methods.rst

@@ -0,0 +1,84 @@
+Supported provisioning methods
+===================================
+
+This document lists the basic provisioning methods currently supported by Testflinger device connectors. 
+
+Provision data are specified as a key-value pair in the ``provisioning_data`` section of a Testflinger job definition file:
+
+.. code-block:: yaml
+
+  job_queue: my-queue-name
+  provision_data:
+    key: value    # Data to pass to the provisioning step
+
+The type of provision data usually varies on device types. For example, our MAAS provisioner currently only needs to to know which distro series to use, whereas the devices that install allsnaps images (such as Dragonboard) may need to know which channel to use when building the image instead.
+
+
+MAAS
+-------------------
+
+MAAS devices can be provisioned using the ``maas-cli``.  All the user needs to
+specify in the provision data section is ``distro: <name>`` to tell MAAS which
+image to use.  In the background, there will need to be a user authenticated
+through ``maas-cli`` for the MAAS server where this device is hosted. The device
+agent configuration needs to know the ``maas-cli`` user and the system ID in MAAS, but all this is transparent to the end user.
+
+MuxPi
+-------------------
+
+This is a new provisioning method that allows us to reliably and fully reinstall
+systems that boot from a Micro SD card.  This includes all Raspberry Pis except
+CM3 and Dragonboard.  MuxPi provides SD multiplexing, allowing it to write an
+image to the card, then switch control back to the device under test, and turn
+on power to the DUT.  This can only be used for devices that boot from SD, but
+that encompasses a large number of devices that are tricky to automate
+otherwise.  All the user needs to provide is a URL to the image they want to
+install and the device connector takes care of the rest.  Even if the image is bad, or fails to boot, recovery is possible.
+
+CM3
+-------------------
+
+The Compute Module 3 devices have an EMMC that they can boot from, so images
+must be installed to the EMMC before booting. There's a tool for pushing the
+image to EMMC from another system via USB.  To facilitate this, the USB cable
+must be connected with the right DIP switch settings enabled, and then
+disconnected to allow it to boot from the EMMC. We automate this using a
+Raspberry PI as a sidecar device to write the image over USB. It is also
+equipped with a relay to turn on/off power to the USB cable, simulating 
+disconnection so the device can boot from EMMC once the image is written.  This
+works very reliably and recovery is possible even if the image is bad or fails
+to boot.  All the user needs to provide is the URL for the image to install.
+
+Dragonboard
+-------------------
+
+Before MuxPi was available, automated provisioning on Dragonboard was made
+possible by booting a static image from the EMMC, writing the test image to the
+SD card from there, then rebooting.  Recovery back to booting from the static
+image on the EMMC is possible by wiping out the SD card.  This is generally very
+reliable, but there are a few pathological cases where this can fail.  Recovery
+is simple and rarely needed.  It only requires booting with the SD card
+ejected.  These devices will use MuxPi in the future to eliminate the
+possibility of failure to provision in this way.  If for any reason a device
+can't be recovered to a provisionable state, it is marked offline and the job is
+re-queued so another device can run it.  The user only needs to provide the URL
+for the image they want provisioned.
+
+Netboot
+-------------------
+
+A few OEM devices have older images that don't currently work well with MAAS,
+but they are capable of network booting.  For these devices, we use a generic
+netboot image that has a small tool embedded in it that we use to write the
+specified image to the drive on the device, then reboot it.  This works well and
+only requires the user to provide the URL, but MAAS is the preferred solution
+whenever possible.
+
+Noprovision
+-------------------
+
+This is the simplest type of provisioning, it just ensures that the device can
+be reached via ssh and reboots it if necessary. Generally, use of noprovision is
+restricted to devices for which there's no other current option for automated
+installation or recovery.  Care should be taken when working with these devices
+to roll back snaps or reset things to a clean state as much as possible.