Merge pull request #180 from jbondpdx/1.4.x
Edits to new Function: `create_ini_settings` in README
This commit is contained in:
Hunter Haugen
commit
43f0c68631
1 changed files with 137 additions and 136 deletions
267
README.markdown
267
README.markdown
|
|
@ -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',
|
||||
|
|
@ -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 => '',
|
||||
|
|
@ -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',
|
||||
|
|
@ -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.
|
||||
|
|
@ -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
|
||||
|
|
@ -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,
|
||||
|
|
@ -138,7 +140,7 @@ 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',
|
||||
}
|
||||
|
|
@ -146,12 +148,120 @@ glance_api_config { 'HEADER/important_config':
|
|||
|
||||
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
|
||||
|
|
@ -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.
|
||||
|
|
@ -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
|
||||
|
||||
|
|
@ -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: " ".
|
||||
|
|
@ -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
|
||||
|
||||
Manages multiple `ini_setting` resources from a hash. Note that this cannot be used with ini_subsettings.
|
||||
|
||||
`create_ini_settings($settings, $defaults)`
|
||||
|
||||
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!
|
||||
#### Arguments
|
||||
|
||||
#### Parameters
|
||||
##### First argument: `settings`
|
||||
|
||||
##### `$settings`
|
||||
*Required.* Specify a hash representing the `ini_setting` resources you want to create.
|
||||
|
||||
*Required.* Specify a hash with the ini_setting resources.
|
||||
##### Second argument: `defaults`
|
||||
|
||||
###### 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'
|
||||
}
|
||||
~~~
|
||||
*Optional.* Accepts a hash to be used as the values for any attributes not defined in the first argument.
|
||||
|
||||
###### Example with special parameters
|
||||
~~~
|
||||
defaults = { 'path' => '/tmp/foo.ini' }
|
||||
$example = { 'section1' => {
|
||||
'setting1' => 'value1',
|
||||
'settings2' => {
|
||||
'ensure' => 'absent'
|
||||
~~~puppet
|
||||
$example = {
|
||||
'section1' => {
|
||||
'setting1' => {
|
||||
'value' => 'value1', 'path' => '/tmp/foo.ini'
|
||||
}
|
||||
}
|
||||
}
|
||||
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',
|
||||
}
|
||||
~~~
|
||||
|
||||
##### `$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.
|
||||
|
|
|
|||
Loading…
Reference in a new issue