Deploying Pega Platform Using Compute Engine and Cloud SQL

This tutorial shows you how to deploy Pega Platform on Google Cloud. You'll find this tutorial useful if you're a sysadmin, developer, or engineer who's interested in the details of the deployment process.

Pega Platform is a business process management (BPM) and customer relationship management (CRM) platform. Pega helps enterprises and agencies quickly build business apps that deliver the outcomes and end-to-end customer experiences they need.

This guide assumes that you have a basic familiarity with Cloud Shell, Cloud SQL, Compute Engine, and the Linux command line.


The Pega Platform is a Java EE-compliant enterprise application that consists of two layers:

  • Application servers host the Pega Platform application and provide interconnectivity to other systems.
  • Database servers store the rules, data, and work objects that are used and generated by the Pega Platform.

Application users and developers typically access the Pega Platform through a web browser.

Applications can also expose HTTP-based services, such as SOAP or REST, for administration or to process automation in a headless environment.

This tutorial provides the following:

  • A reference architecture for implementing a scalable Pega application on Google Cloud that's suitable for a development environment. Your infrastructure and security needs vary, so you can adjust the configurations described in this tutorial accordingly.
  • A GitHub repository that contains scripts that you use in the tutorial to install Pega and other required components.
  • Instructions for how to stage the Pega Platform 7.4 installation media, how to deploy scripts, and how to deploy the reference architecture.
  • Instructions for how to configure Pega to support Cloud Load Balancing.

At the end of this tutorial, you'll have a Pega cluster with a single Cloud SQL for PostgreSQL instance and three clustered Compute Engine application virtual machines (VMs) fronted by Cloud Load Balancing for web traffic. All SQL connections are made by using Cloud SQL Proxy. This tutorial uses the us-central1 region for the Pega deployment.

The following products are used in this tutorial. If you use different versions of these products, you might need to make adjustments to the scripts and commands that are referenced in this tutorial and in the repositories.

  • Pega Platform 7.4
  • PostgreSQL 9.6
  • Red Hat Enterprise Linux 7
  • Apache Tomcat 8.5

The following diagram shows the architecture of the Pega deployment discussed in this tutorial.

Architecture of Pega deployment


  • Deploy PostgreSQL by using Cloud SQL.
  • Configure Pega.
  • Install the Pega Rulebase.
  • Install Pega app servers.
  • Use Cloud Logging and Cloud Monitoring for error reporting and monitoring during the installation.


This tutorial uses billable components of Google Cloud, including:

  • Compute Engine
  • Persistent Disk
  • Cloud SQL
  • Cloud Storage
  • Networking

Use the Pricing Calculator to generate a cost estimate based on your projected usage.

Before you begin

  1. Make sure that you have the Pega 7.4 installation media file. If you don't yet have it, contact Pega Support.
  2. Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.
  3. In the Google Cloud Console, on the project selector page, select or create a Google Cloud project.

    Go to project selector

  4. Make sure that billing is enabled for your Cloud project. Learn how to confirm that billing is enabled for your project.

  5. Enable the Compute Engine, Cloud SQL Admin, Logging, and Monitoring APIs.

    Enable the APIs

  6. In the Google Cloud Console, on the project selector page, select or create a Google Cloud project.

    Go to project selector

  7. Make sure that billing is enabled for your Cloud project. Learn how to confirm that billing is enabled for your project.

  8. Enable the Compute Engine, Cloud SQL Admin, Logging, and Monitoring APIs.

    Enable the APIs

You use Cloud Shell for all of the terminal commands in this tutorial. When you finish this tutorial, you can avoid continued billing by deleting the resources that you created. See Cleaning up for more detail.

Preparing your environment

In this section, you make default settings for values that are used throughout the tutorial, like region and zone. In this tutorial, you use us-central1 as the default region and us-central1-b as the default zone.

