Installing modules

If you want to get started with a new Bolt project and you need specific modules from the Puppet Forge, you can install the modules and their dependencies using the Bolt command line.

When you create a project with the modules command-line option and a comma-separated list of Forge modules, Bolt installs the latest versions of each module and resolves and installs all dependencies required by those modules. For example, to turn the current directory into a project named example_project with the puppetlabs/apache and puppetlabs/mysql modules installed, use the following command:

*nix shell command

bolt project init example_project --modules puppetlabs-apache,puppetlabs-mysql

PowerShell cmdlet

New-BoltProject -Name example_project -Modules puppetlabs-apache,puppetlabs-mysql

The project's Puppetfile lists the puppetlabs/apache and puppetlabs/mysql modules and all of their dependencies:

# example_project/Puppetfile
mod 'puppetlabs-apache', '5.5.0'
mod 'puppetlabs-mysql', '10.6.0'
mod 'puppetlabs-stdlib', '6.3.0'
mod 'puppetlabs-concat', '6.2.0'
mod 'puppetlabs-translate', '2.2.0'
mod 'puppetlabs-resource_api', '1.1.0'
mod 'puppetlabs-puppetserver_gem', '1.1.1'

Before you use the Bolt command line to install a module to an existing project, make sure the project is configured to use dependency management. If your bolt-project.yaml file contains a modules key, your project is set up for dependency management. If your bolt-project.yaml file does not contain a modules key, migrate your project.

To update the modules in your project, run:

*nix shell command

bolt module install --force

Powershell cmdlet

Install-BoltModule -Force

Bolt updates your modules to the latest available versions and attempts to resolve all of the modules in the project configuration file to ensure that there are no version conflicts between modules and their dependencies.

In most cases, you can use the Bolt command line to install a new module. However, there are times when you might want to manually specify a module instead of using the Bolt command line. For example, you might want to add a git module, which is not supported through the command line, or you might want to add a large number of modules to your project at once and you don't want to string together multiple commands.

To manually specify a module in a Bolt project, add a specification to the project configuration file bolt-project.yaml. Specifications are listed under the modules key, and include specific keys depending on the type of module specified.

If you need to install a module from a private git repository, see Skip dependency resolution.

If you need to pin a module in your Bolt project to a specific version, you can add a version requirement to the module in your bolt-project.yaml and run the install command with the force option.

Follow these steps to pin a module version:

1. Find the module under the modules key in your bolt-project.yaml file.

2. Add a version_requirement key that specifies the version requirements for the module. For example, the following bolt-project.yaml file sets the version requirement for the puppetlabs/apache module to greater than or equal to 4.0.0, but less than 6.0.0:

   # bolt-project.yaml
   ...
   modules:
   - name: puppetlabs/apache
     version_requirement: '>= 4.0.0 < 6.0.0'

3. Run the following command. The force option is required because you've made a change to your bolt-project.yaml file, and it no longer matches the Puppetfile.

   *nix shell command

   bolt module install --force 

   Powershell cmdlet

   Install-BoltModule -Force

When you run the install command with the force option, Bolt attempts to resolve all of the modules in the project configuration file to ensure that there are no version conflicts between modules and their dependencies. Bolt fails with an error message if it cannot resolve a dependency due to a version requirement.

🔩 Tip: For information on how to specify module versions, see the Puppet documentation on Specifying versions.

You can configure Bolt to use a Forge other than the Puppet Forge when it installs Forge modules. To configure Bolt to use an alternate Forge, set the module-install configuration option in either your project configuration file, bolt-project.yaml, or the default configuration file, bolt-defaults.yaml.

To use an alternate Forge for installing Forge modules, set the baseurl key under the forge section of the module-install option:

# bolt-project.yaml
module-install:
  forge:
    baseurl: https://forge.example.com

📖 Related information

• bolt-project.yaml options

• bolt-defaults.yaml options

If your workstation cannot connect directly to the internet, you can configure Bolt to use a proxy when it installs modules. To configure Bolt to use a proxy when it installs modules, set the module-install configuration option in either your project configuration file, bolt-project.yaml, or the default configuration file, bolt-defaults.yaml.

To set a global proxy that is used for installing Forge and git modules, set the proxy key under module-install:

# bolt-project.yaml
module-install:
  proxy: https://proxy.com:8080

You can also set a proxy that is only used when installing Forge modules. To set a proxy for installing Forge modules, set the proxy key under the forge section of the module-install option:

