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