h1. Parameterized class support in Foreman

{{toc}}

The latest version of Foreman brings parameterized class support to the UI. This document is a walkthrough of setting up the required steps.

h2. Requirements

* Foreman 1.1+

* Foreman-Proxy 1.1+

* Puppet 2.6.5+

h2. Setup

Firstly, you'll need to enable the PCS support. Go to More->Settings, select the Puppet tab, and ensure Parametrized_Classes_in_ENC" is set to True. 

!PCS_settings.png!

Now you'll need to import some parameterized classes from your puppet master. You can skip this if you already have parameterized modules on your master, but since the [[Using_Puppet_Module_ready_to_use|foreman-installer]] has several such classes, we'll use those for this example. Assuming default paths (adjust this as necessary):

    cd /etc/puppet/modules/production

git clone --recursive https://github.com/theforeman/foreman-installer -b develop

Now import your classes via the Foreman Proxy. Go to More-> Puppet Classes and click Import. If all goes well you'll get a screen showing the classes that are to be imported. Accept the changes, and you should return to the Puppet Classes page, with all the new classes listed.

!imported_classes.png!

h2. Configure a class

We'll work with the "foreman" class from the installer. Click on the foreman class, and you should get a page with 3 tabs, like so:

!PCS_3tabs.png!

The midddle tab, "Smart Class Parameter", is the important one. Click onto that, and you should see something like this:

!PCS_edit_params.png!

On the left we have a list of possible parameters that the class supports. On the right, we have the configuration options for the parameter selected.

Lets configure the foreman class to change the user the foreman processes run as. Select the "user" parameter, at the end of the list. Now lets go through the options:

* Puppet Environments / Name

  These can't be edited, they're just for information.

* Description

  Purely information textbox for making notes in. Not passed to puppet, or reused anywhere else

* Override (*important*)

  If this is unchecked, Foreman will not attempt to control this variable, and it will not be passed to Puppet via the ENC.

* Type

  The type of data we want to pass. Most commonly a string, but many other data types are supported. There's no easy way to tell what type of data puppet is expecting, so you will need to read through the code/documentation that comes with a particular module to find out

* Default Value

  This will be imported from puppet initially, but if puppet is using any class inheritance, you'll get something unhelpful like "${$foreman::params::user}". This is because Foreman won't follow the inheritance, so you'll need to set a sensible default value

Ok, so let's configure our "user" parameter. We want to tick Override, set type to "String" and set the default value to "foreman", like so:

!PCS_configure_user.png!

h2. Setting up Matchers

We've configured the default, but that's not very useful. We need to be able to override the default for hosts or groups of hosts. To do that we need the "Override Value For Specific Hosts" section at the bottom of the page.

Let's say that any machine in the "development" puppet environment should use a value of "foremandev" instead of "foreman" for the "user" parameter. Add "environment" to the end of the matchers list, then click the "New Matcher-Value" button, and fill it out like this:

    Match: environment = development

Value: foremandev

!PCS_matcher_env.png!

This is a basic configuration - for more complex examples of using matchers, see the SmartVariables page.

h2. Complex Data

Here's a screenshot of adding an array parameter. Note the use of YAML in the editbox:

(screenshot)

h2. Editing Param from within a Host

If foreman manages the value of a class parameter ("override"), it's also possible to update a host-specific override from the host itself. That way you don't have to grant access to the Puppet Classes page to everyone. From a Host, click Edit, go to the Parameters tab, and you'll see the variable, the class-scope, and the current value. You can then override the value for that host:

(screenshot)

If you go back and look at the Puppet class, you'll see Foreman has added a matcher for that host:

(screenshot)

Currently this only works for Hosts, not Hostgroups. For more complex logic, like matching on facts, use the Puppet Class page

h2. Input Validation

The "Optional Input Validation" section can be used to restrict the allowed values for the parameter. This functions in the same way as for SmartVariables, but it is important to note that the validation applies to changes made from the Host edit page as well as the Puppet Classes edit page. 

For example, to restrict the "user" field to either "foreman" or "foremandev", tick the Required checkbox, and then set:

    Type: List

Rule: foreman,foremandev