← Back to branch summary

~ubuntu-branches/ubuntu/raring/cloud-init/raring

« back to all changes in this revision

Viewing changes to doc/merging.rst

  • Committer: Package Import Robot
  • Author(s): Scott Moser
  • Date: 2013-03-27 10:04:41 UTC
  • mfrom: (245.1.4 raring)
  • Revision ID: package-import@ubuntu.com-20130327100441-o1u6gxh6f5pat822
Tags: 0.7.2~bzr804-0ubuntu1
https://launchpad.net/bugs/1067888
https://launchpad.net/bugs/1160462
* New upstream snapshot.
  * use python-requests rather than urllib2 for http (LP: #1067888)
  * handle failure of resizefs better.  Specifically, do not show
    warnings or stack trace in lxc (LP: #1160462)

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/merging.rst
 
1
Overview
 
2
--------
 
3
 
 
4
This was done because it has been a common feature request that there be a
 
5
way to specify how cloud-config yaml "dictionaries" are merged together when
 
6
there are multiple yamls to merge together (say when performing an #include).
 
7
 
 
8
Since previously the merging algorithm was very simple and would only overwrite
 
9
and not append lists, or strings, and so on it was decided to create a new and
 
10
improved way to merge dictionaries (and there contained objects) together in a
 
11
way that is customizable, thus allowing for users who provide cloud-config data
 
12
to determine exactly how there objects will be merged.
 
13
 
 
14
For example.
 
15
 
 
16
.. code-block:: yaml
 
17
 
 
18
   #cloud-config (1)
 
19
   run_cmd:
 
20
     - bash1
 
21
     - bash2
 
22
   
 
23
   #cloud-config (2)
 
24
   run_cmd:
 
25
     - bash3
 
26
     - bash4
 
27
 
 
28
The previous way of merging the following 2 objects would result in a final 
 
29
cloud-config object that contains the following.
 
30
 
 
31
.. code-block:: yaml
 
32
 
 
33
   #cloud-config (merged)
 
34
   run_cmd:
 
35
     - bash3
 
36
     - bash4
 
37
 
 
38
Typically this is not what users want, instead they would likely prefer:
 
39
 
 
40
.. code-block:: yaml
 
41
 
 
42
   #cloud-config (merged)
 
43
   run_cmd:
 
44
     - bash1
 
45
     - bash2
 
46
     - bash3
 
47
     - bash4
 
48
 
 
49
This way makes it easier to combine the various cloud-config objects you have
 
50
into a more useful list, thus reducing duplication that would have had to
 
51
occur in the previous method to accomplish the same result.
 
52
 
 
53
Customizability
 
54
---------------
 
55
 
 
56
Since the above merging algorithm may not always be the desired merging
 
57
algorithm (like how the previous merging algorithm was not always the preferred
 
58
one) the concept of customizing how merging can be done was introduced through
 
59
a new concept call 'merge classes'. 
 
60
 
 
61
A merge class is a class defintion which provides functions that can be used
 
62
to merge a given type with another given type.
 
63
 
 
64
An example of one of these merging classes is the following:
 
65
 
 
66
.. code-block:: python
 
67
 
 
68
   class Merger(object):
 
69
       def __init__(self, merger, opts):
 
70
           self._merger = merger
 
71
           self._overwrite = 'overwrite' in opts
 
72
   
 
73
       # This merging algorithm will attempt to merge with
 
74
       # another dictionary, on encountering any other type of object
 
75
       # it will not merge with said object, but will instead return
 
76
       # the original value
 
77
       #
 
78
       # On encountering a dictionary, it will create a new dictionary
 
79
       # composed of the original and the one to merge with, if 'overwrite'
 
80
       # is enabled then keys that exist in the original will be overwritten
 
81
       # by keys in the one to merge with (and associated values). Otherwise
 
82
       # if not in overwrite mode the 2 conflicting keys themselves will
 
83
       # be merged.
 
84
       def _on_dict(self, value, merge_with):
 
85
           if not isinstance(merge_with, (dict)):
 
86
               return value
 
87
           merged = dict(value)
 
88
           for (k, v) in merge_with.items():
 
89
               if k in merged:
 
90
                   if not self._overwrite:
 
91
                       merged[k] = self._merger.merge(merged[k], v)
 
92
                   else:
 
93
                       merged[k] = v
 
94
               else:
 
95
                   merged[k] = v
 
96
           return merged
 
97
 
 
98
As you can see there is a '_on_dict' method here that will be given a source value
 
99
and a value to merge with. The result will be the merged object. This code itself
 
100
is called by another merging class which 'directs' the merging to happen by
 
101
analyzing the types of the objects to merge and attempting to find a know object
 
102
that will merge that type. I will avoid pasting that here, but it can be found
 
103
in the `mergers/__init__.py` file (see `LookupMerger` and `UnknownMerger`).
 
104
 
 
105
So following the typical cloud-init way of allowing source code to be downloaded
 
106
and used dynamically, it is possible for users to inject there own merging files
 
107
to handle specific types of merging as they choose (the basic ones included will
 
108
handle lists, dicts, and strings). Note how each merge can have options associated
 
109
with it which affect how the merging is performed, for example a dictionary merger
 
110
can be told to overwrite instead of attempt to merge, or a string merger can be
 
111
told to append strings instead of discarding other strings to merge with.
 
112
 
 
113
How to activate
 
114
---------------
 
115
 
 
116
There are a few ways to activate the merging algorithms, and to customize them
 
117
for your own usage.
 
118
 
 
119
1. The first way involves the usage of MIME messages in cloud-init to specify
 
120
   multipart documents (this is one way in which multiple cloud-config is joined
 
121
   together into a single cloud-config). Two new headers are looked for, both
 
122
   of which can define the way merging is done (the first header to exist wins).
 
123
   These new headers (in lookup order) are 'Merge-Type' and 'X-Merge-Type'. The value
 
124
   should be a string which will satisfy the new merging format defintion (see
 
125
   below for this format).
 
126
2. The second way is actually specifying the merge-type in the body of the
 
127
   cloud-config dictionary. There are 2 ways to specify this, either as a string
 
128
   or as a dictionary (see format below). The keys that are looked up for this
 
129
   definition are the following (in order), 'merge_how', 'merge_type'.
 
130
 
 
131
String format
 
132
********
 
133
 
 
134
The string format that is expected is the following.
 
135
 
 
136
::
 
137
    
 
138
   classname1(option1,option2)+classname2(option3,option4)....
 
139
 
 
140
The class name there will be connected to class names used when looking for the
 
141
class that can be used to merge and options provided will be given to the class
 
142
on construction of that class.
 
143
 
 
144
For example, the default string that is used when none is provided is the following:
 
145
 
 
146
::
 
147
    
 
148
   list(extend)+dict()+str(append)
 
149
 
 
150
Dictionary format
 
151
********
 
152
 
 
153
In cases where a dictionary can be used to specify the same information as the
 
154
string format (ie option #2 of above) it can be used, for example.
 
155
 
 
156
.. code-block:: python
 
157
 
 
158
   {'merge_how': [{'name': 'list', 'settings': ['extend']},
 
159
                  {'name': 'dict', 'settings': []},
 
160
                  {'name': 'str', 'settings': ['append']}]}
 
161
 
 
162
This would be the equivalent format for default string format but in dictionary
 
163
form instead of string form.
 
164
 
 
165
Specifying multiple types and its effect
 
166
----------------------------------------
 
167
 
 
168
Now you may be asking yourself, if I specify a merge-type header or dictionary
 
169
for every cloud-config that I provide, what exactly happens?
 
170
 
 
171
The answer is that when merging, a stack of 'merging classes' is kept, the
 
172
first one on that stack is the default merging classes, this set of mergers
 
173
will be used when the first cloud-config is merged with the initial empty
 
174
cloud-config dictionary. If the cloud-config that was just merged provided a 
 
175
set of merging classes (via the above formats) then those merging classes will
 
176
be pushed onto the stack. Now if there is a second cloud-config to be merged then
 
177
the merging classes from the cloud-config before the first will be used (not the
 
178
default) and so on. This way a cloud-config can decide how it will merge with a
 
179
cloud-config dictionary coming after it.
 
180
 
 
181
Other uses
 
182
----------
 
183
 
 
184
The default merging algorithm for merging 'conf.d' yaml files (which form a initial
 
185
yaml config for cloud-init) was also changed to use this mechanism so its full
 
186
benefits (and customization) can also be used there as well. Other places that
 
187
used the previous merging are also similar now extensible (metadata merging for
 
188
example).