Installing and configuring Deployment Manager 3.1.x
Use Deployment Manager to create continuous integration and delivery (CI/CD) pipelines, which automate tasks and allow you to quickly deploy high-quality software to production.
See the following topics for more information about installing and configuring Deployment Manager:
- Step 1: Installing Deployment Manager on premises
- Step 2: Configuring systems in the pipeline
- Step 3: Configuring systems for branch-based development (optional)
- Step 4: Configuring additional settings
For information on using Deployment Manager, see Using Deployment Manager 3.1.x.
Step 1: Installing Deployment Manager on premises
If you are using Deployment Manager on Pega Platform™, complete the following steps to install it.
- Install Pega 7.4 on all systems in the CI/CD pipeline.
- Browse to the Deployment Manager Pega Exchange page, and then download DeploymentManager03.0x.0x.zip for your version of Deployment Manager to your local disk on each system.
- Extract the DeploymentManager03.0x.0x.zip file.
- Use the Import wizard to import files into the appropriate systems. For more information about the Import wizard, see Importing a file by using the Import wizard.
- On the orchestration server, import the following files:
- PegaDevOpsFoundation_03.01.0x.zip
- PegaDeploymentManager_03.01.0x.zip
- On the development, QA, staging, and production systems, import the PegaDevOpsFoundation_03.01.0x.zip file.
- Optional: If you are using a distributed development, on the remote development system, import the PegaDevOpsFoundation_03.01.0x.zip file.
Step 2: Configuring systems in the pipeline
You must complete the following steps to set up a pipeline for all supported CI/CD workflows. If you are using branches, you must configure additional settings after you perform the required steps.
- Step 2a: Configuring the orchestration server
- Step 2b: Configuring candidate systems
- Step 2c: Creating repositories on the orchestration server and candidate systems
Step 2a: Configuring the orchestration server
The orchestration server is the system on which release managers configure and manage CI/CD pipelines.
- Create an application that the release manager uses for creating, managing, and running pipelines, by using the New Application wizard. For more information, see Creating an application.
- Add the PegaDeploymentManager application to your application stack.
- In the Designer Studio header, click the name of your application, and then click Definition.
- In the Built on application section, click Add application.
- In the Name field, press the Down Arrow key and select PegaDeploymentManager.
- In the Version field, press the Down Arrow key and select the version of Deployment Manager that you are using.
- Click .
Ensure that this application remains unlocked and has at least one unlocked ruleset.
- Optional: If your system is not configured for HTTPS, verify that TLS/SSL settings are not enabled on the api and cicd service packages.
- Click Records > Integration-Resources > Service Package.
- Click api.
- On the Context tab, verify that the Require TLS/SSL for REST services in this package check box is cleared.
- Click Records > Integration-Resources > Service Package.
- Click cicd.
- On the Context tab, verify that the Require TLS/SSL for REST services in this package check box is cleared.
- Add the PegaRULES:RepositoryAdministrator, PegaRULES:PegaAPI, and PegaRULES:SecurityAdministrator roles to the Administrator access groups that were generated by the New Application wizard.
- Click Designer Studio > Org & Security > Groups & Roles > Access Groups.
- Click an access group to open it.
- In the Available roles section, click Add role.
- In the field that is displayed, press the Down Arrow key and select PegaRULES:RepositoryAdministrator.
- Click Add role.
- In the field that is displayed, press the Down Arrow key and select PegaRULES:PegaAPI.
- Click Add role.
- In the field that is displayed, press the Down Arrow key and select PegaRULES:SecurityAdministrator.
- Save the Edit Access Group rule form.
- If you are a Pega Cloud customer, specify that content is stored in the Pega database:
- Click the name of your application, and then click Definition.
- Click Integration & security.
- In the Content management system section, click Store in Pega database.
- Click Save.
- Create an authentication profile on the orchestration server that references an operator ID whose access group points to the target application on each candidate system. For example, if the operator that is on the candidate systems has the credentials janedoe/rules, you must create an authentication profile on the orchestration server that is also configured with the janedoe/rules credentials. For more information about configuring authentication profiles, see Creating an authentication profile.
If the operator IDs and passwords are different on the candidate systems, you must create multiple authentication profiles.
- Configure the candidate systems in your pipeline. For more information, see Step 2b: Configuring candidate systems.
Step 2b: Configuring candidate systems
Configure each system system that is used for the development, QA, staging, and production stage in the pipeline.
- Use the Import wizard to import your target application into each candidate system. For more information about the Import wizard, see Importing a file by using the Import wizard.
- On each candidate system, add the PegaDevOpsFoundation application to your application stack.
- In the Designer Studio header, click the name of your application, and then click Definition.
- In the Built on application section, click .
- In the Name field, press the Down Arrow key and select PegaDevOpsFoundation.
- In the Version field, press the Down Arrow key and select the version of Deployment Manager that you are using.
- Click .
- On each candidate system, add the PegaRULES:RepositoryAdministrator, PegaRULES:PegaAPI, and PegaRULES:SecurityAdministrator roles to the operator that you use to access your application on each system.
- Log in to each Pega Platform server with an operator whose default access group points to your application. This is the same operator that you configured on the orchestration server whose authentication profile points to this system from the orchestration server.
- Click your user profile and select Access group.
- In the Available roles section, click Add role.
- In the field that is displayed, press the Down Arrow key and select PegaRULES:RepositoryAdministrator.
- Click Add role.
- In the field that is displayed, press the Down Arrow key and select PegaRULES:PegaAPI.
- Click Add role.
- In the field that is displayed, press the Down Arrow key and select PegaRULES:SecurityAdministrator.
- Click Save.
- On each candidate system, create an authentication profile and configure it with the operator ID and password of the release manager operator. Use the operator ID and password of the administrative operator that was generated when you created a new application on the orchestration server. All candidate systems use this authentication profile to communicate with the orchestration server about the status of the tasks in the pipeline.
- Click Create > Security > Authentication Profile.
- In the name field, enter ReleaseManager.
- Configure the authentication profile to use the release manager operator ID and password, and configure other information, as appropriate. For example, if the credentials of the release manager are rmanager/rules, configure each authentication profile on the candidate systems with the rmanager/rules credentials.
For more information about creating authentication profiles, see Creating an authentication profile.
- Optional: If your system is not configured for HTTPS, verify that TLS/SSL settings are not enabled on the api and cicd service packages.
- Click Records > Integration-Resources > Service Package.
- Click api.
- On the Context tab, verify that the Require TLS/SSL for REST services in this package check box is cleared.
- Click Records > Integration-Resources > Service Package.
- Click cicd.
- On the Context tab, verify that the Require TLS/SSL for REST services in this package check box is cleared.
On the development system, create a product rule that defines the application package that will be moved through repositories in the pipeline. For more information, see Product rules: Completing the Create, Save As, or Specialization form.
- Configure repositories through which to move artifacts in your pipeline. For more information, see Step 2c: Creating repositories on the orchestration server and candidate systems.
Step 2c: Creating repositories on the orchestration server and candidate systems
If you are using Deployment Manager on premises, create repositories on the orchestration server and all candidate systems to move your application between all the systems in the pipeline. You can use a supported repository type that is provided in Pega Platform, or you can create a custom repository type.
If you are using Deployment Manager on Pega Cloud, default repositories are provided. If you want to use repositories other than the ones provided, you can create your own.
For more information about creating a supported repository type, see Creating a repository connection.
For more information about creating a custom repository type, see Creating custom repository types for Deployment Manager.
When you create repositories, note the following information:
- The Pega repository type is not supported.
- Ensure that each repository has the same name on all systems.
- When you create JFrog Artifactory repositories, ensure that you create a Generic package type in JFrog Artifactory. Also, when you create the authentication profile for the repository in Pega Platform, you must select the Preemptive authentication check box.
After you configure a pipeline, you can verify that the repository connects to the URL of the development and production repositories by clicking Test Connectivity on the Repository rule form.
Step 3: Configuring systems for branch-based development (optional)
After you configure the orchestration server and all your candidate systems, configure additional settings so that you can use pipelines if you are using branches in a distributed or non-distributed branch-based environment.
- Step 3a: Configuring the development system for branch-based development
- Step 3b: Configuring the orchestration server for branch-based development
Step 3a: Configuring the development system for branch-based development
You must configure the development system to create a pipeline in a branch-based environment.
- On the development system (in nondistributed environment) or the main development system (in a distributed environment), create a Dynamic System Setting to define the URL of the orchestration server, even if the orchestration server and the development system are the same system.
- Click Create > Records > SysAdmin > Dynamic System Settings.
- In the Owning Ruleset field, enter
Pega-DevOps-Foundation
. - In the Setting Purpose field, enter
RMURL
. - Click Create and open.
- On the Settings tab, in the Value field, enter the URL of the orchestration server. Use this format: http://hostname:port/prweb/PRRestService.
- Click .
- Complete the following steps on either the development system (in a non-distributed environment) or the remote development system (in a distributed environment).
- Use the New Application wizard to create a new development application that developers will log in to. This application allows development teams to maintain a list of development branches without modifying the definition of the target application.
- Add the target application of the pipeline as a built-on application layer of the development application.
- Log in to the application.
- In the Designer Studio header, click the name of your application, and then click Definition.
- In the Built-on application section, click Add application.
- In the Name field, press the Down Arrow key and select the name of the target application.
- In the Version field, press the Down Arrow key and select the target application version.
- Click Save.
- Lock the application rulesets to prevent developers from making changes to rules after branches have been merged.
- In the Designer Studio header, click the name of your application, and then click Definition.
- In the Application rulesets section, click the Open icon for each ruleset that you want to lock.
- Click .
- Optional: It is recommended that you merge branches by using the Merge Branch wizard. However, you can publish a branch to the remote development system to start a build. Publishing a branch when you have multiple pipelines per application is not supported.
- In Designer Studio, enable Pega repository types. For more information, see Enabling the Pega repository type.
- Create a new Pega repository type. For more information, see Creating a repository connection. Ensure that you do the following tasks:
- In the Host ID field, enter the URL of the development system.
- The default access group of the operator that is configured for the authentication profile of this repository should point to the pipeline application on the development system (in a nondistributed environment) or main development system (in a distributed environment).
- Configure the orchestration server. For more information, see Step 3b: Configuring the orchestration server for branch-based development.
Step 3b: Configuring the orchestration server for branch-based development
Configure the orchestration server so that you can use pipelines in a branch-based environment.
- Create a Dynamic System Setting to define the operator who can start queued builds. The build will be started using the operator that you define in this Dynamic System Setting.
- Click Create > Sysadmin > Dynamic System Settings.
- In the Owning Ruleset field, enter
Pega-DevOps-DeploymentManager
. - In the Setting Purpose field, enter
ReleaseManager
. - Click Create and open.
- On the Settings tab, in the Value field, enter the operator ID whose default access group points to the release manager application.
- Click .
- Save the Pega-DeploymentManager agent to your ruleset and set its access group to the release manager application access group.
- Click Designer Studio > System > Operations > Agent Management.
- Filter the Name column with
Pega-DeploymentManager
. - Click the Security tab.
- In the Access Group field, press the Down Arrow key and select the access group of the release manager application.
- Click Save.
Step 4: Configuring additional settings
As part of your pipeline, you can optionally send email notifications to users, configure Jenkins if you are using a Jenkins task, and upgrade to the latest version of Deployment Manager if you are using a previous version. See the following topics for more information:
- Configuring email notifications on the orchestration server
- Configuring Jenkins
- Upgrading to Deployment Manager 3.x.x on the orchestration server
Configuring email notifications on the orchestration server
You can optionally configure email notifications on the orchestration server. For example, users can receive emails when pre-merge criteria are not met and the system cannot create a build.
To configure the orchestration server to send emails, complete the following steps:
- Use the Email wizard to configure an email account and listener by clicking Designer Studio > Integration > Email > Email Wizard. This email account sends notifications to users when events occur, for example, if there are merge conflicts. For detailed information, see the procedure for “Configuring an email account that receives email and creates or manages work” in Entering email information in the Email wizard.
- From the What would you like to do? list, select Receive an email and create/manage a work object.
- From the What is the class of your work type? list, select Pega-Pipeline-CD.
- From the What is your starting flow name? list, select NewWork.
- From the What is your organization? list, select the organization that is associated with the work item.
- In the What Ruleset? field, select the ruleset that contains the generated email service rule. This ruleset applies to the work class.
- In the What RuleSet Version? field, select the version of the ruleset for the generated email service rule.
- Click Next to configure the email listener.
- In theEmail Account Name field, enter
Pega-Pipeline-CD
, which is the name of the email account that the listener references for incoming and outgoing email. - In the Email Listener Name field, enter the name of the email listener. Begin the name with a letter, and use only letters, numbers, the ampersand character (&), and hyphens.
- In the Folder Name field, enter the name of the email folder that the listener monitors. Typically, this folder is INBOX.
- In the Service Package field, enter the name of the service package to be deployed. Begin the name with a letter, and use only letters, numbers, and hyphens to form an identifier.
- In the Service Class field, enter the service class name.
- In the Requestor User ID field, press the Down Arrow Key and select the operator ID of the release manager operator.
- In the Requestor Password field, enter the password for the release manager operator.
- In the Requestor User ID field, enter the operator ID that the email service uses when it runs.
- In the Password field, enter the password for the operator ID.
- Click Next to continue the wizard and configure the service package. For more information, see Configuring the service package in the Email wizard.
- After you complete the wizard, enable the listener that you created in the Email Wizard. For more information, see Starting a listener.
Email notifications
Emails are also preconfigured with information about each notification type. For example, when a build failure occurs, the email that is sent provides information, such as the pipeline name and URL of the system on which the build failure occurred.
Preconfigured emails are sent in the following scenarios:
- Build start – When a build starts, an email is sent to the release manager and, if you are using branches, to the operator who started a build.
- Build failure – If any step in the build process is unsuccessful, the build pauses. An email is sent to the release manager and, if you are using branches, to the operator who started the branch merge.
- Build step completion – When a step in a build process is completed, an email is sent to the release manager and, if you are branches, to the operator who started the branch merge.
- Stage completion – When a stage in a build process is completed, an email is sent to the release manager and, if you are using branches, to the operator who started the branch merge.
- Build completion – When a build is successfully completed, an email is sent to the release manager and, if you are using branches, to the operator who started the branch merge.
- Manual tasks requring approval – When a manual task requires email approval from a user, an email is sent to the user, who can approve or reject the task from the email.
- Stopped build – When a build is stopped, an email is sent to the release manager and, if you are using branches, to the operator who started the branch merge.
- Pega unit testing failure – If a Pega unit test cannot successfully run on a step in the build, an email is sent to the release manager and, if you are using branches, to the operator who started the branch merge.
- Schema changes required – If you do not have the required schema privileges to deploy them on application packages that require those changes, an email is sent to the operator who started the build.
Configuring Jenkins
If you are using a Jenkins task in your pipeline, configure Jenkins so that it can communicate with the orchestration server.
- On the orchestration server, create an authentication profile that uses Jenkins credentials.
- Click Create > Security > Authentication Profile.
- Enter a name, and then click Create and open.
- In the User name field, enter the user name of the Jenkins user.
- Click Set password, enter the Jenkins password, and then click Submit.
- Click the Preemptive authentication check box.
- Click .
- Because the Jenkins task does not support Cross-Site Request Forgery (CSRF), disable it by completing the following steps:
- In Jenkins, click Manage Jenkins.
- Click Configure Global Security.
- In the CRSF Protection section, clear the Prevent Cross Site Request Forgery exploits check box.
- Click Save.
- Install the Post build task plug-in.
- Install the curl command on the Jenkins server.
- Create a new freestyle project.
- On the General tab, select the This project is parameterized check box.
- Add the BuildID and CallBackURL parameters.
- Click Add parameter, and then select String parameter.
- In the String field, enter BuildID.
- Click Add parameter, and thenselect String parameter.
- In the String field, enter CallBackURL.
- In the Build Triggers section, select the Trigger builds remotely check box.
- In the Authentication Token field, select the token that you want to use when you start Jenkins jobs remotely.
- In the Build Environment section, select the Use Secret text(s) or file(s)check box.
- In the Bindings section, do the following actions:
- Click Add, and then select User name and password (conjoined).
- In the Variable field, enter RMCREDENTIALS .
- In the Credentials field, click Specific credentials.
- Click Add, and then select Jenkins.
- In the Add credentials dialog box, in the Username field, enter the operator ID of the release manager operator that is configured on the orchestration server.
- In the Password field, enter the password.
- Click .
- In the Post-Build Actions section, do one of the following actions, depending on your operating system:
- If Jenkins is running on Microsoft Windows, add the following post-build tasks:
- Click Add post-build action, and then select Post build task.
- In the Log text field, enter a unique string that for the message that is displayed in the build console output when a build fails, for example BUILD FAILURE.
- In the Script field, enter curl --user %RMCREDENTIALS% -H "Content-Type: application/json" -X POST --data "{\"jobName\":\"%JOB_NAME%\",\"buildNumber\":\"%BUILD_NUMBER%\",\"pyStatusValue\":\"FAIL\",\"pyID\":\"%BuildID%\"}" "%CallBackURL%".
- Click Add another task.
- In the Log text field, enter a unique string that for the message that is displayed in the build console output when a build is successful, for example BUILD SUCCESS.
- In theScript field, entercurl --user %RMCREDENTIALS% -H "Content-Type: application/json" -X POST --data "{\"jobName\":\"%JOB_NAME%\",\"buildNumber\":\"%BUILD_NUMBER%\",\"pyStatusValue\":\"SUCCESS\",\"pyID\":\"%BuildID%\"}" "%CallBackURL%"
- Click .
- If Jenkins is running on UNIX or Linux, add the following post-build tasks. Use the dollar sign ($) to access the environment variables instead of the percent sign (%).
- Click Add post-build action, and then select Post build task.
- In the Log text field, enter a unique string that for the message that is displayed in the build console output when a build fails, for example BUILD FAILURE.
- In the Script field, enter curl --user $RMCREDENTIALS -H "Content-Type: application/json" -X POST --data "{\"jobName\":\"$JOB_NAME\",\"buildNumber\":\"$BUILD_NUMBER\",\"pyStatusValue\":\"FAIL\",\"pyID\":\"$BuildID\"}" "$CallBackURL"
- Click Add another task.
- In the Log text field, enter a unique string that for the message that is displayed in the build console output when a build is successful, for example BUILD SUCCESS.
- In the Script field, enter curl --user $RMCREDENTIALS -H "Content-Type: application/json" -X POST --data "{\"jobName\":\"$JOB_NAME\",\"buildNumber\":\"$BUILD_NUMBER\",\"pyStatusValue\":\"SUCCESS\",\"pyID\":\"$BuildID\"}" "$CallBackURL"
- Click .
Upgrading to Deployment Manager 3.1.x on the orchestration server
If you are using an earlier version of Deployment Manager, upgrade to Deployment Manager 3.1.x by running the pxUpdatePipeline activity in the Data-Pipeline-Configuration classon the orchestration server.
- In Designer Studio, search for pxUpdatePipeline, and then click the activity in the dialog box that displays the results.
- Click Actions > Run.
- In the dialog box that appears, click .