Puppet Forge: Customize your user experience and track module downloads
With a Puppet Forge user account, you can enjoy a customized user experience and stay current with your module downloads. In the Downloads section of your user profile, you can view a list of your downloaded modules and compare your versions with the most recent versions on the Forge, based on the information in the changelog. In this way, you can help to ensure that your Puppet infrastructure is updated and reliable. In addition, you can audit your download activity.
To get started, ensure that you have a user account and upload your Puppetfile, which helps to determine the current state of the module inventory as compared to recent versions on Forge. To automatically sync your ongoing download activity, obtain an authorization token and use it to configure your download mechanisms (such as the r10k tool or Puppet Bolt®). For instructions, see the following topics.
Create a Forge user account
A Forge user account is required to use profile features like download tracking. If you don't have an account, complete the Create a Forge account form.
Upload your Puppetfile
To determine the current state of your module inventory, you can upload your Puppetfile to the Forge. Go to the Downloads section and use the Upload configurations action.
You can configure automatic download tracking, as described in the following sections. However, you can also manually upload your Puppetfile at any time. Note that this will clear your existing download activity.
Generate an API token
An application programming interface (API) token is required to track your download activity.
To generate an API token, open your Forge user profile. In the API Keys section, click Create a new key. Give the token a name (like "Downloads for production") and save the token in a secure location. You will not be able to view the full token again, but you can list or revoke existing tokens in the API Keys section of your Forge profile.
Depending on how you intend to download modules, you can configure r10k, Bolt, or Puppet with this token as described in the following sections.
Configure download tracking with r10k
To configure download tracking with r10k, you must use r10k 3.10.0 or later. The main configuration file for r10k is /etc/puppetlabs/r10k/r10k.yaml. In that file, add token information, using the API token you previously created:
# r10k.yaml
forge:
authorization_token: 'Bearer <your API token>'
baseurl: 'https://forgeapi.puppet.com'
Then add the modules you wish to download to your Puppetfile. For information about configuring a Puppetfile, see the r10k documentation.
Configure download tracking with Bolt
To configure download tracking with Bolt, you must use Bolt version 3.18.0 or later. Add token information to your bolt-project.yaml file to configure your downloads:
# bolt-project.yaml
module-install:
forge:
authorization_token: 'Bearer <your API token>'
baseurl: https://forgeapi.puppet.com
Then add the modules that you want to download to your project. For more information about configuring your Bolt project, see the Bolt project documentation.
Configure download tracking with Puppet
To install modules with the puppet module install command (for example, in a script you've written or to download modules with puppetlabs_spec_helper), you must configure Puppet to use your API token.
In the /etc/puppetlabs/puppet/puppet.conf file, add the following setting in the [main] section:
# puppet.conf
[main]
authorization_token: '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 the module installation docs for instructions.
FAQ
I usually download the module tarball with my browser. Will this download be included as part of my profile downloads?
You must be logged in to your Forge account to record the download with your browser. At the top of the Welcome to Puppet Forge webpage, click Log in and enter your credentials. Then use the manual download option from the module page.
What if I lose the API token?
Use your Forge profile page to revoke that token and generate a new one.
How do I get help if I'm having trouble with a module?
Please post your queries in the #forge-modules Slack channel maintained by the Puppet Community.
How do I configure the Forge API with custom tools I've written?
For general HTTP request authentication, see the Forge API docs for instructions. If you're using the forge-ruby gem, configure the gem with an API token, which will handle authorization.
Last Revised: March 07, 2024