From 1df451e76d98371cf54e7a474c4d46fa3a96361a Mon Sep 17 00:00:00 2001 From: Daniel Watkins Date: Fri, 20 May 2016 13:03:42 +0100 Subject: Clean up merging.rst formatting --- doc/merging.rst | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/doc/merging.rst b/doc/merging.rst index d4d5cd05..4046338b 100644 --- a/doc/merging.rst +++ b/doc/merging.rst @@ -19,13 +19,13 @@ For example. run_cmd: - bash1 - bash2 - + #cloud-config (2) run_cmd: - bash3 - bash4 -The previous way of merging the following 2 objects would result in a final +The previous way of merging the following 2 objects would result in a final cloud-config object that contains the following. .. code-block:: yaml @@ -56,7 +56,7 @@ Customizability Since the above merging algorithm may not always be the desired merging algorithm (like how the previous merging algorithm was not always the preferred one) the concept of customizing how merging can be done was introduced through -a new concept call 'merge classes'. +a new concept call 'merge classes'. A merge class is a class defintion which provides functions that can be used to merge a given type with another given type. @@ -69,7 +69,7 @@ An example of one of these merging classes is the following: def __init__(self, merger, opts): self._merger = merger self._overwrite = 'overwrite' in opts - + # This merging algorithm will attempt to merge with # another dictionary, on encountering any other type of object # it will not merge with said object, but will instead return @@ -129,12 +129,12 @@ for your own usage. definition are the following (in order), 'merge_how', 'merge_type'. String format -******** +************* The string format that is expected is the following. :: - + classname1(option1,option2)+classname2(option3,option4).... The class name there will be connected to class names used when looking for the @@ -144,11 +144,11 @@ on construction of that class. For example, the default string that is used when none is provided is the following: :: - + list()+dict()+str() Dictionary format -******** +***************** In cases where a dictionary can be used to specify the same information as the string format (ie option #2 of above) it can be used, for example. @@ -171,7 +171,7 @@ for every cloud-config that I provide, what exactly happens? The answer is that when merging, a stack of 'merging classes' is kept, the first one on that stack is the default merging classes, this set of mergers will be used when the first cloud-config is merged with the initial empty -cloud-config dictionary. If the cloud-config that was just merged provided a +cloud-config dictionary. If the cloud-config that was just merged provided a set of merging classes (via the above formats) then those merging classes will be pushed onto the stack. Now if there is a second cloud-config to be merged then the merging classes from the cloud-config before the first will be used (not the -- cgit v1.2.3 From b699df642dec996c517a94ea44f5e763c08570d0 Mon Sep 17 00:00:00 2001 From: Daniel Watkins Date: Fri, 20 May 2016 13:13:08 +0100 Subject: 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 --- doc/merging.rst | 24 +++++++++++++++--------- doc/rtd/topics/merging.rst | 6 +++--- 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 -- cgit v1.2.3 From 75907ec96181599dc0282aac989ce02a88c3b39d Mon Sep 17 00:00:00 2001 From: Daniel Watkins Date: Thu, 2 Jun 2016 16:20:18 +0100 Subject: Integrate MP feedback --- doc/merging.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/merging.rst b/doc/merging.rst index 2967ca9d..afe1a6dd 100644 --- a/doc/merging.rst +++ b/doc/merging.rst @@ -190,5 +190,5 @@ 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. +configuration. As was the case before merging was implemented, +user-data will overwrite conf.d configuration without merging. -- cgit v1.2.3