Debian Codegraph @

docs/src/cdist-stages.rst

raw
1 Execution stages
2 ================
3
4 Description
5 -----------
6 When cdist is started, it passes through different stages.
7
8
9 Stage 1: target information retrieval
10 -------------------------------------
11 In this stage information is collected about the target host using so called
12 explorers. Every existing explorer is run on the target and the output of all
13 explorers are copied back into the local cache. The results can be used by
14 manifests and types.
15
16
17 Stage 2: run the initial manifest
18 ---------------------------------
19 The initial manifest, which should be used for mappings of hosts to types,
20 is executed. This stage creates objects in a cconfig database that contains
21 the objects as defined in the manifest for the specific host. In this stage,
22 no conflicts may occur, i.e. no object of the same type with the same id may
23 be created, if it has different parameters.
24
25
26 Stage 3: object information retrieval
27 -------------------------------------
28 Every object is checked whether its type has explorers and if so, these are
29 executed on the target host. The results are transferred back
30 and can be used in the following stages to decide what changes need to be made
31 on the target to implement the desired state.
32
33
34 Stage 4: run the object manifest
35 --------------------------------
36 Every object is checked whether its type has a executable manifest. The
37 manifest script may generate and change the created objects. In other words,
38 one type can reuse other types.
39
40 For instance the object __apache/www.example.org is of type __apache, which may
41 contain a manifest script, which creates new objects of type __file.
42
43 The newly created objects are merged back into the existing tree. No conflicts
44 may occur during the merge. A conflict would mean that two different objects
45 try to create the same object, which indicates a broken configuration.
46
47
48 Stage 5: code generation
49 ------------------------
50 In this stage for every created object its type is checked for executable
51 gencode scripts. The gencode scripts generate the code to be executed on the
52 target on stdout. If the gencode executables fail, they must print diagnostic
53 messages on stderr and exit non-zero.
54
55
56 Stage 6: code execution
57 -----------------------
58 For every object the resulting code from the previous stage is transferred to
59 the target host and executed there to apply the configuration changes.
60
61
62 Stage 7: cache
63 --------------
64 The cache stores the information from the current run for later use.
65
66
67 Summary
68 -------
69 If, and only if, all the stages complete without errors, the configuration
70 will be applied to the target.