Pega deployment on Kubernetes

This project provides Helm charts and basic examples for deploying Pega on Kubernetes. You will also need to download the required installation kit from the Pega Community which includes rules and data to preload into your relational database. Deploying Pega on Kubernetes requires Pega Infinity 8.2 or newer.

Supported Kubernetes environments

Pegasystems has validated deployments on the following Kubernetes IaaS and PaaS environments.

• Open-source Kubernetes (and MiniKube for personal deployments)
• Microsoft Azure Kubernetes Service (AKS) - see the AKS runbook
• Amazon Elastic Kubernetes Service (EKS) - see the EKS runbook
• Google Kubernetes Engine (GKE) - see the GKE runbook
• Red Hat OpenShift
• VMware Tanzu Kubernetes Grid Integrated Edition (TKGI) - see the TKGI runbook

Getting started

This project assumes you have an installation of Kubernetes available and have Helm installed locally. The following commands will verify your installation. The exact output may be slightly different, but they should return without error.

$ helm version
version.BuildInfo{Version:"v3.0.0", GitCommit:"e29ce2a54e96cd02ccfce88bee4f58bb6e2a28b6", GitTreeState:"clean", GoVersion:"go1.13.4"}

If this command does not successfully return, install Helm 3 for your operating system. See Helm Installation for more information. If you are running Helm 2.x, you will see both a client and server (tiller) portion returned by the version command. Some of the commands below will also differ slightly for Helm 2.x.

1. Add the Pega repository to your Helm installation.

$ helm repo add pega https://dl.bintray.com/pegasystems/pega-helm-charts

2. Verify the new repository by searching it.

$ helm search repo pega
NAME       	            CHART VERSION	APP VERSION	DESCRIPTION
pega/pega  	              1.2.0        	           	Pega installation on kubernetes
pega/addons	              1.2.0        	1.0        	A Helm chart for Kubernetes 
pega/backingservices          1.2.0        	                Helm Chart to provisioning backing services for Pega (eg. Search and Reporting Service)

There are three charts available in this repository - addons, backingservices, and pega.

The addons chart installs a collection of supporting services and tools required for a Pega deployment. The services you will need to deploy will depend on your cloud environment - for example you may need a load balancer on Minikube, but not for EKS. These supporting services are deployed once per Kubernetes environment, regardless of how many Pega Infinity instances are deployed.

The backingservices chart installs services like 'Search and Reporting Service' (SRS) that you can configure with one or more Pega deployments. You can deploy these backing services in their own namespace; you can isolate the services to a single environment or share them across multiple Pega Infinity environments.

Example: Single backing service shared across all pega environments:

backingservice 'Search and Reporting Service' deployed and the service endpoint configured across dev, staging and production pega environments. The service provides isolation of data in a shared setup.

Multiple backing service deployments:

You can deploy more than one instance of backing service deployments, in case you want to host a separate deployment of 'Search and Reporting Service' for non-production and production deployments of Pega Infinity. You must configure the appropriate service endpoint using the Pega Infinity deployment values.

3. Download the values file for pega/pega, pega/addons and pega/backingservices.

$ helm inspect values pega/pega > pega.yaml
$ helm inspect values pega/addons > addons.yaml
$ helm inspect values pega/backingservices > backingservices.yaml

4. Edit your values yaml files to specify all required information and customizations for your environment.

• Instructions to configure the Pega chart
• Instructions to configure the Pega addons
• Instructions to configure the Pega backingservices

5. Create namespaces for your Pega deployment, backingservices and the addons (if applicable for your environment).

$ kubectl create namespace mypega
$ kubectl create namespace pegaaddons
$ kubectl create namespace pegabackingservices

6. To install the backingservices chart, run the following helm command after configuring your values.yaml file (if applicable for your environment).

$ helm install backingservices pega/backingservices --namespace pegabackingservices --values backingservices.yaml

7. To install the addons chart, run the following helm command after configuring your values.yaml file (if applicable for your environment).

$ helm install addons pega/addons --namespace pegaaddons --values addons.yaml

8. With addons and backservices deployed, you are ready to deploy Pega Infinity using the pega chart. Before installing using the chart, it is a good idea to review the detailed deployment guide to understand how Pega deploys as a distributed system. Running a Helm installation using the pega chart installs a Pega Infinity instance into a specified namespace. After you edit the chart with your configuration requirements, run the following command to install the pega chart.

$ helm install mypega pega/pega --namespace mypega --values pega.yaml

To edit the charts and deploy using a local version of the pega/addons, pega/backingservices, or pega/pega charts, you must include the filepath to your local chart directory in your Helm chart reference.

9. To delete your deployment of Pega nodes, enter the command (this will not delete your database):

$ helm delete mypega

Downloading Docker images for your deployment

Clients with appropriate licenses can request access to several required images from the Pega-managed Docker image repository. With your access key, you can log in to the image repository and download these Docker images to install the Pega Platform onto your database. After you pull the images to your local system, you must push them into your private Docker registry.

To download your preferred version of the Pega image to your local system, specify the version tag when by entering:

$ sudo docker pull pega-docker.downloads.pega.com/platform/pega:<version>

Digest: <encryption verification>
Status: Downloaded pega-docker.downloads.pega.com/platform/pega:<version>

For details, see the examples listed in the preparation runbook:

• Preparing your local Linux system
• Preparing your local Windows 10 system

Pegasystems uses a standard naming practice of hostname/product/image:tag. Pega images are available from the host site, pega-docker.downloads.pega.com. Pega maintains four types of required Docker images for Client-managed Cloud deployments of Pega Platform:

For the platform/installer image, the :tag represents the version of Pega you want to install, for example the tag :8.5.1 will install Pega Platform version 8.5.1.

For platform/pega and platform/search images, Pega also offers an image with a version tag appended with a datestamp using the pattern pegaVersion-YYYYMMDD to indicate the version and the date that Pega built the image. For example, if you pull the platform/pega with a tag, pega:8.5.1-20201026, the tag indicates that Pega built this 8.5.1 image on 26 October 2020. Using the version tag without the datestamp will always point to the most recently built image for that version.

The Docker image platform-services/search-n-reporting-service is used with the Search and Reporting Service, or SRS subchart under backing services. The SRS subchart deployment provisions the latest generation of search and reporting capabilities in Pega Infinity. This service is an alternate search feature to the previously used platform/search image-based Elasticsearch deployment. To configure this service, see Instructions to configure the Pega backingservices.

The datestamp ensures that the image you download includes the changes that Pega engineering commits to the repository using pull requests by a certain date. While Pega builds the most current patch version of each minor release one time each day, Pega makes the last five daily-built images available for client downloads. After Pega releases a new patch version, the prior patch version no longer receives daily builds with a datestamp tag.

After you obtain access to the Pega-provided host repository and pull each image, you can re-tag and push each of the Pega-provided images to your preferred Docker registry to make them available to the deployment. For an overview of tagging and managing Docker images, see the Docker article, Deploy a registry server.

After you have the images in your Docker repository, you then provide your registry URL, credentials, and reference each image appropriately in the Pega Helm chart. You can find example usage details for referencing the three images in a repository in the appropriate runbook for your type of deployment.

These images do not expire, and you can keep them in your repository for as long as you require.

Contributing

This is an open source project and contributions are welcome. Please see the contributing guidelines to get started.