Configure the primary server

The Puppet vRO Plug-in requires you install and configure a Puppet Enterprise (PE) 2018.1.0+ primary server, which can be done manually or with a module. Ensure it is accessible on the same network as the vRO appliance.

The easiest way to configure the primary server is using the puppetlabs/vra_puppet_plugin_prep module. The module helps you automatically configure SSH, creates an RBAC user, configures autosign, and installs puppet strings. You still need to classify nodes, create a rule, and add the primary server endpoint manually.

If you decide to use the module to set up your primary server, you can skip over the first four setup processes in this guide and proceed to Role class location.

If you don't want to use the module for setup, the guide walks you through all of the following steps:

Configuring ssh into the primary server with a password and running commands as root.
Creating an RBAC user on the primary server. Note as of plug-in version 3.2, RBAC permissions have changed.
Configuring autosigning to use challengePassword in the CSR with a shared secret.
Installing puppet-strings.
Making sure role manifests are in the <environment>/site/role/manifests directory.
Checking nodes are classified with the trustes.extensions.pp_role in the console or $trusted['pp_role'] in the site.pp.

Configuring PE environment groups to use the trused.extensions.pp_environment fact.

Primary server shell access

The vRO Plug-in needs to be able to ssh into the primary server and run commands. You can run these commands as the root user or a non-root user with sudo.

Configure one of the following on your primary server:

Root user ssh
- Enable root ssh access

Non-root user ssh

Create a local user on the primary server
Enable ssh with password authentication
Enable passwordless sudo for the user

An example set of the /etc/sudoers.d/user file:

## This file allows the vRO plugin user 'vro-plugin-user' to remove nodes that are destroyed in vRO/vRA.
## This file also disallows the user 'vro-plugin-user' from removing the primary server and other PE Internal certs.

