Skip to content

Commit

Permalink
(FM-7341) - Added REFERENCE.md and updated documentation
Browse files Browse the repository at this point in the history
  • Loading branch information
@eimlav
eimlav committed Nov 29, 2018
1 parent 1df764b commit e66b9cf
Show file tree
Hide file tree
Showing 6 changed files with 618 additions and 424 deletions.
342 changes: 1 addition & 341 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -9,8 +9,6 @@
* [Beginning with concat](#beginning-with-concat)
4. [Usage - Configuration options and additional functionality](#usage)
5. [Reference - An under-the-hood peek at what the module is doing and how](#reference)
* [Defines](#defines)
* [Parameters](#parameters)
* [Removed functionality](#removed-functionality)
6. [Limitations - OS compatibility, etc.](#limitations)
7. [Development - Guide for contributing to the module](#development)
Expand Down Expand Up @@ -116,345 +114,7 @@ When you're finished, the motd file will look something like this:

## Reference

### Defines
* `concat`: Manages a file, compiled from one or more text fragments.
* `concat::fragment`: Manages a fragment of text to be compiled into a file.

### Types
* `concat_file`: Generates a file with content from fragments sharing a common unique tag.
* `concat_fragment`: Manages the fragment.

### Parameters

#### Define: `concat`

All the parameters listed below are optional.

##### `backup`

Data type: Boolean, String.

Specifies whether (and how) to back up the destination file before overwriting it. Your value gets passed on to Puppet's [native `file` resource](https://docs.puppetlabs.com/references/latest/type.html#file-attribute-backup) for execution. Valid options: `true`, `false`, or a string representing either a target filebucket or a filename extension beginning with ".".

Default value: 'puppet'.

##### `ensure`

Data type: String.

Specifies whether the destination file should exist. Setting to 'absent' tells Puppet to delete the destination file if it exists, and negates the effect of any other parameters. Valid options: 'present' and 'absent'.

Default value: 'present'.

##### `ensure_newline`

Data type: Boolean.

Specifies whether to add a line break at the end of each fragment that doesn't already end in one. Valid options: `true` and `false`.

Default value: `false`.

##### `group`

Optional.

Data type: String, Integer.

Specifies a permissions group for the destination file. Valid options: a string containing a group name.

Default value: `undef`.

##### `mode`

Data type: String.

Specifies the permissions mode of the destination file. Valid options: a string containing a permission mode value in octal notation.

Default value: '0644'.

##### `order`

Data type: String.

Specifies a method for sorting your fragments by name within the destination file. Valid options: 'alpha' (e.g., '1, 10, 2') or 'numeric' (e.g., '1, 2, 10').

You can override this setting for individual fragments by adjusting the `order` parameter in their `concat::fragment` declarations.

Default value: 'alpha'.

##### `owner`

Optional.

Data type: String, Integer.

Specifies the owner of the destination file. Valid options: a string containing a username.

Default value: `undef`.

##### `path`

Data type: Stdlib::AbsolutePath.

Specifies a destination file for the combined fragments. Valid options: a string containing an absolute path.

Default value: `namevar`

##### `replace`

Data type: Boolean.

Specifies whether to overwrite the destination file if it already exists. Valid options: `true` and `false`.

Default value: `true`.

##### `show_diff`

Data type: Boolean.

Specifies whether to set the show_diff parameter for the file resource. Useful for hiding secrets stored in hiera from insecure reporting methods. Valid options: `true` and `false`.

Default value: `true`.

##### `validate_cmd`

Optional.

Data type: String.

Specifies a validation command to apply to the destination file. Requires Puppet version 3.5 or newer. Valid options: a string to be passed to a file resource.

Default value: `undef`.

##### `warn`

Data type: Boolean, String.

Specifies whether to add a header message at the top of the destination file. Valid options: the booleans `true` and `false`, or a string to serve as the header.

If you set 'warn' to `true`, `concat` adds the following line with an `order` of `0`:

Default value: `false`.

~~~
# This file is managed by Puppet. DO NOT EDIT.
~~~

Before 2.0.0, this parameter would add a newline at the end of the warn
message. To improve flexibilty, this was removed. Please add it explicitly if
you need it.

##### `selinux_ignore_defaults`

See the `file` type's
[`selinux_ignore_defaults`](https://docs.puppetlabs.com/references/latest/type.html#file-attribute-selinux_ignore_defaults)
documentention.

##### `selrange`

See the `file` type's
[`selrange`](https://docs.puppetlabs.com/references/latest/type.html#file-attribute-selrange)
documentention.

##### `selrole`

See the `file` type's
[`selrole`](https://docs.puppetlabs.com/references/latest/type.html#file-attribute-selrole)
documentention.

##### `seltype`

See the `file` type's
[`seltype`](https://docs.puppetlabs.com/references/latest/type.html#file-attribute-seltype)
documentention.

##### `seluser`

See the `file` type's
[`seluser`](https://docs.puppetlabs.com/references/latest/type.html#file-attribute-seluser)
documentention.


#### Define: `concat::fragment`

Except where noted, all the below parameters are optional.

##### `content`

Data type: String.

Supplies the content of the fragment. **Note**: You must supply either a `content` parameter or a `source` parameter. Valid options: a string.

Default value: `undef`.

##### `order`

Data type: String, Integer.

Reorders your fragments within the destination file. Fragments that share the same order number are ordered by name. Valid options: a string (recommended) or an integer.

Default value: '10'.

##### `source`

Data type: String, Array.

Specifies a file to read into the content of the fragment. **Note**: You must supply either a `content` parameter or a `source` parameter. Valid options: a string or an array, containing one or more Puppet URLs.

Default value: `undef`.

##### `target`

*Required.*

Data type: String.

Specifies the destination file of the fragment. Valid options: a string containing the path or title of the parent `concat` resource.


#### Type: `concat_file`

##### `backup`

Data type: String, Boolean.

Specifies whether (and how) to back up the destination file before overwriting it. Your value gets passed on to Puppet's [native `file` resource](https://docs.puppetlabs.com/references/latest/type.html#file-attribute-backup) for execution. Valid options: `true`, `false`, or a string representing either a target filebucket or a filename extension beginning with ".".

Default value: 'puppet'.

##### `ensure`

Data type: String.

Specifies whether the destination file should exist. Setting to 'absent' tells Puppet to delete the destination file if it exists, and negates the effect of any other parameters. Valid options: 'present' and 'absent'.

Default value: 'present'.

##### `ensure_newline`

Data type: Boolean.

Specifies whether to add a line break at the end of each fragment that doesn't already end in one. Valid options: `true` and `false`.

Default value: `false`.

##### `group`

Data type: String, Integer.

Specifies a permissions group for the destination file. Valid options: a string containing a group name.

Default value: `undef`.

##### `mode`

Data type: String.

Specifies the permissions mode of the destination file. Valid options: a string containing a permission mode value in octal notation.

Default value: '0644'.

##### `order`

Data type: String.

Specifies a method for sorting your fragments by name within the destination file. Valid options: 'alpha' (e.g., '1, 10, 2') or 'numeric' (e.g., '1, 2, 10').

You can override this setting for individual fragments by adjusting the `order` parameter in their `concat::fragment` declarations.

Default value: 'numeric'.

##### `owner`

Data type: String, Integer.

Specifies the owner of the destination file. Valid options: a string containing a username.

Default value: `undef`.

##### `path`

Data type: String.

Specifies a destination file for the combined fragments. Valid options: a string containing an absolute path. Default value: the title of your declared resource.

Default value: `namevar`.

##### `replace`

Data type: Boolean.

Specifies whether to overwrite the destination file if it already exists. Valid options: `true` and `false`.

Default value: `true`.

##### `tag`

Data type: String.

*Required.* Specifies a unique tag reference to collect all concat_fragments with the same tag.

##### `validate_cmd`

Data type: String

Specifies a validation command to apply to the destination file. Requires Puppet version 3.5 or newer. Valid options: a string to be passed to a file resource.

Default value: `undef`.

##### `format`

Data type: String

Specify what data type to merge the fragments as. Valid options: 'plain', 'yaml', 'json', 'json-array', 'json-pretty', 'json-array-pretty'.

Default value: `plain`.

##### `force`

Data type: Boolean

Specifies whether to merge data structures, keeping the values with higher order. Valid options: `true` and `false`.

Default value: `false`.

#### Type: `concat_fragment`

##### `content`

Data type: String.

Supplies the content of the fragment. **Note**: You must supply either a `content` parameter or a `source` parameter. Valid options: a string.

Default value: `undef`.

##### `order`

Data type: String, Integer.

Reorders your fragments within the destination file. Fragments that share the same order number are ordered by name. Valid options: a string (recommended) or an integer.

Default value: '10'.

##### `source`

Data type: String.

Specifies a file to read into the content of the fragment. **Note**: You must supply either a `content` parameter or a `source` parameter. Valid options: a string or an array, containing one or more Puppet URLs.

Default value: `undef`.

##### `tag`

Data type: String.

*Required.* Specifies a unique tag to be used by concat_file to reference and collect content.

##### `target`

Data type: String.

*Required.* Specifies the destination file of the fragment. Valid options: a string containing the path or title of the parent `concat_file` resource.
See [REFERENCE.md](https://github.com/puppetlabs/puppetlabs-concat/blob/master/REFERENCE.md)

### Removed functionality

Expand Down
Loading

0 comments on commit e66b9cf

Please sign in to comment.