Understanding the relationship between foreman hostgroups, classes, and puppet manifests and catalogs

I know, the topic is a mouthful, but this here noob is confused.
I’m trying to understand how associating classes to a host group in foreman,
translates to puppet manifests and catalogs for given hosts?

Example: I created a class called ‘lucee’, and in my development environment site.pp file,
I listed two nodes, lucee1 and lucee2. The puppet agent run installed everything as expected.
But I discovered that lucee was also installed on a node called nodejs, which was not intended.

I found that I needed to remove the class lucee and lucee::params from the host group
of which all 3 are members of.

I guess my question is, apparently some things defined in foreman can directly translate to
puppet catalogs, even though they are not explicitly configured in puppet manifests.
Where is this information kept, and is it something that can be viewed outside of the UI?

How do I know which things are puppet configurations, and which are in foreman?

Or am I just confused on how to use hosts, host groups, environments, locations, organizations,
classes, in relation to puppet manifests?


let me try to answer this. I’ll also give some recommendations on how I do things. Please take them with a grain of salt and evaluate whatever these are applicable for you. For the sake of my time, I do not add links to Puppt docs: Please google yourself

  • Foreman acts as an External Node Classifier (ENC). This means drop site.pp, it does not get evaluated. Instead, the ENC will do about the same thing: Add classes and variables to a host object and create a catalog for a specific host (= node) only (host level). Foreman will resolve classes and parameters usually from the hostgroups (see bellow). To see it in action, go to a specific host and the press YAML button. Basically, this YAML is fed to the puppet master.
  • You do not need to use the ENC feature and can instead rely completely on Hiera. However, to get started easy, you should try ENC first. And as you explicitly mentioned hostgroups in your question, I assume you rather want to use foreman to manage classes.

Note: One of the biggest challenges I faced using the ENC model is class dependency. You can never be sure if a class you need was actually declared when your class is calling it, let alone with the parameters it needs. To be fair, this is a more a puppet issue then Foreman’s. However, if you rely on this a lot, you should consider the hiera route.


You already managed to import these. I assume you are seeing hosts in the Hosts tab and your classes in the classes tab. Classes are usually grouped in modules are installed on your puppet master using puppet module. To make parameter values accessible to change in Foreman, you need to ‘override’ the parameter default in the Smart Class Parameter tab


This is a puppet concept witch Foreman reflects. Please read the docs, but it basically allows you to have the same classes but different versions. Imagine you are working on your own Puppet classes: Maybe you want to test things on a small number of development hosts in an environment called development while most hosts in the production environment are unaffected (using the old code)


Is a way in Foreman to hierarchically organise hosts. On hostgroup level you assign classes and overwrite parameters of these classes. You may have the same class on different hosts.
Example: You have a bunch of web servers wich are load balanced. You need serve two websites, foo.com and bar.com. Create hostgoups foo.com and bar.com; then add hosts to the group. Change the vhost parameter on host group level.
I use hostgroups to model the structure of our company; they mirror Organisational Units in Active Directory. They work in a hierarchical way: Lower level hostgroups inherit values and parameters from upper levels. Hierarchies are organised from mot general on the top to the most specific on the bottom

Config Groups

Config groups hold a bunch of classes grouped together. You cannot assign actual values there. However, I would suggest Example: The file server config group has nfs, samba and sssd classes. This is pretty useful, and you should make a lot of use of them early on. I think it is best practice to only assign config groups to hosts and hostgroups. This make it easy to propagate changes later on when you really have a lot of classes.

Note: You can also assign classes directly to hosts. However, I see only edge use cases for this. You should avoid doing this when possible.


Great post, do you want to repost this in the Tutorial section of our forums? We really need more good resources about Foreman and we are trying to build this section with inspiration stuff for our documentation NG.

1 Like

@lzap, certainly! However, I just wrote this up quickly from memory without any real fact checking. I certainly would like some comments from you guys before I repost it to tutorials?

Looks good to me, perhaps a puppet expert would have some: @ekohl

I just want to point out that the Puppet server will consult both the node definitions (site.pp, and other nodes under <ENVIRONMENTS DIRECTORY>/<ENVIRONMENT>/manifests/) and the ENC. The data is merged as discussed at https://puppet.com/docs/puppet/5.5/lang_node_definitions.html#merging-with-enc-data

Foreman won’t evaluate the node definitions, but Puppet will.

1 Like

@Stefan_Lasiewski - thanks, good point; I certainly did not know about this.
That said, I would not consider using node defs along ENC a good practice as it is not very transparent can lead to unexpected behavior… ?

Agreed. Having used both simultaneously, I would recommend using one strategy.

Node definitions are one of the simplest ways to get started with Puppet and making changes is super easy, but they are pretty primitive and only good enough for basic configuration and for importing classes.

Right! I did put it here: