Chapter 3. Adding Puppet Modules to Red Hat Satellite


You can import Puppet classes from modules on your Puppet server and classify Hosts and Puppet Environments, to which the classes belong. You can also customize the parameters of assigned classes. This allows you to control what parameters are passed to the puppet-agent on the Host through the external node classifier (ENC).

3.1. Puppet Environments

A Puppet environment is defined as an isolated set of Puppet agent nodes that can be associated with a specific set of Puppet modules. In Satellite context we can think of a Puppet environment as a set of Hosts running the Puppet agent that are associated with a specific set of Puppet modules. For example, nodes that are associated with environment Production only have access to the modules that are in environment Production.

Puppet environments are used to separate Puppet modules from different types of Host. A typical use is to enable changes to a module to be tested in one environment before being pushed to another. A Puppet module can contain facts and functions as well as one or more Puppet classes that you can assign to Hosts. Modules are part of an environment, Puppet classes are only part of an environment because they are part of a module.

In Red Hat Satellite, a Puppet environment will be created automatically for a Content View if the CV has a Puppet module. The automatically created Puppet environment name includes the organization label, the life-cycle environment, the Content View name, and the Content View ID. For example, KT_Example_Org_Library_RHEL6Server_3.

Creating Puppet Environments within Red Hat Satellite

  1. Navigate to Configure Environments and select New Puppet Environment.
  2. Give the new environment a name and click Submit to save the changes.

Note that if the environment does not exist on the Puppet master and you subsequently run an import, Satellite will prompt for the environment to be deleted.

Note

Puppet fails to retrieve the Puppet CA certificate while registering a host with a host group associated with a Puppet environment created inside a Production environment. To create a suitable Puppet environment to be associated with a host group, follow these steps:

  1. Manually create a directory and change the owner:

    # mkdir /etc/puppetlabs/code/environments/example_environment
    # chown apache /etc/puppetlabs/code/environments/example_environment
  2. Navigate to Configure Environments and click Import environment from. The button name will include the FQDN of the internal or external Capsule.
  3. Choose the created directory and click Update.

Importing Puppet Environments to Red Hat Satellite

Satellite can detect all the environments and Puppet modules contained on a Puppet master, and import them automatically. To do this, go to Configure > Environments and click the Import from button. The button name will include the FQDN of the internal or external Capsule. Satellite will scan the Puppet master via the Capsule, and display a list of the detected changes. Select the changes you want to apply and select Update to apply the changes.

Note that the Capsule will only detect environments that contain one or more Puppet classes, so ensure that at least one Puppet module containing a class has been deployed to the Puppet master.

Assigning a Puppet Environment to a Host

Navigate to Hosts > All Hosts, select a host by name from the Hosts list and then select Edit. On the Host tab you can select a Puppet Environment for the host. Selecting an environment will filter the classes on the Puppet Classes tab to help distinguish the classes in the selected environment.

You can mass-assign an environment to a group of hosts. Select the check boxes of the required hosts in the Hosts list, and then select Change Environment from the Select Action drop-down menu at the top of the page.

Assigning Puppet Environments to Host Groups

When creating a Host Group, the environment field is pre-populated by the environment that was automatically created by the associated Content View, if any.

By default, a user creating a new host and selecting the Host Group will automatically have the environment pre-selected. The user can change the environment of the new host.

3.2. Parameters

Red Hat Satellite parameters define key-value pairs to use when provisioning hosts. These are similar to Puppet’s concept of a default scope parameter. You can define parameters when setting up a host with Puppet.

Types of Parameters

Red Hat Satellite has two types of parameters:

Simple Parameters
String parameters that define a relationship between a key and value pair. They cannot be overridden by user configuration, but they are overridden according to Satellite’s parameter hierarchy. The following parameters are simple parameters in Red Hat Satellite: Global, organization-level, location-level, domain-level, subnet level, operating system level, host group, and host parameters.
Smart Class Parameters
Complex parameters that define a value for a key but allow conditional arguments, validation, and overrides for specific object types. Smart class parameters enable a Puppet class to get external data. They are used in Puppet classes, and are called parameterized classes in Puppet terminology. The hierarchy for these parameters can be configured in the web UI.

