Parameterized class support in Foreman¶

• Table of contents
• Parameterized class support in Foreman
  • Requirements
  • Screencast
  • 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+

Screencast¶

{{youtube(Ksr0tilbmcc)}}

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.

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 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.

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:

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

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:

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

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:

This will be converted to the normal ["a","b"] syntax when you save. You can also use Hashes, YAML or JSON as data types too.

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:

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

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