Skip to content

Commit

Permalink
Merge pull request redhat-openstack#180 from jbondpdx/1.4.x
Browse files Browse the repository at this point in the history 
Edits to new Function: `create_ini_settings` in README
  • Loading branch information
@hunner
hunner committed Jul 27, 2015
2 parents f72730d + d9b4c36 commit 43f0c68
Showing 1 changed file with 137 additions and 136 deletions.
273 changes: 137 additions & 136 deletions README.markdown
View file
Original file line number Diff line number Diff line change
Expand Up @@ -25,10 +25,9 @@ Many applications use INI-style configuration files to store their settings. Thi

###Beginning with inifile


To manage a single setting in an INI file, add the `ini_setting` type to a class:

~~~
~~~puppet
ini_setting { "sample setting":
ensure => present,
path => '/tmp/foo.ini',
Expand All @@ -51,9 +50,12 @@ The inifile module tries hard not to manipulate your file any more than it needs

Use the `ini_subsetting` type:

~~~puppet
JAVA_ARGS="-Xmx512m -XX:+HeapDumpOnOutOfMemoryError -XX:HeapDumpPath=/var/log/pe-puppetdb/puppetdb-oom.hprof"
~~~
JAVA_ARGS="-Xmx192m -XX:+HeapDumpOnOutOfMemoryError -XX:HeapDumpPath=/var/log/pe-puppetdb/puppetdb-oom.hprof "


~~~puppet
ini_subsetting {'sample subsetting':
ensure => present,
section => '',
Expand All @@ -67,11 +69,12 @@ ini_subsetting {'sample subsetting':

###Use a non-standard section header

~~~
~~~puppet
default:
minage = 1
maxage = 13
~~~

~~~puppet
ini_setting { 'default minage':
ensure => present,
path => '/etc/security/users',
Expand All @@ -85,7 +88,6 @@ ini_setting { 'default minage':

###Implement child providers


You might want to create child providers that inherit the `ini_setting` provider, for one or both of these purposes:

* Make a custom resource to manage an application that stores its settings in INI files, without recreating the code to manage the files themselves.
Expand All @@ -94,7 +96,7 @@ You might want to create child providers that inherit the `ini_setting` provider

To implement child providers, first specify a custom type. Have it implement a namevar called `name` and a property called `value`:

~~~
~~~ruby
#my_module/lib/puppet/type/glance_api_config.rb
Puppet::Type.newtype(:glance_api_config) do
ensurable
Expand All @@ -114,7 +116,7 @@ end

Your type also needs a provider that uses the `ini_setting` provider as its parent:

~~~
~~~ruby
# my_module/lib/puppet/provider/glance_api_config/ini_setting.rb
Puppet::Type.type(:glance_api_config).provide(
:ini_setting,
Expand All @@ -138,20 +140,128 @@ end

Now the settings in /etc/glance/glance-api.conf file can be managed as individual resources:

~~~
~~~puppet
glance_api_config { 'HEADER/important_config':
value => 'secret_value',
}
~~~

If you've implemented self.file_path, you can have Puppet purge the file of all lines that aren't implemented as Puppet resources:

~~~
~~~puppet
resources { 'glance_api_config'
purge => true,
}
~~~

### Manage multiple ini_settings

To manage multiple ini_settings, use the [`create_ini_settings`](#function-create_ini_settings) function.

~~~puppet
$defaults = { 'path' => '/tmp/foo.ini' }
$example = { 'section1' => { 'setting1' => 'value1' } }
create_ini_settings($example, $defaults)
~~~

results in:

~~~puppet
ini_setting { '[section1] setting1':
ensure => present,
section => 'section1',
setting => 'setting1',
value => 'value1',
path => '/tmp/foo.ini',
}
~~~

To include special parameters, the following code:

~~~puppet
$defaults = { 'path' => '/tmp/foo.ini' }
$example = {
'section1' => {
'setting1' => 'value1',
'settings2' => {
'ensure' => 'absent'
}
}
}
create_ini_settings($example, $defaults)
~~~

results in:

~~~puppet
ini_setting { '[section1] setting1':
ensure => present,
section => 'section1',
setting => 'setting1',
value => 'value1',
path => '/tmp/foo.ini',
}
ini_setting { '[section1] setting2':
ensure => absent,
section => 'section1',
setting => 'setting2',
path => '/tmp/foo.ini',
}
~~~

#### Manage multiple ini_settings with Hiera

This example requires Puppet 3.x/4.x, as it uses automatic retrieval of Hiera data for class parameters and `puppetlabs/stdlib`.

For the profile `example`:

~~~puppet
class profile::example (
$settings,
) {
validate_hash($settings)
$defaults = { 'path' => '/tmp/foo.ini' }
create_ini_settings($settings, $defaults)
}
~~~

Provide this in your Hiera data:

~~~puppet
profile::example::settings:
section1:
setting1: value1
setting2: value2
setting3:
ensure: absent
~~~

Results in:

~~~puppet
ini_setting { '[section1] setting1':
ensure => present,
section => 'section1',
setting => 'setting1',
value => 'value1',
path => '/tmp/foo.ini',
}
ini_setting { '[section1] setting2':
ensure => present,
section => 'section1',
setting => 'setting2',
value => 'value2',
path => '/tmp/foo.ini',
}
ini_setting { '[section1] setting3':
ensure => absent,
section => 'section1',
setting => 'setting3',
path => '/tmp/foo.ini',
}
~~~


##Reference

###Public Types
Expand All @@ -164,9 +274,6 @@ resources { 'glance_api_config'

* [`create_ini_settings`](#function-create_ini_settings)




### Type: ini_setting

Manages a setting within an INI file.
Expand Down Expand Up @@ -207,12 +314,9 @@ Determines whether the specified setting should exist. Valid options: 'present'

##### `section_suffix`

*Optional.* Designates the string that will appear after the section's name. Default value: "]"

**NOTE:** The way this type finds all sections in the file is by looking for lines like `${section_prefix}${title}${section_suffix}`


*Optional.* Designates the string that will appear after the section's name. Default value: "]".

**NOTE:** This type finds all sections in the file by looking for lines like `${section_prefix}${title}${section_suffix}`.

### Type: ini_subsetting

Expand Down Expand Up @@ -248,7 +352,6 @@ Specifies whether the subsetting should be present. Valid options: 'present' and

*Required.* Designates a subsetting to manage within the specified setting. Valid options: a string.


##### `subsetting_separator`

*Optional.* Specifies a string to use between subsettings. Valid options: a string. Default value: " ".
Expand All @@ -257,142 +360,40 @@ Specifies whether the subsetting should be present. Valid options: 'present' and

*Optional.* Supplies a value for the specified subsetting. Valid options: a string. Default value: undefined.




### Function: create_ini_settings

`create_ini_settings($settings, $defaults)`
Manages multiple `ini_setting` resources from a hash. Note that this cannot be used with ini_subsettings.

Manage multiple ini_setting resources from a hash with comfort. You can provide a hash in your manifest and feed it from Hiera. This can however not be used with ini_subsettings!
`create_ini_settings($settings, $defaults)`

#### Parameters
#### Arguments

##### `$settings`
##### First argument: `settings`

*Required.* Specify a hash with the ini_setting resources.
*Required.* Specify a hash representing the `ini_setting` resources you want to create.

###### Example
~~~
defaults = { 'path' => '/tmp/foo.ini' }
$example = { 'section1' => { 'setting1' => 'value1' } }
create_ini_settings($example, $defaults)
~~~
results in a resource
~~~
ini_setting { '[section1] setting1':
ensure => present,
section => 'section1',
setting => 'setting1',
value => 'value1',
path => '/tmp/foo.ini'
}
~~~
##### Second argument: `defaults`

###### Example with special parameters
~~~
defaults = { 'path' => '/tmp/foo.ini' }
$example = { 'section1' => {
'setting1' => 'value1',
'settings2' => {
'ensure' => 'absent'
}
}
}
create_ini_settings($example, $defaults)
~~~
results in resources
~~~
ini_setting { '[section1] setting1':
ensure => present,
section => 'section1',
setting => 'setting1',
value => 'value1',
path => '/tmp/foo.ini',
}
ini_setting { '[section1] setting2':
ensure => absent,
section => 'section1',
setting => 'setting2',
path => '/tmp/foo.ini',
*Optional.* Accepts a hash to be used as the values for any attributes not defined in the first argument.

~~~puppet
$example = {
'section1' => {
'setting1' => {
'value' => 'value1', 'path' => '/tmp/foo.ini'
}
}
}
~~~

##### `$defaults`

*Optional, but recommended.*

This works exactly like `create_resources` defaults parameter. Use it to not repeat yourself to often
and write settings more densely. Example usage see parameter `$settings` above.

If you omit this parameter, you will need to add the `path` and `value` attribute to every single setting as a hash
(`$example = { 'section1' => { 'setting1' => { 'value' => 'value1', 'path' => '/tmp/foo.ini' } } }`).
This most certainly is not what you want, but if you need it it's there.

Default value: '{}'.

#### Example with Hiera
This example will need Puppet 3.x/4.x as it uses automatic retrieval of Hiera data for class parameters and
`puppetlabs/stdlib` (you use that one already, don't you?).

Of course you may use `hiera_hash` when on Puppet 2.x or other use cases. Remember this is only one example,
feel free to live your creativity on writing manifests.

Imagine a profile `example`:
~~~
class profile::example (
$settings,
) {
validate_hash($settings)
$defaults = { 'path' => '/tmp/foo.ini' }
create_ini_settings($settings, $defaults)
}
~~~

Now provide this in your Hiera data:
~~~
profile::example::settings:
section1:
setting1: value1
setting2: value2
setting3:
ensure: absent
~~~

This will result in resources:
~~~
ini_setting { '[section1] setting1':
ensure => present,
section => 'section1',
setting => 'setting1',
value => 'value1',
path => '/tmp/foo.ini',
}
ini_setting { '[section1] setting2':
ensure => present,
section => 'section1',
setting => 'setting2',
value => 'value2',
path => '/tmp/foo.ini',
}
ini_setting { '[section1] setting3':
ensure => absent,
section => 'section1',
setting => 'setting3',
path => '/tmp/foo.ini',
}
~~~



##Limitations

This module has been tested on [all PE-supported platforms](https://forge.puppetlabs.com/supported#compat-matrix), and no issues have been identified. Additionally, it is tested (but not supported) on Windows 7, Mac OS X 10.9, and Solaris 12.

##Development

#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.
Expand Down

0 comments on commit 43f0c68

Please sign in to comment.