The ServiceNow Puppet Spoke is a ServiceNow application that provides a series of default catalog items for the ServiceNow portal. These catalog items provide an interface in ServiceNow to execute task and plan based workflows such as managing a service, installing an agent, or whatever other task/plan based workflows you might want to trigger from ServiceNow.

In addition to the provided catalog items, the Spoke ships with several actions and flows that a ServiceNow Developer can use to create custom catalog items. If a task or plan exists in Puppet, you can likely create a catalog item to trigger that task/plan from ServiceNow.

Setup

1. Install the following plugins in your ServiceNow instance:

   1. Flow Designer Support for Service Catalog
   2. ServiceNow IntegrationHub Starter Pack Installer [com.glide.hub.integrations]

2. Install the Puppet Spoke from the ServiceNow Store

3. Generate a Puppet RBAC token for use by a service by running the command puppet-access login [username] --print

   1. The user that generates this token must have permission to create task and plan jobs via the orchestrator api.

4. Configure the Connection & Credential Alias

   Puppet Spoke comes with a default Connection & Credential Alias called Puppet Enterprise Connection; however, a ServiceNow admin can create a new Connection & Credential Alias if the client has more than one Puppet Enterprise that they want to manage in ServiceNow.

(Optional) Create an extra Connection & Credential Alias

1. Navigate to Credentials & Connections > Connection & Credential Aliases.
2. Click New.
3. Complete the fields on the form.

Create a Credential

1. Navigate to Credentials & Connections > Credentials.
2. Click New and select API Key Credentials from the list.
3. Complete the fields on the form shown below, paste the RBAC token created from Step 3 into the API Key field.

Create a Connection

1. Navigate to Credentials & Connections > Connections.
2. Click New and select HTTP(s) Connection.
3. Complete the fields on the form as shown below:
   • Credentials: Select the newly created credential record
   • Connection alias: Select the desired connection alias (for example, Puppet Enterprise Connection)
   • Select the use MID Server box only if you are using a MID Server.
   • Host: the hostname of your Puppet Enterprise Server
   • Override Default Port: Must always be 8143
   • Protocol: https
   • URL Builder: Must be checked to add the port to the connection url
4. Click Submit

MID Server Setup

It's best practice to use MID Server to allow the integration to securely communicate with the Puppet Server. If your Puppet Server is using a self-signed certificate then you need to take appropriate steps to ensure that the certificate is trusted:

1. On the Puppet Server host, get the location of the ca_cert.pem file, which is used to sign the console’s certificate, by running: puppet config print cacert
2. On the MID Server host, paste the content of the ca_cert.pem certificate into a new file.
3. Use the ServiceNow documented method to import the certificate into the java keystore of the MID Server. See Add SSL certificates for the MID Server
   Note: When using the commands below you are prompted for the keystore password. The default password is changeit, but your ServiceNow administrators can change it.
   1. Open a command prompt and navigate to the folder containing the JRE keytool. This is the location of the JRE you installed. For example: C:\Program Files\Java\jre1.8.0_161\bin
   2. Import a certificate into the MID Server's cacerts keystore, using this command: keytool -import -alias <certificate alias> -file "<path to certificate>" -keystore "<path to the JRE>\lib\security\cacerts"
      • For example, for a windows machine you might enter: keytool -import -alias MyCA -file "C:\myca.cer" -keystore "C:\Program Files\Java\jre1.8.0_161\lib\security\cacerts"
        • You can use the dir command to locate the path to the JRE in windows: dir jre /AD /s
      • For a linux machine you might enter: sudo keytool -import -alias MyCA -file "/tmp/myca.cer" -keystore "/home/user_name/agent/jre/lib/security/cacerts"
        • You can use the find command to locate the path to the JRE in linux: sudo find / -name jre

If you will not be using a MID Server, or are setting this integration up for testing purposes you can set the following settings in ServiceNow instead of setting up a MID Server. Please note that this is not recommended outside of a testing environment.

• com.glide.communications.httpclient.verify_revoked_certificate: False
• com.glide.communications.httpclient.trustmanager_trust_all: True
• com.glide.communications.httpclient.verify_hostname: False
• com.glide.communications.trustmanager_trust_all: True

Testing the connection

Test the connection by running a flow.

1. Navigate to the ServiceNow service portal and select one of the puppet service catalog items (for example, "Run a Command").

   

2. Use the credential alias we just created for the Puppet Server field.

3. Fill in the other parameters as needed.

   

4. Submit and check to see if from the Puppet console if your job was successful.

   

Configuring Retry Duration and Job Timeout

The Puppet Spoke comes with default catalog item configurations as shown below. These records are used to configure the retry duration between job status updates, and the job timeout which sets a maximum run time for a catalog item.

Puppet task/plan name: The task/plan name in Puppet Enterprise
Catalog item: The catalog item related to the task/plan
Retry duration: How often to refresh job result from Puppet
Job timeout: Maximum runtime to get the Job result
Retry Duration and Job timeout can be modified if desired.
Important Note: Each Catalog Item needs to have a Puppet Catalog Item Configuration record with a proper Puppet task/plan name associated with it otherwise the Flow won’t run.

Support and Troubleshooting

The most common issues with this Application typically involve a failed connection back to Puppet Enterprise.

• Please consider reviewing that your network is allowing communication between Puppet Enterprise and ServiceNow by reviewing the MID Server Setup.
• Please ensure that your Puppet Enterprise RBAC token is valid, has sufficient permissions to trigger jobs via the orchestrator api, and has not expired.
• Please ensure that your ServiceNow user has sufficient permissions to either install or use the Application.

Finally please note that the request item updates that are returned to ServiceNow from Puppet Enterprise are only as good as the underlying Puppet task or plan that a ServiceNow flow utilizes. In some cases it may be necessary to request an improvement from the task/plan author.

Wrap Up

With the setup complete, you are now able to run all of the default catalog items provided by the Puppet Spoke. If you wish to add additional Spoke content you may utilize the underlying flows and actions to create new catalog items and puppet catalog item configuration records to add more functionality.