The following parameter hierarchy applies for simple parameters:

Global Parameters

Default parameters that apply to every host in Satellite. Configured in Configure > Global parameters. To set global parameters using Hammer CLI, enter the following command:

# hammer global-parameter set --name parameter_name --value parameter_value
Organization-level parameters

Parameters that affect all hosts in a given organization. Organization-level parameters override Global parameters. Configured in Administer > Organizations > Edit > Parameters. To set organization-level parameters using Hammer CLI, enter the following command:

# hammer organization set-parameter --organization "Your Organization" \
--name parameter_name --value parameter_value
Location-level parameters

Parameters that affect all hosts in a given location. Location-level parameters override Organization-level and Global parameters. Configured in Administer > Locations > Edit > Parameters. To set location-level parameters using Hammer CLI, enter the following command:

# hammer location set-parameter --location "Your_Location" \
--name parameter_name --value parameter_value
Domain Parameters

Parameters that affect all hosts in a given domain. Domain parameters override Location-level and higher parameters. Configured in Infrastructure > Domains > [choose_a_domain] > Parameters. To set domain parameters using Hammer CLI, enter the following command:

# hammer domain set-parameter --domain domain_name \
--name parameter_name --value parameter_value
Subnet Parameters

Parameters that affect all hosts that have a primary interface in a given Subnet. Subnet parameters override Host Group system level and higher parameters. Configured in Infrastructure > Subnets > [choose_a_subnet] > Parameters. To set subnet parameters using Hammer CLI, enter the following command:

# hammer subnet set-parameter --subnet subnet_name \
--name parameter_name --value parameter_value
Operating System Level Parameters

Parameters that affect all hosts with a given operating system. Operating system level parameters override Domain and higher parameters. Configured in Hosts > Operating systems > [choose_an_operating_system] > Parameters. To set operating system parameters using Hammer CLI, enter the following command:

# hammer os set-parameter --operatingsystem os_name \
--name parameter_name --value parameter_value
Host Group Parameters

Parameters that affect all hosts in a given Host Group. Host Group parameters override Operating system level and higher parameters. Configured in Configure > Host Groups > [choose_a_host_group] > Parameters. To set host group parameters using Hammer CLI, enter the following command:

# hammer hostgroup set-parameter --hostgroup hostgroup_name \
--name parameter_name --value parameter_value
Host Parameters

Parameters that affect a specific host. All previously inherited parameters are visible on the Parameters subtab and can be overridden. Configured in Hosts > All hosts > Edit > Parameters. To set host parameters using Hammer CLI, enter the following command:

# hammer host set-parameter --host host_name \
--name parameter_name --value parameter_value

Using Parameters with Puppet Classes

Red Hat Satellite has two ways to supply values to a Puppet master for a host to use with a Puppet class:

Smart Variables
A tool to provide global parameters to the Puppet master, in key-value form, for classes that do not have Smart class parameters. They enable overriding parameter values in a Puppet manifest. They are intended for use when a class does not have Smart class parameters or in special cases when a global parameter is desired. They can have multiple possible values, all depending on hierarchical context or various conditions a user can apply. They existed before Puppet had parameterized classes and today are kept either for backward compatibility or for the use of global parameters where you want validations, to use only with specific Puppet classes, and for types other than string (because otherwise you could just use the simple parameters).
Parameterized Classes
Puppet classes containing Smart class parameters. The classes are imported from the Puppet master and the name of the parameter, for example $::name (preferred) or $name, is defined by the person who wrote the class and cannot be changed. They enable you to decide the value of the variable for a specific class rather than globally.

Configured parameters are included in each host’s corresponding YAML file and sent to the Puppet master. The YAML file can be viewed in the web UI on the page for a specific host. You should not manually change the /etc/foreman/settings.yaml configuration file because they are overwritten the next time you run the satellite-installer command.

