Mercurial > repos > other > Puppet

comparison modules/concat/README.md @ 275:d9352a684e62

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Mass update of modules to remove deprecation warnings
author IBBoard <dev@ibboard.co.uk>
date Sun, 26 Jan 2020 11:36:07 +0000
parents 37675581a273
children adf6fe9bbc17
comparison
equal deleted inserted replaced
274:b2571c28fc27 275:d9352a684e62
1 #Concat 1 # concat
2 2
3 [![Build Status](https://travis-ci.org/puppetlabs/puppetlabs-concat.png?branch=master)](https://travis-ci.org/puppetlabs/puppetlabs-concat) 3 #### Table of Contents
4
5 ####Table of Contents
6 4
7 1. [Overview](#overview) 5 1. [Overview](#overview)
8 2. [Module Description - What the module does and why it is useful](#module-description) 6 2. [Module Description - What the module does and why it is useful](#module-description)
9 3. [Setup - The basics of getting started with concat](#setup)
10 * [What concat affects](#what-concat-affects)
11 * [Setup requirements](#setup-requirements)
12 * [Beginning with concat](#beginning-with-concat) 7 * [Beginning with concat](#beginning-with-concat)
13 4. [Usage - Configuration options and additional functionality](#usage) 8 4. [Usage - Configuration options and additional functionality](#usage)
14 * [API _deprecations_](#api-deprecations)
15 5. [Reference - An under-the-hood peek at what the module is doing and how](#reference) 9 5. [Reference - An under-the-hood peek at what the module is doing and how](#reference)
16 5. [Limitations - OS compatibility, etc.](#limitations) 10 * [Removed functionality](#removed-functionality)
17 6. [Development - Guide for contributing to the module](#development) 11 6. [Limitations - OS compatibility, etc.](#limitations)
12 7. [Development - Guide for contributing to the module](#development)
18 13
19 ##Overview 14 <a id="overview"></a>
15 ## Overview
20 16
21 This module constructs files from multiple fragments in an ordered way. 17 The concat module lets you construct files from multiple ordered fragments of text.
22 18
23 ##Module Description 19 <a id="module-description"></a>
20 ## Module Description
24 21
25 This module lets you use many concat::fragment{} resources throughout 22 The concat module lets you gather `concat::fragment` resources from your other modules and order them into a coherent file through a single `concat` resource.
26 your modules to construct a single file at the end. It does this through
27 a shell (or ruby) script and a temporary holding space for the fragments.
28 23
29 ##Setup 24 <a id="beginning-with-concat"></a>
30 25 ### Beginning with concat
31 ###What concat affects
32
33 * Installs concatfragments.[sh|rb] based on platform.
34 * Adds a concat/ directory into Puppets `vardir`.
35
36 ###Beginning with concat
37 26
38 To start using concat you need to create: 27 To start using concat you need to create:
39 28
40 * A concat{} resource for the final file. 29 * A concat{} resource for the final file.
41 * One or more concat::fragment{}'s. 30 * One or more concat::fragment{}s.
42 31
43 A minimal example might be: 32 A minimal example might be:
44 33
45 ```puppet 34 ~~~
46 concat { '/tmp/file': 35 concat { '/tmp/file':
47 ensure => present, 36 ensure => present,
48 } 37 }
49 38
50 concat::fragment { 'tmpfile': 39 concat::fragment { 'tmpfile':
51 target => '/tmp/file', 40 target => '/tmp/file',
52 content => 'test contents', 41 content => 'test contents',
53 order => '01' 42 order => '01'
54 } 43 }
55 ``` 44 ~~~
56 45
57 ##Usage 46 <a id="usage"></a>
47 ## Usage
58 48
59 Please be aware that there have been a number of [API 49 ### Maintain a list of the major modules on a node
60 _deprecations_](#api-deprecations).
61 50
62 If you wanted a /etc/motd file that listed all the major modules 51 To maintain an motd file that lists the modules on one of your nodes, first create a class to frame up the file:
63 on the machine. And that would be maintained automatically even
64 if you just remove the include lines for other modules you could
65 use code like below, a sample /etc/motd would be:
66 52
67 <pre> 53 ~~~
68 Puppet modules on this server:
69
70 -- Apache
71 -- MySQL
72 </pre>
73
74 Local sysadmins can also append to the file by just editing /etc/motd.local
75 their changes will be incorporated into the puppet managed motd.
76
77 ```puppet
78 class motd { 54 class motd {
79 $motd = '/etc/motd' 55 $motd = '/etc/motd'
80 56
81 concat { $motd: 57 concat { $motd:
82 owner => 'root', 58 owner => 'root',
83 group => 'root', 59 group => 'root',
84 mode => '0644' 60 mode => '0644'
85 } 61 }
86 62
87 concat::fragment{ 'motd_header': 63 concat::fragment { 'motd_header':
88 target => $motd, 64 target => $motd,
89 content => "\nPuppet modules on this server:\n\n", 65 content => "\nPuppet modules on this server:\n\n",
90 order => '01' 66 order => '01'
91 } 67 }
92 68
93 # local users on the machine can append to motd by just creating 69 # let local users add to the motd by creating a file called
94 # /etc/motd.local 70 # /etc/motd.local
95 concat::fragment{ 'motd_local': 71 concat::fragment { 'motd_local':
96 target => $motd, 72 target => $motd,
97 source => '/etc/motd.local', 73 source => '/etc/motd.local',
98 order => '15' 74 order => '15'
99 } 75 }
100 } 76 }
101 77
102 # used by other modules to register themselves in the motd 78 # let other modules register themselves in the motd
103 define motd::register($content="", $order='10') { 79 define motd::register (
80 $content = "",
81 $order = '10',
82 ) {
104 if $content == "" { 83 if $content == "" {
105 $body = $name 84 $body = $name
106 } else { 85 } else {
107 $body = $content 86 $body = $content
108 } 87 }
109 88
110 concat::fragment{ "motd_fragment_$name": 89 concat::fragment { "motd_fragment_$name":
111 target => '/etc/motd', 90 target => '/etc/motd',
112 order => $order, 91 order => $order,
113 content => " -- $body\n" 92 content => " -- $body\n"
114 } 93 }
115 } 94 }
116 ``` 95 ~~~
117 96
118 To use this you'd then do something like: 97 Then, in the declarations for each module on the node, add `motd::register{ 'Apache': }` to register the module in the motd.
119 98
120 ```puppet 99 ~~~
121 class apache { 100 class apache {
122 include apache::install, apache::config, apache::service 101 include apache::install, apache::config, apache::service
123 102
124 motd::register{ 'Apache': } 103 motd::register { 'Apache': }
125 } 104 }
105 ~~~
106
107 These two steps populate the /etc/motd file with a list of the installed and registered modules, which stays updated even if you just remove the registered modules' `include` lines. System administrators can append text to the list by writing to /etc/motd.local.
108
109 When you're finished, the motd file will look something like this:
110
111 ~~~
112 Puppet modules on this server:
113
114 -- Apache
115 -- MySQL
116
117 <contents of /etc/motd.local>
118 ~~~
119
120 <a id="reference"></a>
121 ## Reference
122
123 See [REFERENCE.md](https://github.com/puppetlabs/puppetlabs-concat/blob/master/REFERENCE.md)
124
125 <a id="removed-functionality"></a>
126 ### Removed functionality
127
128 The following functionality existed in previous versions of the concat module, but was removed in version 2.0.0:
129
130 Parameters removed from `concat::fragment`:
131 * `gnu`
132 * `backup`
133 * `group`
134 * `mode`
135 * `owner`
136
137 The `concat::setup` class has also been removed.
138
139 Prior to concat version 2.0.0, if you set the `warn` parameter to a string value of `true`, `false`, 'yes', 'no', 'on', or 'off', the module translated the string to the corresponding boolean value. In concat version 2.0.0 and newer, the `warn_header` parameter treats those values the same as other strings and uses them as the content of your header message. To avoid that, pass the `true` and `false` values as booleans instead of strings.
140
141 <a id="limitations"></a>
142 ## Limitations
143
144 This module has been tested on [all PE-supported platforms](https://forge.puppetlabs.com/supported#compat-matrix), and no issues have been identified.
145
146 For an extensive list of supported operating systems, see [metadata.json](https://github.com/puppetlabs/puppetlabs-concat/blob/master/metadata.json)
147
148 ## Development
149
150 Acceptance tests for this module leverage [puppet_litmus](https://github.com/puppetlabs/puppet_litmus).
151 To run the acceptance tests follow the instructions [here](https://github.com/puppetlabs/puppet_litmus/wiki/Tutorial:-use-Litmus-to-execute-acceptance-tests-with-a-sample-module-(MoTD)#install-the-necessary-gems-for-the-module).
152 You can also find a tutorial and walkthrough of using Litmus and the PDK on [YouTube](https://www.youtube.com/watch?v=FYfR7ZEGHoE).
153
154 If you run into an issue with this module, or if you would like to request a feature, please [file a ticket](https://tickets.puppetlabs.com/browse/MODULES/).
155 Every Monday the Puppet IA Content Team has [office hours](https://puppet.com/community/office-hours) in the [Puppet Community Slack](http://slack.puppet.com/), alternating between an EMEA friendly time (1300 UTC) and an Americas friendly time (0900 Pacific, 1700 UTC).
156
157 If you have problems getting this module up and running, please [contact Support](http://puppetlabs.com/services/customer-support).
158
159 If you submit a change to this module, be sure to regenerate the reference documentation as follows:
160
161 ```bash
162 puppet strings generate --format markdown --out REFERENCE.md
126 ``` 163 ```
127 164
128 ##Reference 165 ### Contributors
129 166
130 ###Classes 167 Richard Pijnenburg ([@Richardp82](http://twitter.com/richardp82))
131 168
132 ####Public classes 169 Joshua Hoblitt ([@jhoblitt](http://twitter.com/jhoblitt))
133 170
134 ####Private classes 171 [More contributors](https://github.com/puppetlabs/puppetlabs-concat/graphs/contributors).
135 * `concat::setup`: Sets up the concat script/directories.
136
137 ###Parameters
138
139 ###Defines
140
141 ####concat
142
143 #####`ensure`
144 Controls if the combined file is present or absent.
145
146 ######Example
147 - ensure => present
148 - ensure => absent
149
150 #####`path`
151 Controls the destination of the file to create.
152
153 ######Example
154 - path => '/tmp/filename'
155
156 #####`owner`
157 Set the owner of the combined file.
158
159 ######Example
160 - owner => 'root'
161
162 #####`group`
163 Set the group of the combined file.
164
165 ######Example
166 - group => 'root'
167
168 #####`mode`
169 Set the mode of the combined file.
170
171 ######Example
172 - mode => '0644'
173
174 #####`warn`
175 Determine if a warning message should be added at the top of the file to let
176 users know it was autogenerated by Puppet. It should be a boolean or a string
177 containing the contents of the warning message.
178
179 ######Example
180 - warn => true
181 - warn => false
182 - warn => '# This file is autogenerated!'
183
184 #####`force`
185 Determine if empty files are allowed when no fragments were added.
186
187 ######Example
188 - force => true
189 - force => false
190
191 #####`backup`
192 Controls the filebucket behavior used for the file.
193
194 ######Example
195 - backup => 'puppet'
196
197 #####`replace`
198 Controls if Puppet should replace the destination file if it already exists.
199
200 ######Example
201 - replace => true
202 - replace => false
203
204 #####`order`
205 Controls the way in which the shell script chooses to sort the files. It's
206 rare you'll need to adjust this.
207
208 ######Allowed Values
209 - order => 'alpha'
210 - order => 'numeric'
211
212 #####`ensure_newline`
213 Ensure there's a newline at the end of the fragments.
214
215 ######Example
216 - ensure_newline => true
217 - ensure_newline => false
218
219 #####`validate_cmd`
220 Ensure the destination file passes the following validation command.
221 Only supported on Puppet >= 3.5.0.
222
223 ######Example
224 - validate_cmd => '/usr/sbin/apache2 -t -f %'
225 - validate_cmd => '/usr/sbin/visudo -c -f %'
226
227 ####concat::fragment
228
229 #####`target`
230 Choose the destination file of the fragment.
231
232 ######Example
233 - target => '/tmp/testfile'
234
235 #####`content`
236 Create the content of the fragment.
237
238 ######Example
239 - content => 'test file contents'
240
241 #####`source`
242 Find the sources within Puppet of the fragment.
243
244 ######Example
245 - source => 'puppet:///modules/test/testfile'
246 - source => ['puppet:///modules/test/1', 'puppet:///modules/test/2']
247
248 #####`order`
249 Order the fragments.
250
251 ######Example
252 - order => '01'
253
254 Best practice is to pass a string to this parameter but integer values are accepted.
255
256 #####`ensure`
257 Control the file of fragment created.
258
259 ######Example
260 - ensure => 'present'
261 - ensure => 'absent'
262
263 #####`mode`
264 Set the mode of the fragment.
265
266 ######Example
267 - mode => '0644'
268
269 #####`owner`
270 Set the owner of the fragment.
271
272 ######Example
273 - owner => 'root'
274
275 #####`group`
276 Set the group of the fragment.
277
278 ######Example
279 - group => 'root'
280
281 #####`backup`
282 Control the filebucket behavior for the fragment.
283
284 ######Example
285 - backup => 'puppet'
286
287 ### API _deprecations_
288
289 #### Since version `1.0.0`
290
291 ##### `concat{}` `warn` parameter
292
293 ```puppet
294 concat { '/tmp/file':
295 ensure => present,
296 warn => 'true', # generates stringified boolean value warning
297 }
298 ```
299
300 Using stringified Boolean values as the `warn` parameter to `concat` is
301 deprecated, generates a catalog compile time warning, and will be silently
302 treated as the concatenated file header/warning message in a future release.
303
304 The following strings are considered a stringified Boolean value:
305
306 * `'true'`
307 * `'yes'`
308 * `'on'`
309 * `'false'`
310 * `'no'`
311 * `'off'`
312
313 Please migrate to using the Puppet DSL's native [Boolean data
314 type](http://docs.puppetlabs.com/puppet/3/reference/lang_datatypes.html#booleans).
315
316 ##### `concat{}` `gnu` parameter
317
318 ```puppet
319 concat { '/tmp/file':
320 ensure => present,
321 gnu => $foo, # generates deprecation warning
322 }
323 ```
324
325 The `gnu` parameter to `concat` is deprecated, generates a catalog compile time
326 warning, and has no effect. This parameter will be removed in a future
327 release.
328
329 Note that this parameter was silently ignored in the `1.0.0` release.
330
331 ##### `concat::fragment{}` `ensure` parameter
332
333 ```puppet
334 concat::fragment { 'cpuinfo':
335 ensure => '/proc/cpuinfo', # generates deprecation warning
336 target => '/tmp/file',
337 }
338 ```
339
340 Passing a value other than `'present'` or `'absent'` as the `ensure` parameter
341 to `concat::fragment` is deprecated and generates a catalog compile time
342 warning. The warning will become a catalog compilation failure in a future
343 release.
344
345 This type emulates the Puppet core `file` type's disfavored [`ensure`
346 semantics](http://docs.puppetlabs.com/references/latest/type.html#file-attribute-ensure)
347 of treating a file path as a directive to create a symlink. This feature is
348 problematic in several ways. It copies an API semantic of another type that is
349 both frowned upon and not generally well known. It's behavior may be
350 surprising in that the target concatenated file will not be a symlink nor is
351 there any common file system that has a concept of a section of a plain file
352 being symbolically linked to another file. Additionally, the behavior is
353 generally inconsistent with most Puppet types in that a missing source file
354 will be silently ignored.
355
356 If you want to use the content of a file as a fragment please use the `source`
357 parameter.
358
359 ##### `concat::fragment{}` `mode/owner/group` parameters
360
361 ```puppet
362 concat::fragment { 'foo':
363 target => '/tmp/file',
364 content => 'foo',
365 mode => $mode, # generates deprecation warning
366 owner => $owner, # generates deprecation warning
367 group => $group, # generates deprecation warning
368 }
369 ```
370
371 The `mode` parameter to `concat::fragment` is deprecated, generates a catalog compile time warning, and has no effect.
372
373 The `owner` parameter to `concat::fragment` is deprecated, generates a catalog
374 compile time warning, and has no effect.
375
376 The `group` parameter to `concat::fragment` is deprecated, generates a catalog
377 compile time warning, and has no effect.
378
379 These parameters had no user visible effect in version `1.0.0` and will be
380 removed in a future release.
381
382 ##### `concat::fragment{}` `backup` parameter
383
384 ```puppet
385 concat::fragment { 'foo':
386 target => '/tmp/file',
387 content => 'foo',
388 backup => 'bar', # generates deprecation warning
389 }
390 ```
391
392 The `backup` parameter to `concat::fragment` is deprecated, generates a catalog
393 compile time warning, and has no effect. It will be removed in a future
394 release.
395
396 In the `1.0.0` release this parameter controlled file bucketing of the file
397 fragment. Bucketting the fragment(s) is redundant with bucketting the final
398 concatenated file and this feature has been removed.
399
400 ##### `class { 'concat::setup': }`
401
402 ```puppet
403 include concat::setup # generates deprecation warning
404
405 class { 'concat::setup': } # generates deprecation warning
406 ```
407
408 The `concat::setup` class is deprecated as a public API of this module and
409 should no longer be directly included in the manifest. This class may be
410 removed in a future release.
411
412 ##### Parameter validation
413
414 While not an API depreciation, users should be aware that all public parameters
415 in this module are now validated for at least variable type. This may cause
416 validation errors in a manifest that was previously silently misbehaving.
417
418 ##Limitations
419
420 This module has been tested on:
421
422 * RedHat Enterprise Linux (and Centos) 5/6
423 * Debian 6/7
424 * Ubuntu 12.04
425
426 Testing on other platforms has been light and cannot be guaranteed.
427
428 #Development
429
430 Puppet Labs modules on the Puppet Forge are open projects, and community
431 contributions are essential for keeping them great. We can’t access the
432 huge number of platforms and myriad of hardware, software, and deployment
433 configurations that Puppet is intended to serve.
434
435 We want to keep it as easy as possible to contribute changes so that our
436 modules work in your environment. There are a few guidelines that we need
437 contributors to follow so that we can have a chance of keeping on top of things.
438
439 You can read the complete module contribution guide [on the Puppet Labs wiki.](http://projects.puppetlabs.com/projects/module-site/wiki/Module_contributing)
440
441 ###Contributors
442
443 The list of contributors can be found at:
444
445 https://github.com/puppetlabs/puppetlabs-concat/graphs/contributors