This version is compatible with:
- Puppet Enterprise 2019.8.x, 2019.7.x, 2019.5.x, 2019.4.x, 2019.3.x
- Puppet >= 6.12.0 < 7.0.0
Start using this module
This module helps you automate change requests in ServiceNow from Continuous Delivery for Puppet Enterprise (CD4PE) pipelines. The module has been tested for compatibility with the following ServiceNow versions:
The intended workflow that this module enables, is as follows:
- Git commit
--creates-->ServiceNow change request
- ServiceNow change request goes through internal approval process
- Change request approved
--orchestrates-->CD4PE code promotion & deployment
The module consist of two parts:
- A Bolt plan (
servicenow_change_requests::prep_servicenow) that is used to prepare ServiceNow for the integration.
- A set of files (in
files/deployments) that provides a custom deployment policy for CD4PE. This content needs to be copied to
site-modules/deploymentsof your control repo, so that CD4PE can use it.
Finally, this README provides the instructions for getting the integration up & running.
These are the requirements for the latest version of the module, see the Compatibility matrix for more specific details.
- Puppet Enterprise 2019.8.3 or higher
- CD4PE 3.13.4 or higher
- ServiceNow Orlando or higher
To ensure we can automate change requests, some things need to be added to ServiceNow:
- An additional change request category:
- A business rule named
Puppet Code Promotionthat triggers on approved
Puppet Codechange requests, and performs the orchestration against CD4PE (pipeline promotion & approvals of deployments to protected environments)
- CD4PE connection information & credentials for the business rule to use
A single plan takes care of setting this up. To run the plan, go to the
Plans section in the left navigation bar in Puppet Enterprise. In the "Run a plan" screen, select the
servicenow_change_requests::prep_servicenow from the Plan dropdown list. If the plan is not listed, ensure that this module has been added to the Puppetfile of your control repo, and that you have performed a code deployment to your production environment.
The plan requires 4 parameters, and has 3 more optional parameters for specific use cases. The 4 required parameters are:
snow_endpoint: The reachable FQDN of the ServiceNow instance (just the name is sufficient)
admin_user: The username of an administrator in ServiceNow, to make the necessary changes
admin_password: The password of the specified admin_user
cd4pe_endpoint: The publicly reachable FQDN of the CD4PE server (just the name, not the full URL)
For example, to configure the ServiceNow instance
https://dev-365937.service-now.com to integrate with a CD4PE server at
https://puppet-cd4pe.mycompany.com, specify the parameters as follows:
snow_endpoint = dev-365937.service-now.com
admin_user = admin
admin_password = <password>
cd4pe_endpoint = puppet-cd4pe.mycompany.com
If you are running a CD4PE version lower than 4.5.0, you will need to set the
br_version parameter to ensure a compatible version of the Business Rule gets installed in ServiceNow:
br_version = 0.2.2
Omit this parameter when you are running CD4PE 4.5.0 or above, which will install version 0.2.3 of the Business Rule, which is compatible with CD4PE 4.5.0.
The optional parameters
cd4pe_port can be used to connect to a CD4PE server on a different port, or via http. For example, to configure the ServiceNow instance
https://dev-365937.service-now.com to integrate with a CD4PE server at
http://puppet-cd4pe.mycompany.com:8080, specify the parameters as follows:
snow_endpoint = dev-365937.service-now.com
admin_user = admin
admin_password = <password>
cd4pe_endpoint = puppet-cd4pe.mycompany.com
cd4pe_https = false
cd4pe_port = 8080
The optional parameter
connection_suffix can be used to integrate multiple CD4PE installations with a single ServiceNow instance. By default, the plan will create a
Puppet_Code Connection Alias in ServiceNow, linked to a
Puppet Code Connection and a
Puppet Code Credential. This is great for when you have a single CD4PE installation. If you have 1 CD4PE installation, you don't need to specify the
To handle the multiple CD4PE installations for ServiceNow to interact with, a separate set of connections & credentials needs to be created in ServiceNow for each CD4PE instance. To let the plan do so, specify an appropriate suffix for this parameter. For example, to setup the integration for a secondary CD4PE installation used for "QA", specify
connection_suffix = QA. This will create the following in ServiceNow:
Puppet Code Connection - QAConnection, linked to the
Puppet Code Credential - QACredential, linked to the
The plan will create a dummy credential in ServiceNow, for the user
firstname.lastname@example.org. After running the plan for the first time, you need to go into ServiceNow and change it to the actual credential info:
- In the ServiceNow navigation bar on the left, type
credentialsin the top filter field.
- In the shown results, select
Connections & Credentialssection
- Click on the credential to change. By default this is named
Puppet Code Credentials. If you specified a
connection_suffixin the plan above, the credential entry will have this suffix.
email@example.com the actual name of the account in CD4PE you want to use for promoting code and approving deployments to protected environments. It's recommended to create a dedicated account in CD4PE for this purpose.
- Update the password to the correct value for the account you specified in the previous step
- Click the
Updatebutton on the lower left part of the form to save the changes.
Once ServiceNow has been prepared, we can setup the integration in CD4PE. This integration makes use of CD4PE's Impact Analysis feature, to determine which nodes are affected by a Puppet code change. A typical pipeline might look like this before the integration:
In this pipeline, the Impact Analysis has been configured to analyse the
With the ServiceNow integration, we will add a step between the "Impact Analysis" and the "Deploy to Production" stages. This step will take the output of the "Impact Analysis" step, and create a ServiceNow change request from the data. Upon approval of the change request in ServiceNow, a business rule runs in ServiceNow that promotes the pipeline to the next stage ("Deploy to Production"). If any subsequent stages require deployment approvals, ServiceNow will monitor them and approve the deployments as necessary.
With the added stage, the pipeline looks like this:
The added stage uses a custom deployment policy named
deployments::servicenow_integration. We need to make this custom deployment policy available to CD4PE first. To do so:
- Copy the
deploymentsdirectory, found in the
filesdirectory of this module, into the
site-modulesdirectory of your control repo. If your control repo still uses a
sitedirectory (instead of
site-modules), then copy the
deploymentsdirectory into the
- We recommend you perform step 1 in the
masterbranch of your control-repo, and then let CD4PE promote these changes to your other branches, all the way into production. Once the
deploymentsdirectory is deployed into production, your CD4PE instance should be able to find the
deployments::servicenow_integrationcustom deployment policy.
Once the custom deployment policy is available, add it to your
- Click on the
...icon of your
Deploy to Productionstage and click
Add a stage before
ServiceNow Change Requestas the Stage Name
- Select your Production environment as the target (this setting has no effect in practice for this particular custom deployment policy)
- Click the
Custom deployment policiesradio button
- Select the
- Set the parameters for the policy:
snow_endpoint: the FQDN of your ServiceNow instance (e.g.
snow_username: the username to authenticate with ServiceNow (e.g.
snow_password: the password to authenticate with ServiceNow (e.g.
stage_to_promote_to: the name of the stage to promote to, when approved (e.g.
Deploy to Production)
- If desired, set (some of the) optional parameters for the policy:
max_changes_per_node: how many resources per node may change before CD4PE recommends this code change warrants more scrutiny (defaults to
report_stage: name of the stage that performs the Impact Analysis (defaults to
Impact Analysis). Set this parameter if your IA stage is not named "Impact Analysis"!
assignment_group: the group in ServiceNow to which the change is assigned (defaults to
connection_alias: the name of the ServiceNow connection alias that should be used for orchestration after the change request is approved (defaults to
auto_create_ci: set to
trueto automatically create CI's in ServiceNow for nodes identified as affected by Impact Analysis, if those nodes do not exist as CI's in ServiceNow (defaults to
Add stageto complete the wizard.
- Click the
Auto-promotecheckbox between the "Impact Analysis" and the "ServiceNow Change Request" stage.
- Ensure no auto-promotion occurs between the "ServiceNow Change Request" stage and the "Deploy to Production" stage.
When preparing ServiceNow, you configured a CD4PE account (changing the dummy
firstname.lastname@example.org account name). This account needs to:
- Exist in CD4PE
- Be a member of the workspace(s) that have pipelines that integrate with ServiceNow
- Have at least
Modulesin the workspace(s)
- If using protected environment, the account must be a member of the approval group for that protected environment.
Once the above steps have been completed, make a Puppet code change in your
master branch to verify the integration works. The CD4PE pipeline should trigger, and the last step should be the ServiceNow Change Request. Once that step has successfully completed:
- Navigate to the Open Changes in ServiceNow
- A new change request should be created, the "Short description" always starts with
Puppet Code -followed by the commit message and the stage to promote to
- Open the change request and note the information it contains:
- The category is set to
- The "Short description" and "Description" have been filled in with information from the code commit
- The "Assignment group" has been configured
- The "Risk and impact analysis" field in the "Planning" section has been filled in with a link to the CD4PE Impact Analysis, and a summary report of the results
- The "Close notes" field in the "Closure information" section contains a hash of all the relevant data to automate the CD4PE pipeline upon approval of the change request
- The "Affected CIs" table shows the records of nodes affected by the change (requires the CI's to exist in ServiceNow, or for the
auto_create_ciparameter to be enabled in the custom deployment policy)
- The category is set to
- Approve the change request (both from the Assignment group and the CAB)
- Once fully approved, click the
Implementbutton on the top right to immediately start implementation of the change. This action triggers the business rule that runs asynchronously
- Switch to the "Notes" section of the change request to see live updates of the orchestration as it happens. If an error does occur, you can see information about it in the
Script Log Statementsarea of ServiceNow.
- Check back in CD4PE to see that the pipeline has been promoted. If the deployment to the production environment was a protected environment, ServiceNow will also attempt to automatically approve this deployment. Of course you need to ensure that the credentials you have configured in ServiceNow have the appropriate permissions in CD4PE to do so.
- Switch back to the change ticket in ServiceNow and navigate to the
Change Taskstable. Notice that 2 change tasks have been created (
Post implementation testing). Note that if the orchestration completed successfully, the Notes will say that the Change Tasks will be closed, and the Close Code for the ticket will be set to successful. Refresh the page of the ticket to verify that is indeed the case.
- The change request is now in the
Reviewstate, and can be closed by clicking the
Closebutton on the top right.
What are plans?
Modules can contain plans that take action outside of a desired state managed by Puppet. It’s perfect for troubleshooting or deploying one-off changes, distributing scripts to run across your infrastructure, or automating changes that need to happen in a particular order as part of an application deployment.
All notable changes to this project will be documented in this file.
- Adds support for CD4PE 4.5.0
Note: CD4PE 4.5.0 changes a certain API call that is used by the ServiceNow Business Rule ("Puppet - Promote code after approval") that this module installs. If you have used a previous version of this module to install the Business Rule, you are required to re-run the
servicenow_change_requests::prep_servicenow plan that this module provides. The plan will automatically update the ServiceNow Business Rule to account for the API change.
If you are running an older version of CD4PE than 4.5.0, you can still use this module, but you will need to specify an extra parameter to the
servicenow_change_requests::prep_servicenow plan to ensure the older version of the Business Rule gets installed. To do so, set the
br_version parameter of the plan to
0.2.2. Once you upgrade to CD4PE 4.5.0, re-run the plan without specifying this parameter to upgrade the Business Rule.
- Support for HTTP proxies (no authentication)
- Quebec support. Note that this requires updating the custom deployment policy content in your control repo with the newer content provided by this module's update.
- The Business Rule in ServiceNow (for interacting with CD4PE) now automatically detects available MID Servers with a REST capability, and uses the first one available for outbound REST calls
- Risk and Impact fields in the Change Request are automatically set in accordance to the Impact Analysis verdict
- Now shows the name of the stage to promote toin the Change Request description, instead of the stage number
- Now properly escapes special characters in commit descriptions, preventing an error when creating the Change Request
compileFailed key in Impact Analysis node report always existing in latest version of CD4PE 4.x
Enable more detailed logging from the Business Rule in ServiceNow
Correctly handle insufficient permissions in CD4PE
Wait for completion on deployments that do not require approval
Add re-triggerable condition to Business Rule for ability to re-run orchestration on a change ticket when desired
Dynamically handle definition of ENDPOINT variable in Business Rule
Correctly handle cookies from CD4PE 3.x and 4.x
Ensure image URLs resolve correctly on the Puppet Forge
First public release to the Puppet Forge
Proper PDK conversion
This release adds functionality to the
auto_create_ci option. When this feature is enabled, newly created CI's in ServiceNow will have some of their fields populated from PuppetDB facts. The following mapping is provided out-of-the box:
(PE Fact => ServiceNow CI field)
fqdn => fqdn domain => dns_domain serialnumber => serial_number operatingsystemrelease => os_version physicalprocessorcount => cpu_count processorcount => cpu_core_count processors.models.0 => cpu_type memorysize_mb => ram is_virtual => virtual macaddress => mac_address
Initial release of this module, intended for early adoption testing
Apache License Version 2.0, January 2004 http://www.apache.org/licenses/ TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION 1. Definitions. "License" shall mean the terms and conditions for use, reproduction, and distribution as defined by Sections 1 through 9 of this document. "Licensor" shall mean the copyright owner or entity authorized by the copyright owner that is granting the License. "Legal Entity" shall mean the union of the acting entity and all other entities that control, are controlled by, or are under common control with that entity. For the purposes of this definition, "control" means (i) the power, direct or indirect, to cause the direction or management of such entity, whether by contract or otherwise, or (ii) ownership of fifty percent (50%) or more of the outstanding shares, or (iii) beneficial ownership of such entity. "You" (or "Your") shall mean an individual or Legal Entity exercising permissions granted by this License. "Source" form shall mean the preferred form for making modifications, including but not limited to software source code, documentation source, and configuration files. "Object" form shall mean any form resulting from mechanical transformation or translation of a Source form, including but not limited to compiled object code, generated documentation, and conversions to other media types. "Work" shall mean the work of authorship, whether in Source or Object form, made available under the License, as indicated by a copyright notice that is included in or attached to the work (an example is provided in the Appendix below). "Derivative Works" shall mean any work, whether in Source or Object form, that is based on (or derived from) the Work and for which the editorial revisions, annotations, elaborations, or other modifications represent, as a whole, an original work of authorship. For the purposes of this License, Derivative Works shall not include works that remain separable from, or merely link (or bind by name) to the interfaces of, the Work and Derivative Works thereof. "Contribution" shall mean any work of authorship, including the original version of the Work and any modifications or additions to that Work or Derivative Works thereof, that is intentionally submitted to Licensor for inclusion in the Work by the copyright owner or by an individual or Legal Entity authorized to submit on behalf of the copyright owner. For the purposes of this definition, "submitted" means any form of electronic, verbal, or written communication sent to the Licensor or its representatives, including but not limited to communication on electronic mailing lists, source code control systems, and issue tracking systems that are managed by, or on behalf of, the Licensor for the purpose of discussing and improving the Work, but excluding communication that is conspicuously marked or otherwise designated in writing by the copyright owner as "Not a Contribution." "Contributor" shall mean Licensor and any individual or Legal Entity on behalf of whom a Contribution has been received by Licensor and subsequently incorporated within the Work. 2. Grant of Copyright License. Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable copyright license to reproduce, prepare Derivative Works of, publicly display, publicly perform, sublicense, and distribute the Work and such Derivative Works in Source or Object form. 3. Grant of Patent License. Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable (except as stated in this section) patent license to make, have made, use, offer to sell, sell, import, and otherwise transfer the Work, where such license applies only to those patent claims licensable by such Contributor that are necessarily infringed by their Contribution(s) alone or by combination of their Contribution(s) with the Work to which such Contribution(s) was submitted. If You institute patent litigation against any entity (including a cross-claim or counterclaim in a lawsuit) alleging that the Work or a Contribution incorporated within the Work constitutes direct or contributory patent infringement, then any patent licenses granted to You under this License for that Work shall terminate as of the date such litigation is filed. 4. Redistribution. You may reproduce and distribute copies of the Work or Derivative Works thereof in any medium, with or without modifications, and in Source or Object form, provided that You meet the following conditions: (a) You must give any other recipients of the Work or Derivative Works a copy of this License; and (b) You must cause any modified files to carry prominent notices stating that You changed the files; and (c) You must retain, in the Source form of any Derivative Works that You distribute, all copyright, patent, trademark, and attribution notices from the Source form of the Work, excluding those notices that do not pertain to any part of the Derivative Works; and (d) If the Work includes a "NOTICE" text file as part of its distribution, then any Derivative Works that You distribute must include a readable copy of the attribution notices contained within such NOTICE file, excluding those notices that do not pertain to any part of the Derivative Works, in at least one of the following places: within a NOTICE text file distributed as part of the Derivative Works; within the Source form or documentation, if provided along with the Derivative Works; or, within a display generated by the Derivative Works, if and wherever such third-party notices normally appear. The contents of the NOTICE file are for informational purposes only and do not modify the License. You may add Your own attribution notices within Derivative Works that You distribute, alongside or as an addendum to the NOTICE text from the Work, provided that such additional attribution notices cannot be construed as modifying the License. You may add Your own copyright statement to Your modifications and may provide additional or different license terms and conditions for use, reproduction, or distribution of Your modifications, or for any such Derivative Works as a whole, provided Your use, reproduction, and distribution of the Work otherwise complies with the conditions stated in this License. 5. Submission of Contributions. Unless You explicitly state otherwise, any Contribution intentionally submitted for inclusion in the Work by You to the Licensor shall be under the terms and conditions of this License, without any additional terms or conditions. Notwithstanding the above, nothing herein shall supersede or modify the terms of any separate license agreement you may have executed with Licensor regarding such Contributions. 6. Trademarks. This License does not grant permission to use the trade names, trademarks, service marks, or product names of the Licensor, except as required for reasonable and customary use in describing the origin of the Work and reproducing the content of the NOTICE file. 7. Disclaimer of Warranty. Unless required by applicable law or agreed to in writing, Licensor provides the Work (and each Contributor provides its Contributions) on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied, including, without limitation, any warranties or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE. You are solely responsible for determining the appropriateness of using or redistributing the Work and assume any risks associated with Your exercise of permissions under this License. 8. Limitation of Liability. In no event and under no legal theory, whether in tort (including negligence), contract, or otherwise, unless required by applicable law (such as deliberate and grossly negligent acts) or agreed to in writing, shall any Contributor be liable to You for damages, including any direct, indirect, special, incidental, or consequential damages of any character arising as a result of this License or out of the use or inability to use the Work (including but not limited to damages for loss of goodwill, work stoppage, computer failure or malfunction, or any and all other commercial damages or losses), even if such Contributor has been advised of the possibility of such damages. 9. Accepting Warranty or Additional Liability. While redistributing the Work or Derivative Works thereof, You may choose to offer, and charge a fee for, acceptance of support, warranty, indemnity, or other liability obligations and/or rights consistent with this License. However, in accepting such obligations, You may act only on Your own behalf and on Your sole responsibility, not on behalf of any other Contributor, and only if You agree to indemnify, defend, and hold each Contributor harmless for any liability incurred by, or claims asserted against, such Contributor by reason of your accepting any such warranty or additional liability. END OF TERMS AND CONDITIONS APPENDIX: How to apply the Apache License to your work. To apply the Apache License to your work, attach the following boilerplate notice, with the fields enclosed by brackets "" replaced with your own identifying information. (Don't include the brackets!) The text should be enclosed in the appropriate comment syntax for the file format. We also recommend that a file or class name and description of purpose be included on the same "printed page" as the copyright notice for easier identification within third-party archives. Copyright [yyyy] [name of copyright owner] Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.