Important

Parameterized class support is enabled by default in Satellite. To confirm it is enabled, navigate to Administer > Settings, select the Puppet tab, and ensure the Parameterized Classes in ENC is set to True.

3.3. Configuring Smart Class Parameters

The following procedure configures parameters within a class. Classes that contain parameters are referred to as parameterized classes.

Smart class parameters are common for all organizations. Any user with the edit_external_parameters permission can edit these parameters. If you want to restrict permissions to edit smart class parameters, see the KCS solution Restrict permissions to edit puppet classes and their smart class parameters which are common between multiple organizations.

Configuring Smart Class Parameters

  1. Click Configure > Puppet Classes.
  2. Select a class from the list that has parameters as indicated in the Parameters column.
  3. Click the Smart Class Parameter tab. This displays a new screen. The left section contains a list of possible parameters the class supports. The right section contains the configuration options for the parameter selected.
  4. Select a parameter from the left-hand list.
  5. Edit the Description text box to add any plain text notes.
  6. Select Override to allow Satellite control over this variable. If the check box is not selected, Satellite does not pass the new variable to Puppet.
  7. Select the Parameter type of data to pass. This is most commonly a string, but other data types are supported.
  8. Enter a Default Value for the parameter to be sent to the Puppet master if no host match occurs.
  9. Optional: Select Omit to not send a value to the Puppet master unless an override match occurs.
  10. Optional: Select Hidden value if the field contains data you do not want to be displayed while you are working.
  11. Use the Optional Input Validator section to restrict the allowed values for the parameter. Choose a Validator type (either a list of comma-separated values or a regular expression, regexp) and input the allowed values or regular expression code in the Validator rule field.
  12. The Prioritize Attribute Order section will appear if the Override option is selected. This provides options for overriding values for specific hosts based upon conditional arguments. The attribute type and its value is known as a matcher.
  13. In the Order field, set the order of precedence in which the host attributes or Facts are to be evaluated against the matchers by arranging the entries in the list. You can add an attribute that is present in Facter and cannot be confused with a host attribute to the default list.

    If you want to create a logical AND condition between matchers and use multiple attributes as a matcher key, arrange them on one line as a comma-separated list in the following format:

    location,environment
    Note

    Until BZ#1772381 is resolved, note that the Order tooltip displays incorrect example configuration for using multiple attributes as a matcher key.

  14. Click Add Matcher to add a conditional argument. The attributes to match against correspond to the entries in the Order list. If no matcher is configured then only the default value can be used for the override feature.
  15. From the Attribute type list, select the attribute.
  16. In the field next to the attributes, enter the attribute string.
  17. In the Value field, enter the value that you want.

    Dynamic data is possible by using parameters and Puppet Facts in the Value field in Embedded Ruby (ERB) template syntax. For example, to use a Puppet Fact as part of the value:

    <%= @host.facts['network_eth0'] %>

    To list available Puppet Facts navigate to Monitor > Facts.

    For more information on ERB syntax see Template Writing Reference in Managing Hosts.

  18. Click Submit.

Setting a single attribute as a matcher key

You can set a single attribute as a matcher key.

For example, to supply the test value of a parameter to the Puppet master for any host within the Default_Location location, complete the following steps:

  1. To the Order field, append location.
  2. Click Add Matcher and from the Attribute type list, select location.
  3. In the field next to the attributes, enter Default_Location.
  4. In the Value field, enter test.
  5. Click Submit.

Setting multiple attributes as a matcher key

You can set multiple attributes as a matcher.

For example, to supply the test value of a parameter to the Puppet master for any host within the Default_Location location and the development environment, complete the following steps:

  1. To the Order field, append location,environment.
  2. Click Add Matcher and from the Attribute type list, select location,environment.
  3. In the field next to the attributes, enter Default_Location,development.
  4. In the Value field, enter test.
  5. Click Submit.

