Debian Codegraph @

docs/src/cdist-best-practice.rst

raw
1 Best practice
2 =============
3 Practices used in real environments
4
5 Passwordless connections
6 ------------------------
7 It is recommended to run cdist with public key authentication.
8 This requires a private/public key pair and the entry
9 "PermitRootLogin without-password" in the sshd server.
10 See sshd_config(5) and ssh-keygen(1).
11
12
13 Speeding up ssh connections
14 ---------------------------
15 When connecting to a new host, the initial delay with ssh connections
16 is pretty big. As cdist makes many connections to each host successive
17 connections can be sped up by "sharing of multiple sessions over a single
18 network connection" (quote from ssh_config(5)). This is also called "connection
19 multiplexing".
20
21 Cdist implements this since v4.0.0 by executing ssh with the appropriate
22 options (`-o ControlMaster=auto -o ControlPath=/tmp/<tmpdir>/s -o
23 ControlPersist=2h`).
24
25 Note that the sshd_config on the server can configure the maximum number of
26 parallel multiplexed connections this with `MaxSessions N` (N defaults to 10
27 for OpenSSH v7.4).
28
29
30 Speeding up shell execution
31 ----------------------------
32 On the source host, ensure that /bin/sh is *not* bash: bash is quite slow for
33 script execution. Instead, you could use dash after installing it::
34
35 ln -sf /bin/dash /bin/sh
36
37
38 Multi master or environment setups
39 ----------------------------------
40 If you plan to distribute cdist among servers or use different
41 environments, you can do so easily with the included version
42 control git. For instance if you plan to use the typical three
43 environments production, integration and development, you can
44 realise this with git branches::
45
46 # Go to cdist checkout
47 cd /path/to/cdist
48
49 # Create branches
50 git branch development
51 git branch integration
52 git branch production
53
54 # Make use of a branch, for instance production
55 git checkout production
56
57 Similar if you want to have cdist checked out at multiple machines,
58 you can clone it multiple times::
59
60 machine-a % git clone git://your-git-server/cdist
61 machine-b % git clone git://your-git-server/cdist
62
63
64 Separating work by groups
65 -------------------------
66 If you are working with different groups on one cdist-configuration,
67 you can delegate to other manifests and have the groups edit only
68 their manifests. You can use the following snippet in
69 **conf/manifests/init**::
70
71 # Include other groups
72 sh -e "$__manifest/systems"
73
74 sh -e "$__manifest/cbrg"
75
76
77 Maintaining multiple configurations
78 -----------------------------------
79 When you need to manage multiple sites with cdist, like company_a, company_b
80 and private for instance, you can easily use git for this purpose.
81 Including a possible common base that is reused across the different sites::
82
83 # create branches
84 git branch company_a company_b common private
85
86 # make stuff for company a
87 git checkout company_a
88 # work, commit, etc.
89
90 # make stuff for company b
91 git checkout company_b
92 # work, commit, etc.
93
94 # make stuff relevant for all sites
95 git checkout common
96 # work, commit, etc.
97
98 # change to private and include latest common stuff
99 git checkout private
100 git merge common
101
102
103 The following **.git/config** is taken from a real world scenario::
104
105 # Track upstream, merge from time to time
106 [remote "upstream"]
107 url = git://git.schottelius.org/cdist
108 fetch = +refs/heads/*:refs/remotes/upstream/*
109
110 # Same as upstream, but works when being offline
111 [remote "local"]
112 fetch = +refs/heads/*:refs/remotes/local/*
113 url = /home/users/nico/p/cdist
114
115 # Remote containing various ETH internal branches
116 [remote "eth"]
117 url = sans.ethz.ch:/home/services/sans/git/cdist-eth
118 fetch = +refs/heads/*:refs/remotes/eth/*
119
120 # Public remote that contains my private changes to cdist upstream
121 [remote "nico"]
122 url = git.schottelius.org:/home/services/git/cdist-nico
123 fetch = +refs/heads/*:refs/remotes/nico/*
124
125 # The "nico" branch will be synced with the remote nico, branch master
126 [branch "nico"]
127 remote = nico
128 merge = refs/heads/master
129
130 # ETH stable contains rock solid configurations used in various places
131 [branch "eth-stable"]
132 remote = eth
133 merge = refs/heads/stable
134
135 Have a look at git-remote(1) to adjust the remote configuration, which allows
136
137
138 Multiple developers with different trust
139 ----------------------------------------
140 If you are working in an environment that requires different people to
141 work on the same configuration, but having different privileges, you can
142 implement this scenario with a gateway host and sudo:
143
144 - Create a dedicated user (for instance **cdist**)
145 - Setup the ssh-pubkey for this user that has the right to configure all hosts
146 - Create a wrapper to update the cdist configuration in ~cdist/cdist
147 - Allow every developer to execute this script via sudo as the user cdist
148 - Allow run of cdist as user cdist on specific hosts on a per user/group basis.
149
150 - f.i. nico ALL=(ALL) NOPASSWD: /home/cdist/bin/cdist config hostabc
151
152 For more details consult sudoers(5)
153
154
155 Templating
156 ----------
157 * create directory files/ in your type (convention)
158 * create the template as an executable file like files/basic.conf.sh, it will output text using shell variables for the values
159
160 .. code-block:: sh
161
162 #!/bin/sh
163 # in the template, use cat << eof (here document) to output the text
164 # and use standard shell variables in the template
165 # output everything in the template script to stdout
166 cat << EOF
167 server {
168 listen 80;
169 server_name $SERVERNAME;
170 root $ROOT;
171
172 access_log /var/log/nginx/$SERVERNAME_access.log
173 error_log /var/log/nginx/$SERVERNAME_error.log
174 }
175 EOF
176
177 * in the manifest, export the relevant variables and add the following lines to your manifest:
178
179 .. code-block:: console
180
181 # export variables needed for the template
182 export SERVERNAME='test"
183 export ROOT='/var/www/test'
184 # render the template
185 mkdir -p "$__object/files"
186 "$__type/files/basic.conf.sh" > "$__object/files/basic.conf"
187 # send the rendered template
188 __file /etc/nginx/sites-available/test.conf \
189 --state present
190 --source "$__object/files/basic.conf"
191
192
193 Testing a new type
194 ------------------
195 If you want to test a new type on a node, you can tell cdist to only use an
196 object of this type: Use the '--initial-manifest' parameter
197 with - (stdin) as argument and feed object into stdin
198 of cdist:
199
200 .. code-block:: sh
201
202 # Singleton type without parameter
203 echo __ungleich_munin_server | cdist config --initial-manifest - munin.panter.ch
204
205 # Singleton type with parameter
206 echo __ungleich_munin_node --allow 1.2.3.4 | \
207 cdist config --initial-manifest - rails-19.panter.ch
208
209 # Normal type
210 echo __file /tmp/stdintest --mode 0644 | \
211 cdist config --initial-manifest - cdist-dev-01.ungleich.ch
212
213
214 Other content in cdist repository
215 ---------------------------------
216 Usually the cdist repository contains all configuration
217 items. Sometimes you may have additional resources that
218 you would like to store in your central configuration
219 repository (like password files from KeepassX,
220 Libreoffice diagrams, etc.).
221
222 It is recommended to use a subfolder named "non-cdist"
223 in the repository for such content: It allows you to
224 easily distinguish what is used by cdist and what is not
225 and also to store all important files in one
226 repository.
227
228
229 Notes on CDIST_ORDER_DEPENDENCY
230 -------------------------------
231 With CDIST_ORDER_DEPENDENCY all types are executed in the order in which they
232 are created in the manifest. The current created object automatically depends
233 on the previously created object.
234
235 It essentially helps you to build up blocks of code that build upon each other
236 (like first creating the directory xyz than the file below the directory).
237
238 This can be helpful, but one must be aware of its side effects.
239
240
241 CDIST_ORDER_DEPENDENCY kills parallelization
242 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
243 Suppose you have defined CDIST_ORDER_DEPENDENCY and then, among other things,
244 you specify creation of three, by nature independent, files.
245
246 **init**
247
248 .. code-block:: sh
249
250 CDIST_ORDER_DEPENDENCY=1
251 export CDIST_ORDER_DEPENDENCY
252
253 ...
254 __file /tmp/file1
255 __file /tmp/file2
256 __file /tmp/file3
257 ...
258
259 Due to defined CDIST_ORDER_DEPENDENCY cdist will execute them in specified order.
260 It is better to use CDIST_ORDER_DEPENDENCY in well defined blocks:
261
262 **init**
263
264 .. code-block:: sh
265
266 CDIST_ORDER_DEPENDENCY=1
267 export CDIST_ORDER_DEPENDENCY
268 ...
269 unset CDIST_ORDER_DEPENDENCY
270
271 __file /tmp/file1
272 __file /tmp/file2
273 __file /tmp/file3
274
275 CDIST_ORDER_DEPENDENCY=1
276 export CDIST_ORDER_DEPENDENCY
277 ...
278 unset CDIST_ORDER_DEPENDENCY