| 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 |