Puppet Enterprise 2017.2

The Puppet Plug-in for vRealize Automation (vRA) provides tools and out-of-the-box components that easily create, provision, and manage application stacks on virtual servers.

Note: This user guide walks you through setting up a reference implementation of the plug-in, vRO, and vRA, and isn’t designed for out-of-the-box use in production. Once you’ve completed this guide, you should have a working environment and examples with which you can develop your own Puppet code, vRO workflows, and vRA blueprints.

Super quick start

Follow the Getting Started instructions included with the starter content if you’re familiar with installing Puppet Enterprise and working with vRA/vRO, or if you just want to see a condensed plan for creating a reference implementation with vRA 7.3 Enterprise and Puppet Enterprise 2016.4 or newer.

Note: These docs assume vRA 7.3 Enterprise and building your own blueprints with the new Puppet component in the vRA GUI. You can still access the previous version of these docs for working with vRA 7.x and IaaS blueprints with custom Puppet properties and the two prebuilt blueprints which can be found on this branch of the starter content.

What the Puppet plug-in can do

With a single click, Puppet, vRealize Orchestrator (vRO), and vRA can automatically create a VM, install the Puppet agent, autosign its certificate, add Puppet roles and profiles, install the required Puppet modules and the software they configure, and set up the server for immediate use.

If you’re new to Puppet and vRO, you can use vRO and vRA to set up a live, functional Puppet-managed system with much less effort than building one manually.

If you’re experienced with vRO, vRealize Automation (vRA), and Puppet, you can also use this plug-in to model common Puppet workflows as vRO workflows and vRA blueprints, then deploy them just as easily as other VMs while maintaining the advantages of a Puppet-managed infrastructure.

If you are using vRealize Automation Enterprise 7.3 or higher, then adding Puppet management to blueprints is built into the vRA GUI. This plugin is still required for the integration to work. Once you have installed the plugin and configured it with vRA 7.3 you can drag and drop Puppet management into blueprints.

Prerequisites

The Puppet plug-in 3.0 is compatible with the following configurations:

You can use the Puppet plug-in 3.0 with vRA 7.3 Enterprise edition, which includes an advanced GUI experience with drag-and-drop Puppet components on blueprints. To do so, you must have:

  • A Puppet master server running Puppet Enterprise 2016.4 or newer
  • vRealize Automation Enterprise 7.3
  • Either internal/external vRO 7.x appliance (vRA includes an internal vRO appliance)

You can also use the plug-in with any vRA version from 6 to 7.3. To do so, you must have:

  • A Puppet master server running Puppet Enterprise 2016.4 or newer
  • vRealize Orchestrator 6 or newer (vRA includes an internal vRO appliance)
  • vRealize Automation 6 or newer
  • vRealize Automation Enterprise 7.3 or newer required for GUI integration

Agent nodes being managed by Puppet must run an operating system supported by the Puppet agent.

Note: The 32-bit version of Microsoft Windows Puppet agent is not compatible with vRO plug-in management. You must use the 64-bit (x64) agent.

Removing previous versions of the Puppet plug-in

The plug-in does not currently support upgrades from the previous vRO Puppet plug-in versions. If you’re using any previous version of the plug-in, you must completely remove it before installing. For best results, delete all puppet elements from the vRO GUI client first and then copy this script from the vRO starter content to the appliance and execute it.

Using a reference implementation

The following instructions guide you through installing and configuring a reference implementation of the Puppet plug-in using Puppet Enterprise 2017.2 and vRA 7.3. This implementation is designed to create a development environment with vRO, vRA, and Puppet running as quickly as possible in order to help you learn how these tools work together.

The reference implementation isn’t designed with production deployments in mind. Once you’re familiar with how the plug-in works, you can install it into your production vRO/vRA infrastructure and build compatible workflows and blueprints.

The plug-in works with many implementations of Puppet Enterprise, vRO, and vRA. While you can use these instructions to set up this plugin with other versions of Puppet Enterprise and vRO/vRA, we recommend using this reference implementation the first time through.

Note: If you’re already experienced with Puppet, vRO, vRA, and the Puppet plug-in, see part 3 for a quick reference of properties and usage.