You also create a file with all of the settings, so that you can load the variables automatically if you need to reopen Cloud Shell and reinitialize the settings.

  1. Open Cloud Shell:

    Open Cloud Shell

  2. Set the default region and zone:

    gcloud compute project-info add-metadata \
        --metadata google-compute-default-region=us-central1,google-compute-default-zone=us-central1-b
  3. Reinitialize the shell:

    gcloud init --console-only

    Press 1 for the first three questions, and then enter the project ID for the last question.

  4. Set an environment variable to hold the name of the Cloud Storage bucket that you create later in this tutorial. For [BUCKET_NAME], substitute your own name. Follow the rules for Cloud Storage bucket names. For details, see Bucket Naming Guidelines.

  5. Set an environment variable to hold the name of your Pega 7.4 installation file. The installation file that you get from Pega is a zip file whose name contains a unique number. In the following example, for [NNNNN], substitute your unique number.

  6. Set an environment variable to hold your Cloud SQL instance name. Follow the rules for instance names—they can contain only lowercase letters, numbers, and hyphens, and must start with a letter.

  7. Set an environment variable to hold your database Pega Admin user password:

  8. Set an environment variable to hold your database Pega Base user password:

  9. Set an environment variable to hold the initial value for your Pega administrator ( password:

  10. Set an environment variable to hold your default region:

    REGION=$(gcloud compute project-info describe \
        --format 'value(')
  11. Create a file with the environment variables:

    cat <<EOF > ~/.pegarc
  12. Load the environment variables in the current session and set Cloud Shell to automatically load the variables on future sign-ins:

    grep -q -F "source ~/.pegarc" ~/.bashrc || echo "source ~/.pegarc" >> ~/.bashrc

Setting up the service account

To allow Pega to have access to the resources for the tutorial, you must create a Google Cloud service account. The service account needs the following roles:

  • cloudsql.client. Used to connect to the Cloud SQL database through Cloud SQL Proxy.
  • storage.objectViewer. Used to download files from Cloud Storage.
  • logging.logWriter. Used to write logs to Cloud Logging.
  • monitoring.metricWriter. Used to write monitoring data to Cloud Monitoring.
  • errorreporting.writer. Used to write error info to Cloud Logging.

To create the service account:

  1. In Cloud Shell, create a service account named pega-app:

    gcloud iam service-accounts create pega-app --display-name "pega-app"
  2. Add the roles to the service account:

    gcloud projects add-iam-policy-binding ${DEVSHELL_PROJECT_ID} \
        --member=serviceAccount:pega-app@${DEVSHELL_PROJECT_ID} \
    gcloud projects add-iam-policy-binding ${DEVSHELL_PROJECT_ID} \
        --member=serviceAccount:pega-app@${DEVSHELL_PROJECT_ID} \
    gcloud projects add-iam-policy-binding ${DEVSHELL_PROJECT_ID} \
        --member=serviceAccount:pega-app@${DEVSHELL_PROJECT_ID} \
    gcloud projects add-iam-policy-binding ${DEVSHELL_PROJECT_ID} \
        --member=serviceAccount:pega-app@${DEVSHELL_PROJECT_ID} \
    gcloud projects add-iam-policy-binding ${DEVSHELL_PROJECT_ID} \
        --member=serviceAccount:pega-app@${DEVSHELL_PROJECT_ID} \

Setting up Cloud SQL

The next step is to create a database. For this tutorial, you use a PostgreSQL database on Cloud SQL.

  1. In Cloud Shell, create the Cloud SQL instance:

    gcloud sql instances create ${CLOUD_SQL_INSTANCE_NAME} \
        --database-version=POSTGRES_9_6 --cpu=2 --region=${REGION} \
        --memory=8GB --storage-auto-increase --backup-start-time=00:00 \

    In this tutorial, you use an instance with two vCPUs and 8 GB of RAM. This step might take a few minutes to complete.

  2. Create the Pega runtime users for your installation using a dual-user configuration. In a dual-user configuration, an Admin user is granted full privileges to the database, and a Base user is granted a smaller subset.

    gcloud sql users create PegaADMIN \
        --instance=${CLOUD_SQL_INSTANCE_NAME}  \
    gcloud sql users create PegaBASE \
        --instance=${CLOUD_SQL_INSTANCE_NAME}  \

Setting up a Cloud Storage bucket

You need to create a Cloud Storage bucket that holds the Pega installation media and other scripts that are used in this tutorial.

  1. In Cloud Shell, create the bucket:

    gsutil mb -c regional -l ${REGION} gs://${GCS_BUCKET}
  2. Using the Cloud Console, upload the Pega 7.4 installation zip file to the new storage bucket. Upload the file to the root of your new bucket.

Uploading the installation scripts to a Cloud Storage bucket

You now download the GitHub source repository that's part of this solution to your Cloud Shell instance. You can then upload the repository to a Cloud Storage bucket.

  1. In Cloud Shell, download the zip file that contains the installation scripts from the GitHub repository:

  2. Unzip the contents of the file:

  3. Upload the scripts to your bucket:

    gsutil cp -rP solutions-compute-cloudsql-pega7-master/ gs://${GCS_BUCKET}/scripts

Installing the Pega Rulebase

The Pega Rulebase stores rules, work items, and other data that Pega uses for its operations. To install the Pega Rulebase, you set up a temporary Compute Engine VM to run the Pega installation scripts. You can use a startup script that has preconfigured settings so that you don't need to manually execute installation commands. In this step, you use a startup script, but you can also perform the installation manually.

The Pega Rulebase installation script performs the following actions:

  • Runs system updates.
  • Installs Cloud Logging and Cloud Monitoring agents.
  • Installs required packages, such as the PostgreSQL client and the Java Development Kit (JDK).
  • Installs and configures Cloud SQL Proxy to connect to the Cloud SQL instance.
  • Downloads and unzips the Pega installation file from the Cloud Storage bucket.
  • Populates the file that contains required environment variables.
  • Downloads the PostgreSQL JDBC driver.
  • Creates the Pega schemas in the database.
  • Runs the Pega Rulebase installation script.

To install the Pega Rulebase:

  1. In Cloud Shell, create the VM that includes the Pega Rulebase installation startup script:

    gcloud compute instances create pega-db-installer \
        --machine-type=n1-standard-4 \
        --service-account=pega-app@${DEVSHELL_PROJECT_ID} \
        --scopes= \
        --image-family rhel-7  \
        --image-project=rhel-cloud \
        --boot-disk-size=35GB \

    This process can take up to 1 hour.

    Tip: You can create the firewall rules and instance template in the following two sections while the Pega installation is running.

  2. Check the status of the installation by viewing the startup script log.

    1. Go to the Cloud Logging console:

      Cloud Logging Console

    2. From the drop-down list, select the Compute Engine instance named pega-db-installer.

    3. Search for startup-script-url to filter only the log messages that come from the startup script.

      When the log line displays Your Pega installation is complete!, you can go to the next step.

  3. Delete the installation VM instance:

    gcloud compute instances delete pega-db-installer

Creating firewall rules

You must create some firewall rules to allow traffic to and from the application servers that you create. Later in this tutorial, you attach the pega-app network tag to your VMs and then configure your firewall rules accordingly.

For a Pega deployment, you must allow the following types of traffic, as defined in the Pega Installation Guide:

  • Pega Hazelcast clustering communication. This uses TCP ports 5701 through 5800 between each Pega application server in the cluster.
  • Pega ElasticSearch node-to-node communication. This uses TCP ports 9300 through 9399 between each Pega application server in the cluster.
  • Port 8080 or 8443 for traffic from your users, or the Cloud Load Balancing IP address ranges. This allows web traffic to reach your Pega installation. The global load balancers have the following source IP ranges:

To create firewall rules:

  1. Allow traffic from any VM with the pega-app network tag to any other VM with the pega-app network tag:

    gcloud compute firewall-rules create pega-internal \
        --description="Pega node to node communication requirements" \
        --action=ALLOW \
        --rules=tcp:9300-9399,tcp:5701-5800 \
        --source-tags=pega-app \
  2. Allow traffic from the global load balancer to any VM that has the pega-app network tag:

    gcloud compute firewall-rules create pega-web-external \
        --description="Pega external web ports" \
        --action=ALLOW \
        --rules=tcp:8080,tcp:8443 \
        --source-ranges=, \

Creating the instance template for the application servers

To create a highly available Pega cluster, you use instance groups to define the location, capacity, and elasticity of your Pega cluster, and you use instance templates to ensure that each VM is running the same configuration.

In this tutorial, you use the n1-standard-2 machine type, which has 2 vCPUs and 7.5 GB of RAM. For more information, see the documentation on Google Cloud machine types. Adjust your settings accordingly, depending on the requirements of your environment.

  • Create the instance template:

    gcloud compute instance-templates create pega-app \
        --machine-type=n1-standard-2 \
        --service-account=pega-app@${DEVSHELL_PROJECT_ID} \
        --scopes= \
        --tags=pega-app --image-family rhel-7 --image-project=rhel-cloud \
        --boot-disk-size=20GB \

The Pega app server installation script does the following tasks:

  • Installs the latest system updates.
  • Installs Cloud Logging and Cloud Monitoring agents.
  • Installs the JDK.
  • Installs and configures Cloud SQL Proxy to connect to the Cloud SQL instance and run it as a service.
  • Installs Tomcat.
  • Downloads the PostgreSQL JDBC driver.
  • Configures Tomcat with settings required by Pega.
  • Downloads the Pega installation media from the Cloud Storage bucket and installs the Pega web application archives for Tomcat.
  • Starts Tomcat and Pega.

Creating the instance group

After you create the instance template, you create an instance group that uses the VM templates that you created earlier.

In this tutorial, you create an instance group that has three VMs. The group does not automatically scale. However, it re-creates VMs if any of them shut down.

  1. Create a managed instance group:

    gcloud compute instance-groups managed create "pega-app" \
        --base-instance-name "pega-app" \
        --template "pega-app" \
        --size "3" \

    This command creates an instance group named pega-app that has three VMs.

  2. Create a named port:

    gcloud compute instance-groups managed set-named-ports pega-app \
        --named-ports=pega-web:8080 \

The instance group begins creating your VMs automatically.

Creating the load balancer

To give users access to your Pega application servers, you need to create a load balancer to distribute web traffic between VMs in the instance group. A load balancer is a combination of several components, including the following:

  • A global forwarding rule (frontend).
  • A target proxy.
  • A URL map.
  • A backend service with one or more backends.
  • A health check to determine whether backend services are healthy.

To create the load balancer:

  1. In Cloud Shell, create the health check:

    gcloud compute health-checks create http pega-health \
        --request-path=/prweb/PRRestService/monitor/pingservice/ping \

    This configures the health check to monitor the Pega-provided ping service, which replies with information about whether the Pega instance is up and running. For details, see Verifying that an instance is running.

  2. Create the backend service:

    gcloud compute backend-services create pega-app \
        --health-checks=pega-health \
        --port-name=pega-web \
        --session-affinity=GENERATED_COOKIE \
        --protocol=HTTP --global

    The backend service defines health checks that test whether instances are healthy, and also lets you set load-balancing policies.

  3. Add a backend to the backend service:

    gcloud compute backend-services add-backend pega-app \
        --instance-group=pega-app \
        --global \

    The backend defines which instance group that traffic is routed to.

  4. Create the URL map:

    gcloud compute url-maps create pega-app --default-service=pega-app

    This command sets a default URL map to route all traffic to the backend service that you created. In a more complex architecture, you could route traffic with different URL patterns to different backend services.

  5. Create the target proxy:

    gcloud compute target-http-proxies create pega-app --url-map=pega-app
  6. Create a static IP address:

    gcloud compute addresses create pega-app --global

    This command creates a static IP address that you can use to map to a domain name system (DNS) record. If you prefer an ephemeral IP address, skip this step and omit the --address option from the global forwarding rule in the next step.

  7. Create the frontend global forwarding rule:

    gcloud compute forwarding-rules create pega-app \
        --global \
        --address=$(gcloud compute addresses describe pega-app --global --format 'value(address)') \
        --ip-protocol=TCP \
        --ports=80 \

Connecting to your Pega application

It might take 5 to 10 minutes for the instance group to become available for the first time. In this section, you check that your deployment goes online, and you then go to the main login page.

  1. To check the status of your load balancer, go to the Load balancing page in the Cloud Console.

    Open the Load Balancing Page

    When the deployment is ready, in the Backends column you see a green status icon next to the name of your load balancer.

  2. Find the IP address that you assigned to your load balancer:

    gcloud compute forwarding-rules describe pega-app --global
  3. Copy and paste the IP address into your browser using the following syntax. For [IP_ADDRESS], substitute the IP address that you got in the preceding step.


Configuring the Pega deployment

To fully support the load balancer, you need to create Dynamic System Settings. This tells Pega what cookie to look for when an administrator quiesces a Pega node, and ensures that end users maintain their web sessions properly.

You need to create two system settings to enable this feature. In this tutorial, you use Dynamic System Settings, which lets you create the settings only once for an entire cluster.

Tip: You can also import the settings by using the Application Import Wizard. For details, see What's next.

  1. In a browser window, sign in to the Pega console using your user name and the password (PEGA_ADMIN_PW) that you set in the Preparing your environment section.

    You are prompted to change the password the first time you sign in.

  2. In the Pega console, click Create > SysAdmin > Dynamic System Settings.

  3. In the Create Dynamic System Settings page, configure the following settings:

    • Short description: prconfig/session/ha/quiesce/customSessionInvalidationMethod
    • Owning Ruleset: Pega-Engine
    • Setting Purpose: prconfig/session/ha/quiesce/customSessionInvalidationMethod
  4. Click Create and open.

  5. Set the value field to configurable-cookie-invalidator and click Save.

  6. Click the down arrow to the right of Save, and then click Save As.

    Save As option for Dynamic System Settings

  7. Create another setting with the following values:

    • Short Description: prconfig/session/ha/quiesce/cookieToInvalidate
    • Owning Ruleset: Pega-Engine
    • Setting Purpose: prconfig/session/ha/quiesce/cookieToInvalidate
  8. Click Create and open.

  9. Set the value field to GCLB and then click Save.

  10. In Cloud Shell, perform a rolling restart for the instance group:

    gcloud beta compute instance-groups managed rolling-action \
        restart pega-app \

    When all of your Application Servers come back online, your deployment is complete.

For more information about configuring session affinity in Pega, check out the Pega Help Documentation on PDN for reference.

Clean up

To avoid incurring charges to your Google Cloud account for the resources used in this tutorial, either delete the project that contains the resources, or keep the project and delete the individual resources.

Delete the project

  1. In the Cloud Console, go to the Manage resources page.

    Go to Manage resources

  2. In the project list, select the project that you want to delete, and then click Delete.
  3. In the dialog, type the project ID, and then click Shut down to delete the project.

What's next