Chapter 3. Adding Puppet Modules to Red Hat Satellite 6
Puppet modules form a part of a Satellite Product in Red Hat Satellite 6. This means you must create a custom Product and then upload the modules that form the basis of that Product. For example, a custom Product might consist of a set of Puppet modules required to setup an HTTP server, a database, and a custom application. Custom Products can also include repositories with RPM packages that apply to your application.
3.1. Creating a Custom Product
The first step to adding our Puppet module is to create a custom Product.
Creating a Custom Product
- Login to your Red Hat Satellite 6 Server.
- Navigate to Content > Products.
- Click Create Product.
-
Provide your custom Product with a Name. In this example, use
MyProduct
as the name. - The Label field automatically populates with a label based on the Name.
- Provide a GPG Key, Sync Plan, and a Description if required. For our example, leave those fields blank.
- Click Save.
Satellite now has a new Product called MyProduct
.
3.2. Creating a Puppet Repository in a Custom Product
The next procedure creates a Puppet repository in our custom Product.
Creating a Custom Puppet Repository
-
On the Products page, click on the custom Product created previously (
MyProduct
). - Navigate to the Repositories subtab.
- Click New Repository.
-
Provide the repository with a Name. This example uses the name
MyRepo
. - The Label field automatically populates with a label based on the Name.
-
Select
puppet
as the repository Type. - Leave the URL field blank. This field is used for remote repositories, but in our case Satellite 6 creates its own repository.
- Click Save.
The custom Product now contains a repository to store our Puppet modules.
3.3. Uploading a Puppet Module to a Repository
Now we upload our mymodule module to the newly created repository, which adds it to our custom Product.
-
Click the
Name
of the newly created repository. - In the Upload Puppet Module section, click Browse and select the mymodule archive.
- Click Upload.
You can upload more modules to this repository. For our example, we only need to upload the mymodule module.
Our Puppet module is now a part of your Red Hat Satellite 6 environment. Next we publish the module as part of a Content View.
3.4. Removing a Puppet Module from a Repository
If you aim to remove redundant modules from custom repositories in the future, use the Manage Puppet Modules feature.
- On the Products page, click on the custom Product containing the module to remove.
-
Click the
Name
of the repository containing the module to remove. - Click Manage Puppet Modules. The screen displays a list of Puppet modules contained within the repository.
- Select the modules to remove.
- Click Remove Puppet Modules.
Satellite removes the chosen modules from your repository.
3.5. Adding Puppet Modules from a Git Repository
As an alternative to manually uploading modules, Red Hat Satellite 6 includes a utility called pulp-puppet-module-builder
. This tool checks out repositories containing a set of modules, builds the modules, and publishes them in a structure for Satellite 6 to synchronize. This provides an efficient way to manage module development in Git and include them in the Satellite 6 workflow.
The use of Modulefile is deprecated since Puppet version 3. If you build any Puppet module containing a Modulefile when using Puppet version 3.X, a deprecation warning is printed. Satellite 6.3 will include Puppet version 4 which will ignore the Modulefile data. The data in the Modulefile must be moved to a metadata.json
file. You can convert a module to use a metadata.json
file as follows:
-
Run
puppet module build
Module_Directory once. - Delete the Modulefile.
-
Check the updated
metadata.json
file into the revision control repository.
You can also install the pulp-puppet-module-builder
tool on other machines using the pulp-puppet-tools package.
One common method is to run the utility on the Satellite 6 Server itself and publish to a local directory.
Publishing a Git Repository to a Local Directory
Create a directory on the Satellite Server to synchronize the modules:
# mkdir /var/www/puppet-modules # chmod 755 /var/www/puppet-modules
Store your modules under the /var/www/ directory, otherwise SELinux will block the repository synchronization. If required to use another directory, you can use the httpd_sys_r_content_t or pulp_tmp_t SELinux type. Using the httpd_sys_r_content_t SELinux type allows the webserver to read the files. See the SELinux User’s and Administrator’s Guide for information on setting SELinux file types.
Run the
pulp-puppet-module-builder
and checkout the Git repository:# pulp-puppet-module-builder --output-dir=/var/www/puppet-modules \ --url=git@mygitserver.com:mymodules.git --branch=develop
This checks out the
develop
branch of the Git repository fromgit@mygitserver.com:mymodules.git
and publishes the modules to /var/www/puppet-modules/.
The same procedure applies to publishing modules to an HTTP server.
Publishing Git Repository to a Web Server
Create a directory on the web server to synchronize the modules.
# mkdir /var/www/html/puppet-modules # chmod 755 /var/www/html/puppet-modules
Run the
pulp-puppet-module-builder
and checkout the Git repository.# pulp-puppet-module-builder \ --output-dir=/var/www/html/puppet-modules \ --url=git@mygitserver.com:mymodules.git --branch=develop
This checks out the
develop
branch of the Git repository fromgit@mygitserver.com:mymodules.git
and publishes the modules to /var/www/html/puppet-modules/.
In the Satellite 6 web UI, create a new repository with the URL set to the location of your published modules.
Creating a Repository for Puppet Modules from Git
-
On the Products page, click on the custom Product created previously (
MyProduct
). - Navigate to the Repositories subtab.
- Click New Repository.
-
Provide the repository with a Name. This example uses the name
MyGitRepo
. - The Label field automatically populates with a label based on the Name.
-
Select
puppet
as the repository Type. In the URL field, set the location you defined earlier. For example, local directories on the Satellite 6 Server use the
file://
protocol:file:///modules
A remote repository uses the
http://
protocol:http://webserver.example.com/modules/
- Click Save.
- Click Sync Now to synchronize the repository.
The Puppet modules in the Git repository are now included in your Satellite 6 Server.
3.6. Publishing a Content View
The final step to getting our Puppet module ready for consumption is to publish it as part of a Content View. You can add this module to an existing view but for our example we will create a new view.
Publishing a Content View
- Navigate to Content > Content Views.
- Click + Create New View.
-
Provide your view with a Name. In this example, we use
MyView
as the name. - The Label field automatically populates with a label based on the Name.
- Make sure Composite View is not selected.
- Click Save.
- Select the Name of your newly created view.
- Navigate to Content > Repositories.
- Add the required Red Hat Enterprise Linux repositories, including a base Red Hat Enterprise Linux Server RPM collection and a Red Hat Satellite Tools RPM collection for the same version. The Tools RPM collection contains the packages to set up our remote Puppet configuration on provisioned systems.
- Navigate to Puppet Modules.
- Click Add New Module.
- Scroll to your module and click Select a Version.
- Scroll to the module version Use Latest and click Select Version.
- Our module is now a part of the Content View. Navigate to Versions to publish and promote a new version of the Content View.
- Click Publish New Version. On the Publish New Version page, click Save. This publishes the Content View with our module.
- Scroll to the new version of our view and click Promote. Choose a life-cycle environment and click Promote Version. This makes the view a part of the chosen life-cycle environment.
Our Content View is now published. As a part of the Content View creation, Red Hat Satellite 6 creates a new Puppet environment for use in the provisioning process. This Puppet environment contains our module. You can view this new Puppet environment on the Configure > Environments page.
3.7. 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 6 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
-
Navigate to Configure
Environments and select New Puppet Environment. - 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.
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:
Manually create a directory and change the owner:
# mkdir /etc/puppet/environments/example_environment # chown apache /etc/puppet/environments/example_environment
-
Navigate to Configure
Environments and click Import environment from. The button name will include the FQDN of the internal or external Capsule. - 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.8. 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.
- Organization-level parameters
- Parameters that affect all hosts in a given organization. Organization-level parameters override Global parameters. Configured in Administer > Organizations > Edit > Parameters.
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.
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.
Parameterized class support is enabled by default in Satellite 6. 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.9. 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
- Click Configure > Puppet Classes.
- Select a class from the list that has parameters as indicated in the Parameters column.
- 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.
- Select a parameter from the left-hand list.
- Edit the Description text box to add any plain text notes.
- 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.
- Select the Key type of data to pass. This is most commonly a string, but other data types are supported.
- Enter a Default value for the parameter to be sent to the Puppet master if no host match occurs.
- Optional: Select Omit to not send a value to the Puppet master unless an override match occurs.
- Optional: Select Hidden value if the field contains data you do not want to be displayed while you are working.
- 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.
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.
- 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.
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 ofserver1.example.com
, then specify the matcher asfqdn=server1.example.com
and the Value astest
.The precedence for matching is as follows:
- If the matcher is a host attribute, use that.
- If there are no attributes with that name, look for a matching host parameter (which is inherited according to the parameter hierarchy).
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.
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.
- Click Submit to save your changes.
For more information on ERB syntax see Template Writing Reference in Managing Hosts.
3.10. 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”.
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
On the client, configure the file permissions:
# chmod a+x /etc/facter/facts.d/my_custom_facts
On the client, check the facts and their respective values:
# facter | grep example example_fact1 => myfact1 example_fact2 => myfact2
In the Satellite web UI:
- Navigate to Configure > Classes and select the Puppet class you want to configure.
- Click the Smart Class Parameter tab and select the parameter you want to override.
- In the Default Behavior area, select the Override check box.
-
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
. - Select Add Matcher.
-
From the Attribute type menu, select
example_fact1,example_fact2
and in the box after the=
sign, entermyfact1,myfact2
. - 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.
- Click Submit.
On the client, send the facts from the client to the Puppet master:
# puppet agent --test
In the Satellite web UI:
- Navigate to Hosts > Content Hosts and select the name of the Content Host.
-
Click YAML and locate the
classes
section. Check that the parameter has the value you want.
3.11. Configuring Smart Variables
The following procedure configures Smart Variables to override a value in a Puppet class.
Configuring Smart Variables
- Click Configure > Puppet Classes.
- Select a class from the list.
- 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.
- Type a name for the parameter in the Key field.
- Edit the Description text box to add any plain text notes.
- Select the Key type of data to pass. This is most commonly a string, but other data types are supported.
- Enter a Default value for the parameter to be sent to the Puppet master if no host match occurs.
- Optional: Select Hidden value if the field contains data you do not want to be displayed while you are working.
- 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.
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
.- 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.
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 ofserver1.example.com
, then specify the matcher asfqdn=server1.example.com
and the Value astest
.The precedence for matching is as follows:
- If the matcher is a host attribute, use that.
- If there are no attributes with that name, look for a matching host parameter (which is inherited according to the parameter hierarchy).
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.
- Click Submit to save your changes.
For more information on ERB syntax see Template Writing Reference in Managing Hosts.
3.12. Importing Parameterized Classes from a Puppet Master
The following procedure imports parameterized classes from your Puppet master.
The import of parameterized classes happens automatically if your Puppet modules are managed via a Product and a Content View.
Importing Parameterized Classes
- In the Satellite web UI, select from the context menu Any Organization and Any Location.
- Click Configure > Puppet Classes.
- Click Import from Host Name to import parameterized classes from your Puppet master.
- The Puppet Classes page displays with the new classes listed.
3.13. 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.
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.9, “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.
- In the web UI, navigate to Configure > Classes.
- Select the name of the Puppet class from the list.
- 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.
- Click Add Variable to add a new parameter.
-
Enter the parameter in the Key field. In this example,
content_for_motd
. -
Edit the Description text box, for example
Testing /tmp motd Text
. - Select the Key type of data to pass. Select string.
-
Type a Default Value for the parameter. For example,
No Unauthorized Use
. - 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.
- 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.
-
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 ofserver1.example.com
, then specify the Match asfqdn=server1.example.com
and the Value asThis is for Server1
. - Click Submit to save your changes.