From cf93b5d140aae2cd99001fc3077f7d646d33c4be Mon Sep 17 00:00:00 2001
From: Alberto Contreras <alberto.contreras@canonical.com>
Date: Thu, 25 Jul 2024 15:17:09 +0200
Subject: [PATCH] doc: add doc for custom datasources (#5548)

---
 doc/rtd/development/datasource_creation.rst       |  2 ++
 doc/rtd/reference/base_config_reference.rst       |  2 ++
 .../custom_modules/custom_datasource.rst          | 15 +++++++++++++++
 3 files changed, 19 insertions(+)

diff --git a/doc/rtd/development/datasource_creation.rst b/doc/rtd/development/datasource_creation.rst
index 98f9f88419a..5f8d2b02da2 100644
--- a/doc/rtd/development/datasource_creation.rst
+++ b/doc/rtd/development/datasource_creation.rst
@@ -170,6 +170,8 @@ Datasources included in upstream cloud-init benefit from ongoing maintenance,
 compatibility with the rest of the codebase, and security fixes by the upstream
 development team.
 
+If this is not possible, one can add
+:ref:`custom out-of-tree datasources to cloud-init<custom_datasource>`.
 
 .. _make-mime: https://cloudinit.readthedocs.io/en/latest/explanation/instancedata.html#storage-locations
 .. _DMI: https://www.dmtf.org/sites/default/files/standards/documents/DSP0005.pdf
diff --git a/doc/rtd/reference/base_config_reference.rst b/doc/rtd/reference/base_config_reference.rst
index 9686d456d11..e1602c5df4f 100644
--- a/doc/rtd/reference/base_config_reference.rst
+++ b/doc/rtd/reference/base_config_reference.rst
@@ -221,6 +221,8 @@ Other keys
 The :ref:`network configuration<network_config>` to be applied to this
 instance.
 
+.. _base_config_datasource_pkg_list:
+
 ``datasource_pkg_list``
 ^^^^^^^^^^^^^^^^^^^^^^^
 
diff --git a/doc/rtd/reference/custom_modules/custom_datasource.rst b/doc/rtd/reference/custom_modules/custom_datasource.rst
index 7b300781cc7..d3ddffbc593 100644
--- a/doc/rtd/reference/custom_modules/custom_datasource.rst
+++ b/doc/rtd/reference/custom_modules/custom_datasource.rst
@@ -2,3 +2,18 @@
 
 Custom DataSource
 *****************
+
+Custom 3rd-party out-of-tree DataSources can be added to cloud-init by:
+
+#. :ref:`Implement a DataSource<datasource_creation>` in a Python file.
+
+#. Place that file in as a single Python module or package in folder included
+   in ``$PYTHONPATH``.
+
+#. Extend the :ref:`base-configuration<base_config_reference>`'s
+   :ref:`datasource_pkg_list<base_config_datasource_pkg_list>` to include the
+   Python package where the DataSource is located.
+
+#. Extend the :ref:`base-configuration<base_config_reference>`'s
+   :ref:`datasource_list<base_config_datasource_list>` to include the name of
+   the custom DataSource.