Precedence for Matching Overview

Satellite uses the following precedence when matching hosts:

  1. Satellite searches the matcher in host attributes.
  2. If there is no match in host attributes, Satellite searches the matcher in host parameters, which are inherited according to the parameter hierarchy.
  3. If there is no match in host parameters, Satellite searches the matcher in host Facts.

3.4. Applying Facts Using a Parent Host Group

You can use a parent host group to apply facts to members of multiple host groups.

Prerequisites

  • You have host groups with hosts assigned.
  • You have a parent host group with host groups assigned.

Applying facts to members of multiple host groups

  1. In the Satellite web UI, navigate to Configure > Classes.
  2. Select the Puppet class you want to use.
  3. Click the Smart Class Parameter tab.
  4. Select a parameter from the left-hand list you want to override.
  5. Optional: Edit the Description field to add any plain text notes.
  6. Select Override to grant Satellite control over this variable.
  7. Select the Parameter type of data to pass. This is most commonly a string, but other data types are supported.
  8. Optional: Enter a Default Value for the parameter to send to the Puppet master if no host match occurs.
  9. Optional: Select Omit not to send a value to the Puppet master unless an override match occurs.
  10. Optional: Select Hidden Value if the field contains data you do not want to be displayed while you are working.
  11. Optional: Use the Optional Input Validator section to restrict the allowed values for the parameter. Select a Validator Type, which is either a list of comma-separated values or a regular expression, regexp, and add the allowed values or regular expression code in the Validator rule field.
  12. In the Prioritize Attribute Order area, set the Order of precedence in which to evaluate the host attributes or Facts against the matchers by arranging the entries in the list. You can add to the default list. To create a logical AND condition between matchers, arrange the matchers on one line as a comma-separated list.
  13. In the Specify Matchers area, click Add Matcher to add a conditional argument.
  14. Set the Attribute type to hostgroup.
  15. After the = sign, enter the host group that you want to match against. In this example, the parent host group.
  16. In the Value field, enter the value that you want to send to the Content Hosts that belong to the parent host group.
  17. Click Submit.

    If the parent host group is part of a hierarchy of host groups, enter all the parents as follows for the matcher value: top_host_group/intermediate_host_group/parent_host_group.

3.5. Using Multiple Custom Facts

The following is an example of creating and using multiple custom facts and their values in a Puppet Smart class parameter matcher.

Prerequisites

  • You have imported Puppet environments and have a Puppet Module with smart classes in Satellite.
  • You have a client provisioned and registered to Satellite.
  • For a client not provisioned by Satellite, check that the client is configured as described in Section 6.2, “Applying Configuration to Existing Clients”.

    1. On the client, create two or more custom facts and assign values to them. For example:

      # vi /etc/facter/facts.d/my_custom_facts
      #! /bin/bash
      echo example_fact1=myfact1
      echo example_fact2=myfact2
    2. On the client, configure the file permissions:

      # chmod a+x /etc/facter/facts.d/my_custom_facts
    3. On the client, check the facts and their respective values:

      # facter | grep example
       example_fact1 => myfact1
       example_fact2 => myfact2
    4. In the Satellite web UI:

      1. Navigate to Configure > Classes and select the Puppet class you want to configure.
      2. Click the Smart Class Parameter tab and select the parameter you want to override.
      3. In the Default Behavior area, select the Override check box.
      4. In the Prioritize Attribute Order area, in the Order field, add the example facts to the end of the list. To create a logical AND condition between the two facts, add them as a comma separated list example_fact1,example_fact2.
      5. Select Add Matcher.
      6. From the Attribute type menu, select example_fact1,example_fact2 and in the box after the = sign, enter myfact1,myfact2.
      7. In the Value field, enter the value you want to send to the Content Host when a match is made for the two attributes and their values.
      8. Click Submit.
    5. On the client, send the facts from the client to the Puppet master:

      # puppet agent --test
    6. In the Satellite web UI:

      1. Navigate to Hosts > Content Hosts and select the name of the Content Host.
      2. Click YAML and locate the classes section. Check that the parameter has the value you want.

