summaryrefslogtreecommitdiff
path: root/doc
diff options
context:
space:
mode:
authorDaniel Watkins <daniel.watkins@canonical.com>2016-05-20 13:13:08 +0100
committerDaniel Watkins <daniel.watkins@canonical.com>2016-05-20 13:13:08 +0100
commitb699df642dec996c517a94ea44f5e763c08570d0 (patch)
tree8ce19b5291d8a232c34fe06b1f10b5dd35e48e40 /doc
parent1df451e76d98371cf54e7a474c4d46fa3a96361a (diff)
downloadvyos-cloud-init-b699df642dec996c517a94ea44f5e763c08570d0.tar.gz
vyos-cloud-init-b699df642dec996c517a94ea44f5e763c08570d0.zip
Update merging documentation to make its application clearer
Currently, some users think that user-data and conf.d configuration will be merged together[0]. This has never been the case, and we should make it clear that this is not currently supported to avoid user confusion. [0] https://bugs.launchpad.net/cloud-init/+bug/1532234
Diffstat (limited to 'doc')
-rw-r--r--doc/merging.rst24
-rw-r--r--doc/rtd/topics/merging.rst6
2 files changed, 18 insertions, 12 deletions
diff --git a/doc/merging.rst b/doc/merging.rst
index 4046338b..2967ca9d 100644
--- a/doc/merging.rst
+++ b/doc/merging.rst
@@ -1,15 +1,16 @@
Overview
--------
-This was done because it has been a common feature request that there be a
-way to specify how cloud-config yaml "dictionaries" are merged together when
-there are multiple yamls to merge together (say when performing an #include).
+This was implemented because it has been a common feature request that there be
+a way to specify how cloud-config yaml "dictionaries" provided as user-data are
+merged together when there are multiple yamls to merge together (say when
+performing an #include).
Since previously the merging algorithm was very simple and would only overwrite
and not append lists, or strings, and so on it was decided to create a new and
improved way to merge dictionaries (and there contained objects) together in a
-way that is customizable, thus allowing for users who provide cloud-config data
-to determine exactly how there objects will be merged.
+way that is customizable, thus allowing for users who provide cloud-config
+user-data to determine exactly how there objects will be merged.
For example.
@@ -181,8 +182,13 @@ cloud-config dictionary coming after it.
Other uses
----------
-The default merging algorithm for merging 'conf.d' yaml files (which form a initial
-yaml config for cloud-init) was also changed to use this mechanism so its full
+In addition to being used for merging user-data sections, the default merging
+algorithm for merging 'conf.d' yaml files (which form an initial yaml config
+for cloud-init) was also changed to use this mechanism so its full
benefits (and customization) can also be used there as well. Other places that
-used the previous merging are also similar now extensible (metadata merging for
-example).
+used the previous merging are also, similarly, now extensible (metadata
+merging, for example).
+
+Note, however, that merge algorithms are not used *across* types of
+configuration. As was previously the case, merged user-data will still
+overwrite conf.d configuration.
diff --git a/doc/rtd/topics/merging.rst b/doc/rtd/topics/merging.rst
index 8a03f3c7..2bd87b16 100644
--- a/doc/rtd/topics/merging.rst
+++ b/doc/rtd/topics/merging.rst
@@ -1,5 +1,5 @@
-=========
-Merging
-=========
+==========================
+Merging User-Data Sections
+==========================
.. include:: ../../merging.rst