Merge pull request #114 from apenney/docs-change
Rewrite the docs to fit the current best practices for Puppetlabs
This commit is contained in:
Ashley Penney
commit
46afc2fda5
1 changed files with 340 additions and 63 deletions
403
README.md
403
README.md
|
|
@ -1,17 +1,63 @@
|
|||
What is it?
|
||||
===========
|
||||
#Concat
|
||||
|
||||
[](https://travis-ci.org/puppetlabs/puppetlabs-concat)
|
||||
|
||||
####Table of Contents
|
||||
|
||||
A Puppet module that can construct files from fragments.
|
||||
1. [Overview](#overview)
|
||||
2. [Module Description - What the module does and why it is useful](#module-description)
|
||||
3. [Setup - The basics of getting started with concat](#setup)
|
||||
* [What concat affects](#what-concat-affects)
|
||||
* [Setup requirements](#setup-requirements)
|
||||
* [Beginning with concat](#beginning-with-concat)
|
||||
4. [Usage - Configuration options and additional functionality](#usage)
|
||||
* [API _deprecations_](#api-deprecations)
|
||||
5. [Reference - An under-the-hood peek at what the module is doing and how](#reference)
|
||||
5. [Limitations - OS compatibility, etc.](#limitations)
|
||||
6. [Development - Guide for contributing to the module](#development)
|
||||
|
||||
Please see the comments in the various .pp files for details
|
||||
as well as posts on my blog at http://www.devco.net/
|
||||
##Overview
|
||||
|
||||
Released under the Apache 2.0 licence
|
||||
This module constructs files from multiple fragments in an ordered way.
|
||||
|
||||
Usage:
|
||||
------
|
||||
##Module Description
|
||||
|
||||
This module lets you use many concat::fragment{} resources throughout
|
||||
your modules to construct a single file at the end. It does this through
|
||||
a shell (or ruby) script and a temporary holding space for the fragments.
|
||||
|
||||
##Setup
|
||||
|
||||
###What concat affects
|
||||
|
||||
* Installs concatfragments.[sh|rb] based on platform.
|
||||
* Adds a concat/ directory into Puppets `vardir`.
|
||||
|
||||
###Beginning with concat
|
||||
|
||||
To start using concat you need to create:
|
||||
|
||||
* A concat{} resource for the final file.
|
||||
* One or more concat::fragment{}'s.
|
||||
|
||||
A minimal example might be:
|
||||
|
||||
```puppet
|
||||
concat { '/tmp/file':
|
||||
ensure => present,
|
||||
}
|
||||
|
||||
concat::fragment { 'tmpfile':
|
||||
target => '/tmp/file'
|
||||
content => 'test contents',
|
||||
order => '01'
|
||||
}
|
||||
```
|
||||
|
||||
##Usage
|
||||
|
||||
Please be aware that there have been a number of [API
|
||||
_deprecations_](#api-deprecations).
|
||||
|
||||
If you wanted a /etc/motd file that listed all the major modules
|
||||
on the machine. And that would be maintained automatically even
|
||||
|
|
@ -29,7 +75,6 @@ Local sysadmins can also append to the file by just editing /etc/motd.local
|
|||
their changes will be incorporated into the puppet managed motd.
|
||||
|
||||
```puppet
|
||||
# class to setup basic motd, include on all nodes
|
||||
class motd {
|
||||
$motd = '/etc/motd'
|
||||
|
||||
|
|
@ -67,8 +112,11 @@ define motd::register($content="", $order=10) {
|
|||
content => " -- $body\n"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
# a sample apache module
|
||||
To use this you'd then do something like:
|
||||
|
||||
```puppet
|
||||
class apache {
|
||||
include apache::install, apache::config, apache::service
|
||||
|
||||
|
|
@ -76,88 +124,317 @@ class apache {
|
|||
}
|
||||
```
|
||||
|
||||
Detailed documentation of the class options can be found in the
|
||||
manifest files.
|
||||
##Reference
|
||||
|
||||
Known Issues:
|
||||
-------------
|
||||
* Since puppet-concat now relies on a fact for the concat directory,
|
||||
you will need to set up pluginsync = true on both the master and client
|
||||
node's '/etc/puppet/puppet.conf' for at least the first run.
|
||||
You have this issue if puppet fails to run on the client and you have
|
||||
a message similar to
|
||||
"err: Failed to apply catalog: Parameter path failed: File
|
||||
paths must be fully qualified, not 'undef' at [...]/concat/manifests/setup.pp:44".
|
||||
###Classes
|
||||
|
||||
Contributors:
|
||||
-------------
|
||||
**Paul Elliot**
|
||||
####Public classes
|
||||
|
||||
* Provided 0.24.8 support, shell warnings and empty file creation support.
|
||||
####Private classes
|
||||
* `concat::setup`: Sets up the concat script/directories.
|
||||
|
||||
**Chad Netzer**
|
||||
###Parameters
|
||||
|
||||
* Various patches to improve safety of file operations
|
||||
* Symlink support
|
||||
###Defines
|
||||
|
||||
**David Schmitt**
|
||||
####concat
|
||||
|
||||
* Patch to remove hard coded paths relying on OS path
|
||||
* Patch to use file{} to copy the resulting file to the final destination. This means Puppet client will show diffs and that hopefully we can change file ownerships now
|
||||
#####`ensure`
|
||||
Controls if the combined file is present or absent.
|
||||
|
||||
**Peter Meier**
|
||||
######Example
|
||||
- ensure => present
|
||||
- ensure => absent
|
||||
|
||||
* Basedir as a fact
|
||||
* Unprivileged user support
|
||||
#####`path`
|
||||
Controls the destination of the file to create.
|
||||
|
||||
**Sharif Nassar**
|
||||
######Example
|
||||
- path => '/tmp/filename'
|
||||
|
||||
* Solaris/Nexenta support
|
||||
* Better error reporting
|
||||
#####`owner`
|
||||
Set the owner of the combined file.
|
||||
|
||||
**Christian G. Warden**
|
||||
######Example
|
||||
- owner => 'root'
|
||||
|
||||
* Style improvements
|
||||
#####`group`
|
||||
Set the group of the combined file.
|
||||
|
||||
**Reid Vandewiele**
|
||||
######Example
|
||||
- group => 'root'
|
||||
|
||||
* Support non GNU systems by default
|
||||
#####`mode`
|
||||
Set the mode of the combined file.
|
||||
|
||||
**Erik Dalén**
|
||||
######Example
|
||||
- mode => '0644'
|
||||
|
||||
* Style improvements
|
||||
#####`warn`
|
||||
Determine if a warning message should be added at the top of the file to let
|
||||
users know it was autogenerated by Puppet.
|
||||
|
||||
**Gildas Le Nadan**
|
||||
######Example
|
||||
- warn => true
|
||||
- warn => false
|
||||
|
||||
* Documentation improvements
|
||||
#####`warn_message`
|
||||
Set the contents of the warning message.
|
||||
|
||||
**Paul Belanger**
|
||||
######Example
|
||||
- warn_message => 'This file is autogenerated!'
|
||||
|
||||
* Testing improvements and Travis support
|
||||
#####`force`
|
||||
Determine if empty files are allowed when no fragments were added.
|
||||
|
||||
**Branan Purvine-Riley**
|
||||
######Example
|
||||
- force => true
|
||||
- force => false
|
||||
|
||||
* Support Puppet Module Tool better
|
||||
#####`backup`
|
||||
Controls the filebucket behavior used for the file.
|
||||
|
||||
**Dustin J. Mitchell**
|
||||
######Example
|
||||
- backup => 'puppet'
|
||||
|
||||
* Always include setup when using the concat define
|
||||
#####`replace`
|
||||
Controls if Puppet should replace the destination file if it already exists.
|
||||
|
||||
**Andreas Jaggi**
|
||||
######Example
|
||||
- replace => true
|
||||
- replace => false
|
||||
|
||||
* Puppet Lint support
|
||||
#####`order`
|
||||
Controls the way in which the shell script chooses to sort the files. It's
|
||||
rare you'll need to adjust this.
|
||||
|
||||
**Jan Vansteenkiste**
|
||||
######Allowed Values
|
||||
- order => 'alpha'
|
||||
- order => 'numeric'
|
||||
|
||||
* Configurable paths
|
||||
#####`ensure_newline`
|
||||
Ensure there's a newline at the end of the fragments.
|
||||
|
||||
**Joshua Hoblitt**
|
||||
######Example
|
||||
- ensure_newline => true
|
||||
- ensure_newline => false
|
||||
|
||||
* Remove requirement to manually include `concat::setup` in the manifest
|
||||
* Style improvements
|
||||
* Parameter validation / refactor parameter handling
|
||||
* Test coverage
|
||||
####concat::fragment
|
||||
|
||||
Contact:
|
||||
--------
|
||||
puppet-users@ mailing list.
|
||||
#####`target`
|
||||
Choose the destination file of the fragment.
|
||||
|
||||
######Example
|
||||
- target => '/tmp/testfile'
|
||||
|
||||
#####`content`
|
||||
Create the content of the fragment.
|
||||
|
||||
######Example
|
||||
- content => 'test file contents'
|
||||
|
||||
#####`source`
|
||||
Find the sources within Puppet of the fragment.
|
||||
|
||||
######Example
|
||||
- source => 'puppet:///modules/test/testfile'
|
||||
- source => ['puppet:///modules/test/1', 'puppet:///modules/test/2']
|
||||
|
||||
#####`order`
|
||||
Order the fragments.
|
||||
|
||||
######Example
|
||||
- order => '01'
|
||||
|
||||
#####`ensure`
|
||||
Control the file of fragment created.
|
||||
|
||||
######Example
|
||||
- ensure => 'present'
|
||||
- ensure => 'absent'
|
||||
- ensure => 'file'
|
||||
- ensure => 'directory'
|
||||
|
||||
#####`mode`
|
||||
Set the mode of the fragment.
|
||||
|
||||
######Example
|
||||
- mode => '0644'
|
||||
|
||||
#####`owner`
|
||||
Set the owner of the fragment.
|
||||
|
||||
######Example
|
||||
- owner => 'root'
|
||||
|
||||
#####`group`
|
||||
Set the group of the fragment.
|
||||
|
||||
######Example
|
||||
- group => 'root'
|
||||
|
||||
#####`backup`
|
||||
Control the filebucket behavior for the fragment.
|
||||
|
||||
######Example
|
||||
- backup => 'puppet'
|
||||
|
||||
### API _deprecations_
|
||||
|
||||
#### Since version `1.0.0`
|
||||
|
||||
##### `concat{}` `warn` parameter
|
||||
|
||||
```puppet
|
||||
concat { '/tmp/file':
|
||||
ensure => present,
|
||||
warn => 'true', # generates stringified boolean value warning
|
||||
}
|
||||
```
|
||||
|
||||
Using stringified Boolean values as the `warn` parameter to `concat` is
|
||||
deprecated, generates a catalog compile time warning, and will be silently
|
||||
treated as the concatenated file header/warning message in a future release.
|
||||
|
||||
The following strings are considered a stringified Boolean value:
|
||||
|
||||
* `'true'`
|
||||
* `'yes'`
|
||||
* `'on'`
|
||||
* `'false'`
|
||||
* `'no'`
|
||||
* `'off'`
|
||||
|
||||
Please migrate to using the Puppet DSL's native [Boolean data
|
||||
type](http://docs.puppetlabs.com/puppet/3/reference/lang_datatypes.html#booleans).
|
||||
|
||||
##### `concat{}` `gnu` parameter
|
||||
|
||||
```puppet
|
||||
concat { '/tmp/file':
|
||||
ensure => present,
|
||||
gnu => $foo, # generates deprecation warning
|
||||
}
|
||||
```
|
||||
|
||||
The `gnu` parameter to `concat` is deprecated, generates a catalog compile time
|
||||
warning, and has no effect. This parameter will be removed in a future
|
||||
release.
|
||||
|
||||
Note that this parameter was silently ignored in the `1.0.0` release.
|
||||
|
||||
##### `concat::fragment{}` `ensure` parameter
|
||||
|
||||
```puppet
|
||||
concat::fragment { 'cpuinfo':
|
||||
ensure => '/proc/cpuinfo', # generates deprecation warning
|
||||
target => '/tmp/file',
|
||||
}
|
||||
```
|
||||
|
||||
Passing a value other than `'present'` or `'absent'` as the `ensure` parameter
|
||||
to `concat::fragment` is deprecated and generates a catalog compile time
|
||||
warning. The warning will become a catalog compilation failure in a future
|
||||
release.
|
||||
|
||||
This type emulates the Puppet core `file` type's disfavored [`ensure`
|
||||
semantics](http://docs.puppetlabs.com/references/latest/type.html#file-attribute-ensure)
|
||||
of treating a file path as a directive to create a symlink. This feature is
|
||||
problematic in several ways. It copies an API semantic of another type that is
|
||||
both frowned upon and not generally well known. It's behavior may be
|
||||
surprising in that the target concatenated file will not be a symlink nor is
|
||||
there any common file system that has a concept of a section of a plain file
|
||||
being symbolically linked to another file. Additionally, the behavior is
|
||||
generally inconsistent with most Puppet types in that a missing source file
|
||||
will be silently ignored.
|
||||
|
||||
If you want to use the content of a file as a fragment please use the `source`
|
||||
parameter.
|
||||
|
||||
##### `concat::fragment{}` `mode/owner/group` parameters
|
||||
|
||||
```puppet
|
||||
concat::fragment { 'foo':
|
||||
target => '/tmp/file',
|
||||
content => 'foo',
|
||||
mode => $mode, # generates deprecation warning
|
||||
owner => $owner, # generates deprecation warning
|
||||
group => $group, # generates deprecation warning
|
||||
}
|
||||
```
|
||||
|
||||
The `mode` parameter to `concat::fragment` is deprecated, generates a catalog compile time warning, and has no effect.
|
||||
|
||||
The `owner` parameter to `concat::fragment` is deprecated, generates a catalog
|
||||
compile time warning, and has no effect.
|
||||
|
||||
The `group` parameter to `concat::fragment` is deprecated, generates a catalog
|
||||
compile time warning, and has no effect.
|
||||
|
||||
These parameters had no user visible effect in version `1.0.0` and will be
|
||||
removed in a future release.
|
||||
|
||||
##### `concat::fragment{}` `backup` parameter
|
||||
|
||||
```puppet
|
||||
concat::fragment { 'foo':
|
||||
target => '/tmp/file',
|
||||
content => 'foo',
|
||||
backup => 'bar', # generates deprecation warning
|
||||
}
|
||||
```
|
||||
|
||||
The `backup` parameter to `concat::fragment` is deprecated, generates a catalog
|
||||
compile time warning, and has no effect. It will be removed in a future
|
||||
release.
|
||||
|
||||
In the `1.0.0` release this parameter controlled file bucketing of the file
|
||||
fragment. Bucketting the fragment(s) is redundant with bucketting the final
|
||||
concatenated file and this feature has been removed.
|
||||
|
||||
##### `class { 'concat::setup': }`
|
||||
|
||||
```puppet
|
||||
include concat::setup # generates deprecation warning
|
||||
|
||||
class { 'concat::setup: } # generates deprecation warning
|
||||
```
|
||||
|
||||
The `concat::setup` class is deprecated as a public API of this module and
|
||||
should no longer be directly included in the manifest. This class may be
|
||||
removed in a future release.
|
||||
|
||||
##### Parameter validation
|
||||
|
||||
While not an API depreciation, users should be aware that all public parameters
|
||||
in this module are now validated for at least variable type. This may cause
|
||||
validation errors in a manifest that was previously silently misbehaving.
|
||||
|
||||
##Limitations
|
||||
|
||||
This module has been tested on:
|
||||
|
||||
* RedHat Enterprise Linux (and Centos) 5/6
|
||||
* Debian 6/7
|
||||
* Ubuntu 12.04
|
||||
|
||||
Testing on other platforms has been light and cannot be guaranteed.
|
||||
|
||||
#Development
|
||||
|
||||
Puppet Labs modules on the Puppet Forge are open projects, and community
|
||||
contributions are essential for keeping them great. We can’t access the
|
||||
huge number of platforms and myriad of hardware, software, and deployment
|
||||
configurations that Puppet is intended to serve.
|
||||
|
||||
We want to keep it as easy as possible to contribute changes so that our
|
||||
modules work in your environment. There are a few guidelines that we need
|
||||
contributors to follow so that we can have a chance of keeping on top of things.
|
||||
|
||||
You can read the complete module contribution guide [on the Puppet Labs wiki.](http://projects.puppetlabs.com/projects/module-site/wiki/Module_contributing)
|
||||
|
||||
###Contributors
|
||||
|
||||
The list of contributors can be found at:
|
||||
|
||||
https://github.com/puppetlabs/puppetlabs-concat/graphs/contributors
|
||||
|
|
|
|||
Loading…
Reference in a new issue