Skip to content

Latest commit

 

History

History
1191 lines (910 loc) · 75 KB

README.md

File metadata and controls

1191 lines (910 loc) · 75 KB
Raw

Pega Helm chart

The Pega Helm chart is used to deploy an instance of Pega Infinity into a Kubernetes environment. This readme provides a detailed description of possible configurations and their default values as applicable. You reference the Pega Helm chart to deploy using the parameter settings in the Helm chart using the helm --set command to specify a one-time override specific parameter settings that you configured in the Pega Helm chart.

Supported providers

Enter your Kubernetes provider which will allow the Helm charts to configure to any differences between deployment environments. These values are case-sensitive and must be lowercase.

Value Deployment target
k8s Open-source Kubernetes
openshift Red Hat Openshift
eks Amazon Elastic Kubernetes Service (EKS)
gke Google Kubernetes Engine (GKE)
pks VMware Tanzu Kubernetes Grid Integrated Edition (TKGI), which used to be Pivotal Container Service (PKS)
aks Microsoft Azure Kubernetes Service (AKS)

Example for a kubernetes environment:

provider: "k8s"

Actions

Use the action section in the helm chart to specify a deployment action. The standard actions is to deploy against an already installed database, but you can also install a Pega system. These values are case-sensitive and must be lowercase.

For additional, required installation parameters, see the Installer section.

Value Action
deploy Start the Pega containers using an existing Pega database installation.
install Install Pega Platform into your database without deploying.
install-deploy Install Pega Platform into your database and then deploy.
upgrade Upgrade or patch Pega Platform in your database without deploying.
upgrade-deploy Upgrade or patch Pega Platform in your database and then deploy.

Example:

action: "deploy"

JDBC Configuration

Use the jdbc section of the values file to specify how to connect to the Pega database. Pega must be installed to this database before deploying on Kubernetes.

URL and Driver Class

These required connection details will point Pega to the correct database and provide the type of driver used to connect. Examples of the correct format to use are provided below.

Example for Oracle:

jdbc:
  url: jdbc:oracle:thin:@//YOUR_DB_HOST:1521/YOUR_DB_NAME
  driverClass: oracle.jdbc.OracleDriver

Example for Microsoft SQL Server:

jdbc:
  url: jdbc:sqlserver://YOUR_DB_HOST:1433;databaseName=YOUR_DB_NAME;selectMethod=cursor;sendStringParametersAsUnicode=false
  driverClass: com.microsoft.sqlserver.jdbc.SQLServerDriver

Example for IBM DB2 for LUW:

jdbc:
  url: jdbc:db2://YOUR_DB_HOST:50000/YOUR_DB_NAME:fullyMaterializeLobData=true;fullyMaterializeInputStreams=true;progressiveStreaming=2;useJDBC4ColumnNameAndLabelSemantics=2;
  driverClass: com.ibm.db2.jcc.DB2Driver

Example for IBM DB2 for z/OS:

jdbc:
  url: jdbc:db2://YOUR_DB_HOST:50000/YOUR_DB_NAME
  driverClass: com.ibm.db2.jcc.DB2Driver

Example for PostgreSQL:

jdbc:
  url: jdbc:postgresql://YOUR_DB_HOST:5432/YOUR_DB_NAME
  driverClass: org.postgresql.Driver

(Optional) Support for providing credentials/certificates using External Secrets Operator

To avoid directly entering your confidential content in your Helm charts such as passwords or certificates in plain text, Pega supports Kubernetes secrets to secure credentials and related information. Use secrets to represent credentials for your database, Docker registry, SSL certificates, externalized kafka service, or any other token or key that you need to pass to a deployed application. Your secrets can be stored in any secrets manager provider. Pega supports two methods of passing secrets to your deployments; choose the method that best suits you organization's needs:

