Parameterized class support in Foreman¶

• Table of contents
• Parameterized class support in Foreman
  • Requirements
  • Setup
  • Configure a class
  • Setting up Matchers
  • Complex Data
  • Editing Param from within a Host
  • Input Validation

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

Requirements¶

• Foreman 1.1+
• Foreman-Proxy 1.1+
• Puppet 2.6.5+

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.

(screenshot)

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 foreman-installer (TODO: link) 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.

(screenshot)

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:

(screenshot)

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

(screenshot)

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
• 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:

(screenshot)

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

(screenshot)

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

Complex Data¶

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

(screenshot)

Editing Param from within a Host¶

It's also possible to update a host-specific override from the host itself. So you don't have to grant access to the Puppet Classes page to everyone. From a Host, click Edit, got 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

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