Vagrant PE build

Download and install Puppet Enterprise with Vagrant.

Synopsis

vagrant-pe_build manages the downloading and installation of Puppet Enterprise on Vagrant boxes to rapidly build a functioning Puppet environment.

Quickstart

Note: This project is part of a larger suite of tools. For an easier way to build a PE infrastructure with Vagrant, check out the parent project: https://github.com/oscar-stack/oscar This documentation should be used when you're using this plugin alone.

To use this Vagrant plugin, you must first have a working Vagrant setup. The examples below assume you're using Virtualbox for virtualization. If you're using another virtualization system, you will have to make adjustments to your Vagrantfile.

Install the plugin by typing: vagrant plugin install vagrant-pe_build

Next, you'll need to manaually download the version of Puppet Enterprise you would like to use. At the time of writing, the latest version is 2018.1.3. https://puppet.com/download-puppet-enterprise (Make sure to download the version for CentOS 7.)

Once that is finished downloading, copy it into a pe_build staging area (defaults to ~/.vagrant/pe_builds) by running this command: vagrant pe-build copy puppet-enterprise-2018.1.3-el-7-x86_64.tar.gz

Then create a Vagrantfile that looks like this:

Vagrant.configure('2') do |config|
  config.pe_build.version = '2018.1.3'

  config.vm.define 'master' do |node|
    node.vm.hostname = 'master.localdomain'
    node.vm.box = 'puppetlabs/centos-7.2-64-nocm'

    node.vm.provision :pe_bootstrap do |p|
      p.role = :master
    end
  end

  config.vm.define 'agent' do |node|
    node.vm.box = 'puppetlabs/centos-7.2-64-nocm'
    node.vm.provision "shell", inline: "echo < YOUR MASTER IP > master.localdomain master | sudo tee -a /etc/hosts"
    node.vm.provision :pe_agent do |p|
      p.master_vm = 'master.localdomain'
    end
  end
end

And then run vagrant up master and after PE is installed, you'll need to manually discover the master's IP and add it to the Vagrantfile.

To do this, type vagrant ssh master and then type ip addr and copy the IP, and paste it into the command for the shell provisioner on the agent.

Finally, to create the agent type vagrant up agent. This entire process is much easier if you use the parent project: https://github.com/oscar-stack/oscar

Vagrantfile Settings

Global config.pe_build Settings

These settings go in the config object namespace and act as defaults in the event multiple machines are being provisioned. These settings are optional and can be overridden in a VM's individual provisioner config.

• config.pe_build.version
  • Description: The version of Puppet Enterprise to install.
• config.pe_build.series
  • Description: An arbitrary string that can be interpolated into URLs.
• config.pe_build.version_file
  • Description: A fully-qualified URI or a path relative to download_root. The contents of this file will be read and used to set version --- overriding any value that may already be set.
• config.pe_build.suffix - Suffix of the Puppet Enterprise installer to use.
  • Description: The distribution specific suffix of the Puppet Enterprise installer to use.
  • Default: :detect
• config.pe_build.filename
  • Description: The filename of the Puppet Enterprise installer.
  • Default: this will use the version and suffix provided to guess a filename of the form puppet-enterprise-<version>-<suffix>.tar.gz.
• config.pe_build.download_root
  • Description: The URI to the directory containing Puppet Enterprise installers if the installer is not yet cached. This setting is optional.
  • Supported URI schemes:
    • http
    • https
    • ftp
    • file
    • A blank URI will default to file.
• config.pe_build.shared_installer
  • Description: Whether to run PE installation using installers and answers shared using the /vagrant directory. If set to false, resources will be downloaded remotely from download_root to the home directory of whichever user account Vagrant is using. Defaults to true.

NOTE: Any occurrence of the string :version or :series in the the strings set as version_file or download_root will be replaced by the corresponding version and series configuration values.

pe_bootstrap Provisioner Settings

These settings are on a per provisioner basis. They configure the individual behaviors of each provisioner instance. All of the config.pe_build options can be overridden at this point.

• role
  • Description: The role of the Puppet Enterprise install.
  • Options: :agent, :master. :agent has been deprecated starting with PE 2015.2.0 and is no longer valid for PE 2016.2.0 having been replaced by a dedicated pe_agent provisioner described below.
  • Default: :agent for PE < 2016.2.0 and :master for PE >= 2016.2.0.
• verbose
  • Description: Whether or not to show the verbose output of the Puppet Enterprise install.
  • Options: true, false
  • Default: true
• master
  • Description: The address of the puppet master
  • Default: master
• answer_file
  • Description: The location of alternate answer file for PE installation. Values can be paths relative to the Vagrantfile's project directory.
  • Default: The default answer file for the Puppet Enterprise version and role.
• answer_extras
  • Description: An array of strings that will be appended to the answer file template, one string per line. This can be used to supply additional answers and override default answers.
  • Default: An empty array.
• relocate_manifests
  • Description: Whether or not to change the PE master to use a config of manifestdir=/manifests and modulepath=/modules. This is meant to be used when the vagrant working directory manifests and modules are remounted on the guest.
  • Options: true, false
  • Default: false
