kafo 7.2.0 → 7.3.0
Sign up to get free protection for your applications and to get access to all the features.
- checksums.yaml +4 -4
- data/Rakefile +6 -5
- data/doc/Kafo.html +151 -0
- data/doc/_index.html +754 -0
- data/doc/class_list.html +51 -0
- data/doc/file.README.html +1038 -0
- data/doc/file_list.html +56 -0
- data/doc/frames.html +17 -0
- data/doc/index.html +1038 -0
- data/doc/method_list.html +3331 -0
- data/doc/top-level-namespace.html +110 -0
- data/lib/kafo/data_type_parser.rb +19 -2
- data/lib/kafo/kafo_configure.rb +1 -1
- data/lib/kafo/version.rb +1 -1
- metadata +11 -2
data/doc/index.html
ADDED
|
@@ -0,0 +1,1038 @@
|
|
|
1
|
+
<!DOCTYPE html>
|
|
2
|
+
<html>
|
|
3
|
+
<head>
|
|
4
|
+
<meta charset="UTF-8">
|
|
5
|
+
<meta name="viewport" content="width=device-width, initial-scale=1.0">
|
|
6
|
+
<title>
|
|
7
|
+
File: README
|
|
8
|
+
|
|
9
|
+
— Documentation by YARD 0.9.34
|
|
10
|
+
|
|
11
|
+
</title>
|
|
12
|
+
|
|
13
|
+
<link rel="stylesheet" href="css/style.css" type="text/css" />
|
|
14
|
+
|
|
15
|
+
<link rel="stylesheet" href="css/common.css" type="text/css" />
|
|
16
|
+
|
|
17
|
+
<script type="text/javascript">
|
|
18
|
+
pathId = "README";
|
|
19
|
+
relpath = '';
|
|
20
|
+
</script>
|
|
21
|
+
|
|
22
|
+
|
|
23
|
+
<script type="text/javascript" charset="utf-8" src="js/jquery.js"></script>
|
|
24
|
+
|
|
25
|
+
<script type="text/javascript" charset="utf-8" src="js/app.js"></script>
|
|
26
|
+
|
|
27
|
+
|
|
28
|
+
</head>
|
|
29
|
+
<body>
|
|
30
|
+
<div class="nav_wrap">
|
|
31
|
+
<iframe id="nav" src="class_list.html?1"></iframe>
|
|
32
|
+
<div id="resizer"></div>
|
|
33
|
+
</div>
|
|
34
|
+
|
|
35
|
+
<div id="main" tabindex="-1">
|
|
36
|
+
<div id="header">
|
|
37
|
+
<div id="menu">
|
|
38
|
+
|
|
39
|
+
<a href="_index.html">Index</a> »
|
|
40
|
+
<span class="title">File: README</span>
|
|
41
|
+
|
|
42
|
+
</div>
|
|
43
|
+
|
|
44
|
+
<div id="search">
|
|
45
|
+
|
|
46
|
+
<a class="full_list_link" id="class_list_link"
|
|
47
|
+
href="class_list.html">
|
|
48
|
+
|
|
49
|
+
<svg width="24" height="24">
|
|
50
|
+
<rect x="0" y="4" width="24" height="4" rx="1" ry="1"></rect>
|
|
51
|
+
<rect x="0" y="12" width="24" height="4" rx="1" ry="1"></rect>
|
|
52
|
+
<rect x="0" y="20" width="24" height="4" rx="1" ry="1"></rect>
|
|
53
|
+
</svg>
|
|
54
|
+
</a>
|
|
55
|
+
|
|
56
|
+
</div>
|
|
57
|
+
<div class="clear"></div>
|
|
58
|
+
</div>
|
|
59
|
+
|
|
60
|
+
<div id="content"><div id='filecontents'>
|
|
61
|
+
<h1 id="label-Kafo">Kafo</h1>
|
|
62
|
+
|
|
63
|
+
<p>A puppet based installer and configurer (not-only) for Foreman and Katello projects. Kafo is a ruby gem that allows you to create fancy user interfaces for puppet modules. It’s some kind of a nice frontend to a</p>
|
|
64
|
+
|
|
65
|
+
<pre class="code ruby"><code class="ruby">echo "include some_modules" | puppet apply
|
|
66
|
+
</code></pre>
|
|
67
|
+
|
|
68
|
+
<h2 id="label-Why+should+I+care-3F">Why should I care?</h2>
|
|
69
|
+
|
|
70
|
+
<p>Suppose you work on software which you want to distribute to a machine in an infrastructure managed by puppet. You write a puppet module for your app. But now you also want to be able to distribute your app to a machine outside of your puppet infrastructure (e.g. install it to your clients) or you want to install it in order to create a puppet infrastructure itself (e.g. foreman or foreman-proxy).</p>
|
|
71
|
+
|
|
72
|
+
<p>With kafo you can reuse your puppet modules for creating an installer. Even better: After the installation you can easily modify your configuration. All using the very same puppet modules.</p>
|
|
73
|
+
|
|
74
|
+
<p>With your installer you can also provide multiple configuration files defining different installation scenarios.</p>
|
|
75
|
+
|
|
76
|
+
<h2 id="label-What+does+it+do-2C+how+does+it+work-3F">What does it do, how does it work?</h2>
|
|
77
|
+
|
|
78
|
+
<p>Kafo reads a config file to find out which modules it should use. Then it loads parameters from puppet manifests and gives you different ways to customize them.</p>
|
|
79
|
+
|
|
80
|
+
<p>There are three options how you can set parameters. You can * predefine them in the configuration file * specify them as CLI arguments * you can use the interactive mode which will ask you for all required parameters</p>
|
|
81
|
+
|
|
82
|
+
<p>Note that your answers (gathered from any mode) are automatically saved for the next run so you don’t have to specify them again. Kafo also supports default values for parameters so you can set only those you want to change. You can also combine all modes to create an answer file with default values easily and then use it for unattended installations.</p>
|
|
83
|
+
|
|
84
|
+
<h2 id="label-How+do+I+use+it-3F">How do I use it?</h2>
|
|
85
|
+
|
|
86
|
+
<p>First install the kafo gem.</p>
|
|
87
|
+
|
|
88
|
+
<p>Using bundler - add kafo gem to your Gemfile and run</p>
|
|
89
|
+
|
|
90
|
+
<pre class="code ruby"><code class="ruby"><span class='id identifier rubyid_bundle'>bundle</span> <span class='id identifier rubyid_install'>install</span>
|
|
91
|
+
</code></pre>
|
|
92
|
+
|
|
93
|
+
<p>or without bundler</p>
|
|
94
|
+
|
|
95
|
+
<pre class="code ruby"><code class="ruby"><span class='id identifier rubyid_gem'>gem</span> <span class='id identifier rubyid_install'>install</span> <span class='id identifier rubyid_kafo'>kafo</span>
|
|
96
|
+
</code></pre>
|
|
97
|
+
|
|
98
|
+
<p>Create a directory for your installer. Let’s say we want to create a foreman-installer.</p>
|
|
99
|
+
|
|
100
|
+
<pre class="code ruby"><code class="ruby"><span class='id identifier rubyid_mkdir'>mkdir</span> <span class='id identifier rubyid_foreman'>foreman</span><span class='op'>-</span><span class='id identifier rubyid_installer'>installer</span>
|
|
101
|
+
<span class='id identifier rubyid_cd'>cd</span> <span class='id identifier rubyid_foreman'>foreman</span><span class='op'>-</span><span class='id identifier rubyid_installer'>installer</span>
|
|
102
|
+
</code></pre>
|
|
103
|
+
|
|
104
|
+
<p>Now we run <code>kafofy</code> script which will prepare the directory structure and optionally create a bin script according to the first parameter.</p>
|
|
105
|
+
|
|
106
|
+
<pre class="code ruby"><code class="ruby">kafofy -n foreman-installer -s foreman
|
|
107
|
+
</code></pre>
|
|
108
|
+
|
|
109
|
+
<p>You can see that it created a modules directory where your puppet modules should live. It also created config and bin directories and the default installation scenario config file. If you specify the argument <code>--name</code> (or -n for short, foreman-installer in this case) a script in the “bin” directory with this name will be created.</p>
|
|
110
|
+
|
|
111
|
+
<p>It’s the script you can use to run the installer. If you did not specify any arguments you can run your installer by <code>kafo-configure</code> which is the default. All configuration related files are to be found in the config directory.</p>
|
|
112
|
+
|
|
113
|
+
<p>You can supply custom location for your scenario configuration and answer files and change configuration and answer files names using options:</p>
|
|
114
|
+
|
|
115
|
+
<pre class="code ruby"><code class="ruby">$ kafofy --help
|
|
116
|
+
Usage: kafofy [options]
|
|
117
|
+
-c, --config_dir DIR location of the scenarios configuration directory [./config/installer-scenarios.d/]
|
|
118
|
+
-s, --scenario SCENARIO scenario file name (without extension) [default]
|
|
119
|
+
-a, --answer_file ANSWERS answer file file name (without extension) [default-answers]
|
|
120
|
+
-n, --name NAME installer name [kafo-configure]
|
|
121
|
+
</code></pre>
|
|
122
|
+
|
|
123
|
+
<p>The scenario configuration file will be created by a default template. It’s the configuration of your installer (so you can setup the log level, path to puppet modules etc). On the other hand, the answer file must be created manually. Answer files define which modules should be used and hold all values for the puppet class parameters.</p>
|
|
124
|
+
|
|
125
|
+
<p>To add another installation scenario just run kafofy again:</p>
|
|
126
|
+
|
|
127
|
+
<pre class="code ruby"><code class="ruby">kafofy -n foreman-installer -s foreman-proxy
|
|
128
|
+
</code></pre>
|
|
129
|
+
|
|
130
|
+
<p>it will create new configuration template for you. You can check available scenarios with:</p>
|
|
131
|
+
|
|
132
|
+
<pre class="code ruby"><code class="ruby">$ bin/foreman-installer --list-scenarios
|
|
133
|
+
Available scenarios
|
|
134
|
+
foreman-proxy (use: --scenario foreman-proxy)
|
|
135
|
+
foreman (use: --scenario foreman)
|
|
136
|
+
</code></pre>
|
|
137
|
+
|
|
138
|
+
<p>Let’s see for example how to install foreman:</p>
|
|
139
|
+
|
|
140
|
+
<pre class="code ruby"><code class="ruby">cd foreman-installer/modules
|
|
141
|
+
git clone https://github.com/theforeman/puppet-foreman/ foreman
|
|
142
|
+
</code></pre>
|
|
143
|
+
|
|
144
|
+
<p>You must also download any dependant modules. Then you need to tell kafo it’s going to use the foreman module.</p>
|
|
145
|
+
|
|
146
|
+
<pre class="code ruby"><code class="ruby">cd ..
|
|
147
|
+
echo "foreman: true" > config/installer-scenarios.d/foreman-answers.yaml
|
|
148
|
+
</code></pre>
|
|
149
|
+
|
|
150
|
+
<p>Alternatively you can use the librarian-puppet project to manage all dependencies for you. You just create a Puppetfile and call librarian to install your modules. See <a href="https://github.com/rodjek/librarian-puppet">github.com/rodjek/librarian-puppet</a> for more details.</p>
|
|
151
|
+
|
|
152
|
+
<p>When you have your modules in-place, fire the installer with -h as argument and specify the foreman scenario to let installer find the right modules</p>
|
|
153
|
+
|
|
154
|
+
<pre class="code ruby"><code class="ruby">bin/foreman-installer -S foreman -h
|
|
155
|
+
</code></pre>
|
|
156
|
+
|
|
157
|
+
<p>This will show you all the possible arguments you can pass to kafo. Note that underscored puppet parameters are automatically converted to dashed arguments. You can also see a documentation extracted from the foreman puppet module and a default value.</p>
|
|
158
|
+
|
|
159
|
+
<p>Now run it without the -h argument. It will print you the puppet apply command to execute. This will be automatized later. Once the installer is run the scenario is remembered and it is not necessary to specify it again. Look at config/answers.yaml, it was populated with default values. To change those options you can use arguments like this</p>
|
|
160
|
+
|
|
161
|
+
<pre class="code ruby"><code class="ruby">bin/foreman-installer --foreman-enc=false --foreman-db-type=sqlite
|
|
162
|
+
</code></pre>
|
|
163
|
+
|
|
164
|
+
<p>or you can run it in interactive mode</p>
|
|
165
|
+
|
|
166
|
+
<pre class="code ruby"><code class="ruby">bin/foreman-installer --interactive
|
|
167
|
+
</code></pre>
|
|
168
|
+
|
|
169
|
+
<p>Also every change made to the <code>config/installer-scenarios.d/foreman-answers.yaml</code> persists and becomes the new default value for the next run.</p>
|
|
170
|
+
|
|
171
|
+
<p>As you may have noticed there are several ways how to specify arguments. Here’s the list: (the lower the item is in this list the higher precedence it has): * default values from puppet modules * values from answers.yaml * values specified on CLI * interactive mode arguments</p>
|
|
172
|
+
|
|
173
|
+
<h2 id="label-Requirements">Requirements</h2>
|
|
174
|
+
|
|
175
|
+
<p>Kafo is supported with Puppet version 7. Puppet may be installed as a gem (add it to Gemfile) or through a package, including official AIO packages.</p>
|
|
176
|
+
|
|
177
|
+
<h2 id="label-How+do+I+report+bugs+or+contribute-3F">How do I report bugs or contribute?</h2>
|
|
178
|
+
|
|
179
|
+
<p>You can find our redmine issue tracker <a href="https://projects.theforeman.org/projects/kafo">here</a>, you can use your github account for logging in. When reporting new issues please don’t forget to specify your: * puppet version * installation options (GEM/RPM/DEB) * error trace (if any) or log with debug level * reproducing steps</p>
|
|
180
|
+
|
|
181
|
+
<p>Since Kafo is a side project of Foreman you can use its IRC channels to contact us on freenode. #theforeman is the channel for generic discussions and #theforeman-dev is reserved only for technical topics. Likewise you can use the Foreman mailing lists on googlegroups. For more information see <a href="https://theforeman.org/support.html">this page</a></p>
|
|
182
|
+
|
|
183
|
+
<p>Patches are always welcome. You can use instructions for Foreman, just substitute Foreman with Kafo. More details are <a href="https://projects.theforeman.org/projects/foreman/wiki/Contribute#New-Way-github">here</a></p>
|
|
184
|
+
|
|
185
|
+
<h1 id="label-Advanced+topics">Advanced topics</h1>
|
|
186
|
+
|
|
187
|
+
<h2 id="label-Testing+aka+noop+etc">Testing aka noop etc</h2>
|
|
188
|
+
|
|
189
|
+
<p>Since you’ll probably want to tweak your installer before you run it, you may find the <code>--noop</code> argument handy (-n for short). This will run puppet in noop so no change will be done to your system. The default value here is set to false!</p>
|
|
190
|
+
|
|
191
|
+
<p>Sometimes you may want kafo not to store answers from the current run. You can disable saving answers by passing a <code>--dont-save-answers</code> argument.</p>
|
|
192
|
+
|
|
193
|
+
<p>Note that running <code>--noop</code> implies <code>--dont-save-answers</code>.</p>
|
|
194
|
+
|
|
195
|
+
<h2 id="label-Executing+Puppet+with+multiple+versions">Executing Puppet with multiple versions</h2>
|
|
196
|
+
|
|
197
|
+
<p>Kafo calls the <code>puppet</code> binary during an installer run to both compute default parameter values and perform the actual installer changes. This relies on <code>puppet</code> being in the PATH environment variable or as fallback, in <code>/opt/puppetlabs/bin</code>.</p>
|
|
198
|
+
|
|
199
|
+
<p>When using Puppet via a Gemfile, Bundler should set up PATH to point at the gem version. If using a system/packaged version, it will typically find and execute /usr/bin/puppet from the regular PATH.</p>
|
|
200
|
+
|
|
201
|
+
<p>When using an AIO packaged version of Puppet, other versions of Puppet from PATH will be preferred if they exist, so they should either be removed or PATH set to prefer /opt/puppetlabs/bin, i.e. <code>export PATH=/opt/puppetlabs/bin:$PATH</code>. Debug logs from Kafo should indicate the full path of the binary used.</p>
|
|
202
|
+
|
|
203
|
+
<p>Note that Kafo parsers relies on puppet-strings to parse manifests.</p>
|
|
204
|
+
|
|
205
|
+
<h2 id="label-Parameters+prefixes">Parameters prefixes</h2>
|
|
206
|
+
|
|
207
|
+
<p>As a default every module parameter is prefixed by the module name. If you use just one module it’s probably not necessary and you can disable this behavior in config/kafo.yaml. Just enable the following option</p>
|
|
208
|
+
|
|
209
|
+
<pre class="code ruby"><code class="ruby">:no_prefix: true
|
|
210
|
+
</code></pre>
|
|
211
|
+
|
|
212
|
+
<h2 id="label-Scenarios">Scenarios</h2>
|
|
213
|
+
|
|
214
|
+
<p>With your installer you can provide multiple configuration files aka. scenarios. Every scenario has its own answer file to store the scenario settings. The files are kept in <code>installer-scenarios.d/</code> directory.</p>
|
|
215
|
+
|
|
216
|
+
<h3 id="label-Using+scenarios">Using scenarios</h3>
|
|
217
|
+
|
|
218
|
+
<p>To list scenarios available on your system</p>
|
|
219
|
+
|
|
220
|
+
<pre class="code ruby"><code class="ruby">foreman-installer --list-scenarios
|
|
221
|
+
</code></pre>
|
|
222
|
+
|
|
223
|
+
<p>The installer needs to know the configuration even for such a basic operation as printing help is because it contains basic settings and defines where to look for module parameters. There are multiple ways how the installer can select the scenario: * from a command line argument <code>-S</code> or <code>--scenario</code></p>
|
|
224
|
+
|
|
225
|
+
<pre class="code ruby"><code class="ruby">foreman-installer --scenario foreman -h
|
|
226
|
+
...
|
|
227
|
+
</code></pre>
|
|
228
|
+
<ul><li>
|
|
229
|
+
<p>by user selection in interractive mode (<code>-i</code> or <code>--interractive</code>)</p>
|
|
230
|
+
|
|
231
|
+
<p>“‘bash foreman-installer -i</p>
|
|
232
|
+
</li></ul>
|
|
233
|
+
|
|
234
|
+
<p>Select installation scenario</p>
|
|
235
|
+
|
|
236
|
+
<p>Please select one of the pre-set installation scenarios. You can customize your installtion later during the installtion.</p>
|
|
237
|
+
|
|
238
|
+
<p> Available actions: 1. Foreman: Basic and most generic installation of Foreman 2. Foreman Proxy: Install Foreman proxy without Foreman 3. Cancel Installation Your choice:</p>
|
|
239
|
+
|
|
240
|
+
<pre class="code ruby"><code class="ruby">* automatically if there is only one scenario available
|
|
241
|
+
* automatically if installer was ran already with scenario selected
|
|
242
|
+
|
|
243
|
+
### Re-installing with different scenario
|
|
244
|
+
|
|
245
|
+
Lets assume you have already completed installation with one scenario (e.g. smart-proxy).
|
|
246
|
+
Now you want to reinstall or upgrade with different scenario (e.g. foreman). This is tricky
|
|
247
|
+
situation and may end with unpredictable results so you should double check
|
|
248
|
+
if the scenario and the puppet modules used in it support such kind of change.
|
|
249
|
+
|
|
250
|
+
Installer tries to prevent unintentional change of a scenario and interrupts when such situation is detected:
|
|
251
|
+
</code></pre>
|
|
252
|
+
|
|
253
|
+
<p>bash foreman-installer -S foreman-installer ERROR: You are trying to replace existing installation with different scenario. This may lead to unpredictable states. Use –force to override. You can use –compare-scenarios to see the differences</p>
|
|
254
|
+
|
|
255
|
+
<pre class="code ruby"><code class="ruby">
|
|
256
|
+
To avoid losing some configuration values installer can detect differences between answer files of the two scenarios.
|
|
257
|
+
To display them use either interactive mode (`-i`) or `--compare-scenarios` flag:
|
|
258
|
+
</code></pre>
|
|
259
|
+
|
|
260
|
+
<p>bash foreman-installer –compare-scenarios –scenario foreman Scenarios are being compared, that may take a while…</p>
|
|
261
|
+
|
|
262
|
+
<p>Values from previous installation that will be added by installer: foreman_proxy::http_port: 8000 -> 8080</p>
|
|
263
|
+
|
|
264
|
+
<p> Values from previous installation that will be lost by scenario change: foreman_proxy::plugin::abrt::enabled: true …</p>
|
|
265
|
+
|
|
266
|
+
<pre class="code ruby"><code class="ruby">
|
|
267
|
+
It may take some time as the installer has to evaluate default values for both scenarios. As a result it prints two lists.
|
|
268
|
+
- __Values from previous installation that will be added by installer:__ - in this list are options present in both scenarios but having different default values.
|
|
269
|
+
The only item from the example says that the default value for the new scenario is '8000' while the value for currently intalled scenario is '8080'.
|
|
270
|
+
When the new scenario is used the installer tries to keep the customized values from current installation and thus will use the `8080` value
|
|
271
|
+
- __Values from previous installation that will be lost by scenario change:__ - this list contains options that are part of current installation
|
|
272
|
+
and are missing from the new scenario. Most of the items are options from puppet modules that are disabled in the new scenario by default but were enabled
|
|
273
|
+
in the old one.
|
|
274
|
+
|
|
275
|
+
If you are sure you want to proceed use `--force` to run the installation. Installer will replace
|
|
276
|
+
the default values with values from the previous installation where possible as was indicated in the `--compare-scenario` output.
|
|
277
|
+
|
|
278
|
+
### Adding scenario
|
|
279
|
+
|
|
280
|
+
You can add new scenario using kafofy as it was explained earlier or by creating
|
|
281
|
+
config and answer file in the `installer-scenarios.d/` directory.
|
|
282
|
+
[Template](https://github.com/theforeman/kafo/blob/master/config/kafo.yaml.example)
|
|
283
|
+
provided by Kafo can be used and customized to satisfy your needs
|
|
284
|
+
</code></pre>
|
|
285
|
+
|
|
286
|
+
<p>bash cp <code>gem content kafo|grep "kafo.yaml.example"</code> <config>/installer-scenarios.d/new-scenario.yaml touch <config>/installer-scenarios.d/new-scenario-answers.yaml</p>
|
|
287
|
+
|
|
288
|
+
<pre class="code ruby"><code class="ruby">
|
|
289
|
+
### Scenario as an installer plugin
|
|
290
|
+
|
|
291
|
+
Scenarios were designed to make it possible to package them separately as optional installer extension.
|
|
292
|
+
Config files are located in separate directory which makes packaging of additional scenarios easy.
|
|
293
|
+
Configuration of paths to modules, checks and hooks accepts multiple directories
|
|
294
|
+
so it is possible to bundle your scenario with additional modules, hooks and checks.
|
|
295
|
+
|
|
296
|
+
### Updating scenarios
|
|
297
|
+
|
|
298
|
+
As your project grows you may need to change your installer modules or add new ones. To make upgrades of existing installations easier
|
|
299
|
+
Kafo has support for scenario migrations. Migrations are ruby scripts similar to hooks and are located
|
|
300
|
+
in `<config>/installer-scenarios.d/your-scenario.migrations/` so each scenario has its own set of independent migrations.
|
|
301
|
+
During its initialization the installer checks for migrations that were not applied yet. It happens exactly between execution of `pre-migrations` and `boot` hooks.
|
|
302
|
+
The installer stores names of applied migrations in `<config>/installer-scenarios.d/your-scenario.migrations/.applied` to avoid runnig the migrations multiple times.
|
|
303
|
+
It is recommended to prefix the migration names with `date +%y%m%d%H%M%S` to avoid migration ordering issues.
|
|
304
|
+
|
|
305
|
+
In a migration you can modify the scenario configuration as well as the answer file. The changed configs are stored immediately after all the migrations were applied.
|
|
306
|
+
If you just want to apply the migrations you can use `--migrations-only` switch.
|
|
307
|
+
Note that `--noop` and `--dont-save-answers` has no effect on migrations.
|
|
308
|
+
|
|
309
|
+
Sample migration adding new module could look like as follows:
|
|
310
|
+
</code></pre>
|
|
311
|
+
|
|
312
|
+
<p>bash cat <<EOF > “/etc/foreman/installer-scenarios.d/foreman-installer.migrations/<code>date +%y%m%d%H%M%S</code>-gutterball.rb” <a href=":mapping">scenario</a>[‘katello::plugin::gutterball’] = { :dir_name => ‘katello’, :manifest_name => ‘plugin/gutterball’ } <a href="'katello::plugin::gutterball'">answers</a> = true EOF</p>
|
|
313
|
+
|
|
314
|
+
<pre class="code ruby"><code class="ruby">
|
|
315
|
+
The migration can also call `facts`, which returns a hash of symbol fact names to values (from
|
|
316
|
+
Facter), to help determine new parameter values.
|
|
317
|
+
</code></pre>
|
|
318
|
+
|
|
319
|
+
<p>ruby <a href="'module'">answers</a>[‘foo’] = ‘bar’ if <a href=":osfamily">facts</a> == ‘Debian’</p>
|
|
320
|
+
|
|
321
|
+
<pre class="code ruby"><code class="ruby">
|
|
322
|
+
<span class='comment'>### Enabling/disabling scenarios
|
|
323
|
+
</span>
|
|
324
|
+
<span class='const'>Scenarios</span> <span class='id identifier rubyid_that'>that</span> <span class='id identifier rubyid_are'>are</span> <span class='id identifier rubyid_deprecated'>deprecated</span> <span class='kw'>or</span> <span class='id identifier rubyid_wanted'>wanted</span> <span class='id identifier rubyid_to'>to</span> <span class='id identifier rubyid_be'>be</span> <span class='id identifier rubyid_hidden'>hidden</span> <span class='id identifier rubyid_on'>on</span> <span class='id identifier rubyid_the'>the</span> <span class='id identifier rubyid_system'>system</span> <span class='id identifier rubyid_can'>can</span> <span class='id identifier rubyid_be'>be</span> <span class='id identifier rubyid_disabled'>disabled</span> <span class='label'>with:</span>
|
|
325
|
+
</code></pre>
|
|
326
|
+
|
|
327
|
+
<p>bash foreman-installer –disable-scenario deprecated-scenario Scenario deprecated-scenario was disabled.</p>
|
|
328
|
+
|
|
329
|
+
<pre class="code ruby"><code class="ruby">The disabled scenario is not shown in the scenario list and is prevented from being installed.
|
|
330
|
+
It is not deleted from the file system however so the custom values in the answer file are preserved
|
|
331
|
+
and e.g. migration to new scenario is still possible.
|
|
332
|
+
|
|
333
|
+
Disabled scenario can be enabled back again with `foreman-installer --enable-scenario SCENARIO`.
|
|
334
|
+
|
|
335
|
+
## Store
|
|
336
|
+
|
|
337
|
+
Kafo features simple key value store that can be used to ship data with the installer.
|
|
338
|
+
|
|
339
|
+
The data are loaded from yaml files located in `store.d` directory that is either specified in
|
|
340
|
+
the scenario config's `store_dir:` or on same directory
|
|
341
|
+
level as configuration directory containing the scenarios. The files are loaded in
|
|
342
|
+
alphabetical order and the data are merged in that order.
|
|
343
|
+
|
|
344
|
+
The store is read-only during the run and the content can be influenced only by adding
|
|
345
|
+
new files into the `store.d` directory (e.g. from installer plugins)
|
|
346
|
+
|
|
347
|
+
## Documentation
|
|
348
|
+
|
|
349
|
+
Every parameter that can be set by kafo *must* be documented. This means that
|
|
350
|
+
you must add documentation to your puppet class in init.pp. It's basically a
|
|
351
|
+
rdoc formatted documentation that must be above the class definitions. There can
|
|
352
|
+
be no space between the doc block and the class definition.
|
|
353
|
+
|
|
354
|
+
In case of emergency, it's still possible to use
|
|
355
|
+
`--ignore-undocumented` option, but in general it's not recommended to override it.
|
|
356
|
+
|
|
357
|
+
Example:
|
|
358
|
+
</code></pre>
|
|
359
|
+
|
|
360
|
+
<p>puppet</p>
|
|
361
|
+
|
|
362
|
+
<h1 id="label-Manage+your+foreman+server">Manage your foreman server</h1>
|
|
363
|
+
|
|
364
|
+
<p>#</p>
|
|
365
|
+
|
|
366
|
+
<h1 id="label-This+class+...">This class …</h1>
|
|
367
|
+
|
|
368
|
+
<h1 id="label-...+does+what+it+does.">… does what it does.</h1>
|
|
369
|
+
|
|
370
|
+
<p>#</p>
|
|
371
|
+
|
|
372
|
+
<h1 id="label-3D-3D-3D+Parameters-3A">=== Parameters:</h1>
|
|
373
|
+
|
|
374
|
+
<p>#</p>
|
|
375
|
+
|
|
376
|
+
<h1 id="label-24foreman_url-3A-3A+URL+on+which+foreman+is+going+to+run">$foreman_url:: URL on which foreman is going to run</h1>
|
|
377
|
+
|
|
378
|
+
<p>#</p>
|
|
379
|
+
|
|
380
|
+
<h1 id="label-24enc-3A-3A+Should+foreman+act+as+an+external+node+classifier+-28manage+puppet+class">$enc:: Should foreman act as an external node classifier (manage puppet class</h1>
|
|
381
|
+
|
|
382
|
+
<h1 id="label-assignments-29">assignments)</h1>
|
|
383
|
+
|
|
384
|
+
<p># class foreman ( String $foreman_url = $foreman::params::foreman_url, Boolean $enc = $foreman::params::enc ) { class { ‘foreman::install’: } }</p>
|
|
385
|
+
|
|
386
|
+
<pre class="code ruby"><code class="ruby">
|
|
387
|
+
You can separate your parameters into groups like this.
|
|
388
|
+
|
|
389
|
+
Example - separating parameters into groups:
|
|
390
|
+
</code></pre>
|
|
391
|
+
|
|
392
|
+
<p>puppet</p>
|
|
393
|
+
|
|
394
|
+
<h1 id="label-Manage+your+foreman+server">Manage your foreman server</h1>
|
|
395
|
+
|
|
396
|
+
<p>#</p>
|
|
397
|
+
|
|
398
|
+
<h1 id="label-3D-3D-3D+Parameters-3A">=== Parameters:</h1>
|
|
399
|
+
|
|
400
|
+
<p>#</p>
|
|
401
|
+
|
|
402
|
+
<h1 id="label-24foreman_url-3A-3A+URL+on+which+foreman+is+going+to+run">$foreman_url:: URL on which foreman is going to run</h1>
|
|
403
|
+
|
|
404
|
+
<p>#</p>
|
|
405
|
+
|
|
406
|
+
<h1 id="label-3D-3D-3D+Advanced+parameters-3A">=== Advanced parameters:</h1>
|
|
407
|
+
|
|
408
|
+
<p>#</p>
|
|
409
|
+
|
|
410
|
+
<h1 id="label-24foreman_port-3A-3A+Foreman+listens+on+this+port">$foreman_port:: Foreman listens on this port</h1>
|
|
411
|
+
|
|
412
|
+
<p>#</p>
|
|
413
|
+
|
|
414
|
+
<h1 id="label-3D-3D-3D-3D+MySQL-3A">==== MySQL:</h1>
|
|
415
|
+
|
|
416
|
+
<p>#</p>
|
|
417
|
+
|
|
418
|
+
<h1 id="label-24mysql_host-3A-3A+MySQL+server+address">$mysql_host:: MySQL server address</h1>
|
|
419
|
+
|
|
420
|
+
<pre class="code ruby"><code class="ruby">
|
|
421
|
+
<span class='const'>When</span> <span class='id identifier rubyid_you'>you</span> <span class='id identifier rubyid_run'>run</span> <span class='id identifier rubyid_the'>the</span> <span class='id identifier rubyid_installer'>installer</span> <span class='id identifier rubyid_with'>with</span> <span class='id identifier rubyid_the'>the</span>
|
|
422
|
+
</code></pre>
|
|
423
|
+
|
|
424
|
+
<p>–help<code>argument it displays only parameters specified in the</code>=== Parameters:“‘ group. If you don’t specify any group all parameters will be considered as basic and will be displayed.</p>
|
|
425
|
+
|
|
426
|
+
<p>If you run the installer with <code>--full-help</code> you’ll receive help for all parameters divided into groups. Note that only headers that include word parameters are considered as parameter groups. Other headers are ignored. Also note that you can nest parameter groups and the child has precedence. Help output does not take header level into account though.</p>
|
|
427
|
+
|
|
428
|
+
<p>So in the previous example, each parameter would be printed in one group even though MySQL is a child of Advanced parameter. All groups in help would be prefixed with a second level (==). The first level is always a module to which the particular parameter belongs.</p>
|
|
429
|
+
|
|
430
|
+
<h2 id="label-Argument+types">Argument types</h2>
|
|
431
|
+
|
|
432
|
+
<p>The data type will be read from the parameter list and defaults to Puppet’s <a href="https://docs.puppet.com/puppet/latest/reference/lang_data_abstract.html#any">Any</a> data type, which Kafo handles as a basic string with no validation.</p>
|
|
433
|
+
|
|
434
|
+
<p>If more specific data types, such as <code>Optional[Array[2]]</code> or similar are given in the <a href="https://docs.puppet.com/puppet/4.5/reference/lang_data_type.html#usage">parameter list</a> then Kafo will parse and validate parameters values according to the specification.</p>
|
|
435
|
+
|
|
436
|
+
<pre class="code ruby"><code class="ruby">class example (
|
|
437
|
+
Boolean $param = false
|
|
438
|
+
) {
|
|
439
|
+
</code></pre>
|
|
440
|
+
|
|
441
|
+
<p>Note that all arguments that are nil (have no value in answers.yaml or you set them UNDEF (see below)) are translated to <code>undef</code> in puppet.</p>
|
|
442
|
+
|
|
443
|
+
<p>If your module declares its own types, you can add new corresponding subclasses of DataType which implement validation and typecasting. This can be added to a <code>boot</code> hook by calling:</p>
|
|
444
|
+
|
|
445
|
+
<pre class="code ruby"><code class="ruby"><span class='const'><span class='object_link'><a href="Kafo.html" title="Kafo (module)">Kafo</a></span></span><span class='op'>::</span><span class='const'><span class='object_link'><a href="Kafo/DataType.html" title="Kafo::DataType (class)">DataType</a></span></span><span class='period'>.</span><span class='id identifier rubyid_register_type'><span class='object_link'><a href="Kafo/DataType.html#register_type-class_method" title="Kafo::DataType.register_type (method)">register_type</a></span></span><span class='lparen'>(</span><span class='tstring'><span class='tstring_beg'>'</span><span class='tstring_content'>YourType</span><span class='tstring_end'>'</span></span><span class='comma'>,</span> <span class='const'><span class='object_link'><a href="Kafo.html" title="Kafo (module)">Kafo</a></span></span><span class='op'>::</span><span class='const'><span class='object_link'><a href="Kafo/DataType.html" title="Kafo::DataType (class)">DataType</a></span></span><span class='op'>::</span><span class='const'>YourType</span><span class='rparen'>)</span>
|
|
446
|
+
</code></pre>
|
|
447
|
+
|
|
448
|
+
<h2 id="label-Array+arguments">Array arguments</h2>
|
|
449
|
+
|
|
450
|
+
<p>Some arguments may be Arrays. If you want to specify array values you can specify CLI argument multiple times e.g.</p>
|
|
451
|
+
|
|
452
|
+
<pre class="code ruby"><code class="ruby">bin/foreman-installer --puppetmaster-environments=development --puppetmaster-environments=production
|
|
453
|
+
</code></pre>
|
|
454
|
+
|
|
455
|
+
<p>In interactive mode you’ll be prompted for another value until you specify blank line.</p>
|
|
456
|
+
|
|
457
|
+
<h2 id="label-Hash+arguments">Hash arguments</h2>
|
|
458
|
+
|
|
459
|
+
<p>You can use a Hash value like an Array. It’s also a multivalue type but you have to specify a key:value pair like in the following example.</p>
|
|
460
|
+
|
|
461
|
+
<pre class="code ruby"><code class="ruby">bin/foreman-installer --puppet-server-git-branch-map=master:some --puppet-server-git-branch-map=development:another
|
|
462
|
+
</code></pre>
|
|
463
|
+
|
|
464
|
+
<p>The same applies to the interactive mode, you enter each pair on separate lines just like with an Array, the only difference is that the line must be formatted as key:value.</p>
|
|
465
|
+
|
|
466
|
+
<p>When parsing the value, the first colon divides key and value. All other colons are ignored.</p>
|
|
467
|
+
|
|
468
|
+
<h2 id="label-Sensitive+arguments">Sensitive arguments</h2>
|
|
469
|
+
|
|
470
|
+
<p>Puppet’s <code>Sensitive</code> data type can be used as long as it’s configured in Hiera too. Given the following manifest:</p>
|
|
471
|
+
|
|
472
|
+
<pre class="code ruby"><code class="ruby">class example (
|
|
473
|
+
Sensitive[String[1]] $password,
|
|
474
|
+
) {
|
|
475
|
+
</code></pre>
|
|
476
|
+
|
|
477
|
+
<p>Here the following Hiera configuration is needed:</p>
|
|
478
|
+
|
|
479
|
+
<pre class="code ruby"><code class="ruby">lookup_options:
|
|
480
|
+
example::password:
|
|
481
|
+
convert_to: "Sensitive"
|
|
482
|
+
</code></pre>
|
|
483
|
+
|
|
484
|
+
<p>This is based on <a href="https://puppet.com/docs/puppet/6/securing-sensitive-data.html">Puppet’s documentation</a>.</p>
|
|
485
|
+
|
|
486
|
+
<p>Note that to provide a default inside the manifest inheritance must be used.</p>
|
|
487
|
+
|
|
488
|
+
<pre class="code ruby"><code class="ruby">class example (
|
|
489
|
+
Sensitive[String[1]] $password = $example::params::password,
|
|
490
|
+
) inherits example::params {
|
|
491
|
+
}
|
|
492
|
+
|
|
493
|
+
class example::params {
|
|
494
|
+
$password = Sensitive('supersecret')
|
|
495
|
+
}
|
|
496
|
+
</code></pre>
|
|
497
|
+
|
|
498
|
+
<h2 id="label-Default+values">Default values</h2>
|
|
499
|
+
|
|
500
|
+
<p>Default values for parameters are read from the class definitions in the manifests. If values are given inline then these will be stored by Kafo as the initial value of the parameter (unless set in the answers file or later changed by the user), e.g.</p>
|
|
501
|
+
|
|
502
|
+
<pre class="code ruby"><code class="ruby">class foreman(
|
|
503
|
+
$foreman_url = 'https://example.com'
|
|
504
|
+
) {
|
|
505
|
+
</code></pre>
|
|
506
|
+
|
|
507
|
+
<p>If the “params” pattern is used, where the default parameter values are defined in another class then Kafo will attempt to retrieve them by running Puppet, using <code>include</code> on the params class and then getting the variable value. This will retrieve default values set by conditionals correctly, e.g.</p>
|
|
508
|
+
|
|
509
|
+
<pre class="code ruby"><code class="ruby">class foreman(
|
|
510
|
+
$foreman_url = $::foreman::params::foreman_url,
|
|
511
|
+
) inherits foreman::params {
|
|
512
|
+
</code></pre>
|
|
513
|
+
|
|
514
|
+
<pre class="code ruby"><code class="ruby">class foreman::params {
|
|
515
|
+
$foreman_url = 'https://example.com'
|
|
516
|
+
}
|
|
517
|
+
</code></pre>
|
|
518
|
+
|
|
519
|
+
<p>If no inline default is given in the manifest, then Kafo will attempt to look up a default value using <a href="https://docs.puppet.com/puppet/latest/lookup_quick_module.html">data stored in the module</a>. This can be specified with Hiera data files (or even a data function) in the module under <code>data/</code>.</p>
|
|
520
|
+
|
|
521
|
+
<h2 id="label-Resetting+an+argument">Resetting an argument</h2>
|
|
522
|
+
|
|
523
|
+
<p>Existing stored parameters can be reset back to their default value from the command line or interactive mode. This deletes the stored value in the answers file and stores the default from the Puppet manifest in its place.</p>
|
|
524
|
+
|
|
525
|
+
<p>The default value is the value set in, or computed by the Puppet params manifest. This will <em>not</em> reset to any defaults specified in the answers file before running the Kafo-based installer, they are not kept.</p>
|
|
526
|
+
|
|
527
|
+
<p>Using the CLI, a –reset option is available for every parameter, e.g.</p>
|
|
528
|
+
|
|
529
|
+
<pre class="code ruby"><code class="ruby">bin/foreman-installer --reset-puppet-server-git-branch-map
|
|
530
|
+
</code></pre>
|
|
531
|
+
|
|
532
|
+
<p>The parameter can also be reset to the default in interactive mode, via the reset parameters sub-menu under each module.</p>
|
|
533
|
+
|
|
534
|
+
<h2 id="label-Grouping+in+interactive+mode">Grouping in interactive mode</h2>
|
|
535
|
+
|
|
536
|
+
<p>If your module has too many parameters you may find the grouping feature useful. Every block in your documentation (prefixed by header) forms a group. Unlike for help, all blocks are used in interactive mode. Suppose you have the following example:</p>
|
|
537
|
+
|
|
538
|
+
<pre class="code ruby"><code class="ruby"><span class='comment'># Testing class
|
|
539
|
+
</span><span class='comment'>#
|
|
540
|
+
</span><span class='comment'># == Parameters:
|
|
541
|
+
</span><span class='comment'>#
|
|
542
|
+
</span><span class='comment'># $one:: number one
|
|
543
|
+
</span><span class='comment'>#
|
|
544
|
+
</span><span class='comment'># == Advanced parameters:
|
|
545
|
+
</span><span class='comment'>#
|
|
546
|
+
</span><span class='comment'># $two:: number two
|
|
547
|
+
</span><span class='comment'>#
|
|
548
|
+
</span><span class='comment'># === Advanced A:
|
|
549
|
+
</span><span class='comment'>#
|
|
550
|
+
</span><span class='comment'># $two_a:: 2_a
|
|
551
|
+
</span><span class='comment'>#
|
|
552
|
+
</span><span class='comment'># === Advanced 2_b
|
|
553
|
+
</span><span class='comment'>#
|
|
554
|
+
</span><span class='comment'># $two_b:: 2_b
|
|
555
|
+
</span><span class='comment'>#
|
|
556
|
+
</span><span class='comment'># == Extra parameters:
|
|
557
|
+
</span><span class='comment'>#
|
|
558
|
+
</span><span class='comment'># $three:: number three
|
|
559
|
+
</span></code></pre>
|
|
560
|
+
|
|
561
|
+
<p>When you enter the Testing class module in interactive mode you can see parameters from the Basic group and options to configure parameters which belong to the rest of groups on same level, in this case Advanced and Extra parameters.</p>
|
|
562
|
+
|
|
563
|
+
<pre class="code ruby"><code class="ruby">Module foreman configuration
|
|
564
|
+
1. Enable/disable foreman module, current value: true
|
|
565
|
+
2. Set one, current value: '1'
|
|
566
|
+
3. Configure Advanced parameters
|
|
567
|
+
4. Configure Extra parameters
|
|
568
|
+
5. Back to main menu
|
|
569
|
+
</code></pre>
|
|
570
|
+
|
|
571
|
+
<p>When you enter Extra parameters, you see only $three and an option to get back to the parent. In Advanced you can see $two and two more subgroups - Advanced A and Advanced B. When you enter these subgroups, you can again see their parameters. Nesting is unlimited. Also there’s no naming rule. Just notice that the main group must be called <code>Parameters</code> and it’s parameters are always displayed on first level of the module configuration.</p>
|
|
572
|
+
|
|
573
|
+
<pre class="code ruby"><code class="ruby">Group Extra parameters (of module foreman)
|
|
574
|
+
1. Set two_b, current value: '2b'
|
|
575
|
+
2. Back to parent menu
|
|
576
|
+
</code></pre>
|
|
577
|
+
|
|
578
|
+
<p>If there’s no primary group a new one is created for you and it does not have any parameter. This means when a user enters the module configuration he or she will see only subgroups in the menu (no parameters until a particular subgroup is entered). If there is no group in the documentation a new primary group is created and it holds all module parameters (there are no subgroups in the module configuration).</p>
|
|
579
|
+
|
|
580
|
+
<h2 id="label-Conditional+parameters+in+interactive+mode">Conditional parameters in interactive mode</h2>
|
|
581
|
+
|
|
582
|
+
<p>You can also define conditions to parameters and their groups. These conditions are evaluated in interactive mode and are based on the results which are then displayed to the user. You can use this for example to hide mysql_* parameters when $db_type is not set ‘mysql’. Let’s look at following example</p>
|
|
583
|
+
|
|
584
|
+
<pre class="code ruby"><code class="ruby"><span class='comment'># Testing class
|
|
585
|
+
</span><span class='comment'>#
|
|
586
|
+
</span><span class='comment'># == Parameters:
|
|
587
|
+
</span><span class='comment'>#
|
|
588
|
+
</span><span class='comment'># $use_db:: use database?
|
|
589
|
+
</span><span class='comment'>#
|
|
590
|
+
</span><span class='comment'># == Database parameters: condition: $use_db
|
|
591
|
+
</span><span class='comment'>#
|
|
592
|
+
</span><span class='comment'># $database_type:: mysql/sqlite
|
|
593
|
+
</span><span class='comment'>#
|
|
594
|
+
</span><span class='comment'># === MySQL: condition: $database_type == 'mysql'
|
|
595
|
+
</span><span class='comment'>#
|
|
596
|
+
</span><span class='comment'># $remote:: use remote connection
|
|
597
|
+
</span><span class='comment'># $host server to connect to
|
|
598
|
+
</span><span class='comment'># condition: $remote
|
|
599
|
+
</span><span class='comment'># $socket server to connect to
|
|
600
|
+
</span><span class='comment'># condition: !$remote
|
|
601
|
+
</span></code></pre>
|
|
602
|
+
|
|
603
|
+
<p>Here you can see we defined several conditions on the group and parameter level. You can write a condition in ruby. All dollar-prefixed words will be substituted with the value of the particular puppet parameter.</p>
|
|
604
|
+
|
|
605
|
+
<p>Note that conditions are combined using <code>&&</code> when you nest them. So these are facts based on example:</p>
|
|
606
|
+
<ul><li>
|
|
607
|
+
<p>$database_type, $remote, $host, $socket are displayed only when $use_db is set to true</p>
|
|
608
|
+
</li><li>
|
|
609
|
+
<p>$remote, $host, $socket are displayed only when $database_type is set to ‘mysql’</p>
|
|
610
|
+
</li><li>
|
|
611
|
+
<p>$host is displayed only if $remote is set to true, $socket is displayed otherwise</p>
|
|
612
|
+
</li></ul>
|
|
613
|
+
|
|
614
|
+
<p>Here’s explanation how conditions are constructed</p>
|
|
615
|
+
|
|
616
|
+
<pre class="code ruby"><code class="ruby">-----------------------------------------------------------------------------
|
|
617
|
+
| parameter name | resulting condition |
|
|
618
|
+
-----------------------------------------------------------------------------
|
|
619
|
+
| $use_db | true |
|
|
620
|
+
| $database_type | true && $use_db |
|
|
621
|
+
| $remote | true && $use_db && $database_type == 'mysql' |
|
|
622
|
+
| $host | true && $use_db && $database_type == 'mysql' && $remote |
|
|
623
|
+
| $socket | true && $use_db && $database_type == 'mysql' && !$remote |
|
|
624
|
+
-----------------------------------------------------------------------------
|
|
625
|
+
</code></pre>
|
|
626
|
+
|
|
627
|
+
<p>As already said you can use whatever ruby code, so you could leverage e.g. parentheses, &&, ||, !, and, or</p>
|
|
628
|
+
|
|
629
|
+
<h2 id="label-Custom+modules+and+manifest+names">Custom modules and manifest names</h2>
|
|
630
|
+
|
|
631
|
+
<p>By default Kafo expects a common module structure. For example if you add</p>
|
|
632
|
+
|
|
633
|
+
<pre class="code ruby"><code class="ruby">foreman: true
|
|
634
|
+
</code></pre>
|
|
635
|
+
|
|
636
|
+
<p>to you answer file, Kafo expects a <code>foreman</code> subdirectory in <code>modules/</code>. Also it expects that there will be init.pp which it will instantiate. If you need to change this behavior you can via <code>mapping</code> option in <code>config/kafo.yaml</code>.</p>
|
|
637
|
+
|
|
638
|
+
<p>Suppose we have a puppet module and we want to use a puppet/server.pp as our init file. Also we want to name our module puppetmaster. To do so we add the following mapping to kafo.yaml</p>
|
|
639
|
+
|
|
640
|
+
<pre class="code ruby"><code class="ruby">:mapping:
|
|
641
|
+
:puppetmaster: # a module name, so we'll have puppetmaster: true in answer file
|
|
642
|
+
:dir_name: 'puppet' # the subdirectory in modules/
|
|
643
|
+
:manifest_name: 'server' # manifest filename without .pp extension
|
|
644
|
+
:params_path: ... # params manifest full path, overriding params_name, must be with .pp extension
|
|
645
|
+
:params_name: 'params' # name of manifest holding the params class without .pp extension
|
|
646
|
+
</code></pre>
|
|
647
|
+
|
|
648
|
+
<p>Note that if you add a mapping you must enter both the dir_name and manifest_name even if one of them is already the default. The arguments params_path and params_name are optional. You can use just “params_name” or override not just the file name but also complete paths using “params_path”. If you use “params_path” for this purpose, “params_name” is ignored.</p>
|
|
649
|
+
|
|
650
|
+
<h2 id="label-Validations">Validations</h2>
|
|
651
|
+
|
|
652
|
+
<p>If class parameters are declared with Puppet data types then Kafo will validate user inputs against Puppet’s type validation rules.</p>
|
|
653
|
+
|
|
654
|
+
<h2 id="label-Enabling+or+disabling+module">Enabling or disabling module</h2>
|
|
655
|
+
|
|
656
|
+
<p>You can enable or disable a module specified in the answers.yaml file. Every module automatically adds two options to the foreman-installer script. For the module “foreman” you have two flag options <code>--enable-foreman</code> and <code>--no-enable-foreman</code>.</p>
|
|
657
|
+
|
|
658
|
+
<p>When you disable a module all its answers will be removed and “module” will be set to false. When you reenable the module you’ll end up with the default values.</p>
|
|
659
|
+
|
|
660
|
+
<h2 id="label-Special+values+for+arguments">Special values for arguments</h2>
|
|
661
|
+
|
|
662
|
+
<p>Sometimes you may want to enforce <code>undef</code> value for a particular parameter. You can set this value by specifying an UNDEF string e.g.</p>
|
|
663
|
+
|
|
664
|
+
<pre class="code ruby"><code class="ruby">bin/foreman-installer --foreman-db-password=UNDEF
|
|
665
|
+
</code></pre>
|
|
666
|
+
|
|
667
|
+
<p>It also works in interactive mode.</p>
|
|
668
|
+
|
|
669
|
+
<p>You may also need to override array parameters with empty array values. For this purpose you can use <code>EMPTY_ARRAY</code> string as a value. Similarly you can use <code>EMPTY_HASH</code> for hash parameters.</p>
|
|
670
|
+
|
|
671
|
+
<h2 id="label-Hooks">Hooks</h2>
|
|
672
|
+
|
|
673
|
+
<p>You may need to add new features to the installer. Kafo provides a simple hook mechanism that allows you to run custom code at several different occasions. We currently support the following hooks.</p>
|
|
674
|
+
<ul><li>
|
|
675
|
+
<p>pre_migrations - just after kafo reads its configuration - useful for config file updates. Only in this stage it is posible to request config reload (<code>Kafo.request_config_reload</code>) to get in our changes</p>
|
|
676
|
+
</li><li>
|
|
677
|
+
<p>boot - before kafo is ready to work, useful for adding new installer arguments, but logger won’t work yet</p>
|
|
678
|
+
</li><li>
|
|
679
|
+
<p>init - just after hooking is initialized and kafo is configured, parameters have no values yet</p>
|
|
680
|
+
</li><li>
|
|
681
|
+
<p>pre_values - just before value from CLI is set to parameters (they already have default values)</p>
|
|
682
|
+
</li><li>
|
|
683
|
+
<p>pre_validations - just after system checks and before validations are executed (and before interactive wizard is started), at this point all parameter values are already set but not yet stored in answer file</p>
|
|
684
|
+
</li><li>
|
|
685
|
+
<p>pre_commit - after validations or interactive wizard have completed, all parameter values are set but not yet stored in the answer file</p>
|
|
686
|
+
</li><li>
|
|
687
|
+
<p>pre - just before puppet is executed to converge system, after parameter values are stored in the answer file</p>
|
|
688
|
+
</li><li>
|
|
689
|
+
<p>post - just after puppet is executed to converge system</p>
|
|
690
|
+
</li><li>
|
|
691
|
+
<p>pre_exit - happens during exit handling, before exit is completed</p>
|
|
692
|
+
</li></ul>
|
|
693
|
+
|
|
694
|
+
<p>For better understanding when the hooks are executed see the <img src="doc/kafo_run.png" />.</p>
|
|
695
|
+
|
|
696
|
+
<p>Let’s assume we want to add the <code>--reset-foreman-db</code> option to our foreman-installer. We could add the following lines to the generated installer script.</p>
|
|
697
|
+
|
|
698
|
+
<pre class="code ruby"><code class="ruby"><span class='id identifier rubyid_require'>require</span> <span class='tstring'><span class='tstring_beg'>'</span><span class='tstring_content'>kafo/hooking</span><span class='tstring_end'>'</span></span>
|
|
699
|
+
|
|
700
|
+
<span class='comment'># first hook that creates new app option --reset-foreman-db
|
|
701
|
+
</span><span class='const'>KafoConfigure</span><span class='period'>.</span><span class='id identifier rubyid_hooking'>hooking</span><span class='period'>.</span><span class='id identifier rubyid_register_boot'>register_boot</span><span class='lparen'>(</span><span class='symbol'>:add_reset_option</span><span class='rparen'>)</span> <span class='kw'>do</span>
|
|
702
|
+
<span class='id identifier rubyid_app_option'>app_option</span> <span class='tstring'><span class='tstring_beg'>'</span><span class='tstring_content'>--reset-foreman-db</span><span class='tstring_end'>'</span></span><span class='comma'>,</span>
|
|
703
|
+
<span class='symbol'>:flag</span><span class='comma'>,</span> <span class='tstring'><span class='tstring_beg'>'</span><span class='tstring_content'>Drop foreman database first? You will lose all data!</span><span class='tstring_end'>'</span></span><span class='comma'>,</span> <span class='symbol'>:default</span> <span class='op'>=></span> <span class='kw'>false</span>
|
|
704
|
+
<span class='kw'>end</span>
|
|
705
|
+
|
|
706
|
+
<span class='comment'># second hook which resets the db if value was set to true
|
|
707
|
+
</span><span class='const'>KafoConfigure</span><span class='period'>.</span><span class='id identifier rubyid_hooking'>hooking</span><span class='period'>.</span><span class='id identifier rubyid_register_pre'>register_pre</span><span class='lparen'>(</span><span class='symbol'>:reset_db</span><span class='rparen'>)</span> <span class='kw'>do</span>
|
|
708
|
+
<span class='kw'>if</span> <span class='id identifier rubyid_app_value'>app_value</span><span class='lparen'>(</span><span class='symbol'>:reset_foreman_db</span><span class='rparen'>)</span> <span class='op'>&&</span> <span class='op'>!</span><span class='id identifier rubyid_app_value'>app_value</span><span class='lparen'>(</span><span class='symbol'>:noop</span><span class='rparen'>)</span>
|
|
709
|
+
<span class='backtick'>`</span><span class='tstring_content'>which foreman-rake > /dev/null 2>&1</span><span class='tstring_end'>`</span></span>
|
|
710
|
+
<span class='kw'>if</span> <span class='gvar'>$?</span><span class='period'>.</span><span class='id identifier rubyid_success?'>success?</span>
|
|
711
|
+
<span class='id identifier rubyid_logger'>logger</span><span class='period'>.</span><span class='id identifier rubyid_info'>info</span> <span class='tstring'><span class='tstring_beg'>'</span><span class='tstring_content'>Dropping database!</span><span class='tstring_end'>'</span></span>
|
|
712
|
+
<span class='id identifier rubyid_output'>output</span> <span class='op'>=</span> <span class='backtick'>`</span><span class='tstring_content'>foreman-rake db:drop 2>&1</span><span class='tstring_end'>`</span></span>
|
|
713
|
+
<span class='id identifier rubyid_logger'>logger</span><span class='period'>.</span><span class='id identifier rubyid_debug'>debug</span> <span class='id identifier rubyid_output'>output</span><span class='period'>.</span><span class='id identifier rubyid_to_s'>to_s</span>
|
|
714
|
+
<span class='kw'>unless</span> <span class='gvar'>$?</span><span class='period'>.</span><span class='id identifier rubyid_success?'>success?</span>
|
|
715
|
+
<span class='id identifier rubyid_logger'>logger</span><span class='period'>.</span><span class='id identifier rubyid_warn'>warn</span> <span class='tstring'><span class='tstring_beg'>"</span><span class='tstring_content'>Unable to drop DB, ignoring since it's not fatal, output was: '</span><span class='embexpr_beg'>#{</span><span class='id identifier rubyid_output'>output</span><span class='embexpr_end'>}</span><span class='tstring_content'>''</span><span class='tstring_end'>"</span></span>
|
|
716
|
+
<span class='kw'>end</span>
|
|
717
|
+
<span class='kw'>else</span>
|
|
718
|
+
<span class='id identifier rubyid_logger'>logger</span><span class='period'>.</span><span class='id identifier rubyid_warn'>warn</span> <span class='tstring'><span class='tstring_beg'>'</span><span class='tstring_content'>Foreman not installed yet, can not drop database!</span><span class='tstring_end'>'</span></span>
|
|
719
|
+
<span class='kw'>end</span>
|
|
720
|
+
<span class='kw'>end</span>
|
|
721
|
+
<span class='kw'>end</span>
|
|
722
|
+
</code></pre>
|
|
723
|
+
|
|
724
|
+
<p>Note that the hook is evaluated in HookContext object which provides a DSL:</p>
|
|
725
|
+
<ul><li>
|
|
726
|
+
<p><code>app_option</code> creates a new installer option</p>
|
|
727
|
+
</li><li>
|
|
728
|
+
<pre class="code ruby"><code class="ruby"><span class='lparen'>(</span><span class='symbol'>:reset_foreman_db</span><span class='rparen'>)</span>
|
|
729
|
+
</code></pre>
|
|
730
|
+
|
|
731
|
+
<p>accesses values of installer options</p>
|
|
732
|
+
</li><li>
|
|
733
|
+
<pre class="code ruby"><code class="ruby">('module name', 'parameter name')
|
|
734
|
+
</code></pre>
|
|
735
|
+
|
|
736
|
+
<p>accessor allows parameters to be modified if already defined</p>
|
|
737
|
+
</li><li>
|
|
738
|
+
<p><code>add_module</code> registers your own module not specified in the answer file (custom mapping is also supported), useful if you need to add some module to the existing installer based on kafo but you don’t have control over its source code</p>
|
|
739
|
+
</li><li>
|
|
740
|
+
<pre class="code ruby"><code class="ruby"><span class='lparen'>(</span><span class='tstring'><span class='tstring_beg'>'</span><span class='tstring_content'>module_name</span><span class='tstring_end'>'</span></span><span class='rparen'>)</span>
|
|
741
|
+
</code></pre>
|
|
742
|
+
|
|
743
|
+
<p>indicates whether a module is currently enabled</p>
|
|
744
|
+
</li><li>
|
|
745
|
+
<p><code>get_custom_config</code> and <code>store_custom_config</code> access custom config storage which persists among kafo runs</p>
|
|
746
|
+
</li><li>
|
|
747
|
+
<p><code>logger</code> is also available for writing log messages</p>
|
|
748
|
+
</li></ul>
|
|
749
|
+
|
|
750
|
+
<p>For more details, see <a href="https://github.com/theforeman/kafo/blob/master/lib/kafo/hook_context.rb">hook_context.rb</a>.</p>
|
|
751
|
+
|
|
752
|
+
<p>If you don’t want to modify your installer script you can place your hooks into the hooks directory. By default the hooks dir is searched for ruby files in subdirectories based on hook type. For example pre hooks are searched for in <code>$installer_dir/hooks/pre/*.rb</code> The hooks from the previous example would look like this. The only change to the code is that you don’t explicitely register hooks, it’s done automatically for you.</p>
|
|
753
|
+
|
|
754
|
+
<pre class="code ruby"><code class="ruby"><span class='comment'># hooks/boot/10-add_reset_option.rb
|
|
755
|
+
</span><span class='id identifier rubyid_app_option'>app_option</span> <span class='tstring'><span class='tstring_beg'>'</span><span class='tstring_content'>--reset-foreman-db</span><span class='tstring_end'>'</span></span><span class='comma'>,</span> <span class='symbol'>:flag</span><span class='comma'>,</span> <span class='tstring'><span class='tstring_beg'>'</span><span class='tstring_content'>Drop foreman database first? You will lose all data!</span><span class='tstring_end'>'</span></span><span class='comma'>,</span> <span class='symbol'>:default</span> <span class='op'>=></span> <span class='kw'>false</span>
|
|
756
|
+
</code></pre>
|
|
757
|
+
|
|
758
|
+
<pre class="code ruby"><code class="ruby"><span class='comment'># hooks/pre/10-reset_option_feature.rb
|
|
759
|
+
</span><span class='kw'>if</span> <span class='id identifier rubyid_app_value'>app_value</span><span class='lparen'>(</span><span class='symbol'>:reset_foreman_db</span><span class='rparen'>)</span> <span class='op'>&&</span> <span class='op'>!</span><span class='id identifier rubyid_app_value'>app_value</span><span class='lparen'>(</span><span class='symbol'>:noop</span><span class='rparen'>)</span>
|
|
760
|
+
<span class='backtick'>`</span><span class='tstring_content'>which foreman-rake > /dev/null 2>&1</span><span class='tstring_end'>`</span></span>
|
|
761
|
+
<span class='kw'>if</span> <span class='gvar'>$?</span><span class='period'>.</span><span class='id identifier rubyid_success?'>success?</span>
|
|
762
|
+
<span class='id identifier rubyid_logger'>logger</span><span class='period'>.</span><span class='id identifier rubyid_info'>info</span> <span class='tstring'><span class='tstring_beg'>'</span><span class='tstring_content'>Dropping database!</span><span class='tstring_end'>'</span></span>
|
|
763
|
+
<span class='id identifier rubyid_output'>output</span> <span class='op'>=</span> <span class='backtick'>`</span><span class='tstring_content'>foreman-rake db:drop 2>&1</span><span class='tstring_end'>`</span></span>
|
|
764
|
+
<span class='id identifier rubyid_logger'>logger</span><span class='period'>.</span><span class='id identifier rubyid_debug'>debug</span> <span class='id identifier rubyid_output'>output</span><span class='period'>.</span><span class='id identifier rubyid_to_s'>to_s</span>
|
|
765
|
+
<span class='kw'>unless</span> <span class='gvar'>$?</span><span class='period'>.</span><span class='id identifier rubyid_success?'>success?</span>
|
|
766
|
+
<span class='id identifier rubyid_logger'>logger</span><span class='period'>.</span><span class='id identifier rubyid_warn'>warn</span> <span class='tstring'><span class='tstring_beg'>"</span><span class='tstring_content'>Unable to drop DB, ignoring since it's not fatal, output was: '</span><span class='embexpr_beg'>#{</span><span class='id identifier rubyid_output'>output</span><span class='embexpr_end'>}</span><span class='tstring_content'>''</span><span class='tstring_end'>"</span></span>
|
|
767
|
+
<span class='kw'>end</span>
|
|
768
|
+
<span class='kw'>else</span>
|
|
769
|
+
<span class='id identifier rubyid_logger'>logger</span><span class='period'>.</span><span class='id identifier rubyid_warn'>warn</span> <span class='tstring'><span class='tstring_beg'>'</span><span class='tstring_content'>Foreman not installed yet, can not drop database!</span><span class='tstring_end'>'</span></span>
|
|
770
|
+
<span class='kw'>end</span>
|
|
771
|
+
<span class='kw'>end</span>
|
|
772
|
+
</code></pre>
|
|
773
|
+
|
|
774
|
+
<p>Hooks can additionally be defined by combining all related stages into a single file known as a Multi-stage hook. Multi-stage hooks live in a special directory inside the hooks directory: <code>$installer_dir/hooks/multi</code>. Taking the previous example:</p>
|
|
775
|
+
|
|
776
|
+
<pre class="code ruby"><code class="ruby"><span class='comment'># hooks/multi/10-reset_option_feature.rb
|
|
777
|
+
</span><span class='id identifier rubyid_boot'>boot</span> <span class='kw'>do</span>
|
|
778
|
+
<span class='id identifier rubyid_app_option'>app_option</span> <span class='tstring'><span class='tstring_beg'>'</span><span class='tstring_content'>--reset-foreman-db</span><span class='tstring_end'>'</span></span><span class='comma'>,</span> <span class='symbol'>:flag</span><span class='comma'>,</span> <span class='tstring'><span class='tstring_beg'>'</span><span class='tstring_content'>Drop foreman database first? You will lose all data!</span><span class='tstring_end'>'</span></span><span class='comma'>,</span> <span class='symbol'>:default</span> <span class='op'>=></span> <span class='kw'>false</span>
|
|
779
|
+
<span class='kw'>end</span>
|
|
780
|
+
|
|
781
|
+
<span class='id identifier rubyid_pre'>pre</span> <span class='kw'>do</span>
|
|
782
|
+
<span class='kw'>if</span> <span class='id identifier rubyid_app_value'>app_value</span><span class='lparen'>(</span><span class='symbol'>:reset_foreman_db</span><span class='rparen'>)</span> <span class='op'>&&</span> <span class='op'>!</span><span class='id identifier rubyid_app_value'>app_value</span><span class='lparen'>(</span><span class='symbol'>:noop</span><span class='rparen'>)</span>
|
|
783
|
+
<span class='backtick'>`</span><span class='tstring_content'>which foreman-rake > /dev/null 2>&1</span><span class='tstring_end'>`</span></span>
|
|
784
|
+
<span class='kw'>if</span> <span class='gvar'>$?</span><span class='period'>.</span><span class='id identifier rubyid_success?'>success?</span>
|
|
785
|
+
<span class='id identifier rubyid_logger'>logger</span><span class='period'>.</span><span class='id identifier rubyid_info'>info</span> <span class='tstring'><span class='tstring_beg'>'</span><span class='tstring_content'>Dropping database!</span><span class='tstring_end'>'</span></span>
|
|
786
|
+
<span class='id identifier rubyid_output'>output</span> <span class='op'>=</span> <span class='backtick'>`</span><span class='tstring_content'>foreman-rake db:drop 2>&1</span><span class='tstring_end'>`</span></span>
|
|
787
|
+
<span class='id identifier rubyid_logger'>logger</span><span class='period'>.</span><span class='id identifier rubyid_debug'>debug</span> <span class='id identifier rubyid_output'>output</span><span class='period'>.</span><span class='id identifier rubyid_to_s'>to_s</span>
|
|
788
|
+
<span class='kw'>unless</span> <span class='gvar'>$?</span><span class='period'>.</span><span class='id identifier rubyid_success?'>success?</span>
|
|
789
|
+
<span class='id identifier rubyid_logger'>logger</span><span class='period'>.</span><span class='id identifier rubyid_warn'>warn</span> <span class='tstring'><span class='tstring_beg'>"</span><span class='tstring_content'>Unable to drop DB, ignoring since it's not fatal, output was: '</span><span class='embexpr_beg'>#{</span><span class='id identifier rubyid_output'>output</span><span class='embexpr_end'>}</span><span class='tstring_content'>''</span><span class='tstring_end'>"</span></span>
|
|
790
|
+
<span class='kw'>end</span>
|
|
791
|
+
<span class='kw'>else</span>
|
|
792
|
+
<span class='id identifier rubyid_logger'>logger</span><span class='period'>.</span><span class='id identifier rubyid_warn'>warn</span> <span class='tstring'><span class='tstring_beg'>'</span><span class='tstring_content'>Foreman not installed yet, can not drop database!</span><span class='tstring_end'>'</span></span>
|
|
793
|
+
<span class='kw'>end</span>
|
|
794
|
+
<span class='kw'>end</span>
|
|
795
|
+
<span class='kw'>end</span>
|
|
796
|
+
</code></pre>
|
|
797
|
+
|
|
798
|
+
<p>If you want to add more directories to be search you can use the “hook_dirs” option in the installer configuration file.</p>
|
|
799
|
+
|
|
800
|
+
<pre class="code ruby"><code class="ruby">:hook_dirs:
|
|
801
|
+
- /opt/hooks
|
|
802
|
+
- /my/plugin/hooks
|
|
803
|
+
</code></pre>
|
|
804
|
+
|
|
805
|
+
<p>You can register as many hooks as you need. The order of execution for a particular hook type is based on hook file name.</p>
|
|
806
|
+
|
|
807
|
+
<p>If you want to cancel the installation you can use the <code>exit</code> method and specify an exit code.</p>
|
|
808
|
+
|
|
809
|
+
<h2 id="label-Colors">Colors</h2>
|
|
810
|
+
|
|
811
|
+
<p>Everybody loves colors right? In case you don’t you can disable them using the <code>--no-colors</code> argument or disallow them in the installer config file (search for <code>colors:</code> key and set it to false). If you don’t touch this setting, kafo will try to detect whether colors are supported and will enable/disable it accordingly.</p>
|
|
812
|
+
|
|
813
|
+
<p>Kafo supports two sets of colors, one for terminals with bright and one for dark backround. You can specify your installer default scheme in installer config file (<code>color_of_background</code> key). Alternatively the user can override this default setting with the <code>--color-of-background</code> argument. Possible values are <code>dark</code> and <code>bright</code>.</p>
|
|
814
|
+
|
|
815
|
+
<p>You can reuse the kafo color schema in your custom hooks (so you can reuse dark/bright logic). Look at this example in bin/foreman-installer</p>
|
|
816
|
+
|
|
817
|
+
<pre class="code ruby"><code class="ruby">#!/usr/bin/env ruby
|
|
818
|
+
|
|
819
|
+
# Run the install
|
|
820
|
+
@result = Kafo::KafoConfigure.run
|
|
821
|
+
exit 0 if @result.nil? # --help invocation
|
|
822
|
+
|
|
823
|
+
# Puppet status codes say 0 for unchanged, 2 for changed succesfully
|
|
824
|
+
if [0,2].include?(@result.exit_code)
|
|
825
|
+
say " <%= color('Success!', :good) %>"
|
|
826
|
+
|
|
827
|
+
if module_enabled? 'foreman'
|
|
828
|
+
say " * <%= color('Foreman', :info) %> is running at <%= color('#{get_param('foreman','foreman_url')}', :info) %>"
|
|
829
|
+
say " Default credentials are '<%= color('admin:changeme', :info) %>'"e
|
|
830
|
+
end
|
|
831
|
+
end
|
|
832
|
+
</code></pre>
|
|
833
|
+
|
|
834
|
+
<p>As you can see you can use HighLine helpers (e.g. say) with colors. Look at kafo/color_schema.rb for supported color identifiers. We can guarantee that there will always be at least :good, :bad, :info.</p>
|
|
835
|
+
|
|
836
|
+
<p>Methods like module_enabled? and get_param are just helpers defined in the same file. If you find them useful, here’s the definition</p>
|
|
837
|
+
|
|
838
|
+
<pre class="code ruby"><code class="ruby"><span class='kw'>def</span> <span class='id identifier rubyid_module_enabled?'>module_enabled?</span><span class='lparen'>(</span><span class='id identifier rubyid_name'>name</span><span class='rparen'>)</span>
|
|
839
|
+
<span class='id identifier rubyid_mod'>mod</span> <span class='op'>=</span> <span class='ivar'>@result</span><span class='period'>.</span><span class='id identifier rubyid_module'>module</span><span class='lparen'>(</span><span class='id identifier rubyid_name'>name</span><span class='rparen'>)</span>
|
|
840
|
+
<span class='kw'>return</span> <span class='kw'>false</span> <span class='kw'>if</span> <span class='id identifier rubyid_mod'>mod</span><span class='period'>.</span><span class='id identifier rubyid_nil?'>nil?</span>
|
|
841
|
+
<span class='id identifier rubyid_mod'>mod</span><span class='period'>.</span><span class='id identifier rubyid_enabled?'>enabled?</span>
|
|
842
|
+
<span class='kw'>end</span>
|
|
843
|
+
|
|
844
|
+
<span class='kw'>def</span> <span class='id identifier rubyid_get_param'>get_param</span><span class='lparen'>(</span><span class='id identifier rubyid_mod'>mod</span><span class='comma'>,</span> <span class='id identifier rubyid_name'>name</span><span class='rparen'>)</span>
|
|
845
|
+
<span class='ivar'>@result</span><span class='period'>.</span><span class='id identifier rubyid_param'>param</span><span class='lparen'>(</span><span class='id identifier rubyid_mod'>mod</span><span class='comma'>,</span> <span class='id identifier rubyid_name'>name</span><span class='rparen'>)</span><span class='period'>.</span><span class='id identifier rubyid_value'>value</span>
|
|
846
|
+
<span class='kw'>end</span>
|
|
847
|
+
</code></pre>
|
|
848
|
+
|
|
849
|
+
<h2 id="label-Custom+paths">Custom paths</h2>
|
|
850
|
+
|
|
851
|
+
<p>Usually when you package your installer you want to load files from specific paths. In order to do that you can use following configuration options:</p>
|
|
852
|
+
<ul><li>
|
|
853
|
+
<p>:answer_file: /etc/kafo/kafo.yaml</p>
|
|
854
|
+
</li><li>
|
|
855
|
+
<p>:installer_dir: /usr/share/kafo/</p>
|
|
856
|
+
</li><li>
|
|
857
|
+
<p>:module_dirs: /usr/share/foreman-installer/modules</p>
|
|
858
|
+
</li><li>
|
|
859
|
+
<p>:hook_dirs: /user/share/foreman-installer/hooks</p>
|
|
860
|
+
</li><li>
|
|
861
|
+
<p>:check_dirs: /user/share/foreman-installer/checks</p>
|
|
862
|
+
</li><li>
|
|
863
|
+
<p>:kafo_modules_dir: /usr/share/kafo/modules</p>
|
|
864
|
+
</li><li>
|
|
865
|
+
<p>:store_dir: /etc/foreman-installer/store.d</p>
|
|
866
|
+
</li></ul>
|
|
867
|
+
|
|
868
|
+
<p>Answer file is obvious. The “installer_dir” is the place where your installer is located. E.g. system checks will be loaded from here (under checks subdirectory) if not set elsewhere by <code>check_dirs</code>. You can optionally change foreman-installer modules dir using <code>module_dirs</code> option and hooks dir using <code>hook_dirs</code> option. <code>module_dirs</code>, <code>hook_dirs</code> and <code>check_dirs</code> can hold multiple directories where to look for the resources.</p>
|
|
869
|
+
|
|
870
|
+
<p>On debian systems you may want to specify kafo modules dir independent on your installer location. If you specify this option kafo’s internal-installer puppet-modules will be loaded from here.</p>
|
|
871
|
+
|
|
872
|
+
<h2 id="label-Order+of+puppet+modules+execution">Order of puppet modules execution</h2>
|
|
873
|
+
|
|
874
|
+
<p>When you have more than one module you may end up in the situation where you need a specific order of execution. It seems as a puppet antipattern to me however there may be cases where it’s needed. You can set order in config/kafo.yaml like this</p>
|
|
875
|
+
|
|
876
|
+
<pre class="code ruby"><code class="ruby">order:
|
|
877
|
+
- foreman
|
|
878
|
+
- foreman_proxy
|
|
879
|
+
</code></pre>
|
|
880
|
+
|
|
881
|
+
<p>If you have other modules in your answer file they will be executed after those that have explicit order. Their order is not be specified.</p>
|
|
882
|
+
|
|
883
|
+
<h2 id="label-Changing+the+order+of+module+appearance+in+interactive+mode">Changing the order of module appearance in interactive mode</h2>
|
|
884
|
+
|
|
885
|
+
<p>We sort our modules alphabetically. Sometimes you may want to reorder modules, e.g. a display plugin modules as last module. For this you can use the <code>low_priority_modules</code> configuration option. It accepts an array of patterns considering the first to have the lowest priority. So in follwing example</p>
|
|
886
|
+
|
|
887
|
+
<pre class="code ruby"><code class="ruby">low_priority_modules:
|
|
888
|
+
- compute
|
|
889
|
+
- plugin
|
|
890
|
+
</code></pre>
|
|
891
|
+
|
|
892
|
+
<p>all modules containing a word compute in their name would be listed at the end. If there are two modules containing compute, their order is alphabetical on suffix after compute word. If there are some modules containing word plugin, they will be above compute modules as they were mentioned later.</p>
|
|
893
|
+
|
|
894
|
+
<h2 id="label-Changing+of+log+directory+and+user-2Fgroup">Changing of log directory and user/group</h2>
|
|
895
|
+
|
|
896
|
+
<p>By default kafo logs every run to a separate file in /var/log/kafo. You probably want to put your installation logs alongside with other logs of your application. That’s why kafo has its own configuration file in which you can tune details like these.</p>
|
|
897
|
+
|
|
898
|
+
<p>In order to do that, create a configuration file under config/kafo.yaml. You can use config/kafo.yaml.example as a template. If config/kafo.yaml does not exist default values will be used.</p>
|
|
899
|
+
|
|
900
|
+
<p>As a developer you can appreciate more verbose log. You can set a debug level in config/kafo.yml. Also you can change a user or group that will own the log file. This is usefull if your installer requires to be run as root but you want the logs to be readable by specific users.</p>
|
|
901
|
+
|
|
902
|
+
<h2 id="label-System+checks">System checks</h2>
|
|
903
|
+
|
|
904
|
+
<p>When you want to make sure that a user has a certain software installed or has the right version you can write a simple script and put it into the checks directory. All files found there will be executed and if any of these exits with an non-zero exit code, kafo won’t execute puppet but only print an error message <code>Your system does not meet configuration criteria.</code></p>
|
|
905
|
+
|
|
906
|
+
<p>Everything on STDOUT and STDERR is logged in error level.</p>
|
|
907
|
+
|
|
908
|
+
<p>Example shell script which checks java version</p>
|
|
909
|
+
|
|
910
|
+
<pre class="code ruby"><code class="ruby">#!/bin/sh
|
|
911
|
+
java -version 2>&1 | grep OpenJDK
|
|
912
|
+
exit $?
|
|
913
|
+
</code></pre>
|
|
914
|
+
|
|
915
|
+
<p>If you want to ignore results of the check scripts, you can use the builtin parameter <code>--skip-checks-i-know-better</code> (or <code>-s</code>). This will completely disable running all system check scripts. Note that this option is not persisted between runs.</p>
|
|
916
|
+
|
|
917
|
+
<h2 id="label-Parser+cache">Parser cache</h2>
|
|
918
|
+
|
|
919
|
+
<p>One or more caches of parsed Puppet modules and manifests can be created to skip the use of kafo_parsers at runtime. This is useful when kafo_parsers doesn’t support the version of Puppet in use, and may also provide a small performance benefit. When multiple cache files are used, they are being loaded in order they are specified in the config file. If their files overlap, the later cache fully replaces the previous cache for each file/manifest.</p>
|
|
920
|
+
|
|
921
|
+
<p>Create the cache with <code>kafo-export-params -f parsercache --no-parser-cache</code> and configure it in config/kafo.yaml with:</p>
|
|
922
|
+
|
|
923
|
+
<pre class="code ruby"><code class="ruby"># single cache
|
|
924
|
+
:parser_cache_path: ./parser_cache.yaml
|
|
925
|
+
|
|
926
|
+
# multiple caches
|
|
927
|
+
:parser_cache_path:
|
|
928
|
+
- ./parser_cache.yaml
|
|
929
|
+
- ./another_parser_cache.yaml
|
|
930
|
+
</code></pre>
|
|
931
|
+
|
|
932
|
+
<p>The cache will be skipped if the file modification time of the manifest is greater than the mtime recorded in the cache. Using <code>--parser-cache</code> will force the use of an outdated cache, but this should be used with caution.</p>
|
|
933
|
+
|
|
934
|
+
<h2 id="label-Facts">Facts</h2>
|
|
935
|
+
|
|
936
|
+
<p>Kafo provides a structured fact describing the state. This fact is only present during the Puppet run. Currently it’s the scenario id and name where the id is the same as passed via –scenario by the user and matches the scenario filename with an extension. The name is a human readable version.</p>
|
|
937
|
+
|
|
938
|
+
<pre class="code ruby"><code class="ruby">---
|
|
939
|
+
kafo:
|
|
940
|
+
scenario:
|
|
941
|
+
id: foreman_proxy
|
|
942
|
+
name: Foreman Proxy
|
|
943
|
+
</code></pre>
|
|
944
|
+
|
|
945
|
+
<h2 id="label-Configuring+Hiera">Configuring Hiera</h2>
|
|
946
|
+
|
|
947
|
+
<p>Kafo uses Hiera to include classes and pass parameters to classes using data binding, but this can be extended so parameters can be set for classes not being managed by Kafo. Set a custom Hiera config file in Kafo’s config with:</p>
|
|
948
|
+
|
|
949
|
+
<pre class="code ruby"><code class="ruby">:hiera_config: /usr/share/kafo/hiera.yaml
|
|
950
|
+
</code></pre>
|
|
951
|
+
|
|
952
|
+
<p>The contents of this file are as per the <a href="https://docs.puppet.com/hiera/latest/configuring.html">hiera.yaml docs</a>. Only Hiera version 5 is supported.</p>
|
|
953
|
+
|
|
954
|
+
<p>An answers file will be generated containing <em>all</em> default and overriden values for parameters managed by Kafo. During the run this is available as a <code>kafo.scenario.answer_file</code> fact. This may change in the future to allow a more complex hierarchy.</p>
|
|
955
|
+
|
|
956
|
+
<p>The hierarchy must contain the path <code>%{facts.kafo.scenario.answer_file}</code>. This contains all answers in a temporary location.</p>
|
|
957
|
+
|
|
958
|
+
<p>As an example, a hierarchy could be set up with:</p>
|
|
959
|
+
|
|
960
|
+
<pre class="code ruby"><code class="ruby">hierarchy:
|
|
961
|
+
- name: "Kafo Answers"
|
|
962
|
+
path: "%{facts.kafo.scenario.answer_file}"
|
|
963
|
+
- name: "Other YAML hierarchy levels"
|
|
964
|
+
paths:
|
|
965
|
+
- "family/%{facts.os.family}.yaml"
|
|
966
|
+
- "common.yaml"
|
|
967
|
+
</code></pre>
|
|
968
|
+
|
|
969
|
+
<p>It is possible to include another file above answers:</p>
|
|
970
|
+
|
|
971
|
+
<pre class="code ruby"><code class="ruby">hierarchy:
|
|
972
|
+
- name: "Custom values"
|
|
973
|
+
datadir: "custom"
|
|
974
|
+
path: "override.yaml"
|
|
975
|
+
- name: "Kafo Answers"
|
|
976
|
+
path: "%{facts.kafo.scenario.answer_file}"
|
|
977
|
+
- name: "Other YAML hierarchy levels"
|
|
978
|
+
datadir: "data"
|
|
979
|
+
paths:
|
|
980
|
+
- "family/%{facts.os.family}.yaml"
|
|
981
|
+
- "common.yaml"
|
|
982
|
+
</code></pre>
|
|
983
|
+
|
|
984
|
+
<p>This would give precedence to all Kafo-managed parameter values, but for any others, would check for values per OS family, followed by a <code>common.yaml</code> file.</p>
|
|
985
|
+
|
|
986
|
+
<p>The scenario id is also available as a fact which can be used to provide scenario specific overrides for unmanaged modules.</p>
|
|
987
|
+
|
|
988
|
+
<pre class="code ruby"><code class="ruby">hierarchy:
|
|
989
|
+
- name: "Kafo Answers"
|
|
990
|
+
path: "%{facts.kafo.scenario.answer_file}"
|
|
991
|
+
- name: "Scenario defaults"
|
|
992
|
+
path: "scenario/%{facts.kafo.scenario.id}.yaml"
|
|
993
|
+
</code></pre>
|
|
994
|
+
|
|
995
|
+
<p><a href="https://puppet.com/docs/puppet/4.9/hiera_migrate_v3_yaml.html">Migration from Hiera version 3</a> is documented by Puppet.</p>
|
|
996
|
+
|
|
997
|
+
<h2 id="label-Exit+code">Exit code</h2>
|
|
998
|
+
|
|
999
|
+
<p>Kafo can terminate either before or after puppet is run. If it is run with <code>--detailed-exitcodes</code> Kafo returns the same exit code as puppet does. If kafo terminates after puppet run exit codes are like the following: * ‘1’ means there were parser/validation errors * ‘2’ means there were changes, * ‘4’ means there were failures during the transaction, * ‘6’ means there were both changes and failures.</p>
|
|
1000
|
+
|
|
1001
|
+
<p>Other exit codes that can be returned: * ‘0’ means everything went fine no changes were made * ‘20’ means your system does not meet configuration criteria (system checks failed) * ‘21’ means your answer file contains invalid values * ‘22’ means that puppet modules contains some error (e.g. missing documentation) * ‘23’ means that you have no answer file * ‘24’ means that your answer file asks for puppet module that you did not provide * ‘25’ means that kafo could not get default values from puppet * ‘26’ means that kafo could not find the specified scenario * ‘27’ means that kafo found found scenario configuration error that prevents installation from continuing * ‘28’ means that a value is missing for a parameter given on the command line * ‘29’ means that effective user that ran the installer does not have permission to update the answer file * ‘30’ means that the version of Puppet is incompatible with a module, according to its <a href="https://docs.puppet.com/puppet/latest/modules_metadata.html">metadata.json</a> * ‘130’ user interrupt (^C)</p>
|
|
1002
|
+
|
|
1003
|
+
<h2 id="label-Running+Puppet+Profiling">Running Puppet Profiling</h2>
|
|
1004
|
+
|
|
1005
|
+
<p>Performance data can be gathered during a Puppet run by adding the <code>--profile</code> option. See <a href="https://puppet.com/blog/tune-puppet-for-performance-profiler">Tune Puppet for Performance with Profiler</a> for more information from the Puppet team. Users who wish to perform a Kafo run and gather this type of profiling data to analyze can pass the same option to their installer. The profiling data will then be present in the normal Kafo logs.</p>
|
|
1006
|
+
|
|
1007
|
+
<h2 id="label-Issue+tracker">Issue tracker</h2>
|
|
1008
|
+
|
|
1009
|
+
<p>Issues are tracked in Redmine, see:</p>
|
|
1010
|
+
<ul><li>
|
|
1011
|
+
<p><a href="https://projects.theforeman.org/projects/kafo/issues/">Open Kafo issues</a></p>
|
|
1012
|
+
</li><li>
|
|
1013
|
+
<p><a href="https://projects.theforeman.org/projects/kafo/issues/new">File new issue</a></p>
|
|
1014
|
+
</li></ul>
|
|
1015
|
+
|
|
1016
|
+
<h2 id="label-Related+projects">Related projects</h2>
|
|
1017
|
+
<ul><li>
|
|
1018
|
+
<p><a href="https://github.com/domcleal/kafo_module_lint">kafo_module_lint</a> will lint Puppet modules to ensure data types are specified correctly etc.</p>
|
|
1019
|
+
</li><li>
|
|
1020
|
+
<p><a href="https://github.com/theforeman/kafo_parsers">kafo_parsers</a> parses Puppet manifests for class documentation and parameter data</p>
|
|
1021
|
+
</li><li>
|
|
1022
|
+
<p><a href="https://github.com/voxpupuli/puppet-lint-param-docs">puppet-lint-param-docs</a> will lint Puppet modules to ensure all parameters are documented</p>
|
|
1023
|
+
</li></ul>
|
|
1024
|
+
|
|
1025
|
+
<h1 id="label-License">License</h1>
|
|
1026
|
+
|
|
1027
|
+
<p>This project is licensed under the GPLv3+.</p>
|
|
1028
|
+
</div></div>
|
|
1029
|
+
|
|
1030
|
+
<div id="footer">
|
|
1031
|
+
Generated on Fri Jul 14 17:35:53 2023 by
|
|
1032
|
+
<a href="https://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
|
|
1033
|
+
0.9.34 (ruby-3.2.2).
|
|
1034
|
+
</div>
|
|
1035
|
+
|
|
1036
|
+
</div>
|
|
1037
|
+
</body>
|
|
1038
|
+
</html>
|