# bolt-project.yaml
module-install:
  forge:
    proxy: https://forge-proxy.com:8080

If you need to install modules that require an authorization token to download, you can configure Bolt to pass a token as part of the request it makes to the Forge host. To configure Bolt to use an authorization token, set the module-install configuration option in either your project configuration file, bolt-project.yaml, or the default configuration file, bolt-defaults.yaml.

To set an authorization token that is used when installing Forge modules, set the authorization_token key under the forge section of the module-install option. When you set the authorization_token key, you must also set the baseurl key.

# bolt-project.yaml
module-install:
  forge:
    authorization_token: Bearer eyJhbGciOiJIUzI1NiIsInR5c...
    baseurl: https://forge.example.com

📖 Related information

• bolt-project.yaml options

• bolt-defaults.yaml options

Skipping dependency resolution for a module allows you to take advantage of Bolt's module dependency resolution while still using modules that Bolt cannot resolve dependencies for.

You might want to skip dependency resolution for a module if:

• The module has outdated or incorrect metadata.

• Bolt can't cleanly resolve the module's dependencies.

You can configure Bolt to skip dependency resolution for a module by setting the resolve key for the module specification to false. This key is available for both Forge and git modules.

When you install modules with Bolt, it only resolves module dependencies for module specifications that do not set resolve: false. After resolving dependencies, Bolt generates a Puppetfile with the resolved modules and dependencies, as well as the modules it did not resolve dependencies for.

For example, if your project includes the puppetlabs/ntp Forge module and a git module named private_module that has incorrect metadata, you can configure Bolt to skip dependency resolution for private_module:

# bolt-project.yaml
name: myproject
modules:
  - puppetlabs/ntp
  - name: private_module
    git: git@github.com:puppetlabs/private_module
    ref: 1.0.0
    resolve: false

Note: When setting resolve: false for a git module, you must include the name key.

When you install the project's modules, Bolt resolves dependencies for the puppetlabs/ntp module, skips dependency resolution for private_module, and generates a Puppetfile similar to this:

# This Puppetfile is managed by Bolt. Do not edit.
# For more information, see https://pup.pt/bolt-modules

# The following directive installs modules to the managed moduledir.
moduledir '.modules'

mod 'puppetlabs/ntp', '8.5.0'
mod 'puppetlabs/stdlib', '6.5.0'
mod 'private_module',
  git: 'git@github.com:puppetlabs/private_module'
  ref: '1.0.0'

Because Bolt skips dependency resolution for module specifications that set resolve: false, you'll need to include any dependencies for these modules in your project configuration. For example, if private_module included the following dependency in its metadata.json file:

{
  . . .
  "dependencies": [
    {
      "name": "puppetlabs/docker",
      "version_requirement": ">= 3.0.0"
    }
  ]
}

You would add the dependency to your project configuration:

# bolt-project.yaml
name: myproject
modules:
  - puppetlabs/ntp
  - name: private_module
    git: git@github.com:puppetlabs/private_module
    ref: 1.0.0
    resolve: false
  - name: puppetlabs/docker
    version_requirement: '>= 3.0.0'

If Bolt can't resolve your module dependencies, you can manage your project's Puppetfile manually and use Bolt to install the modules listed in the Puppetfile without resolving dependencies. The process for manually managing your modules uses the new module subcommand, and replaces the now deprecated puppetfile subcommand.

To manually manage a project's Puppetfile and install modules without resolving dependencies, follow these steps:

1. Create a file named Puppetfile in your project directory and add the modules you want to install, including each module's dependencies, to the Puppetfile. For example:

   mod 'private-module',
    git: 'https://github.com/bolt-user/private-module.git',
    ref: 'main'
   mod 'puppetlabs/apache', '5.7.0'
   mod 'puppetlabs/stdlib', '6.5.0'
   mod 'puppetlabs/concat', '6.3.0'
   mod 'puppetlabs/translate', '2.2.0'

2. Install the modules in the Puppetfile without resolving dependencies:

   *nix shell command

   bolt module install --no-resolve

   PowerShell cmdlet

   Install-BoltModule -NoResolve

Bolt installs modules in the Puppetfile to the .modules/ directory in your project directory. If you need to add or remove modules to the project, update your Puppetfile and run the above command again.

If you created a Bolt project before module dependency management was introduced, you can use Bolt's built-in migration tool to update your project.