Part 1: Install and configure Puppet Enterprise

  1. Review the Puppet Enterprise hardware and operating system requirements.

  2. Install Puppet Enterprise on a VM or server. This will serve as the Puppet master server, and must be accessible over the network from the vRO appliance or server. An easy way to install PE is to run the installer in text mode. Then there is only one question to answer: the password for the PE Console GUI.

    Note: For this reference implementation of the vRO plug-in, this must be a new, clean installation of Puppet Enterprise with Code Manager disabled. After running the setup script, you can opt to enable Code Manager.

  3. Add the Puppet plug-in starter pack content by following the instructions in the README.

    The starter content repository provides reference implementations of Puppet roles and profiles for Linux and Windows web server stacks, utility scripts to prepare the master server for vRO, and a templated autosigning script. Once you understand how Puppet, vRO, and vRA work together, you can use these reference implementations to help build your own Puppetized vRO/vRA implementations.

    If you’re already experienced with Puppet, vRO, and vRA, you can replace this reference implementation with your own code or control repository.

  4. Ensure that the Puppet master has a valid DNS hostname and NTP configured. If you don’t have or use a DNS server, provide a valid hostname for the server’s IP address in the master server’s hosts file (typically /etc/hosts).

    Note: Make sure that a hostname is properly configured on the machines you’re installing PE on. All nodes must know their own hostnames. This can be done by properly configuring reverse DNS on your local DNS server, or by setting the hostname explicitly. Setting the hostname usually involves the hostname command and one or more configuration files, while the exact method varies by platform.

    Additionally, all nodes must be able to reach each other by name. This can be done with a local DNS server, or by editing the hosts file on each node (such as /etc/hosts on a Linux node) to point to the proper IP addresses.

  5. Initiate a Puppet run on the master server:

    sudo puppet agent -t
    

    The vRO starter content creates a PE RBAC user and Linux user account on the Puppet master (both are named vro-plugin-user, default password puppetlabs) and adds rules to the sudoers file allowing it to run commands with elevated privileges as required by the plug-in.

    It also adds the following settings to the master’s sshd_config:

    PermitRootLogin yes
    PasswordAuthentication yes
    ChallengeResponseAuthentication no
    
  6. (already done in starter content) To display role class descriptions in the vRealize Automation web GUI, we install puppet-strings, a Puppet documentation extraction command built on YARD:

    puppet resource package puppet-strings provider=puppet_gem
    

    Role class descriptions come from the @summary tag in your Puppet code, which puppet-strings can digest. The vRO starter content role and profile classes already have this built-in. To do this with your own role classes, add a @summary line with a 140 characters or less description. For example:

    # This role installs a MySQL databse and sample data
    #
    # @summary MySQL database server on Linux with sample data
    class role::linux_mysql_database {
      include profile::linux_baseline
      include profile::mysql
      include profile::sample_data
    }
    

Note: If you do not allow a sudo-capable user to run commands for vRO — for instance, if you remove the vro-plugin-user account or revoke its sudoers privileges — you will need to provide vRO with remote access to a user account on the master with those capabilities, or to the master’s root user, which is insecure. You will also have to make a user with the same username in PE RBAC with this single permission: “Nodes > View node data from PuppetDB”

Part 2: Install and configure the Puppet Plug-in

Note: For the reference implementation, we recommend using the vRO built into the vRA appliance. If you you choose to install your own vRO, refer to the vRO documentation. If you previously installed version 1.0 or 2.0 of the plug-in, you must completely remove it before installing version 3.0. See above for more information.

Install the Puppet plug-in

  1. Download the Puppet plug-in’s .vmoapp package from the VMware Solution Exchange.

  2. Login to the vRO server’s control center at https://<VRO-SERVER-IP-ADDRESS>:8283/vco-controlcenter.

  3. Click the Plugins tab.

  4. Click the Install plug-in button.

  5. Install the Puppet plug-in’s .vmoapp package downloaded from the VMware Solution Exchange. Read and accept the EULA, then click Install.

  6. After the installation confirmation message appears, click the Startup Options link in the message reminding you to restart the Orchestrator server. In some versions of vRO this message may not appear, but you still must restart the Orchestrator server.

  7. On the Startup Options page, click the Restart button under the Current Status heading.

Download and install the vRO client

In vRA 7.3, you will not need to run any vRO workflows directly as vRA will handle that for you. But having the vRO client can be really useful for understanding the integration and debugging.

  1. From the main vRO web interface page, click the Start Orchestrator Client link to download the Java vRO client.

  2. Open the client from the location where you downloaded it.

    You can confirm that the Puppet plug-in content is available by opening the Library/Puppet folder in the workflows tab of the client’s left pane.