• Mount secrets into your Docker containers using the External Secrets Operator(https://external-secrets.io/v0.5.3/).

To support this option,

  1. Create two files following the Kubernetes documentation for External Secrets Operator :
    • 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.
  2. Copy both files into the pega-helm-charts/charts/pega/templates directory of your local Helm repository.
  3. Update your local Helm repository to the latest version using the command:
  4. Update your values.yaml file to refer to the external secret manager for DB password.

• Pass secrets directly to your deployment using your organization's recommend practices.

Things to note in case of providing keystore, certificates for Enabling encryption of traffic between Ingress/LoadBalancer and Pod
  1. Configure the CA certificate and keystore as a base64 encrypted string inside your preferred secret manager (AWS Secret Manager, Azure Key Vault etc). For details, see this section.
  2. Have the keystore password as plaintext.
  3. The secret key should be TOMCAT_KEYSTORE_CONTENT, TOMCAT_KEYSTORE_PASSWORD and ca.crt for keystore, keystore password and CA certificate respectively.
  4. For alternate configuration the keys should be TOMCAT_CERTIFICATE_FILE, TOMCAT_CERTIFICATE_KEY_FILE and TOMCAT_CERTIFICATE_CHAIN_FILE, ca.crt(in case of traefik addon enabled) for certificate and key files.

Driver URI

Pega requires a database driver JAR to be provided for connecting to the relational database. This JAR may either be baked into your image by extending the Pega provided Docker image, or it may be pulled in dynamically when the container is deployed. If you want to pull in the driver during deployment, you will need to specify a URL to the driver using the jdbc.driverUri parameter. This address must be visible and accessible from the process running inside the container.

Use the customArtifactory.authentication.basic section to provide access credentials or use customArtifactory.authentication.apiKey to provide an APIKey value and dedicated APIKey header details if you host the driver in a custom artifactory that requires Basic or APIKey Authentication.

If you configured a secret in an external secrets operator for customArtifactory credentials, enter the secret name in customArtifactory.authentication.external_secret_name parameter. For details, see this section.

If your artifactory domain server certificate is not issued by Certificate Authority, you must provide the server certificate using the customArtifactory.certificate parameter. To disable SSL verification, you can set customArtifactory.enableSSLVerification to false and leave the CustomArtifactory.certificate parameter blank.

The Pega Docker images use Java 11, which requires that the JDBC driver that you specify is compatible with Java 11.

Authentication

The simplest way to provide database authorization is via the jdbc.username and jdbc.password parameters. These values will create a Kubernetes Secret and at runtime will be obfuscated and stored in a secrets file.

Connection Properties

You may optionally set your connection properties that will be sent to our JDBC driver when establishing new connections. The format of the string is [propertyName=property;].

Schemas

It is standard practice to have separate schemas for your rules and data. You may specify them as rulesSchema and dataSchema. If desired, you may also optionally set the customerDataSchema for your database. The customerDataSchema defaults to value of dataSchema if not specified. Additional schemas can be defined within Pega.

Example:

jdbc:
 ...
 rulesSchema: "rules"
 dataSchema: "data"
 customerDataSchema: ""

Docker

Specify the location for the Pega Docker image. This image is available on DockerHub, but can also be mirrored and/or extended with the use of a private registry. Specify the url of the image with docker.pega.image. You may optionally specify an imagePullPolicy with docker.pega.imagePullPolicy.

When using a private registry that requires a username and password, specify them using the docker.registry.username and docker.registry.password parameters.

When you download Docker images, it is recommended that you specify the absolute image version and the image name instead of using the latest tag; for example: pegasystems/pega:8.4.4 or platform-services/search-n-reporting-service:1.12.0. When you download these images with these details from the Pega repository, you pull the latest available image. If you pull images only specifying latest, you may not get the image you wanted.

For this reason, it is also recommended that you specify the docker.pega.imagePullPolicy: "IfNotPresent" option in production, since it will ensure that a new generic tagged image will not overwrite the locally cached version.

Example:

docker:
 registry:
   url: "YOUR_DOCKER_REGISTRY"
   username: "YOUR_DOCKER_REGISTRY_USERNAME"
   password: "YOUR_DOCKER_REGISTRY_PASSWORD"
 pega:
   image: "pegasystems/pega:8.4.4"
   imagePullPolicy: "Always"

Deploying with busybox and k8s-wait-for utility images from a private registry

To deploy Pega Platform, the Pega helm chart requires the use of the busybox and k8s-wait-for images. For clients who want to pull these images from a registry other than Docker Hub, they must tag and push these images to another registry, and then pull these images by specifying busybox and k8s-wait-for values as described below.

Example:

utilityImages:
 busybox:
   image: "busybox:1.31.0"
   imagePullPolicy: "IfNotPresent"
 k8s_wait_for:
   image: "dcasavant/k8s-wait-for"
   imagePullPolicy: "IfNotPresent"

Deployment Name (Optional)

Specify a deployment name that is used to differentiate this deployment in your environment. This name will be prepended to the various Pega tiers and the associated k8s objects in your deployment. Your deployment name should be constrained to lowercase alphanumeric and '-' characters.

This is meant as an alternative to renaming individual deployment tiers (see Tiers of a Pega deployment).

For example:

global:
  deployment:
    name: app1-dev

will result in:

>kubectl get pods -n test
NAME                              READY   STATUS    RESTARTS   AGE
app1-dev-search-0                 1/1     Running   0          24m
app1-dev-batch-86584dcd6b-dsvdd   1/1     Running   0          24m
app1-dev-batch-86584dcd6b-lfwjg   1/1     Running   0          7m31s
app1-dev-stream-0                 1/1     Running   0          24m
app1-dev-stream-1                 1/1     Running   0          18m
app1-dev-web-788cfb8cc4-6c5nz     1/1     Running   0          8m57s
app1-dev-web-788cfb8cc4-gcltx     1/1     Running   0          24m

The default value is "pega" if it is unset.

Tiers of a Pega deployment

Pega supports deployments using a multi-tier architecture model that separates application processing from k8s functions. Isolating processing in its own tier supports unique deployment configurations, including the Pega application prconfig, resource allocations, and scaling characteristics. Use the tier section in the helm chart to specify into which tiers you wish to deploy the tier with nodes dedicated to the logical tasks of the tier.

Tier examples

Three values.yaml files are provided to showcase real world deployment examples. These examples can be used as a starting point for customization and are not expected to deployed as-is.

For more information about the architecture for how Pega Platform runs in a Pega cluster, see How Pega Platform and applications are deployed on Kubernetes.

Standard deployment using two tiers

To provision a three tier Pega cluster, use the default example in the helm chart, which is a good starting point for most deployments:

Tier name Description
web Interactive, foreground processing nodes that are exposed to the load balancer. Pega recommends that these node use the node classification “WebUser” nodetype.
batch Background processing nodes which handle workloads for non-interactive processing. Pega recommends that these node use the node classification “BackgroundProcessing” nodetype. These nodes should not be exposed to the load balancer.
stream (Deprecated) For Pega Platform release 8.8 and later, Pega has deprecated the use of embedded "Stream tier" nodes. For new deployments, Pega recommends that you enable an Externalized Kafka configuration under External Services; for existing deployments, nodes that run an embedded deployment of Kafka and are not exposed to the load balancer. Pega requires that these nodes use the node classification “Stream” nodetype.

Small deployment with a single tier

To get started running a personal deployment of Pega on kubernetes, you can handle all processing on a single tier. This configuration provides the most resource utilization efficiency when the characteristics of a production deployment are not necessary. The values-minimal.yaml configuration provides a starting point for this simple model.

Tier Name Description
pega One tier handles all foreground and background processing using the nodeType classification "WebUser,BackgroundProcessing,search,Stream". When your Pega Platform deployment uses an externalize Kafka configuration, your deployment no longer uses the "Stream" node type.

Large deployment for production isolation of processing

To run a larger scale Pega deployment in production, you can split additional processing out to dedicated tiers. The values-large.yaml configuration provides an example of a multi-tier deployment that Pega recommends as a good starting point for larger deployments.

Tier Name Description
web Interactive, foreground processing nodes that are exposed to the load balancer. Pega recommends that these node use the node classification “WebUser” nodetype.
batch Background processing nodes which handle some of the non-interactive processing. Pega recommends that these node use the node classification “BackgroundProcessing,Search,Batch” nodetype. These nodes should not be exposed to the load balancer.
stream (Deprecated) For Pega Platform release 8.8 and later, Pega has deprecated the use of embedded "Stream tier" nodes. For new deployments, Pega recommends that you enable an Externalized Kafka configuration under External Services; for existing deployments, nodes that run an embedded deployment of Kafka and are not exposed to the load balancer. Pega requires that these nodes use the node classification “Stream” nodetype.
bix Nodes dedicated to BIX processing can be helpful when the BIX workload has unique deployment or scaling characteristics. Pega recommends that these node use the node classification “Bix” nodetype. These nodes should not be exposed to the load balancer.

Name (Required)

Use the tier section in the helm chart to specify the name of each tier configuration in order to label a tier in your Kubernetes deployment. This becomes the name of the tier's replica set in Kubernetes. This name must be unique across all Pega deployments to ensure compatibility with logging and monitoring tools.

Example:

name: "mycrm-prod-web"

nodeType (Required)

Node classification is the process of separating nodes by purpose, predefining their behavior by assigning node types. When you associate a work resource with a specific node type,you optimize work performance in your Pega application. For more information, see Node classification.

Specify the list of Pega node types for this deployment. For more information about valid node types, see the Pega Community article on [Node Classification].

Node types for client-managed cloud environments

Example:

nodeType: ["WebUser","bix"]

Requestor configuration

Configuration related to Pega requestor settings is collected under requestor block.

Configuration parameters:

  • passivationTimeSec - inactivity time after which requestor is passivated (persisted) and its resources reclaimed.

Example:

requestor:
  passivationTimeSec: 900

Security context

By default, security context for your Pega pod deployments pegasystems/pega image uses pegauser(9001) as the user and volume mounts uses root(0) as the group. To configure an alternative user for your custom image, set value for runAsUser and to configure an alternative group for volume mounts, set value for fsGroup. Note that pegasystems/pega image works only with pegauser(9001). runAsUser and fsGroup must be configured in securityContext under each tier block and will be applied to Deployments/Statefulsets, see the Kubernetes Documentation.

Example:

tier:
  - name: my-tier
    securityContext:
      runAsUser: RUN_AS_USER
      fsGroup: FS_GROUP

service

Specify the service yaml block to expose a Pega tier to other Kubernetes run services, or externally to other systems. The name of the service will be based on the tier's name, so if your tier is "web", your service name will be "pega-web". If you omit service, no Kubernetes service object is created for the tier during the deployment. For more information on services, see the Kubernetes Documentation.

Configuration parameters:

Parameter Description Default value
port The port of the tier to be exposed to the cluster. For HTTP this is generally 80. 80
targetPort The target port of the container to expose. The Pega container exposes web traffic on port 8080. 8080
serviceType The type of service you wish to expose. LoadBalancer
annotations Optionally add custom annotations for advanced configuration. Specifying a custom set of annotations will result in them being used instead of the default configurations. n/a

Example:

service:
  port: 1234
  targetPort: 1234
  serviceType: LoadBalancer

ingress

Specify the ingress yaml block to expose a Pega tier to access from outside Kubernetes. Pega supports the use of managing SSL certificates for HTTPS configuration using a variety of methods. For more information on services, see the Kubernetes Documentation.

Parameter Description
domain Specify a domain on your network in which you create an ingress to the load balancer.
appContextPath Specify the path for access to the Pega application on a specific tier. If not specified, users will have access to the Pega application via /prweb
tls.enabled Specify the use of HTTPS for ingress connectivity. If the tls block is omitted, TLS will not be enabled.
tls.secretName Specify the Kubernetes secret you created in which you store your SSL certificate for your deployment. For compatibility, see provider support for SSL certificate injection.
tls.useManagedCertificate On GKE, set to true to use a managed certificate; otherwise use false.
tls.ssl_annotation On GKE or EKS, set this value to an appropriate SSL annotation for your provider.
annotations Optionally add custom annotations for advanced configurations. For Kubernetes and EKS deployments, including custom annotations overrides the default configuration; for GKE and AKS deployments, the deployment appends these custom annotations to the default list of annotations.

Depending on your provider or type of certificate you are using use the appropriate annotation:

  • For EKS - use alb.ingress.kubernetes.io/certificate-arn: \<*certificate-arn*\> to specify required ARN certificate.
  • For AKS - use appgw.ingress.kubernetes.io/request-timeout: \<*time-out-in-seconds*\> to configure application gateway timeout settings.

Example:

ingress:
  domain: "tier.example.com"
  annotations:
    annotation-name-1: annotation-value-1
    annotation-name-2: annotation-value-2

Provider support for SSL certificate management

Provider Kubernetes Secrets Cloud SSL management service
AKS Supported None
EKS Not supported Manage certificate using Amazon Certification Manager and use ssl_annotation - see example for details.
PKS (now TKGI) Supported None
GKE Supported Pre-shared or Google-managed certificates

Managing certificates using Kubernetes secrets

In order to manage the SSL certificate using a secret, do the following:

  1. Create the SSL certificate and import it into the environment using the certificate management tools of your choice.

  2. Create the secret and add the certificate to the secret file.

  3. Add the secret name to the pega.yaml file.

  4. Pass the secret to the cluster you created in your environment before you begin the Pega Platform deployment.

Example:

ingress:
  domain: "tier.example.com"
  tls:
    enabled: true
    secretName: web-domain-certificate
    useManagedCertificate: false

Managing certificates in AWS

Instead of Kubernetes secrets, on AWS you must manage your SSL certificates with ACM (AWS certificate manager). Using the ARN of your certificate, you configure the ssl_annotation in your Helm chart.

Example:

ingress:
  domain: "tier.example.com"
  tls:
    enabled: true
    secretName:
    useManagedCertificate: false
    ssl_annotation:
      alb.ingress.kubernetes.io/certificate-arn:<certificate-arn>

Managing certificates in Google Cloud

In addition to Kubernetes secrets, on GCP you may manage your SSL certificates in GKE with two alternative methods. For more information, see the Google Cloud documentation on SSL certificate management.

  • Pre-shared certificate - add the certificate to your Google Cloud project and specify the appropriate ssl annotation in the ingress section.

Example:

ingress:
  domain: "web.dev.pega.io"
  tls:
    enabled: true
    useManagedCertificate: false
    ssl_annotation:
      ingress.gcp.kubernetes.io/pre-shared-cert: webCert
  • Google-managed certificate - Pega Platform deployments can automatically generate a GKE managed certificate when you specify the appropriate SSL annotation in the ingress section. Using a static IP address is not mandatory; if you do not use it, remove the annotation. To use a static IP address, you must create the static IP address during the cluster configuration, then add it using this annotation in the pega.yaml.

Example:

ingress:
  domain: "web.dev.pega.io"
  tls:
    enabled: true
    useManagedCertificate: true
    ssl_annotation:
      kubernetes.io/ingress.global-static-ip-name: web-ip-address

Managing Resources

You can optionally configure the resource allocation and limits for a tier using the following parameters. The default value is used if you do not specify an alternative value. See Managing Kubernetes Resources for more information about how Kubernetes manages resources.

Parameter Description Default value
replicas Specify the number of Pods to deploy in the tier. 1
cpuRequest Initial CPU request for pods in the current tier. 3
cpuLimit CPU limit for pods in the current tier. 4
memRequest Initial memory request for pods in the current tier. 12Gi
memLimit Memory limit for pods in the current tier. 12Gi
initialHeap Specify the initial heap size of the JVM. 4096m
maxHeap Specify the maximum heap size of the JVM. 8192m

JVM Arguments

You can optionally pass in JVM arguments to Tomcat. Depending on the parameter/attribute used, the arguments will be placed into JAVA_OPTS or CATALINA_OPTS environmental variables. Some of the Best-practice arguments for JVM tuning are included by default in CATALINA_OPTS. Pass the required JVM parameters as catalinaOpts attributes in respective values.yaml file.

Example:

tier:
  - name: my-tier
    javaOpts: ""
    catalinaOpts: "-XX:SomeJVMArg=XXX"

Note that some JVM arguments are non-overrideable i.e. baked in the Docker image.
Check RecommendedJVMArgs.md for more details.

nodeSelector

Pega supports configuring certain nodes in your Kubernetes cluster with a label to identify its attributes, such as persistent storage. For such configurations, use the Pega Helm chart nodeSelector property to assign pods in a tier to run on particular nodes with a specified label. For more information about assigning Pods to Nodes including how to configure your Nodes with labels, see the Kubernetes documentation on nodeSelector.

tier:
- name: "my-tier"
  nodeType: "WebUser"

  nodeSelector:
    disktype: ssd

Liveness, readiness, and startup probes

Pega uses liveness, readiness, and startup probes to determine application health in your deployments. For an overview of these probes, see Configure Liveness, Readiness and Startup Probes. Configure a probe for liveness to determine if a Pod has entered a broken state; configure it for readiness to determine if the application is available to be exposed; configure it for startup to determine if a pod is ready to be checked for liveness. You can configure probes independently for each tier. If not explicitly configured, default probes are used during the deployment. Set the following parameters as part of a livenessProbe, readinessProbe, or startupProbe configuration.

Notes:

  • Kubernetes 1.18 and later supports startupProbe. If your deployment uses a Kubernetes version older than 1.18, the helm charts exclude startupProbe and use different default values for livenessProbe and readinessProbe.
  • timeoutSeconds cannot be greater than periodSeconds in some GCP environments. For details, see this API library from Google.

Kubernetes pre-1.18

Parameter Description Default livenessProbe Default readinessProbe
initialDelaySeconds Number of seconds after the container has started before probes are initiated. 200 30
timeoutSeconds Number of seconds after which the probe times out. 20 10
periodSeconds How often (in seconds) to perform the probe. 30 10
successThreshold Minimum consecutive successes for the probe to be considered successful after it determines a failure. 1 1
failureThreshold The number consecutive failures for the pod to be terminated by Kubernetes. 3 3

Kubernetes 1.18+

Parameter Description Default livenessProbe Default readinessProbe Default startupProbe
initialDelaySeconds Number of seconds after the container has started before probes are initiated. 0 0 10
timeoutSeconds Number of seconds after which the probe times out. 20 10 10
periodSeconds How often (in seconds) to perform the probe. 30 10 10
successThreshold Minimum consecutive successes for the probe to be considered successful after it determines a failure. 1 1 1
failureThreshold The number consecutive failures for the pod to be terminated by Kubernetes. 3 3 20

Example:

tier:
  - name: my-tier
      livenessProbe:
        initialDelaySeconds: 60
        timeoutSeconds: 30
        failureThreshold: 5
      readinessProbe:
        initialDelaySeconds: 400
        failureThreshold: 30

Using a Kubernetes Horizontal Pod Autoscaler (HPA)

You may configure an HPA to scale your tier on a specified metric. Only tiers that do not use volume claims are scalable with an HPA. Set hpa.enabled to true in order to deploy an HPA for the tier. For more details, see the Kubernetes HPA documentation.

Parameter Description Default value
hpa.minReplicas Minimum number of replicas that HPA can scale-down 1
hpa.maxReplicas Maximum number of replicas that HPA can scale-up 5
hpa.targetAverageCPUValue Threshold value for scaling based on absolute CPU usage (The default value is 2.55 which represents 2.55 Kubernetes CPU units) 2.55
hpa.targetAverageCPUUtilization Threshold value for scaling based on initial CPU request utilization (Can be set instead of hpa.targetAverageCPUValue to set the threshold as a percentage of the requested CPU)
hpa.targetAverageMemoryUtilization Threshold value for scaling based on initial memory utilization (The default value is 85 which corresponds to 85% of 12Gi ) 85
hpa.enableCpuTarget Set to true if you want to enable scaling based on CPU utilization or false if you want to disable it true
hpa.enableMemoryTarget Set to true if you want to enable scaling based on memory utilization or false if you want to disable it (Pega recommends leaving this disabled) false

Ensure System Availability during Voluntary Disruptions by Using a Kubernetes Pod Disruption Budget (PDB)

To limit the number of Pods running your Pega Platform application that can go down for planned disruptions, Pega allows you to enable a Kubernetes PodDisruptionBudget on a tier. For more details on PDBs, see the Kubernetes Pod Disruption Budgets documentation.

You can configure a Kubernetes PodDisruptionBudget on your tier by setting pdb.enabled to true in your values.yaml file. By default, this value is set to false. You must also specify exactly one of the following parameters to configure the Pod Disruption Budget. These parameters are mutually exclusive, and thus only one may be set. You may provide values that are expressed as percentages (% of pods) or integers (# of pods).

Parameter Description Default value
pdb.minAvailable The minimum number or percentage of pods in the tier that must be available. If this minimum is reached, the Kubernetes deployment will not bring down additional pods for voluntary disruptions until more are available and healthy. 1
pdb.maxUnavailable The maximum number or percentage of pods in the tier that can be unavailable. If this maximum is reached, the Kubernetes deployment will not bring down additional pods for voluntary disruptions until more are available and healthy. 50% (disabled by default)

Volume claim template

A volumeClaimTemplate may be configured for any tier to allow for persistent storage. This allows for stateful tiers such as stream to be run as a StatefulSet rather than a Deployment. Specifying a volumeClaimTemplate should never be used with a custom deployment strategy for rolling updates.

Deployment strategy

The deploymentStrategy can be used to optionally configure the strategy for any tiers deployed as a Kubernetes Deployment. This value will cannot be applied to StatefulSet deployed tiers which use the volumeClaimTemplate parameter.

Environment variables

Pega supports a variety of configuration options for cluster-wide and application settings. In cases when you want to pass a specific environment variable into your deployment on a tier-by-tier basis, you specify a custom env block for your tier as shown in the example below.

Example:

tier:
  - name: my-tier
    custom:
      env:
        - name: MY_ENV_NAME
          value: MY_ENV_VALUE

Service Account

If the pod needs to be run with a specific service account, you can specify a custom serviceAccountName for your deployment tier.

Example:

tier:
  - name: my-tier
    custom:
      serviceAccountName: MY_SERVICE_ACCOUNT_NAME

Sidecar Containers

Pega supports adding sidecar containers to manage requirements for your Pega application services that live outside of the primary tomcat container. This may include company policy requirements, utility images, networking containers, or other examples. For an overview of the versatility sidecar containers present, see How Pods manage multiple containers.

You can specify custom sidecarContainers for your deployment tiers in the Pega Helm chart as shown in the example below. Each sidecar container definition must be a complete container definition, including a name, image, and resources.

Example:

tier:
  - name: my-tier
    custom:
      sidecarContainers:
        - name: SIDECAR_NAME
          image: SIDECAR_IMAGE_URL
          ...
        - name: SIDECAR_NAME_2
          image: SIDECAR_IMAGE_URL_2
          ...

Custom Annotations for Pods

You may optionally provide custom annotations for Pods as metadata to be consumed by other tools and libraries. Pod annotations may be specified by using the podAnnotations element for a given tier.

Example:

tier:
  - name: my-tier
    podAnnotations:
      <annotation-key>: <annotation-value>

Pega configuration files

While Pega includes default configuration files in the Helm charts, the charts provide extension points to override the defaults with additional customizations. To change the configuration file, specify the replacement implementation to be injected into a ConfigMap.

Parameter Description Default value
prconfig A complete prconfig.xml file to inject. See prconfig.xml.
prlog4j2 A complete prlog4j2.xml file to inject. See prlog4j2.xml.
contextXML A complete context.xml template file to inject. See context.xml.tmpl.
serverXML A complete server.xml file to inject See server.xml.tmpl.
webXML A complete web.xml file to inject No default provided, but if config/deploy/web.xml exists, it will be used as the default.

Example:

tier:
  - name: my-tier
    custom:
      prconfig: |-
        ...

      prlog4j2: |-
        ...

      contextXML: |-
        ...

      serverXML: |-
        ...

      webXML: |-
        ...

Pega diagnostic user

While most cloud native deployments will take advantage of aggregated logging using a tool such as EFK, there may be a need to access the logs from Tomcat directly. In the event of a need to download the logs from tomcat, a username and password will be required. You may set pegaDiagnosticUser and pegaDiagnosticPassword to set up authentication for Tomcat.

Cassandra and Pega Customer Decision Hub deployments

If you are planning to use Cassandra (usually as a part of Pega Customer Decision Hub), you may either point to an existing deployment or deploy a new instance along with Pega.

Using an existing Cassandra deployment

To use an existing Cassandra deployment, set cassandra.enabled to false and configure the dds section to reference your deployment.

Use the following parameters to configure the connection to your external Cassandra cluster

Parameter Description Default value
externalNodes A comma separated list of hosts in the Cassandra cluster. Empty
port TCP Port to connect to cassandra. 9042
username The plain text username for authentication with the Cassandra cluster.
Change the value in your helm chart to the username supplied by your Cassandra cluster provider. For better security, avoid plain text usernames and leave this parameter blank; then include the username in an external secrets manager with the key CASSANDRA_USERNAME.
If you make no change, Pega attempts to authenticate with the Cassandra cluster using the default username dnode_ext.		 dnode_ext
password The plain text password for authentication with the Cassandra cluster.
Change the value in your helm chart to the password supplied by your Cassandra cluster provider. For better security, avoid plain text passwords and leave this parameter blank; then include the password in an external secrets manager with the key CASSANDRA_PASSWORD.
If you make no change, Pega attempts to authenticate with the Cassandra cluster using the default password dnode_ext.		 dnode_ext
clientEncryption Enable (true) or disable (false) client encryption on the Cassandra connection. false
trustStore If required, provide the trustStore certificate file name.
When using a trustStore certificate, you must also include a Kubernetes secret name that contains the trustStore certificate in the global.certificatesSecrets parameter.
Pega deployments only support trustStores that use the Java Key Store (.jks) format.		 Empty
trustStorePassword If required provide trustStorePassword value in plain text. For better security leave this parameter blank and include the password in an external secrets manager with the key CASSANDRA_TRUSTSTORE_PASSWORD. Empty
keyStore If required, provide the keystore certificate file name.
When using a keystore certificate, you must also include a Kubernetes secret name that contains the keystore certificate in the global.certificatesSecrets parameter.
Pega deployments only support keystores that use the Java Key Store (.jks) format.		 Empty
keyStorePassword If required provide keyStorePassword value in plain text. For better security leave this parameter blank and include the password in an external secrets manager with the key CASSANDRA_KEYSTORE_PASSWORD. Empty

If you configured a secret in an external secrets operator, enter the secret name in external_secret_name parameter. For details, see this section.

Example:

cassandra:
  enabled: false

dds:
  externalNodes: "CASSANDRA_NODE_IPS"
  port: "9042"
  username: "cassandra_username"
  password: "cassandra_password"
  external_secret_name: ""

Deploying Cassandra with Pega

You may deploy a Cassandra instance along with Pega. Cassandra is a separate technology and needs to be independently managed. When deploying Cassandra, set cassandra.enabled to true and leave the dds section as-is. For more information about configuring Cassandra, see the Cassandra Helm charts.

Pega does not actively update the Cassandra dependency in requirements.yaml. When deploying Cassandra with Pega, you should update its version value in requirements.yaml.

Cassandra minimum resource requirements

Deployment CPU Memory
Development 2 cores 4Gi
Production 4 cores 8Gi

Example:

cassandra:
  enabled: true
  # Set any additional Cassandra parameters. These values will be used by Cassandra's helm chart.
  persistence:
    enabled: true
  resources:
    requests:
      memory: "4Gi"
      cpu: 2
    limits:
      memory: "8Gi"
      cpu: 4

dds:
  externalNodes: ""
  port: "9042"
  username: "dnode_ext"
  password: "dnode_ext"

Search deployment

Use the pegasearch section to configure the source ElasticSearch service that the Pega Platform deployment uses for searching Rules and Work within Pega. The ElasticSearch service defined here is not related to the ElasticSearch deployment if you also define an EFK stack for logging and monitoring in your Pega Platform deployment.

For Pega Platform 8.6 and later:

Pega recommends using the chart 'backingservices' to enable Pega Infinity backing service and to deploy the latest generation of search and reporting capabilities to your Pega applications that run independently on nodes provisioned exclusively to run these services. This is an independently manageable search solution that replaces the previous implementation of Elasticsearch. The SRS supports, but does not require you to enable, Elasticsearch for your Pega Infinity deployment searching capability.

To use this search and reporting service, follow the deployment instructions provided at 'backingservices' before you configure and deploy pega helm chart. You must configure the SRS URL for your Pega Infinity deployment using the parameter in values.yaml as shown the the following table and exmple:

Parameter Description Default value
externalSearchService Set the pegasearch.externalSearchService as true to use Search and Reporting service as the search functionality provider to the Pega platform false
externalURL Set the pegasearch.externalURL value to the Search and Reporting Service endpoint url ""

Example:

pegasearch:
  externalSearchService: true
  externalURL: "http://srs-service.namespace.svc.cluster.local"

Use the below configuration to provision an internally deployed instance of elasticsearch for search functionality within the platform:

Parameter Description Default value
image Set the pegasearch.image location to a registry that can access the Pega search Docker image. The image is available on DockerHub, and you may choose to mirror it in a private Docker repository. pegasystems/search:latest
imagePullPolicy Optionally specify an imagePullPolicy for the search container. ""
replicas Specify the desired replica count. 1
minimumMasterNodes To prevent data loss, you must configure the minimumMasterNodes setting so that each master-eligible node is set to the minimum number of master-eligible nodes that must be visible in order to form a cluster. Configure this value using the formula (n/2) + 1 where n is replica count or desired capacity. For more information, see the ElasticSearch important setting documentation for more information. 1
podSecurityContext.runAsUser ElasticSearch defaults to UID 1000. In some environments where user IDs are restricted, you may configure your own using this parameter. 1000
set_vm_max_map_count Elasticsearch uses a mmapfs directory by default to store its indices. The default operating system limits on mmap counts is likely to be too low, which may result in out of memory exceptions. An init container is provided to set the value correctly, but this action requires privileged access. If privileged access is not allowed in your environment, you may increase this setting manually by updating the vm.max_map_count setting in /etc/sysctl.conf according to the ElasticSearch documentation and can set this parameter to false to disable the init container. For more information, see the ElasticSearch documentation. true
set_data_owner_on_startup Set to true to enable an init container that runs a chown command on the mapped volume at startup to reset the owner of the ES data to the current user. This is needed if a random user is used to run the pod, but also requires privileges to change the ownership of files. false
podAnnotations Configurable annotations applied to all Elasticsearch pods. {}

Additional env settings supported by ElasticSearch may be specified in a custom.env block as shown in the example below.

Example:

pegasearch:
  image: "pegasystems/search:8.3"
  memLimit: "3Gi"
  replicas: 1
  minimumMasterNodes: 2
  custom:
    env:
    - name: TZ
      value: "EST5EDT"

Deploying Pega with externalized kafka service for stream

Deployment of stream with an externalized Kafka configuration requires Pega Infinity 8.4 or later. Starting in 8.7, Pega deprecated the use of embedded stream (using the Stream tier or “Stream” nodetype). For new deployments, Pega recommends deploying Pega Platform using an externalized Kafka configuration as a stream service provider to use your own managed Kafka infrastructure. Pega provides parameters for this configuration in the Pega Helm chart so your stream service starts when your Pega nodes start. For details and requirements about configuring Kafka, see Kafka Cluster requirements. Pega supports migrating existing deployments to use an externalized Kafka configuration as a stream service provider using Pega-provided Helm charts. To use your own managed Kafka infrastructure without the use of stream nodes, Pega provides instructions to run a migration with downtime and potential data loss or with minimal downtime and no downtime. For migration steps, see Switch from embedded Stream to externalized Kafka service.

Stream (externalized Kafka service) settings

Example:

# Stream (externalized Kafka service) settings.
stream:
  # Disabled by default, when enabled, your deployment no longer uses the "Stream" node type.
  enabled: false
  # Provide externalized Kafka service broker urls.
  bootstrapServer: ""
  # Provide Security Protocol used to communicate with kafka brokers. Supported values are: PLAINTEXT, SSL, SASL_PLAINTEXT, SASL_SSL.
  securityProtocol: PLAINTEXT
  # If required, provide trustStore certificate file name
  # When using a trustStore certificate, you must also include a Kubernetes secret name, that contains the trustStore certificate,
  # in the global.certificatesSecrets parameter.
  # Pega deployments only support trustStores using the Java Key Store (.jks) format.
  trustStore: ""
  # If required provide trustStorePassword value in plain text.
  trustStorePassword: ""
  # If required, provide keyStore certificate file name
  # When using a keyStore certificate, you must also include a Kubernetes secret name, that contains the keyStore certificate,
  # in the global.certificatesSecrets parameter.
  # Pega deployments only support keyStores using the Java Key Store (.jks) format.
  keyStore: ""
  # If required, provide keyStore value in plain text.
  keyStorePassword: ""
  # If required, provide jaasConfig value in plain text.
  jaasConfig: ""
  # If required, provide a SASL mechanism**. Supported values are: PLAIN, SCRAM-SHA-256, SCRAM-SHA-512.
  saslMechanism: PLAIN
  # By default, topics originating from Pega Platform have the pega- prefix,
  # so that it is easy to distinguish them from topics created by other applications.
  # Pega supports customizing the name pattern for your Externalized Kafka configuration for each deployment.
  streamNamePattern: "pega-{stream.name}"
  # Your replicationFactor value cannot be more than the number of Kafka brokers and 3.
  replicationFactor: "1"
  # To avoid exposing trustStorePassword, keyStorePassword, and jaasConfig parameters, leave the values empty and
  # configure them using an External Secrets Manager, making sure you configure the keys in the secret in the order:
  # STREAM_TRUSTSTORE_PASSWORD, STREAM_KEYSTORE_PASSWORD and STREAM_JAAS_CONFIG.
  # Enter the external secret name below.
  external_secret_name: ""

Pega database installation and upgrades

Pega requires a relational database that stores the rules, data, and work objects used and generated by Pega Platform. The Pega Platform deployment guide provides detailed information about the requirements and instructions for installations and upgrades. Follow the instructions for Tomcat and your environment's database server.

The Helm charts also support an automated install or upgrade with a Kubernetes Job. The Job utilizes an installation Docker image and can be activated with the action parameter in the Pega Helm chart.

Installations

For installations of the Pega platform, you must specify the installer Docker image and an initial default password for the administrator@pega.com user.

Along with this, you can configure the kubelet pull policy for the image. It is defaulted to IfNotPresent, meaning an image will be pulled if it is "not present". All possible options are IfNotPresent, Always, and Never. Always pulling an image ensures you always have the latest image at all times, even if the specific tag already exists on your machine.

Example:

installer:
  image: "YOUR_INSTALLER_IMAGE:TAG"
  imagePullPolicy: "PREFERRED_IMAGE_PULL_POLICY"
  adminPassword: "ADMIN_PASSWORD"

Upgrades and patches

The Pega Helm charts support zero-downtime patch and upgrades processes which synchronize the required process steps to minimize downtime. With these zero-downtime processes, you and your customers can continue to access and use their applications in your environment with minimal disruption while you patch or upgrade your system.

To upgrade Pega Platform software deployed in a Kubernetes environment in zero-downtime, you must download the latest Pega-provided images for the version to which you are upgrading from Pega Digital Software Delivery and use the Helm chart with versions 1.6.0 or later to complete the upgrade. To learn about how the upgrade process works and its requirements and the steps you must complete, see the Pega-provided runbook, Upgrading Pega Platform in your deployment with zero-downtime. With earlier versions of the Pega Helm charts, you must use the Pega Platform upgrade guides. To obtain the latest upgrade guide, see Stay current with Pega.

To complete your Pega Infinity upgrade, after you upgrade your Pega Platform software using the Pega Helm charts and Docker images, you must use the latest Pega application software Upgrade Guide, which is separate from Pega Platform software. You can locate the appropriate upgrade guide for your installed application from the page, All Products.

To apply a Pega Platform patch with zero-downtime to your existing Pega platform software, you use the same "zero-downtime" parameters that you use for upgrades and use the Pega-provided platform/installer Docker image that you downloaded for your patch version. For step-by-step guidance to apply a Pega Platform patch, see the Pega-provided runbook, Patching Pega Platform in your deployment. The patch process applies only changes observed between the patch and your currently running version and then separately upgrades the data. For details about Pega patches, see Pega software maintenance and extended support policy.

Use the installer section of the values file with the appropriate parameters to install, upgrade, or apply a patch to your Pega Platform software:

Parameter Description Default value
image Reference the platform/installer Docker image that you downloaded and pushed to your Docker registry that your deployment can access. YOUR_INSTALLER_IMAGE:TAG
imagePullPolicy Specify when to pull an image. IfNotPresent
adminPassword Specify a temporary, initial password to log into the Pega application. This will need to be changed at first login. The adminPassword value cannot start with "@". "ADMIN_PASSWORD"
upgrade.upgradeType: Specify the type of process, applying a patch or upgrading. See the next table for details.
upgrade.upgradeSteps: Specify the steps of a custom upgrade process that you want to complete. For zero-downtime, out-of-place-rules, out-of-place-data, or in-place upgrades, leave this parameter empty.
    enable_cluster_upgrade rules_migration rules_upgrade data_upgrade disable_cluster_upgrade
upgrade.targetRulesSchema: Specify the name of the schema you created the process creates for the new rules schema. ""
upgrade.targetDataSchema: For patches to 8.4 and later or upgrades from 8.4.2 and later, specify the name of the schema the process creates for the temporary data schema. After the patch or upgrade, you must delete this temporary data schema from your database. For 8.2 or 8.3 Pega software patches, you can leave this value empty, as is (do not add blank text). ""
Upgrade type Description
zero-downtime If applying any patch or upgrading from 8.4.2 and later, use this option to minimize downtime. This patch or upgrade type migrates the rules to your designated "new rules schema", uses the temporary data schema to host some required data-specific tables, and patches or upgrades the rules to the new version with zero-downtime. With the new rules in place, the process performs a rolling reboot of your nodes, patches or upgrades any required data schema, and redeploys the application using the new rules.
custom Use this option for any upgrade in which you complete portions of the upgrade process in steps. Supported upgrade steps are: enable_cluster_upgrade rules_migration rules_upgrade data_upgrade disable_cluster_upgrade. To specify which steps to include in your custom upgrade, specify them in your pega.yaml file using the upgrade.upgradeSteps parameter.
out-of-place-rules Use this option to migrate a copy of the rules to a new rules schema and run an out-of-place upgrade in that copied schema. This schema will become the rules schema after your upgrade is complete.
out-of-place-data Use this option to complete an out-of-place upgrade of the data schema. This is the final step of the out of place upgrade.
in-place Use this option to upgrade both rules and data in a single run. This will upgrade your environment as quickly as possible but will result in application downtime.
out-of-place Deprecated and supported only with Helm charts prior to version 1.4: For patches using Helm charts from 1.4 or earlier, you can use this process to apply a patch with zero-downtime; for upgrades from 1.4 or earlier this upgrade type minimizes downtime, but still requires some downtime. For patches or upgrades the process places the existing rules in your application into a read-only state, migrates the rules to your designated "new rules schema", and then applies the patch only to changed rules or upgrades all of the rules. With the new rules in place, the process performs a rolling reboot, patches or upgrades the data, and then redeploys your application using the new rules.

Install example:

installer:
  image: "YOUR_INSTALLER_IMAGE:TAG"

Zero-downtime upgrade example:

installer:
  image: "YOUR_INSTALLER_IMAGE:TAG"
  upgrade:
    upgradeType: "zero-downtime"
    targetRulesSchema: "new_rules_schema_name"
    targetDataSchema: "temporary_data_schema_name"

Custom rules upgrade without a data upgrade example:

installer:
  image: "YOUR_INSTALLER_IMAGE:TAG"
  upgrade:
    upgradeType: "custom"
    upgradeSteps: "enable_cluster_upgrade, rules_migration, rules_upgrade, disable_cluster_upgrade"
    targetRulesSchema: "new_rules_schema_name"
    targetDataSchema: "temporary_data_schema_name"

Zero-downtime patch example:

installer:
  image: "YOUR_INSTALLER_IMAGE:TAG"
  upgrade:
    upgradeType: "zero-downtime"
    targetRulesSchema: "new_rules_schema_name"
    targetDataSchema: "temporary_data_schema_name"

Installer Pod Annotations

You can add annotations to the installer pod.

Example:

installer:
  podAnnotations:
    annotation-name1: annotation-value1
    annotation-name2: annotation-value2

Installer Node Selector

You can add node selector to the installer pod to launch the pod on specific node

Example:

installer:
  nodeSelector:
    label: value

Mount the custom certificates into the Tomcat container

Pega supports mounting and passing custom certificates into the tomcat container during your Pega Platform deployment. Pega supports the following certificate formats as long as they are encoded in base64: X.509 certificates such as PEM, DER, CER, CRT. To mount and pass the your custom certificates, use the certificates attributes as a map in the values.yaml file using the format in the following example.

(Optional) Support for providing custom certificates using External Secrets Operator

To avoid directly entering your certificates in plain text, Pega supports Kubernetes secrets to secure certificates. Your certificates can be stored in any secrets manager provider.

• Mount secrets into your Docker containers using the External Secrets Operator(https://external-secrets.io/v0.5.3/).

To support this option,

  1. Create two files following the Kubernetes documentation for External Secrets Operator :
    • 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.
  2. Copy both files into the pega-helm-charts/charts/pega/templates directory of your local Helm repository.
  3. Update your local Helm repository to the latest version using the command:
  4. Update your values.yaml file to refer to the external secret manager for certificates.
  5. Add multiple custom certificates that you maintain as an externally-managed secret, each as a string, separated by a comma in the certificatesSecrets parameter.

• You can either pass certificates as external secrets or as plain text to the Pega values.yaml, but not both. If you provide both, the deployment mounts only external secrets into the tomcat container. Example:

certificatesSecrets: ["secret-to-be-created1","secret-to-be-created2"]
certificates:
    badssl.cer: |
      "-----BEGIN CERTIFICATE-----\n<<certificate content>>\n-----END CERTIFICATE-----\n"

Deploying Hazelcast in Client-Server Model

For Pega Platform deployments using 8.6 and later, Pega recommends adopting a client-server model for your Hazelcast deployment. This deployment model introduces independent scalability for both servers and clients in Pega Platform. To adopt this client-server deployment model, configure the values.yaml section for hazelcast to use the Pega-provided platform/clustering-service Docker image which contains the Hazelcast clustering service image inside it. Using this image, your deployment starts a cluster of Hazelcast server nodes; a plugin provided by Hazelcast, the Hazelcast-Kubernetes Plugin, discovers the Hazelcast members in the cluster.

Deploying the Pega provided platform/clustering-service Docker image which contains the Hazelcast clustering service image inside it, starts a cluster of Hazelcast server nodes. For the discovery of Hazelcast members in the cluster, a plugin provided by Hazelcast, namely Hazelcast-Kubernetes Plugin is used. Out of the two discovery strategies that the latter plugin provides - Kubernetes API and DNS Lookup, the client-server model with Hazelcast uses DNS lookup to resolve the IP addressing of PODs running Hazelcast. For additional information on Hazelcast member discovery, refer the plugin: Hazelcast-Kubernetes Plugin

Specify the platform/clustering-service Docker image that you downloaded in hazelcast.image and set hazelcast.enabled as true to deploy a Pega Platform web cluster separately from a Hazelcast cluster in a client-server deployment model. Using Clustering service for client-server form of deployment is only supported from Pega Platform 8.6 or later.

In this model, nodes running Hazelcast start independently and simultaneously with the Pega web tier nodes and create a cluster with a member count you must specify using hazelcast.replicas parameter. Pega web tier nodes then connect to this Hazelcast cluster in a client-sever model.

Note: If you are deploying Pega Platform below release 8.6, you need to set hazelcast.enabled as false, otherwise the installation will fail. Setting hazelcast.enabled as false deploys Pega and Hazelcast in an Embedded arrangement, in which Hazelcast and Pega Platform run on the same node. The default and recommended deployment strategy for Hazelcast is client-server, Embedded deployment is only being supported for backwards compatibility. Embedded deployment would not be supported in future platform releases.

Clustering Service Compatibility Matrix

Pega Infinity version Clustering Service version Description
< 8.6 NA Clustering Service is not supported for releases 8.5 or below
>= 8.6 = 1.0.3 Pega Infinity 8.6 and later supports using a Pega-provided platform-services/clustering-service Docker Image that is tagged with version 1.0.3 or later.

Configuration Settings

The values.yaml provides configuration options to define the deployment of Hazelcast. Apart from the below parameters when hazelcast.enabled is set to true, additional parameters are required for client-server deployment which have been documented here: Additional Parameters

Parameter Description Default value
hazelcast.image Reference the platform/clustering-service Docker image that you downloaded and pushed to your Docker registry that your deployment can access. YOUR_HAZELCAST_IMAGE:TAG
hazelcast.enabled Set as true if client-server deployment of Pega Platform is required, otherwise false. Note: Set this value as false for Pega platform versions below 8.6, if not set the installation will fail true
hazelcast.replicas Number of initial members to join the Hazelcast cluster 3
hazelcast.username UserName to be used in client-server Hazelcast model for authentication ""
hazelcast.password Password to be used in client-server Hazelcast model for authentication ""
hazelcast.external_secret_name If you configured a secret in an external secrets operator, enter the secret name. For details, see this section. ""

Example

hazelcast:
  image: "YOUR_HAZELCAST_IMAGE:TAG"
  enabled: true
  replicas: 3
  username: ""
  password: ""
  external_secret_name: ""

Enabling encryption of traffic between Ingress/LoadBalancer and Pod

Using Helm version 2.2.0, Pega supports mounting and passing TLS certificates into the container to enable TLS between loadbalancer/ingress and pods during your Pega Platform deployment. Pega supports the keystore formats such as .jks, .keystore. To mount and pass your TLS certificates, use the tls section under service to specify the keystore content, the keystore password and the specified ports for https under 'web' tier in the values.yaml file using the format in the following example.

Parameter Description Default value
service.tls.port The port of the tier to be exposed to the cluster. For HTTPS this is generally 443 443
service.tls.targetPort The target port of the container to expose. The TLS-enabled Pega container exposes web traffic on port 8443. 8443
service.tls.enabled Set as true if TLS is enabled for the tier, otherwise false. false
service.tls.external_secret_name If you configured a secret in an external secrets operator, enter the secret name. For details, see this section. ""
service.tls.keystore The keystore content for the tier. If you leave this value empty, the deployment uses the default keystore. ""
service.tls.keystorepassword The keystore password for the tier. If you leave this value empty, the deployment uses the default password for the default keystore. ""
service.tls.cacertificate The CA certificate for the tier. If you leave this value empty, the deployment uses the default CA certificate for the default keystore. Pass the certificateChainFile file if you are using certificateFile and certificateKeyFile. ""
service.tls.certificateFile The content of the file that contains the server certificate, which you must provide if you do not provide a keystore and keystorepassword. The format of this file is PEM-encoded. ""
service.tls.certificateKeyFile The content of the file that contains the server private key, which you must provide if you do not provide a keystore and keystorepassword. The format of this file is PEM-encoded. ""
service.tls.traefik.enabled Set as true if you enabled Traefik for the tier and deployed the Traefik addon Helm charts; otherwise set it to false. false
service.tls.traefik.serverName The server name for the tier, SAN(Subject Alternative Name) of the certificate present inside the container ""
service.tls.traefik.insecureSkipVerify Set to true to skip verifying the certificate; do this in cases where you do not need a valid root/CA certificate but want to encrypt load balancer traffic. Leave the setting to false to both verify the certificate and encrypt load balancer traffic. false
Important Points to note
  • By default, Pega provides a self-signed keystore and a custom root/CA certificate in Helm chart version 2.2.0. To use the default keystore and CA certificate, leave the parameters service.tls.keystore, service.tls.keystorepassword and service.tls.cacertificate empty.
  • To enable SSL, you must either provide a keystore with a keystorepassword or certificate, certificatekey and cacertificate files in PEM format. If you do not provide either, the deployment implements SSL by passing a Pega-provided default self-signed keystore and a custom root/CA certificate to the Pega web nodes.
  • The CA certificate can be issued by any valid Certificate Authorities or you can also use a self-created CA certificate with proper chaining.
  • To avoid exposing your certificates, you can use external secrets to manage your certificates. Pega also supports specifying the certificate files using the certificate parameters in the Pega values.yaml. To pass the files using these parameters, you must encode the certificate files using base64 and then enter the string output into the appropriate certificate parameter.
  • To encode your keystore and certificate files use the following command: o Linux: cat ca_bundle.crt | base64 -w 0 o Windows: type keystore.jks | openssl base64 (needs openssl)
  • Add the required, base64-encoded content in the values.yaml using either the keystore parameters (service.tls.keystore, service.tls.keystorepassword and service.tls.cacertificate) or the certificate parameters (service.tls.certificateFile, service.tls.certificateKeyFile and service.tls.cacertificate).
  • Create a keystore file with the SAN(Subject Alternate Name) field present in case of Traefik ingress controller.
  • You must use the latest Docker images in order to use this feature; if you use Helm chart version 2.2.0, with outdated Docker images and set service.tls.enabled to true, the deployment logs a Bad Gateway error. Helm chart version 2.2.0, you must update your Pega Platform version to the latest patch version or set service.tls.enabled to false.

Example:

After you enable TLS for the web tier, deploy the traefik addon for k8s provider, and configure the keystore file and password using the external secret operator, set the following parameters in the values.yaml:

# To configure TLS between the ingress/load balancer and the backend, set the following:
tls:
   enabled: true
   external_secret_name: secret-to-be-crated
   keystore: 
   keystorepassword: 
   port: 443
   targetPort: 8443
   # set the value of CA certificate here in case of baremetal/openshift deployments - CA certificate should be in base64 format
   # pass the certificateChainFile file if you are using certificateFile and certificateKeyFile
   cacertificate:
   # provide the SSL certificate and private key as a PEM format
   certificateFile:
   certificateKeyFile:
   # if you will deploy traefik addon chart and enable traefik, set enabled=true; otherwise leave the default setting.
   traefik:
      enabled: true
      serverName: "<< SAN name of the certificate >>"
      # set insecureSkipVerify=true, if the certificate verification has to be skipped
      insecureSkipVerify: false

With TLS enabled for the web tier and the traefik addon deployed for k8s provider, you set the following parameters in the values.yaml:

# To enable TLS encryption between the ingress/load balancer and the deployment backend, configure the following settings:
tls:
   enabled: true
   external_secret_name: 
   keystore: "<< encoded keystore content >>"
   keystorepassword: "<< keystore password >>"
   port: 443
   targetPort: 8443
   # set the value of CA certificate here in case of baremetal/openshift deployments - CA certificate should be in base64 format
   # pass the certificateChainFile file if you are using certificateFile and certificateKeyFile
   cacertificate: "<< encoded CA certificate >>"
  # provide the SSL certificate and private key as a PEM format
   certificateFile:
   certificateKeyFile:
  # if you will deploy traefik addon chart and enable traefik, set enabled=true; otherwise leave the default setting.
   traefik:
      enabled: true
      serverName: "<< SAN name of the certificate >>"
      # set insecureSkipVerify=true, if the certificate verification has to be skipped
      insecureSkipVerify: false

To enable TLS for the web tier using the certificateFile, certificateKeyFile and certificateChainFile instead of a keystore and password, you must set the following parameters in the Pega values.yaml:

# To enable TLS encryption between the ingress/load balancer and the deployment backend, configure the following settings:
tls:
   enabled: true
   external_secret_name:
   keystore: 
   keystorepassword: 
   port: 443
   targetPort: 8443
   # set the value of CA certificate here in case of baremetal/openshift deployments - CA certificate should be in base64 format
   # pass the certificateChainFile file if you are using certificateFile and certificateKeyFile
   cacertificate: "<< encoded certificateChainFile certificate >>"
  # provide the SSL certificate and private key as a PEM format
   certificateFile: "<< encoded certificateFile content >>"
   certificateKeyFile: "<< encoded certificateKeyFile content >>"
   # if you will deploy traefik addon chart and enable traefik, set enabled=true; otherwise leave the default setting.
   traefik:
      enabled: false
      serverName: ""
      # set insecureSkipVerify=true, if the certificate verification has to be skipped
      insecureSkipVerify: true

With TLS enabled for the web tier and the traefik addon is NOT deployed for k8s provider, you set the following parameters in the values.yaml:

# To enable TLS encryption between the ingress/load balancer and the deployment backend, configure the following settings:
tls:
   enabled: true
   external_secret_name:
   keystore: "<< encoded keystore content >>"
   keystorepassword: "<< keystore password >>"
   port: 443
   targetPort: 8443
   # set the value of CA certificate here in case of baremetal/openshift deployments - CA certificate should be in base64 format
   # pass the certificateChainFile file if you are using certificateFile and certificateKeyFile
   cacertificate: "<< encoded CA certificate >>"
  # provide the SSL certificate and private key as a PEM format
   certificateFile:
   certificateKeyFile:
   # if you will deploy traefik addon chart and enable traefik, set enabled=true; otherwise leave the default setting.
   traefik:
      enabled: false
      serverName: ""
      # set insecureSkipVerify=true, if the certificate verification has to be skipped
      insecureSkipVerify: true

Without TLS enabled, and no traefik addon in use, there is no reason to add and verify the certificate. You can use the following parameters in the values.yaml:

# To enable TLS encryption between the ingress/load balancer and the deployment backend, configure the following settings:
tls:
   enabled: false
   external_secret_name:
   keystore: ""
   keystorepassword: ""
   port: 443
   targetPort: 8443
   # set the value of CA certificate here in case of baremetal/openshift deployments - CA certificate should be in base64 format
   # pass the certificateChainFile file if you are using certificateFile and certificateKeyFile
   cacertificate: ""
  # provide the SSL certificate and private key as a PEM format
   certificateFile:
   certificateKeyFile:
   # if you will deploy traefik addon chart and enable traefik, set enabled=true; otherwise leave the default setting.
   traefik:
      enabled: false
      serverName: ""
      # set insecureSkipVerify=true, if the certificate verification has to be skipped
      insecureSkipVerify: true