3.6. Configuring Smart Variables

The following procedure configures Smart Variables to override a value in a Puppet class.

Configuring Smart Variables

  1. Click Configure > Puppet Classes.
  2. Select a class from the list.
  3. Click the Smart Variables tab. This displays a new screen. The left section contains a list of possible parameters the class supports. The right section contains the configuration options for the parameter selected. Click the Add Variable to add a new parameter. Otherwise, select a parameter from the left-hand list.
  4. Type a name for the parameter in the Key field.
  5. Edit the Description text box to add any plain text notes.
  6. Select the Parameter Type of data to pass. This is most commonly a string, but other data types are supported.
  7. Enter a Default Value for the parameter to be sent to the Puppet master if no host match occurs.
  8. Optional: Select Hidden Value if the field contains data you do not want to be displayed while you are working.
  9. Use the Optional Input Validator section to restrict the allowed values for the parameter. Choose a Validator Type (either a list of comma separated values or a regular expression, regexp) and input the allowed values or regular expression code in the Validator rule field.
  10. The Prioritize Attribute Order section provides options for overriding values for specific hosts based upon conditional arguments. The attribute type and its value is known as a matcher.

    1. Set the Order of precedence in which the host attributes or Facts are to be evaluated against the matchers by arranging the entries in the list. You can add to the default list. To create a logical AND condition between matchers, arrange them on one line as a comma separated list.
    2. Click Add Matcher to add a conditional argument. The attributes to match against should correspond to the entries in the Order list. If no matcher is configured then only the default value can be used for the override feature.

      For example, if the desired value of the parameter to be supplied to the Puppet master is test for any host with a fully qualified domain name of server1.example.com, then specify the matcher as fqdn=server1.example.com and the Value as test.

      The precedence for matching is as follows:

      1. If the matcher is a host attribute, use that.
      2. If there are no attributes with that name, look for a matching host parameter (which is inherited according to the parameter hierarchy).
      3. If there is still no match, check the host Facts.

        It is recommended to use an attribute that is present in Facter and cannot be confused with a host attribute. Host attributes can be either host parameters or associations to the host, such as host group, domain, and organization. The matcher must only be something the host has one of, for example config group cannot be used because the host can have many config groups but a host only has one location so location is a valid matcher.

        Dynamic data is possible by using parameters and Puppet Facts in the Value field in Embedded Ruby (ERB) template syntax. For example, to use a Puppet Fact as part of the value:

        <%= @host.facts['network_eth0'] %>

        To list available Puppet Facts navigate to Monitor > Facts.

  11. Click Submit to save your changes.

For more information on ERB syntax see Template Writing Reference in Managing Hosts.

3.7. Importing Parameterized Classes from a Puppet Master

The following procedure imports parameterized classes from your Puppet master.

Note

The import of parameterized classes happens automatically if your Puppet modules are managed via a Product and a Content View.

Importing Parameterized Classes

  1. In the Satellite web UI, select from the context menu Any Organization and Any Location.
  2. Click Configure > Puppet Classes.
  3. Click Import from Host Name to import parameterized classes from your Puppet master.
  4. The Puppet Classes page displays with the new classes listed.

3.8. Using the Smart Variable Tool

Smart Variables are a tool for providing global parameters to the Puppet master for use with Puppet classes that do not contain Smart Class Parameters. The same Smart Matcher rules are used for both Smart Variables and Smart Class Parameters.

Note

The Smart Variables tool was introduced as an interim measure before Puppet modules supported Smart Class Parameters. If you do not have a specific reason to use Smart Variables, Red Hat recommends that you use Smart Class Parameters instead as described in Section 3.3, “Configuring Smart Class Parameters”.

Before Smart Class Parameters were introduced, users who wanted to override a parameter where asked to rewrite their Puppet code to use a global parameter. For example:

