148 lines
No EOL
12 KiB
HTML
148 lines
No EOL
12 KiB
HTML
<?xml version="1.0" encoding="UTF-8"?>
|
||
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>cdist-best-practice(7)</title><link rel="stylesheet" type="text/css" href="docbook-xsl.css" /><meta name="generator" content="DocBook XSL Stylesheets V1.78.1" /></head><body><div xml:lang="en" class="article" lang="en"><div class="titlepage"><div><div><h2 class="title"><a id="idm140431155399840"></a>cdist-best-practice(7)</h2></div><div><div class="author"><h3 class="author"><span class="firstname">Nico</span> <span class="surname">Schottelius</span></h3><code class="email"><<a class="email" href="mailto:nico-cdist--@--schottelius.org">nico-cdist--@--schottelius.org</a>></code></div></div></div><hr /></div><div class="toc"><p><strong>Table of Contents</strong></p><dl class="toc"><dt><span class="section"><a href="#_name">1. NAME</a></span></dt><dt><span class="section"><a href="#_passwordless_connections">2. PASSWORDLESS CONNECTIONS</a></span></dt><dt><span class="section"><a href="#_speeding_up_ssh_connections">3. SPEEDING UP SSH CONNECTIONS</a></span></dt><dt><span class="section"><a href="#_speeding_up_shell_execution">4. SPEEDING UP SHELL EXECUTION</a></span></dt><dt><span class="section"><a href="#_multi_master_or_environment_setups">5. MULTI MASTER OR ENVIRONMENT SETUPS</a></span></dt><dt><span class="section"><a href="#_seperating_work_by_groups">6. SEPERATING WORK BY GROUPS</a></span></dt><dt><span class="section"><a href="#_maintaining_multiple_configurations">7. MAINTAINING MULTIPLE CONFIGURATIONS</a></span></dt><dt><span class="section"><a href="#_multiple_developers_with_different_trust">8. MULTIPLE DEVELOPERS WITH DIFFERENT TRUST</a></span></dt><dt><span class="section"><a href="#_templating">9. TEMPLATING</a></span></dt><dt><span class="section"><a href="#_testing_a_new_type">10. TESTING A NEW TYPE</a></span></dt><dt><span class="section"><a href="#_other_content_in_cdist_repository">11. OTHER CONTENT IN CDIST REPOSITORY</a></span></dt><dt><span class="section"><a href="#_see_also">12. SEE ALSO</a></span></dt><dt><span class="section"><a href="#_copying">13. COPYING</a></span></dt></dl></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_name"></a>1. NAME</h2></div></div></div><p>cdist-best-practice - Practices used in real environments</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_passwordless_connections"></a>2. PASSWORDLESS CONNECTIONS</h2></div></div></div><p>It is recommended to run cdist with public key authentication.
|
||
This requires a private/public key pair and the entry
|
||
"PermitRootLogin without-password" in the sshd server.
|
||
See sshd_config(5) and ssh-keygen(1).</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_speeding_up_ssh_connections"></a>3. SPEEDING UP SSH CONNECTIONS</h2></div></div></div><p>When connecting to a new host, the initial delay with ssh connections
|
||
is pretty big. You can work around this by
|
||
"sharing of multiple sessions over a single network connection"
|
||
(quote from ssh_config(5)). The following code is suitable for
|
||
inclusion into your ~/.ssh/config:</p><pre class="screen">Host *
|
||
ControlPath ~/.ssh/master-%l-%r@%h:%p
|
||
ControlMaster auto
|
||
ControlPersist 10</pre></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_speeding_up_shell_execution"></a>4. SPEEDING UP SHELL EXECUTION</h2></div></div></div><p>On the source host, ensure that /bin/sh is <span class="strong"><strong>not</strong></span> bash: bash is quite slow for
|
||
script execution. Instead, you could use dash after installing it:</p><pre class="screen">ln -sf /bin/dash /bin/sh</pre></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_multi_master_or_environment_setups"></a>5. MULTI MASTER OR ENVIRONMENT SETUPS</h2></div></div></div><p>If you plan to distribute cdist among servers or use different
|
||
environments, you can do so easily with the included version
|
||
control git. For instance if you plan to use the typical three
|
||
environments production, integration and development, you can
|
||
realise this with git branches:</p><pre class="screen"># Go to cdist checkout
|
||
cd /path/to/cdist
|
||
|
||
# Create branches
|
||
git branch development
|
||
git branch integration
|
||
git branch production
|
||
|
||
# Make use of a branch, for instance production
|
||
git checkout production</pre><p>Similar if you want to have cdist checked out at multiple machines,
|
||
you can clone it multiple times:</p><pre class="screen">machine-a % git clone git://your-git-server/cdist
|
||
machine-b % git clone git://your-git-server/cdist</pre></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_seperating_work_by_groups"></a>6. SEPERATING WORK BY GROUPS</h2></div></div></div><p>If you are working with different groups on one cdist-configuration,
|
||
you can delegate to other manifests and have the groups edit only
|
||
their manifests. You can use the following snippet in
|
||
<span class="strong"><strong>conf/manifests/init</strong></span>:</p><pre class="screen"># Include other groups
|
||
sh -e "$__manifest/systems"
|
||
|
||
sh -e "$__manifest/cbrg"</pre></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_maintaining_multiple_configurations"></a>7. MAINTAINING MULTIPLE CONFIGURATIONS</h2></div></div></div><p>When you need to manage multiple sites with cdist, like company_a, company_b
|
||
and private for instance, you can easily use git for this purpose.
|
||
Including a possible common base that is reused accross the different sites:</p><pre class="screen"># create branches
|
||
git branch company_a company_b common private
|
||
|
||
# make stuff for company a
|
||
git checkout company_a
|
||
# work, commit, etc.
|
||
|
||
# make stuff for company b
|
||
git checkout company_b
|
||
# work, commit, etc.
|
||
|
||
# make stuff relevant for all sites
|
||
git checkout common
|
||
# work, commit, etc.
|
||
|
||
# change to private and include latest common stuff
|
||
git checkout private
|
||
git merge common</pre><p>The following <span class="strong"><strong>.git/config</strong></span> is taken from a a real world scenario:</p><pre class="screen"># Track upstream, merge from time to time
|
||
[remote "upstream"]
|
||
url = git://git.schottelius.org/cdist
|
||
fetch = +refs/heads/*:refs/remotes/upstream/*
|
||
|
||
# Same as upstream, but works when being offline
|
||
[remote "local"]
|
||
fetch = +refs/heads/*:refs/remotes/local/*
|
||
url = /home/users/nico/p/cdist
|
||
|
||
# Remote containing various ETH internal branches
|
||
[remote "eth"]
|
||
url = sans.ethz.ch:/home/services/sans/git/cdist-eth
|
||
fetch = +refs/heads/*:refs/remotes/eth/*
|
||
|
||
# Public remote that contains my private changes to cdist upstream
|
||
[remote "nico"]
|
||
url = git.schottelius.org:/home/services/git/cdist-nico
|
||
fetch = +refs/heads/*:refs/remotes/nico/*
|
||
|
||
# The "nico" branch will be synced with the remote nico, branch master
|
||
[branch "nico"]
|
||
remote = nico
|
||
merge = refs/heads/master
|
||
|
||
# ETH stable contains rock solid configurations used in various places
|
||
[branch "eth-stable"]
|
||
remote = eth
|
||
merge = refs/heads/stable</pre><p>Have a look at git-remote(1) to adjust the remote configuration, which allows</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_multiple_developers_with_different_trust"></a>8. MULTIPLE DEVELOPERS WITH DIFFERENT TRUST</h2></div></div></div><p>If you are working in an environment that requires different people to
|
||
work on the same configuration, but having different privileges, you can
|
||
implement this scenario with a gateway host and sudo:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
|
||
Create a dedicated user (for instance <span class="strong"><strong>cdist</strong></span>)
|
||
</li><li class="listitem">
|
||
Setup the ssh-pubkey for this user that has the right to configure all hosts
|
||
</li><li class="listitem">
|
||
Create a wrapper to update the cdist configuration in ~cdist/cdist
|
||
</li><li class="listitem">
|
||
Allow every developer to execute this script via sudo as the user cdist
|
||
</li><li class="listitem">
|
||
Allow run of cdist as user cdist on specific hosts on a per user/group base
|
||
</li><li class="listitem">
|
||
f.i. nico ALL=(ALL) NOPASSWD: /home/cdist/bin/cdist config hostabc
|
||
</li></ul></div><p>For more details consult sudoers(5)</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_templating"></a>9. TEMPLATING</h2></div></div></div><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
|
||
create directory files/ in your type (convention)
|
||
</li><li class="listitem">
|
||
create the template as an executable file like files/basic.conf.sh, it will output text using shell variables for the values
|
||
</li></ul></div><pre class="screen">#!/bin/sh
|
||
# in the template, use cat << eof (here document) to output the text
|
||
# and use standard shell variables in the template
|
||
# output everything in the template script to stdout
|
||
cat << EOF
|
||
server {
|
||
listen 80;
|
||
server_name $SERVERNAME;
|
||
root $ROOT;
|
||
|
||
access_log /var/log/nginx/$SERVERNAME_access.log
|
||
error_log /var/log/nginx/$SERVERNAME_error.log
|
||
}
|
||
EOF</pre><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
|
||
in the manifest, export the relevant variables and add the following lines in your manifest:
|
||
</li></ul></div><pre class="screen"># export variables needed for the template
|
||
export SERVERNAME='test"
|
||
export ROOT='/var/www/test'
|
||
# render the template
|
||
mkdir -p "$__object/files"
|
||
"$__type/files/basic.conf.sh" > "$__object/files/basic.conf"
|
||
# send the rendered template
|
||
__file /etc/nginx/sites-available/test.conf \
|
||
--state present
|
||
--source "$__object/files/basic.conf"</pre></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_testing_a_new_type"></a>10. TESTING A NEW TYPE</h2></div></div></div><p>If you want to test a new type on a node, you can tell cdist to only use an
|
||
object of this type: Use the <span class="emphasis"><em>--initial-manifest</em></span> parameter
|
||
with - (stdin) as argument and feed object into stdin
|
||
of cdist:</p><pre class="screen"># Singleton type without parameter
|
||
echo __ungleich_munin_server | cdist --initial-manifest - munin.panter.ch
|
||
|
||
# Singleton type with parameter
|
||
echo __ungleich_munin_node --allow 1.2.3.4 | \
|
||
cdist --initial-manifest - rails-19.panter.ch
|
||
|
||
# Normal type
|
||
echo __file /tmp/stdintest --mode 0644 | \
|
||
cdist --initial-manifest - cdist-dev-01.ungleich.ch</pre></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_other_content_in_cdist_repository"></a>11. OTHER CONTENT IN CDIST REPOSITORY</h2></div></div></div><p>Usually the cdist repository contains all configuration
|
||
items. Sometimes you may have additional resources that
|
||
you would like to store in your central configuration
|
||
repositiory (like password files from KeepassX,
|
||
Libreoffice diagrams, etc.).</p><p>It is recommended to use a subfolder named "non-cdist"
|
||
in the repository for such content: It allows you to
|
||
easily distinguish what is used by cdist and what not
|
||
and also to store all important files in one
|
||
repository.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_see_also"></a>12. SEE ALSO</h2></div></div></div><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
|
||
cdist(1)
|
||
</li><li class="listitem">
|
||
cdist-tutorial(7)
|
||
</li></ul></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_copying"></a>13. COPYING</h2></div></div></div><p>Copyright (C) 2011-2013 Nico Schottelius. Free use of this software is
|
||
granted under the terms of the GNU General Public License version 3 (GPLv3).</p></div></div></body></html> |