Debian Codegraph @

docs/src/cdist-manifest.rst

raw
1 Manifest
2 ========
3
4 Description
5 -----------
6 Manifests are used to define which objects to create.
7 Objects are instances of **types**, like in object oriented programming languages.
8 An object is represented by the combination of
9 **type + slash + object name**: **\__file/etc/cdist-configured** is an
10 object of the type **__file** with the name **etc/cdist-configured**.
11
12 All available types can be found in the **cdist/conf/type/** directory,
13 use **ls cdist/conf/type** to get the list of available types. If you have
14 setup the MANPATH correctly, you can use **man cdist-reference** to access
15 the reference with pointers to the manpages.
16
17
18 Types in manifests are used like normal command line tools. Let's have a look
19 at an example::
20
21 # Create object of type __package with the parameter state = absent
22 __package apache2 --state absent
23
24 # Same with the __directory type
25 __directory /tmp/cdist --state present
26
27 These two lines create objects, which will later be used to realise the
28 configuration on the target host.
29
30 Manifests are executed locally as a shell script using **/bin/sh -e**.
31 The resulting objects are stored in an internal database.
32
33 The same object can be redefined in multiple different manifests as long as
34 the parameters are exactly the same.
35
36 In general, manifests are used to define which types are used depending
37 on given conditions.
38
39
40 Initial and type manifests
41 --------------------------
42 Cdist knows about two types of manifests: The initial manifest and type
43 manifests. The initial manifest is used to define, which configurations
44 to apply to which hosts. The type manifests are used to create objects
45 from types. More about manifests in types can be found in `cdist type <cdist-type.html>`_.
46
47
48 Define state in the initial manifest
49 ------------------------------------
50 The **initial manifest** is the entry point for cdist to find out, which
51 **objects** to configure on the selected host.
52 Cdist expects the initial manifest at **cdist/conf/manifest/init**.
53
54 Within this initial manifest you define which objects should be
55 created on which host. To distinguish between hosts, you can use the
56 environment variable **__target_host** and/or **__target_hostname** and/or
57 **__target_fqdn**. Let's have a look at a simple example::
58
59 __cdistmarker
60
61 case "$__target_host" in
62 localhost)
63 __directory /home/services/kvm-vm --parents yes
64 ;;
65 esac
66
67 This manifest says: Independent of the host, always use the type
68 **__cdistmarker**, which creates the file **/etc/cdist-configured**,
69 with the timestamp as content.
70 The directory **/home/services/kvm-vm**, including all parent directories,
71 is only created on the host **localhost**.
72
73 As you can see, there is no magic involved, the manifest is simple shell code that
74 utilises cdist types. Every available type can be executed like a normal
75 command.
76
77
78 Splitting up the initial manifest
79 ---------------------------------
80 If you want to split up your initial manifest, you can create other shell
81 scripts in **cdist/conf/manifest/** and include them in **cdist/conf/manifest/init**.
82 Cdist provides the environment variable **__manifest** to reference
83 the directory containing the initial manifest (see `cdist reference <cdist-reference.html>`_).
84
85 The following example would include every file with a **.sh** suffix::
86
87 # Include *.sh
88 for manifest in $__manifest/*.sh; do
89 # And source scripts into our shell environment
90 . "$manifest"
91 done
92
93
94 Dependencies
95 ------------
96 If you want to describe that something requires something else, just
97 setup the variable "require" to contain the requirements. Multiple
98 requirements can be added separated with (optionally consecutive)
99 delimiters including space, tab and newline.
100
101 ::
102
103 1 # No dependency
104 2 __file /etc/cdist-configured
105 3
106 4 # Require above object
107 5 require="__file/etc/cdist-configured" __link /tmp/cdist-testfile \
108 6 --source /etc/cdist-configured --type symbolic
109 7
110 8 # Require two objects
111 9 require="__file/etc/cdist-configured __link/tmp/cdist-testfile" \
112 10 __file /tmp/cdist-another-testfile
113
114
115 Above the "require" variable is only set for the command that is
116 immediately following it. Dependencies should always be declared that way.
117
118 On line 4 you can see that the instantiation of a type "\__link" object needs
119 the object "__file/etc/cdist-configured" to be present, before it can proceed.
120
121 This also means that the "\__link" command must make sure, that either
122 "\__file/etc/cdist-configured" already is present, or, if it's not, it needs
123 to be created. The task of cdist is to make sure, that the dependency will be
124 resolved appropriately and thus "\__file/etc/cdist-configured" be created
125 if necessary before "__link" proceeds (or to abort execution with an error).
126
127 If you really need to make all types depend on a common dependency, you can
128 export the "require" variable as well. But then, if you need to add extra
129 dependencies to a specific type, you have to make sure that you append these
130 to the globally already defined one.
131
132 ::
133
134 # First of all, update the package index
135 __package_update_index
136 # Upgrade all the installed packages afterwards
137 require="__package_update_index" __package_upgrade_all
138 # Create a common dependency for all the next types so that they get to
139 # be executed only after the package upgrade has finished
140 export require="__package_upgrade_all"
141
142 # Ensure that lighttpd is installed after we have upgraded all the packages
143 __package lighttpd --state present
144 # Ensure that munin is installed after lighttpd is present and after all
145 # the packages are upgraded
146 require="$require __package/lighttpd" __package munin --state present
147
148
149 All objects that are created in a type manifest are automatically required
150 from the type that is calling them. This is called "autorequirement" in
151 cdist jargon.
152
153 You can find a more in depth description of the flow execution of manifests
154 in `cdist execution stages <cdist-stages.html>`_ and of how types work in `cdist type <cdist-type.html>`_.
155
156
157 Create dependencies from execution order
158 -----------------------------------------
159 You can tell cdist to execute all types in the order in which they are created
160 in the manifest by setting up the variable CDIST_ORDER_DEPENDENCY.
161 When cdist sees that this variable is setup, the current created object
162 automatically depends on the previously created object.
163
164 It essentially helps you to build up blocks of code that build upon each other
165 (like first creating the directory xyz than the file below the directory).
166
167 Read also about `notes on CDIST_ORDER_DEPENDENCY <cdist-best-practice.html#notes-on-cdist-order-dependency>`_.
168
169 In version 6.2.0 semantic CDIST_ORDER_DEPENDENCY is finally fixed and well defined.
170
171 CDIST_ORDER_DEPENDENCY defines type order dependency context. Order dependency context
172 starts when CDIST_ORDER_DEPENDENCY is set, and ends when it is unset. After each
173 manifest execution finishes, any existing order dependency context is automatically
174 unset. This ensures that CDIST_ORDER_DEPENDENCY is valid within the manifest where it
175 is used. When order dependency context is defined then cdist executes types in the
176 order in which they are created in the manifest inside order dependency context.
177
178 Sometimes the best way to see how something works is to see examples.
179
180 Suppose you have defined **initial manifest**:
181
182 .. code-block:: sh
183
184 __cycle1 cycle1
185 export CDIST_ORDER_DEPENDENCY=1
186 __cycle2 cycle2
187 __cycle3 cycle3
188
189 with types **__cycle1**:
190
191 .. code-block:: sh
192
193 export CDIST_ORDER_DEPENDENCY=1
194 __file /tmp/cycle11
195 __file /tmp/cycle12
196 __file /tmp/cycle13
197
198 **__cycle2**:
199
200 .. code-block:: sh
201
202 __file /tmp/cycle21
203 export CDIST_ORDER_DEPENDENCY=1
204 __file /tmp/cycle22
205 __file /tmp/cycle23
206 unset CDIST_ORDER_DEPENDENCY
207 __file /tmp/cycle24
208
209 **__cycle3**:
210
211 .. code-block:: sh
212
213 __file /tmp/cycle31
214 __file /tmp/cycle32
215 export CDIST_ORDER_DEPENDENCY=1
216 __file /tmp/cycle33
217 __file /tmp/cycle34
218
219 For the above config, cdist results in the following expected *dependency graph*
220 (type *__cycleX* is shown as *cX*, *__file/tmp/cycleXY* is shown as *fcXY*):
221
222 ::
223
224 c1---->fc11
225 | /\
226 | |
227 +----->fc12
228 | /\
229 | |
230 +----->fc13
231
232 c2--+--->fc21
233 /\ |
234 | |
235 | +----->fc22
236 | | /\
237 | | |
238 | +----->fc23
239 | |
240 | |
241 | +----->fc24
242 |
243 |
244 c3---->fc31
245 |
246 |
247 +----->fc32
248 |
249 |
250 +----->fc33
251 | /\
252 | |
253 +----->fc34
254
255 Before version 6.2.0 the above configuration would result in cycle:
256
257 ::
258
259 ERROR: 185.203.112.26: Cycle detected in object dependencies:
260 __file/tmp/cycle11 -> __cycle3/cycle3 -> __cycle2/cycle2 -> __cycle1/cycle1 -> __file/tmp/cycle11!
261
262 The following manifest shows an example for order dependency contexts:
263
264 .. code-block:: sh
265
266 __file /tmp/fileA
267 export CDIST_ORDER_DEPENDENCY=1
268 __file /tmp/fileB
269 __file /tmp/fileC
270 __file /tmp/fileD
271 unset CDIST_ORDER_DEPENDENCY
272 __file /tmp/fileE
273 __file /tmp/fileF
274 export CDIST_ORDER_DEPENDENCY=1
275 __file /tmp/fileG
276 __file /tmp/fileH
277 unset CDIST_ORDER_DEPENDENCY
278 __file /tmp/fileI
279
280 This means:
281
282 * C depends on B
283 * D depends on C
284 * H depends on G
285
286 and there are no other dependencies from this manifest.
287
288
289 Overrides
290 ---------
291 In some special cases, you would like to create an already defined object
292 with different parameters. In normal situations this leads to an error in cdist.
293 If you wish, you can setup the environment variable CDIST_OVERRIDE
294 (any value or even empty is ok) to tell cdist, that this object override is
295 wanted and should be accepted.
296 ATTENTION: Only use this feature if you are 100% sure in which order
297 cdist encounters the affected objects, otherwise this results
298 in an undefined situation.
299
300 If CDIST_OVERRIDE and CDIST_ORDER_DEPENDENCY are set for an object,
301 CDIST_ORDER_DEPENDENCY will be ignored, because adding a dependency in case of
302 overrides would result in circular dependencies, which is an error.
303
304
305 Examples
306 --------
307 The initial manifest may for instance contain the following code:
308
309 .. code-block:: sh
310
311 # Always create this file, so other sysadmins know cdist is used.
312 __file /etc/cdist-configured
313
314 case "$__target_host" in
315 my.server.name)
316 __directory /root/bin/
317 __file /etc/issue.net --source "$__manifest/issue.net
318 ;;
319 esac
320
321 The manifest of the type "nologin" may look like this:
322
323 .. code-block:: sh
324
325 __file /etc/nologin --source "$__type/files/default.nologin"
326
327 This example makes use of dependencies:
328
329 .. code-block:: sh
330
331 # Ensure that lighttpd is installed
332 __package lighttpd --state present
333 # Ensure that munin makes use of lighttpd instead of the default webserver
334 # package as decided by the package manager
335 require="__package/lighttpd" __package munin --state present
336
337 How to override objects:
338
339 .. code-block:: sh
340
341 # for example in the initial manifest
342
343 # create user account foobar with some hash for password
344 __user foobar --password 'some_fancy_hash' --home /home/foobarexample
345
346 # ... many statements and includes in the manifest later ...
347 # somewhere in a conditionally sourced manifest
348 # (e.g. for example only sourced if a special application is on the target host)
349
350 # this leads to an error ...
351 __user foobar --password 'some_other_hash'
352
353 # this tells cdist, that you know that this is an override and should be accepted
354 CDIST_OVERRIDE=yes __user foobar --password 'some_other_hash'
355 # it's only an override, means the parameter --home is not touched
356 # and stays at the original value of /home/foobarexample
357
358 Dependencies defined by execution order work as following:
359
360 .. code-block:: sh
361
362 # Tells cdist to execute all types in the order in which they are created ...
363 export CDIST_ORDER_DEPENDENCY=on
364 __sample_type 1
365 require="__some_type_somewhere/id" __sample_type 2
366 __example_type 23
367 # Now this types are executed in the creation order until the variable is unset
368 unset CDIST_ORDER_DEPENDENCY
369 # all now following types cdist makes the order ..
370 __not_in_order_type 42
371
372 # how it works :
373 # this lines above are translated to:
374 __sample_type 1
375 require="__some_type_somewhere/id __sample_type/1" __sample_type 2
376 require="__sample_type/2" __example_type 23
377 __not_in_order_type 42