Skip to main content

         This documentation site is for previous versions. Visit our new documentation site for current releases.      

Installing, patching, or updating Pega software

Updated on July 20, 2022

After you push the required Docker images to your preferred Docker repository, you install Pega Platform software into your database when you initially deploy Pega Platform into your Kubernetes environment. After you have a deployment running, you can patch or update your Pega software using the latest Docker images.

Client-managed cloud information on Pega Community Client-managed cloud information on Pega Community

Using Pega runbooks specific to your environment

Pega provides step-by-step guidance in example runbooks that are customized for each supported Kubernetes environment. These runbooks guide you through preparation of your local system for the prerequisite configurations that Kubernetes deployments in your preferred environment require; requesting and subsequently downloading Pega-provided Docker images; and installing or patching, with zero downtime, your Pega software deployment. To get started deploying in your environment, access the appropriate runbook in Supported Kubernetes environments.

Getting the Pega charts

To deploy Pega Platform, Pega provides Helm charts in which you specify the requirements of the Pega deployment for your environment. You then use Helm to deploy all the required Kubernetes resources automatically.

Pega maintains a repository of Helm charts that are required to install, apply a patch, or update Pega Platform using Helm. After you add the repository to your local system, you can customize these Pega configuration files for your Pega Platform deployment. To get started using the Pega-provided Helm charts for deploying Pega Platform into the cloud environment of your choice, see Pega deployment on Kubernetes.

Helm Chart parameters

To deploy Pega Platform by using the Pega-provided Helm charts you must update the parameters in the following three charts:

  • To reflect the requirements for your Pega Platform deployment, edit the Pega Helm chart. For details about the Pega Helm chart configuration, see the Pega-specific Helm chart readme.
  • To configure the supporting services and tools, edit the Addons Helm chart. For more information, see the Addons-specific backing sub-charts readme.
  • To configure backing service such as Search and Reporting Service, edit the Backing Services Helm charts. For more information, see the BackingServices Helm chart readme.

For more general details about how to use Helm and Helm charts to manage Kubernetes orchestrations, see the Helm Quickstart Guide.

Best practices for managing configuration using secrets

To avoid directly entering your passwords as plain text in your Helm charts, Pega supports using Kubernetes secrets to secure credentials and related information. Use secrets to represent credentials for your database, Docker registry, or any other token or key that you need to pass to a deployed application. To create a secret, see the overview, Distribute Credentials Securely Using Secrets.

Pega supports two methods of passing secrets to your deployments; clients can choose the method that best suits their organization's needs:

  • Mounting secrets into your Docker containers using the External Secrets Operator - Use a Kubernetes External Secrets Operator to securely manage your secrets and inject them directly into your deployment’s Docker containers. For complete details, see the Kubernetes documentation for External Secrets Operator. Based on your environment type, follow the guidance for your specific cloud provider to create two files:
    • An external secret file that specifies what information in your secret to fetch.
    • A secret store to define access how to access the external and placing the required files in your Helm directory.
    Pega requires you to copy both files into the pega-helm-charts/charts/pega/templates directory of your Helm repository and then reference the secret name in the Pega Helm chart using the jdbc.external_secret_name parameter to refer to the External Secret Operator in which you placed your database password.
  • Passing secrets directly to your deployment - Passing secrets manually to your deployment by entering details into the Helm chart as described in the following table:

    Pass secrets manually to your deployment:

    TypeConfiguration Example
    Credentials using environment variablesenv:
    • - name: DB_USERNAME
    • - valueFrom:
    • - secretKeyRef:
    • - name: mysecret
    key: username
    • - name: DB_PASSWORD
    • - valueFrom:


    • - name: mysecret
    • - key: password
    Credentials using volume mountcontainers:
    • ...
    • - name: secret-volume
    • - mountPath: /opt/pega/secrets


    • - name: secret-volume


    • - secretName: mysecret

Installing other Pega applications

