This page explains how to install and manage modules using the puppet module command.
build and generate actions.puppet moduleThe Puppet Forge is a repository of modules written both by Puppet and by the Puppet user community. These modules solve a wide variety of problems, and using them can save you time and effort.
The puppet module tool provides a command line interface for managing modules from the Forge. Its interface is similar to several common package managers (such as gem, apt-get, or yum). You can use the puppet module command to search for, install, and manage modules.
Important: If you are using Code Manager or r10k, do not use the
puppet modulecommand to install or manage modules. Instead, use a Puppetfile to manage modules in your environments. In particular, note that Code Manager purges modules that were installed to the live code directory with thepuppet modulecommand.
Solaris Note: To use
puppet modulecommands on Solaris systems, you must first install gtar.
puppet module behind a proxyTo use the puppet module command behind a proxy, set the following, replacing <PROXY IP> and <PROXY PORT> with the proxy’s IP address and port:
export http_proxy=http://<PROXY IP>:<PROXY PORT>
export https_proxy=http://<PROXY IP>:<PROXY PORT>
For instance, with an HTTP proxy at 192.168.0.10 on port 8080, set:
export http_proxy=http://192.168.0.10:8080
export https_proxy=http://192.168.0.10:8080
Alternatively, you can set these two proxy settings inside the [user] config section in the puppet.conf file: http_proxy_host and http_proxy_port. For more information, see the configuration reference.
Important: Make sure to set these two proxy settings in the
usersection only. Otherwise, there can be adverse effects.
You can find modules by browsing the Puppet Forge on the web or by using the module tool’s search action.
The Forge houses thousands of modules, including Puppet supported or approved modules. Puppet approved modules pass our specific quality and usability requirements. These modules are recommended by Puppet, but are not supported as part of a Puppet Enterprise license agreement. Puppet supported modules have been tested with Puppet Enterprise and are fully supported by Puppet. If there are no supported or approved modules for what you want to do, evaluate available modules by score, compatibility, documentation, last release date, and number of downloads.
The search action accepts a single search term and returns a list of modules whose names, descriptions, or keywords match the search term.
$ puppet module search apache
Searching http://forge.puppetlabs.com ...
NAME DESCRIPTION AUTHOR KEYWORDS
puppetlabs-apache This is a generic ... @puppetlabs apache web
puppetlabs-passenger Module to manage P... @puppetlabs apache
DavidSchmitt-apache Manages apache, mo... @DavidSchmitt apache
jamtur01-httpauth Puppet HTTP Authen... @jamtur01 apache
jamtur01-apachemodules Puppet Apache Modu... @jamtur01 apache
adobe-hadoop Puppet module to d... @adobe apache
Once you’ve identified the module you want, you can install it.
The puppet module install action installs a module and all of its dependencies. By default, it installs into the first directory in Puppet’s modulepath, which defaults to $codedir/environments/production/modules. (See also: more about the modulepath and how to find the codedir.)
sudo puppet module install puppetlabs-apache
This command accepts the following options:
--target-dir option to specify a different directory for installation. Relatedly:
--environment option to install into a different environment. (Each environment has its own modulepath, which is used to calculate dependencies and choose a default value for --target-dir.)--modulepath option to manually specify a modulepath, instead of using an environment’s.--version option to specify a version of the module. You can use an exact version or a requirement string like >=1.0.3.--force option to forcibly install a module or re-install an existing module. (Note: Does not install dependencies.)--ignore-dependencies option to skip installing any modules required by this module.--debug option to see additional information about what the Puppet module tool is doing.Note: Invalid Version Warnings
If any installed module has an invalid version number (anything other than major.minor.patch), Puppet issues the following warning whenever you install a module:
Warning: module (/Users/youtheuser/.puppet/modules/module) has an invalid version number (0.1). The version has been set to 0.0.0. If you are the maintainer for this module, please update the metadata.json with a valid Semantic Version (http://semver.org).Despite the warning, Puppet still downloads your module and does not permanently change the offending module’s metadata. The version is only changed in memory during the run of the program, in order to calculate dependencies for the modules you’re installing.
To install a module from the Puppet Forge, identify the module you want by its full name. The full name of a Forge module is formatted as username-modulename.
sudo puppet module install puppetlabs-apache
The module tool can install modules from other repositories that mimic the Forge’s interface. To do this, change the module_repository setting in puppet.conf or specify a repository on the command line with the --module_repository option. The value of this setting should be the base URL of the repository; the default value, which uses the Forge, is https://forgeapi.puppetlabs.com.
After setting the repository, follow the instructions above for installing from the Forge.
sudo puppet module install --module_repository http://dev-forge.example.com puppetlabs-apache
To install a module from a release tarball, specify the path to the tarball instead of the module name.
If you cannot connect to the Puppet Forge, or you are installing modules that have not yet been published to the Forge, use the --ignore-dependencies flag. In this case, you must manually install any dependencies.
sudo puppet module install ~/puppetlabs-apache-0.10.0.tar.gz --ignore-dependencies
Note: You can manually install modules without the
puppet moduletool. If you do, you must name your module’s directory appropriately. Module directory names can only contain letters, numbers, and underscores. Dashes and periods are not valid and cause errors when attempting to use the module.
We publish some premium modules exclusively for Puppet Enterprise users. To install a Puppet Enterprise module you must:
After you’ve run puppet module install puppetlabs-<MODULE> you can move the installed module to the directory, server, or version control system repository of your choice.
If you need to install a PE-only module on a PE node that doesn’t have internet access, move the package:
puppet module install puppetlabs-<MODULE> on a licensed node with internet access.puppet module build to build the newly-installed module.puppet module install against the tar.gz.As mentioned in the instructions for installing from a tarball, when installing on a node without internet access, you must manually install any dependencies.
Use the module tool’s list action to see which modules you have installed (and which directory they’re installed in).
--tree option to view the modules arranged by dependency instead of by location on disk.Use the module tool’s upgrade action to upgrade an installed module to the latest version. You must identify the target module by its full name (username-modulename).
--version option to specify a version.--ignore-changes option to upgrade the module while ignoring and overwriting any local changes that might have been made.--ignore-dependencies option to skip upgrading any modules required by this module.Use the module tool’s uninstall action to remove an installed module. You must identify the target module by its full name (username-modulename).
$ sudo puppet module uninstall apache
Error: Could not uninstall module 'apache':
Module 'apache' is not installed
You may have meant `puppet module uninstall puppetlabs-apache`
$ sudo puppet module uninstall puppetlabs-apache
Removed /etc/puppetlabs/code/modules/apache (v0.0.3)
By default, the tool won’t uninstall a module that other modules depend on, or whose files have been edited since it was installed.
--force option to uninstall even if the module is depended upon or has been manually edited.--ignore-changes option to uninstall the module while ignoring and overwriting any local changes that might have been made.If you manage Puppet Enterprise modules with librarian-puppet, you must first install the module, and then commit the module to your version control repository.
To upgrade your Puppet Enterprise module, as with installation, you must:
puppet module actionsView a full description of each action with puppet man module or by viewing the man page online. The main actions of the puppet module command are:
installInstalls a module from either the Forge or a release archive.
sudo puppet module install puppetlabs-apache --version 0.0.2
Accepts the following options:
--target-dir: Specify a different directory for installation.--environment: Install into a different environment.--modulepath: Specify a different modulepath.--version: Specify a version of the module. Accepts an exact version or a requirement string like >=1.0.3.--force: Forcibly install a module or re-install an existing module. (Note: Does not install dependencies.)--ignore-dependencies: Skips installing any modules required by this module.--debug: Displays additional information about what puppet module is doing.listLists installed modules.
sudo puppet module list
searchSearches the Forge for a module.
sudo puppet module search apache
uninstallUninstalls a Puppet module.
sudo puppet module uninstall puppetlabs-apache
upgradeUpgrades a Puppet module.
sudo puppet module upgrade puppetlabs-apache --version 0.0.3
When installing or upgrading a Puppet Enterprise module, you might receive an error like the following:
Error: Request to Puppet Forge failed.
The server being queried was https://forgeapi.puppetlabs.com/v3/releases?module=puppetlabs-f5&module_groups=base+pe_only
The HTTP response we received was '403 Forbidden'
The message we received said 'You must have a valid Puppet Enterprise license on this node in order to download puppetlabs-f5. If you have a Puppet Enterprise license, please see https://docs.puppetlabs.com/pe/latest/modules_installing.html#puppet-enterprise-modules for more information.'
If you aren’t a Puppet Enterprise user, you won’t be able to use this module unless you purchase Puppet Enterprise.
If you are a Puppet Enterprise user, check the following:
puppet module install or puppet module upgrade command? If not, you must use the Puppet module subcommands to install or upgrade Puppet Enterprise modules./opt/puppetlabs/bin/r10k? If not, run r10k from that location.