Puppet Forge Premium Modules

Terms of Use

The use of each module within a premium tier is governed by its own license, which can be found either in its LICENSE file or on the corresponding tab on its page on the Forge.

Purchasing a premium module subscription entitles you to download a module and any updates for as long as your subscription is maintained. If your subscription expires, you are no longer entitled to use the module and will no longer have access to updates or any customer support that you purchased with the module.

You can access and deploy a module after configuring your system with an API key. For instructions, see the following sections. Modules can be installed on as many compile servers as needed for your load-balanced infrastructure, and they can be deployed in your continuous integration pipelines for testing purposes.

Configuring Download Access for Premium Content

Before you download a premium module, you must be a registered Forge user with an active API key.

You can access premium modules based on your personal profile if your registered email address is linked to an entitled Perforce customer account. However, the preferred method is to access premium modules through an entitled Forge organization, as described in Access premium modules.

Complete the following steps:

You can now use the API key for premium module downloads by using Code Manager, r10k, or Puppet Bolt ®:

• If you are a Puppet Enterprise (PE) 2021 or later user, use Code Manager to download premium modules.
• If you are an open source Puppet user, use r10k to download premium modules.
• If you are a Puppet Bolt ® user, use Bolt to download premium modules.

Install and deploy a premium module with Code Manager

If you are a Puppet Enterprise (PE) user, use Code Manager to install and deploy premium modules. Code Manager deploys the modules listed in your Puppetfile.

Restriction:

The following instructions are for installing and deploying a premium module by specifying global settings in Hiera. To test the deployment in a limited environment, configure Hiera for that limited environment. See Creating environments and Configuring Hiera.

Prerequisite:

You must have PE 2021 or later installed.

Procedure:

1. Log in to the PE host server.

2. Create the following file:

   /etc/puppetlabs/puppet/hiera.yaml

3. In the hiera.yaml file, specify the global Hiera configuration:

   # Hiera 5 Global configuration file
   version: 5
   defaults:
     datadir: "data"
   hierarchy:
     name: "Yaml backend"
     data_hash: yaml_data
     paths: "common.yaml"
   

4. Create a data subdirectory by running the following command:

   mkdir /etc/puppetlabs/puppet/data

5. In the data subdirectory, create a common.yaml file with the following configuration information:

   pe_r10k::forge_settings:
     authorization_token: 'Bearer <your API token>'
     baseurl: 'https://forgeapi.puppet.com'
   puppet_enterprise::master::code_manager::forge_settings:
     authorization_token: 'Bearer <your API token>'
   

6. To enforce the updated configuration, run the Puppet agent on your PE server with the following command:

   puppet agent –t

7. Add one or more premium modules to your Puppetfile. For instructions about configuring a Puppetfile, see Managing environment content with a Puppetfile.

8. To download the premium module, run Code Manager with the following command, where <environment> specifies the Puppet environment where the premium module will be downloaded:

   puppet code deploy <environment|--all> --wait

Install and deploy a premium module with Bolt

If you are a Puppet Bolt user, install premium modules with Bolt version 3.18.0 or later.

Add the following section to your bolt-project.yaml file to authorize your downloads:

# bolt-project.yaml
module-install:
  forge:
    authorization_token: 'Bearer <your API token>'
    baseurl: https://forgeapi.puppet.com

Then add the modules from your premium subscription to your project as usual. See the Bolt project documentation for more information about configuring your Bolt project.

Install and deploy a premium module with r10k

If you are an open source Puppet user, install and deploy premium modules with r10k 3.10.0 or later.

Complete the following steps:

1. Add the API key to the r10k configuration file, /etc/puppetlabs/r10k/r10k.yaml

   # r10k.yaml
   forge:
     authorization_token: 'Bearer <your API token>'
     baseurl: 'https://forgeapi.puppet.com'
   

2. Add the modules from your premium subscription to your Puppetfile. See the r10k documentation for more information about configuring a Puppetfile.

3. To deploy the modules, run the following command:

   r10k deploy environment

Tip: For more information about r10k, see Deploying environments with r10K or the readme file on GitHub.

Configure Puppet to use your API key

If you have a custom deployment script, you can install modules with the puppet module install command (for example, in a script you've written or to download modules with puppetlabs_spec_helper). To use this method, you must configure Puppet itself to use your API key.

Important: This is not the preferred method for installing premium modules. Before you use this method, review the other methods and select the best method for your system environment.

In the /etc/puppetlabs/puppet/puppet.conf file, add the following setting in the [main] section:

# puppet.conf
[main]
  forge_authorization = 'Bearer <your API token>'

Install a module in an air-gapped environment

If you have an air-gapped environment, you must manually download module tarballs and transfer them to the appropriate location. See Installing and managing modules from the command line.

FAQ

How can I download the module tarball with my browser?

You must be logged in to your Forge account to download the tarball with your browser. In Puppet Forge, click Log in and follow the prompts. Find the module that you want to download. The module's Start using this module section has a manual download option. In the INSTALLATION METHOD list, click Direct Download.

How do I buy a premium module subscription?

For a list of premium modules, see Puppet Forge. To contact a sales representative about purchasing a premium module subscription, complete the form on the Security Compliance Enforcement webpage.

How do I get access to the content if I lose my Forge credentials?

Email forge@puppet.com for assistance.

What if I lose the API token?

On your Forge profile page, in the API Keys section, revoke that key by clicking Revoke key. Then generate a new key by clicking Create a new key.

What if the person who purchased the subscription has left my company and we can't get into their Forge account?

Contact your sales representative, who can update your subscription to grant access to a company Forge account. To help prevent access issues in the future, consider creating an organization on Puppet Forge so that you can share premium modules with colleagues. For more information, see Benefits of Puppet Forge organizations.

What should I do if I've configured my system and still get a permission denied error?

Check the Puppet Support Portal for solutions and if needed, file a support request by clicking Log a Case.

What support level comes with the premium modules?

Support offerings vary for each type of premium module. Your sales representative can provide information about the support options available for the premium module you are interested in purchasing.

How do I get help if I'm having trouble with a module?

If you have a support contract with your module, you can file a support request. You must have an active support account. In the Puppet Support Portal, at the top right next to the Log in button, click Log a Case.

How do I authenticate to the Forge API with custom tools I've written?

For general HTTP request authentication, see the Forge API documentation for instructions. If you're using the forge-ruby gem, configure it with an API key, and the key will handle authorization for you.

Last Revised: December 24, 2024