class example1 {
  file { '/tmp/foo': content => $global_var }
}

For the above example, $global_var is set in the Smart Variables section of the web UI and the value is associated with the "example1" class. Although it is recommend to precede global variables with :: to restrict Puppet to search the global scope, their absence does not mean a variable is not a global variable.

With the introduction of Smart Class Parameters, the following form could be used:

class example2($var="default") {
  file { '/tmp/foo': content => $var }
}

For the above example, $var is set in the Smart Class Parameters section of the web UI and the value is associated with the "example2" class. If you see a variable defined in the class header, as in the above class example2($var="default"), then you can be sure that $var is a class parameter and you should use the Smart Class Parameter function to override the variable.

As demonstrated, Smart Variables require custom-designed modules using global-namespace parameters, rather than standard modules from the Puppet community, and the result is the same: text placed in '/tmp/foo' in the examples above. Consequently, there is no longer a reason to use Smart Variables except to support legacy modules.

Although Smart Variables are global variables, they are associated with a Puppet class and will only be sent to a host that has that specific Puppet class assigned in Satellite. You can create a Smart Variable with any name, no validation is done in Satellite, but unless the associated Puppet module applied has a matching variable in its code, the Smart Variable will not be used.

Satellite adds the variable you create in Satellite to the Host YAML file. This file can be viewed in the web UI by navigating to Hosts > All Hosts, selecting the name of the host, and then clicking on the YAML button. Satellite sends the Host YAML file to the external node classifier (ENC), a function included with the Puppet master. When the Puppet master queries the ENC about a host, the ENC returns a YAML document describing the state of the host. This YAML document is based on data taken from Puppet Manifests, but is subject to Smart Class Parameter overrides and any Smart Variables.

Applying a Smart Variable to a Host

As Smart Variables should only be used to support your custom Puppet modules previously modified to include a global parameter, the following example uses a simple example called anothermodule. The anothermodule Puppet Manifest is as follows:

class anothermodule {
   file { '/tmp/motd':
     ensure  => file,
     content => $::content_for_motd,
  }
}

This example will supply a value for the $::content_for_motd parameter.

  1. In the web UI, navigate to Configure > Classes.
  2. Select the name of the Puppet class from the list.
  3. Click the Smart Variables tab. This displays a new screen. The left section contains a list of previously created parameters, if any. The right section contains the configuration options.
  4. Click Add Variable to add a new parameter.
  5. Enter the parameter in the Key field. In this example, content_for_motd.
  6. Edit the Description text box, for example Testing /tmp motd Text.
  7. Select the Parameter Type of data to pass. Select string.
  8. Type a Default Value for the parameter. For example, No Unauthorized Use.
  9. Use the Optional Input Validator section to restrict the allowed values for the parameter. Choose a Validator Type (either a list of comma separated values or a regular expression, regexp) and input the allowed values or regular expression code in the Validator rule field.
  10. Use the Prioritize Attribute Order section to set the order of precedence in which the host attributes or Facts are to be evaluated against the matchers (configured below). You can rearrange the entries in the list and add to the default list. To create a logical AND condition between matchers, arrange the names of the matchers on one line as a comma separated list.
  11. In the Specify Matchers section, click Add Matcher to add a conditional argument. The attributes to match against should correspond to the entries in the Order list above. If no matcher is configured, then only the default value can be used. For example, if the desired value of the parameter is This is for Server1 for any host with a fully qualified domain name of server1.example.com, then specify the Match as fqdn=server1.example.com and the Value as This is for Server1.
  12. Click Submit to save your changes.
Red Hat logoGithubRedditYoutubeTwitter

Learn

Try, buy, & sell

Communities

About Red Hat Documentation

We help Red Hat users innovate and achieve their goals with our products and services with content they can trust.

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. For more details, see the Red Hat Blog.

About Red Hat

We deliver hardened solutions that make it easier for enterprises to work across platforms and environments, from the core datacenter to the network edge.

© 2024 Red Hat, Inc.