After you install Pega Platform using the installer Docker that you built, you can install additional Pega applications using the standard application installation process with an application distribution image you download from the Pega-managed sopftware release site. For the installation instructions, search for your installation guide available on the Pega Documentation home page; find you industry application guides using the Find your product pulldown.

Applying a patch to your Pega Platform deployment

Pega supports using the latest Pega Infinity Docker images that include the latest cumulative bundle of bug and security fixes since the last minor release to apply patches with a zero-time patch process:
  • For releases 8.4 and later, the Pega zero-downtime patch scripts use a new rules schema and a temporary data schema and the patch migration script moves the rules between the appropriate schemas in your deployment. At the end of the process the new rules schema becomes the Pega rules schema for your deployment. For more details about this specific patch process, see Patching systems without downtime (for Pega Platform version 8.4 and later).
  • For releases 8.3 and earlier, the Pega zero-downtime patch scripts use a new rules schema and the patch migration script moves the rules between the appropriate schemas. At the end of the process the new rules schema becomes the Pega rules schema for your deployment. For more details about this specific patch process, see Patching systems without downtime (for Pega Platform versions 8.3 and earlier).
Applying a Pega Platform patch includes only rule changes that are observed between the patch and the current version. For complete details about the difference between a major update, a minor update, and a patch, see Updating and patching Pega Infinity.

To get started applying a Pega Platform software patch to your existing deployment, see the Pega-provided runbook Patching Pega Platform in your deployment .

Updating the Pega software in your deployment

The Pega Helm charts support a zero-downtime updates process using the latest Pega Infinity Docker images. The zero-downtime update process synchronizes the required process steps to minimize downtime so you and your customers can continue to access and use their applications in your environment with minimal disruption while you patch or update your system.

To update Pega Platform software deployed in a Kubernetes environment in zero-downtime, you must download the latest -provided-provided images for the version to which you are updating and use the Helm chart with versions 1.6.0 or later to complete the update. To learn about how the update process works and its requirements and the steps you must complete, see the Pega-provided runbook, Updating Pega Platform in your deployment with zero-downtime.

To complete your Pega Infinity update, after you update your Pega Platform software using the Pega-provided Helm charts and Docker images, you must use the latest Pega application software update guide that is separate from Pega Platform software. For the update instructions, search for your update guide available on the Pega Documentation home page; find you industry application guides using the Find your product pulldown.

Configuring logging for Client-managed cloud deployments

Configure diagnostic logging for Pega Platform deployments in your Kubernetes environment to help you diagnose a problem you might encounter when installing, patching or update Pega Platform in your client-managed deployment.

logging, installations, updates

The Pega Helm chart leverages the Pega Platform deployment scripts, which use Apache’s Log4j 2 logging framework. The Log4j configuration is stored in an xml file called prlog4j2.xml. With the Helm chart, you can customize the Log4j configuration, which allows you to add additional debug logging during deployments. Generally, this does not need to be changed, but can be modified if necessary to capture additional debug logging.

For more information on how deployment logging works for Pega Platform, and to see loggers that can be enabled, see .

If you have the Pega helm chart checked out directly, you can modify the prlog4j2.xml file found here: . The file can be modified in the same way as described in the referenced Pega Platform logging article.

If you cannot modify the helm chart files and you can only pass in helm values, you will need to provide a replacement prlog4j2.xml file and mount it into the installation image. The location for the prlog4j2.xml file is controlled by the prlogging.config property, referenced in . To set this value, set the helm chart parameter pega.installer.advancedSettings to a json object containing name-value pairs. For example, you can provide:

helm install mypega pega/pega --namespace mypega --values pega.yaml --set installer.advancedSettings=[{"name": "prlogging.config", "value": "/path/to/mounted/prlog4j2.xml"}]

Have a question? Get answers now.

Visit the Support Center to ask questions, engage in discussions, share ideas, and help others.

Did you find this content helpful?

Want to help us improve this content?

We'd prefer it if you saw us at our best. is not optimized for Internet Explorer. For the optimal experience, please use:

Close Deprecation Notice
Contact us