Red Hat Training

A Red Hat training course is available for Red Hat Satelitte

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

  1. Login to your Red Hat Satellite 6 Server.
  2. Navigate to Content > Products.
  3. Click + New Product.
  4. Provide your custom Product with a Name. In this example, use MyProduct as the name.
  5. The Label field automatically populates with a label based on the Name.
  6. Provide a GPG Key, Sync Plan, and a Description if required. For our example, leave those fields blank.
  7. 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

  1. On the Products page, click on the custom Product created previously (MyProduct).
  2. Navigate to the Repositories subtab.
  3. Click Create Repository.
  4. Provide the repository with a Name. This example uses the name MyRepo.
  5. The Label field automatically populates with a label based on the Name.
  6. Select puppet as the repository Type.
  7. Leave the URL field blank. This field is used for remote repositories, but in our case Satellite 6 creates its own repository.
  8. 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.

  1. Click the Name of the newly created repository.
  2. In the Upload Puppet Module section, click Browse and select the mymodule archive.
  3. 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.

  1. On the Products page, click on the custom Product containing the module to remove.
  2. Click the Name of the repository containing the module to remove.
  3. Click Manage Puppet Modules. The screen displays a list of Puppet modules contained within the repository.
  4. Select the modules to remove.
  5. 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:

  1. Run puppet module build Module_Directory once.
  2. Delete the Modulefile.
  3. Check the updated metadata.json file into the revision control repository.
Note

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

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

  2. 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 from git@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

  1. Create a directory on the web server to synchronize the modules.

    # mkdir /var/www/html/puppet-modules
    # chmod 755 /var/www/html/puppet-modules
  2. 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 from git@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

  1. On the Products page, click on the custom Product created previously (MyProduct).
  2. Navigate to the Repositories subtab.
  3. Click Create Repository.
  4. Provide the repository with a Name. This example uses the name MyGitRepo.
  5. The Label field automatically populates with a label based on the Name.
  6. Select puppet as the repository Type.
  7. 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/
  8. Click Save.
  9. 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

  1. Navigate to Content > Content Views.
  2. Click + Create New View.
  3. Provide your view with a Name. In this example, we use MyView as the name.
  4. The Label field automatically populates with a label based on the Name.
  5. Make sure Composite Content View is not selected.
  6. Click Save.
  7. Select the Name of your newly created view.
  8. Navigate to Content > Repositories.
  9. 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.
  10. Navigate to Puppet Modules.
  11. Click + Add New Module.
  12. Scroll to your module and click Select a Version.
  13. Scroll to the module version Use Latest and click Select Version.
  14. Our module is now a part of the content view. Navigate to Versions to publish and promote a new version of the content view.
  15. Click Publish New Version. On the Publish New Version page, click Save. This publishes the content view with our module.
  16. 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 click 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.

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 on the "Import from" button. The button name will be 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. Configuring Smart Class Parameters from Puppet Classes

Some module classes contain complex parameters, called Smart Class Parameters, that define a value for a key just as a simple parameter does, but allow conditional arguments, validation, and overrides for specific object types. Satellite 6 has the ability to import these parameterized classes and allow modification of such smart parameters. For more information on the types of parameters in Puppet, see Parameters in the Red Hat Satellite Host Configuration Guide.

For example, mymodule contains a parameter for the HTTP port of our web server. This parameter, httpd_port, is set to a default of 8120. However, a situation might occur where we need to use a different port for a provisioned system. Satellite 6 can override the httpd_port parameter during configuration. This provides an easy way to change the HTTP port on our web server.

This procedure requires the mymodule module to be uploaded to a Product and added to a Content View. This is because we need to edit the classes in the resulting Puppet environment. Alternatively, you can download and install another module as described in Chapter 3, Adding Puppet Modules to Red Hat Satellite 6.

  1. Navigate to Configure > Smart class parameters.
  2. A table appears listing all Smart Class Parameters from the classes in your Puppet modules. Enter httpd_port in the search field. Click on the httpd_port parameter.
  3. The options for the Smart Class Parameter appears. To allow overriding this parameter during provisioning, select the Override option.
  4. Selecting the Override option allows us to change the Key type and Default value. This is useful if we aim to globally change this value for all future configurations.

    The following key types are available:

    String

    The value is interpreted as a plain text string. For example, if your Smart Class Parameter sets the host name, the value is interpreted as a string:

    myhost.example.com
    Boolean

    The value is interpreted and validated as a true or false value. Examples include:

    True
    true
    1
    Integer

    The value is interpreted and validated as an integer value. Examples include:

    8120
    -8120
    Real

    The value is interpreted and validated as a real number value. Examples include:

    8120
    -8120
    8.12
    Array

    The value is interpreted and validated as a JSON or YAML array. For example:

    ["Monday","Tuesday","Wednesday","Thursday","Friday"]
    Hash

    The value is interpreted and validated as a JSON or YAML hash map. For example:

    {"Weekdays": ["Monday","Tuesday","Wednesday","Thursday","Friday"], "Weekend": ["Saturday","Sunday"]}
    YAML

    The value is interpreted and validated as a YAML file. For example:

    email:
      delivery_method: smtp
      smtp_settings:
        address: smtp.example.com
        port: 25
        domain: example.com
        authentication: none
    JSON

    The value is interpreted and validated as a JSON file. For example:

    {
      "email":[
        {
          "delivery_method": "smtp"
          "smtp_settings": [
            {
              "address": "smtp.example.com",
              "port": 25,
              "domain": "example.com",
              "authentication": "none"
            }
          ]
        }
      ]
    }

    For this example, leave the default as 8120.

  5. Selecting the Override option also exposes Optional Input Validator, which provides validation for the overridden value. For example, we can include a regular expression to make sure httpd_port is a numerical value. For our example, leave this section blank.
  6. Selecting the Override option also exposes Prioritize attribute order, which defines a hierarchical order of system facts, and Specify matchers. The matcher-value combinations determine the right parameter to use depending on an evaluation of the system facts. For our example, leave these sections with the default settings.
  7. Click Submit.

We now have an override value for the Smart Class Parameter httpd_port.

3.9. 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.8, “Configuring Smart Class Parameters from Puppet Classes”.

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