Meeting requirements and prerequisites
Pega best practices include the following Kubernetes tools and required settings. You should review the information about the public images that Kubernetes deployments of Pega Platform™ may use to ensure your enterprise can access these images.
Install and configure the following required tools:
- Docker – Ensure Docker is installed in your deployment environment. You will need Docker to prepare a Pega Platform installation Docker image. For more information, see the Docker documentation.
- Kubectl – Configure the Kubernetes command line tool to connect and manage your Kubernetes resources. For more information, see the kubectl documentation.
To verify that your kubectl is correctly connected and Docker is running, use the kubectl cluster-info command.
- Helm – It is a Pega best practice to deploy using the Helm charts. Install Helm 3.0 or later. To use Helm, install Kubectl first and configure it to connect to your Kubernetes environment. For more information, see the Helm documentation portal.
For detailed guidance on how to install the required tools on your local system, refer to the following documents:
- Preparing your local Windows 10 system
- Preparing your local Linux system
Each worker node in your cloud environment requires a minimum of 16GB of memory and database instance for Pega Platform must be deployed in the same region as the worker nodes running in your environment. After you initially deploy and test your Pega application workloads, you may find that your applications require more or less resources. To adjust the settings, see the Kubernetes documentation for Resource Quotas.
Storage class settings
Search, Stream, and Cassandra nodes all require dynamic provisioning of persistent volumes. To dynamically provision volumes at deployment time, you must configure a default storage class. For overview information, see Storage Classes; for details on configuring Storage Classes for use with Kubernetes, see Change the default StorageClass.
Service deployment guidelines
Due to standard security conventions that limit running containers with root privileges in most datacenters, Pega recommends running the Pega Platform docker image as a non-root user using a custom security context. For information about defining privilege and access control settings for a Pod or Container, see Configure a Security Context for a Pod or Container.
Because some Kubernetes environments can impose restrictions to prevent running as a specific user or using privileged commands, ensure that your environment meets the following requirements so that your deployment is successful:
- The ElasticSearch and Cassandra replica sets included with the Pega example deployment require containers to be run as a specific User ID. This is needed to ensure that files written to a volume are accessible when the container restarts. This User ID is specified in the template spec as securityContext.runAsUser. Some Kubernetes environments may restrict the ability to run as a specific user by default or limit a User ID to a predefined range. If you encounter an error specifying this User ID, contact the provider of your environment. ElasticSearch and Cassandra specify the following User IDs:
For a security overview see Configure a Security Context for a Pod or Container.
- The Pega Platform search service uses Elasticsearch, which uses an
mmapfsdirectory by default for 64-bit systems to store its indices (for more information, see the Elastic document, Virtual Memory. To increase the mmap count on your environment, do one of the following:
- Update the
/etc/sysctl.confon your nodes and set the value
- Utilize the
set-max-map-countinitContainer in the example yaml file to automatically configure the setting. If you choose this method, note that the init container runs in privileged mode, so you must verify that your environment allows privileged containers.
- Update the
Supported cloud platforms
The following Kubernetes environments are supported. Pega provides configuration templates so you can customize your deployment into one of these supported Kubernetes environments, in addition to other settings your organization needs to deploy Pega Platform™ for your business needs.
|Kubernetes||Kubernetes 1.15 and later||Kubernetes documentation|
|OpenShift||Red Hat OpenShift 3.11 and later||OpenShift versions|
|Amazon EKS Kubernetes||All supported EKS versions.||Available Amazon EKS Kubernetes Versions|
|Google Kubernetes Engine (GKE)||All supported GKE versions.||Available GKE cluster versions|
|VMware Enterprise Pivotal Container Service (PKS)||Pivotal Container Service 1.4 and later||See the release-specific documentation at VMware Enterprise PKS Documentation|
|Azure Kubernetes Service (AKS)||All supported AKS versions.||Supported Kubernetes versions in Azure Kubernetes Service (AKS)|
Pega provides configuration templates so you can customize your deployment into one of these supported Kubernetes environments, in addition to other settings your organization needs to deploy Pega Platform for your business needs. For information about how to deploy Pega Platform on each environment, see the pega-helm-charts Github repository.
Required configurations and settings
Ensure that the following configurations are completed in your environment:
- A database into which you install Pega Platform and maintain Pega application data - See the list of database types that Pega Platform supports in the Platform Support Guide.
- DNS settings - You must configure domain names in your enterprise DNS servers to ensure the exposed Kubernetes services used in Pega deployments receive traffic over your network. For details, see the individual runbook that Pega provides for your type of Kubernetes environment..
- URLs and credentials - you must provide the following URLs and associated credentials when you configure your deployment:
- Your database URL and username, and password.
- Your Docker registry URL, username, and password.
- To use your existing Cassandra service and not deploy the Cassandra service Pega provides, you will need the URL, username, and password to access your external Cassandra node. (a Cassandra service is required for Customer Decision Hub and Pega Marketing).
Choosing your preferred Kubernetes-based services for your deployment
Pega allows you to choose which load balancing and logging services your Pega Platform deployment uses. To support this choice, Pega provides an “addons” Helm chart in the pega-helm-charts project that lets you configure the deployment to use the existing, native services you have in your Kubernetes environment or to use open-sourced services that use publicly-available Docker images.
Pega-provided Helm charts reference open-sourced services that the Pega supports:
- For deploying Cassandra (required for Pega Customer Decision Hub deployments): docker.io/cassandra
- For EFK Logging: docker.elastic.co/elasticsearch/elasticsearch-oss
- For EFK Logging: gcr.io/google-containers/fluentd-elasticsearch
- For EFK Logging: docker.elastic.co/kibana/kibana-oss
- For load balancing using Traefik: docker.io/traefik
If you plan on using these services, you should review the information about these public images that Kubernetes deployments of Pega Platform may use to ensure your enterprise can access these images. If your environment is unable to access these public registries, you must add them to your private registry following your enterprise Docker image policies and then update the reference to your images in the Helm chart.
Pega supports using load balancing and logging services that already exist in your enterprise or environment or using open-sourced ones. You configure your option by using a Pega-provided “addons” Helm chart the pega-helm-charts project. For details, see the Addons Helm chart.
The load balancing configuration requires a domain name for the Pega web service and optionally the stream service. This may require you to work with your networking team or DNS service to provide domain names that route to the correct IP addresses. For examples, on AWS, you can use Amazon Route 53, while in GKE you can use GCP Cloud DNS to configure domain names that route to your Kubernetes cluster.