www.nico.schottelius.org/software/cdist/man/3.0.0/man7/cdist-best-practice.html
2013-12-24 23:11:46 +01:00

148 lines
No EOL
12 KiB
HTML
Raw Blame History

This file contains invisible Unicode characters

This file contains invisible Unicode characters that are indistinguishable to humans but may be processed differently by a computer. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

<?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="idm140029738591776"></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">&lt;<a class="email" href="mailto:nico-cdist--@--schottelius.org">nico-cdist--@--schottelius.org</a>&gt;</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 templates/ in your type (convention)
</li><li class="listitem">
create the template as an executable file like templates/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 &lt;&lt; eof (here document) to output the text
# and use standard shell variables in the template
# output everything in the template script to stdout
cat &lt;&lt; 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/templates/basic.conf.sh" &gt; "$__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>