Defaults:vro-plugin-user !requiretty
vro-plugin-user ALL = (root) NOPASSWD: /opt/puppetlabs/bin/puppet config print *
vro-plugin-user ALL = (root) NOPASSWD: !/opt/puppetlabs/bin/puppet config print *[[\:blank\:]]*
vro-plugin-user ALL = (root) NOPASSWD: /opt/puppetlabs/bin/puppet resource service puppet ensure=stopped
vro-plugin-user ALL = (root) NOPASSWD: /opt/puppetlabs/bin/puppet resource service puppet ensure=running enable=true
vro-plugin-user ALL = (root) NOPASSWD: /opt/puppetlabs/bin/facter -p puppetversion
vro-plugin-user ALL = (root) NOPASSWD: /opt/puppetlabs/bin/facter -p pe_server_version
vro-plugin-user ALL = (root) NOPASSWD: /opt/puppetlabs/bin/puppet agent -t
vro-plugin-user ALL = (root) NOPASSWD: /opt/puppetlabs/bin/puppet agent --test --color=false --detailed-exitcodes
vro-plugin-user ALL = (root) NOPASSWD: /opt/puppetlabs/bin/puppet node purge *
vro-plugin-user ALL = (root) NOPASSWD: !/opt/puppetlabs/bin/puppet node purge *[[\:blank\:]]*
vro-plugin-user ALL = (root) NOPASSWD: !/opt/puppetlabs/bin/puppet node purge pe-internal-mcollective-servers
vro-plugin-user ALL = (root) NOPASSWD: !/opt/puppetlabs/bin/puppet node purge pe-internal-peadmin-mcollective-client
vro-plugin-user ALL = (root) NOPASSWD: /bin/ls -1 /etc/puppetlabs/code/environments/
vro-plugin-user ALL = (root) NOPASSWD: /opt/puppetlabs/bin/puppet strings *
vro-plugin-user ALL = (root) NOPASSWD: /bin/find /etc/puppetlabs/code/environments/*

Create an RBAC user

The vRO Plug-in uses an RBAC user to read console data. The username and password need to be the same as the ssh user.

Create a new user role for the vRO Plug-in.
1. In the console, click Access control > User roles.
2. In the Name field, enter a name for the vRO user.
3. In the Description field, enter a description for the role, for example, vRO Plug-in user role.
4. Click Add role.

Assign permissions to the newly created user role to allow for viewing node data.

On the User roles page, click vRO Puppet Plug-in
Click Permissions.

In the Add a permission dropdown, add the following permissions:


Type	Action	Instance
Nodes	View node data from PuppetDB
Agent	Run Puppet on the agent nodes
Tasks	Run tasks	Tasks: all permitted on all nodes
Job Orchestrator	Start, stop, and view jobs
Certificate requests	Accept and reject

Click Commit.

Create a new RBAC user for the vRO plugin.
Ensure the name of the user is the same as the ssh user.
1. In the console, click Access control > Users.
2. In the Full name field, enter the user name.
3. In the Login field, enter the user name.
4. Click Add local user.
Add the new user to the user role you just created.
1. On the User role page, click User role.
2. Click vRO Puppet user.
3. In the Member users tab, in the User name field, select the user you just created.
4. Click Add user, and commit changes.
Set the password for the new user to be the same as the ssh password.
1. On the Users page, click the user's full name.
2. Click Generate password reset.
3. Copy the link provided in the message and open it in a new browser window.

Autosign configuration

The Puppet vRO Plug-in installs the PE agent on newly deployed nodes.

To avoid manually approving new agent certificates, you can automate this process securely with an autosigning policy. Use the vra_puppet_plugin_prep module to configure autosigning using a shared key when classified on the primary server.

If you want autosigning but don’t want to use the vra_puppet_plugin_prep module, you can configure the same shared-key autosigning manually. The csr_attributes.yaml contains the challengePassword, which can be used inside the autosigning script to confirm that the certificate can be signed.

The vra_puppet_plugin_prep module autosign script:

#!/opt/puppetlabs/puppet/bin/ruby
#
# A note on logging:
#   This script's stderr and stdout are only shown at the DEBUG level
#   of the primary server's logs. This means you won't see the error messages
#   in puppetserver.log by default. All you'll see is the exit code.
#
#   https://docs.puppet.com/puppet/latest/ssl_autosign.html#policy-executable-api
#
# Exit Codes:
#   0 - A matching challengePassword was found.
#   1 - No challengePassword was found.
#   2 - The wrong challengePassword was found.
#
require 'puppet/ssl'

csr = Puppet::SSL::CertificateRequest.from_s(STDIN.read)
valid_pass = 'SecretPassword'

if pass = csr.custom_attributes.find do |attribute|
     ['challengePassword', '1.2.840.113549.1.9.7'].include? attribute['oid']
   end
else
  puts 'No challengePassword found. Not automatically accepting the request.'
  exit 1
end

if pass['value'] == valid_pass
  exit 0
else
  puts "challengePassword does not match: #{pass['value']}"
  exit 2
end

Install Puppet strings

Install the puppet-strings gem on the primary server by running the following commands:

puppet resource package rgen provider=puppet_gem
puppet resource package puppet-strings provider=puppet_gem

Results

The puppet-strings gem is responsible for populating the descriptions of the roles in vRA. The role classes need the @summary tag to populate this section.

An example role with the @summary tag:

# This role installs a MySQL database 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

}

Role class location

The Puppet vRO plugin is designed to populate the $trusted['pp_role'] fact with the role specified in the blueprint.

These roles are populated in the vRA UI by looking for <environment>/site/role/manifests/**/*.pp files. The files are then parsed with puppet-strings to populate a summary. Classes in other locations in the control repository are not accessible to the Puppet configuration management item in the vRA blueprint. If you are not using the enterprise version of vRA, you can populate any class by setting the Puppet.RoleClass property in the blueprint.

See the vRO/vRA property reference for more information.

Node classification

The vRO Plug-in populates the $trusted['pp_role'] fact with the classname of the role from the request.

Use the $trusted['pp_role'] fact to classify the node with the class. The reference implementation uses a node group for each role with a rule that matches the role to the trusted.extensions.pp_role fact.

Example of a matching rule for the node group:

trusted.extensions.pp_role = role::webserver

Alternatively, if you use the site.pp for managing classification, you can leverage the $trusted['pp_role'] for inclusion. For example:

if $trusted['pp_role'] and defined($trusted['pp_role']) {
  include $trusted['pp_role']
}

Use the method that complies with your existing configuration.

Environment group configuration

The PE console is responsible for classifying the node into the correct environment.

In the vRO configuration, each node has the $trusted['pp_environment'] fact populated with the environment configured in vRA. Use the trusted.extensions.pp_environment in the rules for your environment groups. See the environment node group documentation for instructions on creating environment node groups and the rules documentation for adding rules to the environment node group.

An example rule for the development environment group:

trusted.extensions.pp_environment = development