doc: update docs adding YAML 1.1 spec and jinja template references

doc/rtd/explanation/configuration.rst

@@ -11,12 +11,16 @@ higher priority source overwrites the lower priority source.
 Base configuration
 ==================
 
+The base configuration format uses `YAML version 1.1`_, but may be
+declared as jinja templates which cloud-init will render at runtime with
+:ref:`instance data <instancedata-Using>` variables.
+
 From lowest priority to highest, configuration sources are:
 
-- **Hardcoded config**: Config_ that lives within the source of ``cloud-init``
+- **Hardcoded config** Config_ that lives within the source of ``cloud-init``
   and cannot be changed.
 - **Configuration directory**: Anything defined in :file:`/etc/cloud/cloud.cfg`
-  and :file:`/etc/cloud/cloud.cfg.d`.
+  and :file:`/etc/cloud/cloud.cfg.d/*.cfg`.
 - **Runtime config**: Anything defined in :file:`/run/cloud-init/cloud.cfg`.
 - **Kernel command line**: On the kernel command line, anything found between
   ``cc:`` and ``end_cc`` will be interpreted as cloud-config user data.
@@ -25,6 +29,11 @@ These four sources make up the base configuration. The contents of this
 configuration are defined in the
 :ref:`base configuration reference page<base_config_reference>`.
 
+.. note::
+   Base configuration may contain
+   :ref:`cloud-config<explanation/format:Cloud config data>` which may be
+   overridden by vendor data and user data.
+
 Vendor and user data
 ====================
 
@@ -33,11 +42,6 @@ Added to the base configuration are :ref:`vendor data<vendordata>` and
 
 These get fetched from the datasource and are defined at instance launch.
 
-.. note::
-   While much of what is defined in the base configuration can be overridden by
-   vendor data and user data, base configuration sources do not conform to
-   :ref:`#cloud-config<user_data_formats>`.
-
 Network configuration
 =====================
 
@@ -81,3 +85,4 @@ images.
 
 .. _Config: https://github.com/canonical/cloud-init/blob/b861ea8a5e1fd0eb33096f60f54eeff42d80d3bd/cloudinit/settings.py#L22
 .. _cloud.cfg template: https://github.com/canonical/cloud-init/blob/main/config/cloud.cfg.tmpl
+.. _YAML version 1.1: https://yaml.org/spec/1.1/current.html

doc/rtd/explanation/format.rst

@@ -3,29 +3,27 @@
 User data formats
 *****************
 
-User data that will be acted upon by ``cloud-init`` must be in one of the
-following types.
+User data is opaque configuration data provided by a platform to an instance at
+launch configure the instance. User data can be one of the following types.
 
 .. _user_data_formats-cloud_config:
 
 Cloud config data
 =================
 
-Cloud-config is the simplest way to accomplish some things via user data.
-Using cloud-config syntax, the user can specify certain things in a
-human-friendly format.
+Cloud-config is the preferred user data format. The cloud config format is a
+declarative syntax which uses `YAML version 1.1`_ with keys which describe
+desired instance state. Cloud-config can be used to define how an instance
+should be configured in a human-friendly format.
 
-These things include:
+These things may include:
 
-- ``apt upgrade`` should be run on first boot
-- a different ``apt`` mirror should be used
-- additional ``apt`` sources should be added
-- certain SSH keys should be imported
+- performing package upgrades on first boot
+- configuration of different package mirrors or sources
+- initial user or group setup
+- importing certain SSH keys or host keys
 - *and many more...*
 
-.. note::
-   This file must be valid YAML syntax.
-
 See the :ref:`yaml_examples` section for a commented set of examples of
 supported cloud config formats.
 
@@ -34,7 +32,7 @@ using a MIME archive.
 
 .. note::
    Cloud config data can also render cloud instance metadata variables using
-   jinja templating. See :ref:`instance_metadata` for more information.
+   :ref:`jinja templates <instancedata-Using>`.
 
 .. _user_data_script:
 
@@ -47,7 +45,7 @@ Begins with: ``#!`` or ``Content-Type: text/x-shellscript`` when using a MIME
 archive.
 
 User data scripts can optionally render cloud instance metadata variables using
-jinja templating. See :ref:`instance_metadata` for more information.
+:ref:`jinja templates <instancedata-Using>`.
 
 Example script
 --------------
@@ -222,5 +220,6 @@ appliances. Setting ``allow_userdata: false`` in the configuration will disable
 ``cloud-init`` from processing user data.
 
 .. _make-mime: https://github.com/canonical/cloud-init/blob/main/cloudinit/cmd/devel/make_mime.py
+.. _YAML version 1.1: https://yaml.org/spec/1.1/current.html
 .. [#] See your cloud provider for applicable user-data size limitations...
 .. _this blog post: http://foss-boss.blogspot.com/2011/01/advanced-cloud-init-custom-handlers.html