• autosign
  • Description: Whether or not to configure a PE master with an autosign.conf which accepts all incoming cert requests.
  • Options: true, false
  • Default: true

pe_agent Provisioner Settings

The pe_agent provisioner installs the Puppet Agent for PE 2015.2.0 and above and, optionally, configures PE Master VMs to support the new agent.

NOTE: The pe_agent provisioner currently does not share any configuration with the global config.pe_build settings.

• master_vm
  • Description: The name of a VM in the current Vagrant environment which hosts the Puppet master that the agent should be connected to. When this is set, the master, autosign and autopurge settings are populated with default values. If the master_vm setting is not used, then the master setting must be populated with the hostname of the Puppet Master.
  • Default: nil.
• autosign
  • Description: An boolean switch which controls whether or not to sign the agent's certificate after installation. Requires master_vm to be set.
  • Options: true, false
  • Default: true, if master_vm is set.
• autopurge
  • Description: An boolean switch which controls whether or not to clean the agent's certificate from the master and purge agent data from PuppetDB when the agent VM is destroyed. Requires master_vm to be set.
  • Options: true, false
  • Default: true, if master_vm is set.
• master
  • Description: The hostname or fqdn of the puppet master. Must be specified if master_vm is not set.
  • Default: nil. Defaults to vm.hostname of the Puppet Master if master_vm is set and master_vm if vm.hostname is not set.
• version
  • Description: The version number of the PE Agent to install. NOTE: Currently, agents always receive the 'current' version installed on the master. Support for setting the version number of agents will be added in a future release. * Options: A version string, x.y.z[-optional-stuff], or the string 'current'.
  • Default: 'current'.
• agent_type
  • Description: The type of agent to provision. This can be set to a agent, compile master, or an HA replica. Some automations are built in to configure the specified agent type on the primary master. Possible values are 'agent', 'replica', 'compile'
  • Default: 'agent'.

Commands

Other Usage Examples

Minimal PE 2015.x configuration

Same as above, but uses pe_agent to provision agent nodes instead of pe_bootstrap.

Vagrant.configure('2') do |config|
  config.pe_build.version = '2015.3.3'

  config.vm.define 'master' do |node|
    node.vm.box = 'puppetlabs/centos-7.2-64-nocm'

    node.vm.provision :pe_bootstrap do |p|
      p.role = :master
    end
  end

  config.vm.define 'agent1' do |node|
    node.vm.box = 'puppetlabs/centos-7.2-64-nocm'
    node.vm.provision :pe_agent do |p|
      p.master_vm = 'master'
    end
  end
end

Specifying a download root

Vagrant.configure('2') do |config|
  config.pe_build.version = '3.8.4'
  config.pe_build.download_root = 'http://my.pe.download.mirror/installers'

  # Alternately, a local directory can be specified
  #config.pe_build.download_root = 'file://Users/luke/Downloads'

  config.vm.define 'master' do |node|
    node.vm.box = 'puppetlabs/centos-7.2-64-nocm'

    node.vm.provision :pe_bootstrap do |p|
      p.role = :master
    end
  end

  config.vm.define 'agent1' do |node|
    node.vm.box = 'puppetlabs/centos-7.2-64-nocm'

    node.vm.provision :pe_bootstrap
  end
end

Using a manual answers file

Vagrant.configure('2') do |config|
  config.pe_build.version = '3.8.4'
  config.pe_build.download_root = 'http://my.pe.download.mirror/installers'

  # Alternately, a local directory can be specified
  #config.pe_build.download_root = 'file://Users/luke/Downloads'

  config.vm.define 'master' do |node|
    node.vm.box = 'puppetlabs/centos-7.2-64-nocm'

    node.vm.provision :pe_bootstrap do |p|
      p.role = :master
      p.answer_file = 'answers/vagrant_master.answers.txt'
    end
  end

  config.vm.define 'agent1' do |node|
    node.vm.box = 'puppetlabs/centos-7.2-64-nocm'

    node.vm.provision :pe_bootstrap
  end
end

Manually setting an installer filename

Vagrant.configure('2') do |config|
  config.pe_build.version  = '3.8.4'
  config.pe_build.filename = 'puppet-enterprise-3.8.4-el-7-x86_64.tar.gz'

  config.vm.define 'master' do |node|
    node.vm.box = 'puppetlabs/centos-7.2-64-nocm'

    node.vm.provision :pe_bootstrap do |p|
      p.role = :master
    end
  end

  config.vm.define 'agent1' do |node|
    node.vm.box = 'puppetlabs/centos-7.2-64-nocm'

    node.vm.provision :pe_bootstrap
  end
end

Requirements

Ensure VMs have a FQDN set before installing PE. The easiest way to do this is by setting the hostname attribute of the VM configuration.

Puppet Enterprise relies on SSL for security so you'll need to ensure that your SSL configuration isn't borked. vagrant-hosts is recommended to configure VMs with semi-sane DNS.

Guest VMs need to be able to directly communicate. You'll need to ensure that they have private network interfaces prepared.

Contact

• Source code
• Issue tracker