Part 3: Managing and provisioning infrastructure with vRA and Puppet

Note: If you haven’t yet installed vRA, refer to the vRA documentation.

Once vRO and the Puppet plug-in are configured, you can use vRealize Automation (vRA) to request servers using blueprints.

Designing blueprints with Puppet features

In the previous version of the starter content we shipped Blueprints that you could install via CloudClient, but with vRA 7.3 Enterprise and the Puppet plug-in for vRA 3.0, it is simpler to create a new blueprint from scratch using the new Puppet component in the GUI. Follow these instructions to create your own blueprints.

Note: You can still access the previous version of these docs for consuming those prebuilt blueprints for vRA 7.x here and download them from this branch of the starter content.

Note: For detailed information about designing vRA blueprints, consult the vRA documentation

vRO/vRA property reference

The Puppet plug-in uses the following properties for blueprint and workflow development. They can be used when creating traditional IaaS blueprints without the Puppet GUI component in vRA 7.3 Enterprise:

vRO JavaScript variable name vRA property name Type Description
puppetRoleClass Puppet.RoleClass string The fully qualified Puppet class that implements the node’s role.
puppetCodeEnvironment Puppet.CodeEnvironment string The environment on the Puppet master in which vRO should look for Puppet code.
puppetNodeCertname Puppet.Node.Certname string The Puppet agent sets this based on the node’s certname, which is based on its fully qualified domain name.
puppetAutosignSharedSecret Puppet.Autosign.SharedSecret secureString The shared secret that nodes should provide to the Puppet master in order to autosign certificate requests.
sshUsername Puppet.SSH.Username string Username used to connect to a node via SSH.
sshPassword Puppet.SSH.Password secureString Password used to connect to a node via SSH.
winRMUsername Puppet.WinRM.Username string Username used to connect to a node via WinRM.
winRMPassword Puppet.WinRM.Password secureString Password used to connect to a node via WinRM.

vRO/vRA actions reference

The Puppet plug-in ships with several actions that can be used in workflows and integrations with vRA, for instance to populate the contents of input fields or dropdown menus.

Action name Description
escapeShellArgument Used internally by the plugin to escape a string used in a shell command.
escapePowerShellValue Used internally by the plugin to escape a string used in a PowerShell command.
escapeJSON Used internally by the plugin to escape a JSON string for stuctured facts or other uses.
getSectionText Used internally by the plugin for parsing Error messages.
formatShellArguments Used internally by the plugin to format and escape a set of strings containing arguments to a shell command. Calls escapeShellArgument.
executeCommand Used internally by the plugin to execute a shell command on a Linux Puppet Master.
getMasters Returns an array of strings containing the UUIDs of all of the Puppet:Master objects in the vRO inventory. Returns [””] if there are no Puppet:Master objects.
getMasterByUUID Returns a Puppet:Master object given a UUID string. Returns null if there is no object matching that UUID.
getEnvironments Returns an array of strings which are the environment names on the Puppet:Master specified by a UUID. Returns [””] if there are no environments.
getRoleClasses Returns an array of strings which are role class names on the Puppet:Master specified by a UUID and in a specified environment. Returns [””] if there are no role classes there.
getRoleClassesWithDescriptions Used internally, returns specially formated JSON string used by vRA 7.3 Enterprise with the role classes and their descriptions from a master’s environment. Throws an error if no master UUID or environment name provided. Optionally accepts a filter regex string to limit results.

All actions are visible on the “Actions” tab of the Java vRO client when in “Design” view, where you can view the full source code of each action, including parameters and return types.

Encrypting content with eyaml

Securing passwords used in the manifest is beyond the scope of this reference implementation. As a starting point, many Puppet deployments use Hiera, a key/value lookup tool for configuration, with eyaml, or encrypted YAML, to solve this problem. This solution not only provides secure storage for the password value, but also provides parameterization to support reuse, opening the door to easy password rotation policies across an entire network of nodes.

Troubleshooting

Running workflows after upgrading from plug-in version 1.0 or 2.0 results in errors

The plug-in does not currently support upgrades from the previous vRO Puppet plug-in versions. If you’re using any previous version of the plug-in, you must completely remove it before installing. The vRO starter content repository includes a script to assist with removing the plug-in.

Release notes

For known issues and details about specific plug-in releases, see the release notes.

Back to top