Installing Puppet Enterprise-only modules without internet access

I joined Puppet a little over a year ago to work on the Puppet Knowledge Base. We’ve organized the Puppet Knowledge Base with dedicated sections that:

  • Help administrators install and configure Puppet.
  • Offer insights about how to get the most out of new features in Puppet Enterprise.
  • Best practices for upgrading and managing Puppet.
  • How to integrate with Puppet, leveraging prebuilt modules for technologies such as AWS, Azure, Docker, Red Hat, VMware and much, much more.

Every day is an opportunity to put myself into your shoes, learn about Puppet Enterprise from our engineers, and help you solve problems. I worked with Alan Petersen (formerly of Professional Services) to write an article on how to install PE-only modules offline. Senior Support Engineer Adam Bottchen kindly agreed to help me bring it up to date for our most recent version.

How do I install a PE-only module on a machine that doesn't have internet access?

Version and installation information

PE version: 2016.2.x
OS: Any *nix

Depending on the security requirements of your infrastructure, you might have a Puppet master (or master of masters) that does not have access to the internet. Such Puppet masters can't download and install modules available only to PE customers (for example, the puppetlabs-vsphere module). You can only install these modules using the puppet module install command run from a Puppet master with a PE license and internet access.

Here's how to install PE-only modules when your Puppet master has no internet access.

Step 1: Download the module

To download the module, you need a machine that does have internet access, and with part of enough of PE on it to do module installation. There are two options:

  • Install a Puppet master on the internet-connected machine. This option uses only one installer, but requires stopping unnecessary services after installation.

    or

  • Install a Puppet agent on the internet-connected machine, and modify it to download modules. This option is cleaner than installing a Puppet master, because it does not create many extra resources. However, it does require some extra setup steps, including installing multiple packages and installing the pe-license package separately.

Review the following procedures to determine which one best suits your needs.

Option 1: Install a Puppet master and download the module

With this option, you install a Puppet master on a machine that can access the internet.

  1. Set up a machine that can access the internet.

  2. Download a PE installation tarball, or use the one you already have.

  3. Create a pe.conf file with the following contents:

{
  "console_admin_password": "null"
  "puppet_enterprise::puppet_master_host": "%{::trusted.certname}"
  "puppet_enterprise::console_host": "null"
  "puppet_enterprise::puppetdb_host": "null"
}
  1. Run the PE installer pointed at the pe.conf file: sudo ./puppet-enterprise-installer -c pe.conf.

  2. After the installation completes, stop the puppet and pe-puppetserver services:

    • puppet resource service puppet ensure=stopped

    • puppet resource service pe-puppetserver ensure=stopped

  3. Install your PE license key on the Puppet agent in the /etc/puppetlabs/ directory.

    Tip: Find the PE license key on the Puppet master at /etc/puppetlabs/license.key.

  4. Install the PE-only module into a temporary directory. For example, run puppet module install puppetlabs-vsphere --target-dir /tmp.

After the module downloads, transfer it through your infrastructure depending on your module installation method.

Option 2: Install and modify a Puppet agent, and download the module

With this option, you install a Puppet agent on a machine that can access the internet. Note that this Puppet agent should not be connected to your existing infrastructure.

  1. Set up a machine that can access the internet.

  2. Download the appropriate Puppet agent.

  3. Install the agent package. For example, for a RHEL 7 agent, run rpm -i puppet-agent-1.5.2-1.el7.x86_64.rpm.

  4. Install your PE license key on the Puppet agent in the /etc/puppetlabs/ directory.

    Tip: Find the PE license key on the Puppet master at /etc/puppetlabs/license.key.

  5. Copy the pe-license package from your Puppet master to the agent and install it by running rpm -i pe-license-0.1.5.7-1.pe.<PLATFORM>.noarch.rpm.

    Tip: Find the PE license package in the PE installation tarball, in the packages/public/<PE VERSION>/<PLATFORM AND ARCH>/ directory.

  6. Open the agent's puppet.conf file in an editor, and in the [main] section, add module_groups = base+pe_only.

  7. Install the PE-only module into a temporary directory. For example, run /opt/puppetlabs/bin/puppet module install puppetlabs-vsphere --target-dir /tmp.

After the module downloads, transfer it through your infrastructure, depending on how you normally install modules.

Step 2: Install the module

You have two options:

  • If you're using Code Management or r10k to manage your Puppet environments, add the module to your internal repo to make it available.

    or

  • If you're not using Code Management, install the module directly on the Puppet master.

Option 1: Install the module using Code Management

Transfer the module into your Git repo and add it to your control repo's Puppetfile:

  1. Check the module into your Git repo and copy the commit SHA.

  2. In your control repo, edit your Puppetfile to add the path to the module and the commit SHA. For example:

mod 'puppetlabs/vsphere',
  :git => 'https://gitlab.company.net/puppet/puppetlabs-vsphere',
  :ref => '00526d86dfb3487d9be893cbd3698c362132b6ac'

Note: Repeat this process whenever you update the module.

Option 2: Install the module directly on the Puppet master

  1. Create a tarball of the downloaded module. For example, run tar -czf puppetlabs-vsphere.tar.gz vsphere.

  2. Copy the tarball to your Puppet master.

    Tip: If your download machine does not have network access to the Puppet master, transfer the tarball with some transferable media.

  3. Install the module on the Puppet master. For example, run puppet module install -f ./puppetlabs-vsphere.tar.gz.

If you have compile masters, perform steps 2 and 3 on each compile master.

Note: Repeat this process whenever you update the module.

Troubleshooting

License or license package invalid or not properly installed

If your PE license or license package is invalid or not properly installed, you will see the following error:

# puppet module install puppetlabs-vsphere --target-dir /tmp
Notice: Preparing to install into /tmp ...
Notice: Downloading from https://forgeapi.puppetlabs.com ...
Error: Request to Puppet Forge failed.
  The server being queried was https://forgeapi.puppetlabs.com/v3/releases?module=puppetlabs-vsphere
  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-vsphere. If you have a Puppet Enterprise license, please see https://docs.puppetlabs.com/pe/latest/modules_installing.html#puppet-enterprise-modules for more information.'

To correct this issue, ensure that you have a valid license installed in the /etc/puppetlabs directory.

puppet.conf not properly configured

If you did not edit the [main] section of puppet.conf to contain module_groups = base+pe_only, you will see the following error:

# puppet module install puppetlabs-vsphere --target-dir /tmp
Notice: Preparing to install into /tmp ...
Notice: Downloading from https://forgeapi.puppetlabs.com ...
Error: Could not install 'puppetlabs-vsphere' (latest)
  No releases are available from https://forgeapi.puppetlabs.com
    Does 'puppetlabs-vsphere' have at least one published release?

To correct this error, ensure that the puppet.conf file is configured correctly.

In summary

Remember, we’re here to help. You don’t have to do it by yourself. Between our helpful team at Puppet, tons of resources including the support portal & knowledge base, documentation, Puppet Forge, training and our large community of Puppet users and customers, there’s a good chance you’ll have your answer sooner than you think.

Suzanne Baunsgard is an associate tech writer at Puppet. Adam Bottchen, senior support engineer at Puppet, also contributed to this post.

Learn more

  • Check out all the support services we offer Puppet Enterprise customers.

  • And check out all the learning resources available to you, whether you use PE or open source Puppet.

Puppet sites use proprietary and third-party cookies. By using our sites, you agree to our cookie policy.