1 files changed, 89 insertions, 0 deletions
diff --git a/doc/rtd/development/datasource_creation.rst b/doc/rtd/development/datasource_creation.rst
new file mode 100644
index 00000000..f55508fc
--- /dev/null
+++ b/doc/rtd/development/datasource_creation.rst
@@ -0,0 +1,89 @@
+.. _datasource_creation:
+
+Datasource creation
+*******************
+
+There are multiple ways to provide `user data`, `metadata`, and
+`vendor data`, and each cloud solution prefers its own way. A datasource
+abstract base class defines a single interface to interact with the different
+clouds. Each cloud implementation must inherit from this base class to use this
+shared functionality and interface. See :file:`cloud-init/sources/__init__.py`
+to see this class.
+
+If you are interested in adding a new datasource for your cloud platform you
+will need to do all of the following:
+
+Identify a mechanism for positive identification of the platform
+================================================================
+
+It is good practice for a cloud platform to positively identify itself to
+the guest. This allows the guest to make educated decisions based on the
+platform on which it is running. On the x86 and arm64 architectures, many
+clouds identify themselves through `DMI`_ data. For example, Oracle's public
+cloud provides the string ``'OracleCloud.com'`` in the DMI chassis-asset
+field.
+
+``Cloud-init``-enabled images produce a log file with details about the
+platform. Reading through this log in :file:`/run/cloud-init/ds-identify.log`
+may provide the information needed to uniquely identify the platform.
+If the log is not present, you can generate it by running from source
+:file:`./tools/ds-identify` or the installed location
+:file:`/usr/lib/cloud-init/ds-identify`.
+
+The mechanism used to identify the platform will be required for the
+``ds-identify`` and datasource module sections below.
+
+Add datasource module cloudinit/sources/DataSource<CloudPlatform>.py
+====================================================================
+
+We suggest you start by copying one of the simpler datasources
+such as ``DataSourceHetzner``.
+
+Add tests for datasource module
+===============================
+
+Add a new file with some tests for the module to
+:file:`cloudinit/sources/test_<yourplatform>.py`. For example, see
+:file:`cloudinit/sources/tests/test_oracle.py`
+
+Update ``ds-identify``
+======================
+
+In ``systemd`` systems, ``ds-identify`` is used to detect which datasource
+should be enabled, or if ``cloud-init`` should run at all. You'll need to
+make changes to :file:`tools/ds-identify`.
+
+Add tests for ``ds-identify``
+=============================
+
+Add relevant tests in a new class to
+:file:`tests/unittests/test_ds_identify.py`. You can use ``TestOracle`` as
+an example.
+
+Add your datasource name to the built-in list of datasources
+============================================================
+
+Add your datasource module name to the end of the ``datasource_list``
+entry in :file:`cloudinit/settings.py`.
+
+Add your cloud platform to apport collection prompts
+====================================================
+
+Update the list of cloud platforms in :file:`cloudinit/apport.py`. This list
+will be provided to the user who invokes :command:`ubuntu-bug cloud-init`.
+
+Enable datasource by default in Ubuntu packaging branches
+=========================================================
+
+Ubuntu packaging branches contain a template file,
+:file:`debian/cloud-init.templates`, which ultimately sets the default
+``datasource_list`` when installed via package. This file needs updating when
+the commit gets into a package.
+
+Add documentation for your datasource
+=====================================
+
+You should add a new file in :file:`doc/datasources/<cloudplatform>.rst`.
+
+.. _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