h1. Instantiate Puppet resources

Foreman acts as an external node classifier (ENC) for Puppet, which allows it to pass a list of classes, global and class parameters.  It isn't able to instantiate individual resources (such as a file or package), or a defined type through this interface.

Instead, you have a few possible approaches.

h2. Creating a simple wrapper class or module

Resources should generally be kept in a class which can then be included where needed.  For static resources, this is the best way.

* "Learning Puppet — Modules and Classes":https://docs.puppetlabs.com/learning/modules1.html

h2. Basic dynamic resources with arrays

If the resources you're managing are simple and all have the same properties and parameters, you can use Puppet's array resource declaration syntax ("array of title docs":https://docs.puppetlabs.com/puppet/3/reference/lang_resources.html#array-of-titles) to create many resources at once.

In this example to install a list of packages, we create /etc/puppet/environments/production/modules/packages/manifests/init.pp with:

<pre>

class packages($list = []) {

  package { $list:

    ensure => installed,

  }

}

</pre>

When you import this "packages" class, it will have a "list" parameter.  In Foreman's UI, go to _Configure_, _Puppet classes_, "packages", _Smart class parameters_ and tick the _Override_ checkbox on the "list" parameter.  Set the _Parameter type_ to _json_ and use "JSON syntax":http://www.w3schools.com/json/json_syntax.asp to set the list parameter to an array of values, e.g.

    ["httpd","vim"]

You can then override this per host or host group and supply a new array.

h2. Advanced dynamic resources with create_resources

Puppet ships a "create_resources function":https://docs.puppetlabs.com/references/stable/function.html#createresources (since Puppet 2.7) that takes a hash of resources to instantiate, and this hash can again be passed into a class as a parameter.

Use a similar pattern to the example above, but this time we'll pass an entire hash in:

<pre>

class packages($resources = {}) {

  create_resources('package', $resources)

}

</pre>

For the parameter value, again set the parameter type to JSON or YAML and then store a hash such as this (JSON example):

<pre>

{"httpd":{"ensure":"installed"},"vim":{"ensure":"installed"},"emacs":{"ensure":"absent"}}

</pre>

Note that the keys of the first level of the hash are the names of the resources (what usually goes after the resource type on the first list), and then the values are a full hash of the properties and parameters of the resource.  You'll need to supply them all ("type documentation":http://docs.puppetlabs.com/references/stable/type.html).

Also important is that JSON hashes do not have the same syntax as Puppet.  JSON uses colons (":") as key/value separators, while Puppet uses "=>".  Foreman will give a parse error if you try using "=>"!

Foreman can store complex parameters using YAML or JSON, here's a YAML example which may be easier to read and work with:

<pre>

---

httpd:

  ensure: installed

vim:

  ensure: installed

emacs:

  ensure: absent

</pre>

h2. Using defined types to minimise duplication

Using create_resources means all resource properties/params need to be passed in.  When they're often the same, or you have multiple resources to instantiate, it's usually simpler to wrap it all in a defined type and then instantiate that.  Here's an example to manage services:

/etc/puppet/environments/production/modules/services_wrapper/manifests/single_service.pp (depends on "stdlib":https://forge.puppetlabs.com/puppetlabs/stdlib):

<pre>

class services_wrapper::single_service($start = true) {

  service { $title:

    ensure  => str2bool($start) ? 'running' : 'stopped',

    enabled => str2bool($start),

  }

}

</pre>

/etc/puppet/environments/production/modules/services_wrapper/manifests/init.pp:

<pre>

class services_wrapper($resources = {}) {

  create_resources('services_wrapper::single_service', $resources)

}

</pre>

And then in the parameter:

<pre>

---

httpd:

dbus:

nfs:

  start: false

</pre>