3 files changed, 55 insertions, 3 deletions
diff --git a/doc/source/admin/fast-track.rst b/doc/source/admin/fast-track.rst
index 20ca6199f..e42942818 100644
--- a/doc/source/admin/fast-track.rst
+++ b/doc/source/admin/fast-track.rst
@@ -15,6 +15,19 @@ provisioned within a short period of time.
    the ``noop`` networking. The case where inspection, cleaning and
    provisioning networks are different is not supported.
 
+.. note::
+   Fast track mode is very sensitive to long-running processes on the conductor
+   side that may prevent agent heartbeats from being registered.
+
+   For example, converting a large image to the raw format may take long enough
+   to reach the fast track timeout. In this case, you can either :ref:`use raw
+   images <stream_raw_images>` or move the conversion to the agent side with:
+
+   .. code-block:: ini
+
+    [DEFAULT]
+    force_raw_images = False
+
 Enabling
 ========
 
diff --git a/doc/source/admin/interfaces/deploy.rst b/doc/source/admin/interfaces/deploy.rst
index 7db5a24ff..79d004ad0 100644
--- a/doc/source/admin/interfaces/deploy.rst
+++ b/doc/source/admin/interfaces/deploy.rst
@@ -81,6 +81,46 @@ accessible from HTTP service. Please refer to configuration option
 ``FollowSymLinks`` if you are using Apache HTTP server, or
 ``disable_symlinks`` if Nginx HTTP server is in use.
 
+.. _stream_raw_images:
+
+Streaming raw images
+--------------------
+
+The Bare Metal service is capable of streaming raw images directly to the
+target disk of a node, without caching them in the node's RAM. When the source
+image is not already raw, the conductor will convert the image and calculate
+the new checksum.
+
+.. note::
+   If no algorithm is specified via the ``image_os_hash_algo`` field, or if
+   this field is set to ``md5``, SHA256 is used for the updated checksum.
+
+For HTTP or local file images that are already raw, you need to explicitly set
+the disk format to prevent the checksum from being unnecessarily re-calculated.
+For example:
+
+.. code-block:: shell
+
+    baremetal node set <node> \
+        --instance-info image_source=http://server/myimage.img \
+        --instance-info image_os_hash_algo=sha512 \
+        --instance-info image_os_hash_value=<SHA512 of the raw image> \
+        --instance-info image_disk_format=raw
+
+To disable this feature and cache images in the node's RAM, set
+
+.. code-block:: ini
+
+   [agent]
+   stream_raw_images = False
+
+To disable the conductor-side conversion completely, set
+
+.. code-block:: ini
+
+   [DEFAULT]
+   force_raw_images = False
+
 .. _ansible-deploy:
 
 Ansible deploy
diff --git a/doc/source/install/refarch/common.rst b/doc/source/install/refarch/common.rst
index 800632fd5..ce0dedfb1 100644
--- a/doc/source/install/refarch/common.rst
+++ b/doc/source/install/refarch/common.rst
@@ -277,9 +277,8 @@ the space requirements are different:
   In both cases a cached image is converted to raw if ``force_raw_images``
   is ``True`` (the default).
 
-  .. note::
-    ``image_download_source`` can also be provided in the node's
-    ``driver_info`` or ``instance_info``. See :ref:`image_download_source`.
+  See :ref:`image_download_source` and :ref:`stream_raw_images` for more
+  details.
 
 * When network boot is used, the instance image kernel and ramdisk are cached
   locally while the instance is active.