Deploy Pega Platform™ on an Azure Kubernetes Service (AKS) cluster set up in your Microsoft Azure account. The procedures are written for any level of user, from a system administrator to a development engineer who is interested in learning how to install and deploy Pega Platform onto an AKS cluster.
Pega helps enterprises and agencies quickly build business apps that deliver the outcomes and end-to-end customer experiences that you need. Use the procedures in this guide, to install and deploy Pega software onto an AKS cluster without much experience in either AKS configurations or Pega Platform deployments.
Create a deployment of Pega Platform on which you can implement a scalable Pega application in an AKS cluster. You can use this deployment for a Pega Platform development environment. By completing these procedures, you deploy Pega Platform on an AKS cluster with an SQL database instance and two clustered virtual machines (VMs).
Use Kubernetes tools and the customized orchestration tools and Docker images to orchestrate a deployment in a AKS cluster that you create for the deployment:
-
Prepare your local system:
-
To prepare a local Linux system, install required applications and configuration files - Preparing your local Linux system – 45 minutes.
-
To prepare a local Windows system, install required applications and configuration files - Preparing your local Windows 10 system – 45 minutes.
-
-
Create an AKS cluster and an SQL database resource in your Azure account - Prepare your AKS resources – 45 minutes.
-
Customize a configuration file with your AKS details and use the command-line tools, kubectl and Helm, to install and then deploy Pega Platform onto your AKS cluster - Deploying Pega Platform using Helm charts – 90 minutes.
-
Configure your network connections in the DNS management zone of your choice so you can log in to Pega Platform - Logging in to Pega Platform – 10 minutes.
To understand how Pega maps Kubernetes objects with Pega applications and services, see How Pega Platform and applications are deployed on Kubernetes.
This guide assumes:
-
You have a basic familiarity with running commands from a Windows 10 PowerShell with Administrator privileges or a Linux command prompt with root privileges.
-
You use open source packaging tools on Windows or Linux to install applications onto your local system.
The following account, resources, and application versions are required for use in this document:
-
A Microsoft Azure account with a payment method set up to pay for the Azure resources that you create and appropriate Microsoft Azure account permissions and knowledge to:
-
Create an AKS service, an SQL Database, and a storage resource.
-
Select an appropriate location in which to deploy Microsoft Azure resources; the document assumes your location is US East.
-
You are responsible for any financial costs incurred for your AKS resources.
-
-
Pega Platform 8.3.1 or later.
-
Pega Docker images – your deployment requires the use of a custom Docker image to install Pega Platform into a database that is used by your AKS cluster. After you build your image, you must make it available in a private Docker registry. To build your own image from the base image that Pega provides, you must have:
-
A DockerHub account to which you will push your final image to a private DockerHub repository. The image you build with Pega-provided components cannot be shared in a public DockerHub repository.
-
The Docker application downloaded to your local system, either Linux- or Windows-based. Log into your DockerHub account from the Docker application on your local system.
-
-
A Pega Platform distribution kit downloaded and extracted on your local system.
-
Helm 3.0 or later. Helm is only required to use the Helm charts and not to use the Kubernetes YAML examples directly. For more information, see the Helm documentation portal.
-
kubectl – the Kubernetes command-line tool that you use to connect to and manage your Kubernetes resources.
In order to deploy Pega Platform to an AKS environment, you must create the AKS resources that the deployment will use in your Azure account. This section covers the details necessary to create an AKS cluster and an SQL database resource.
To deploy Pega using an AKS cluster, create the cluster in an existing project in your Microsoft Azure account. During deployment the required Kubernetes configuration file is copied into the cluster. Create a cluster with two VMs that have sufficient memory and CPU resources to support a deployment of Pega Platform that can perform under high workloads.
-
In a web browser, login to Microsoft Azure Portal (https://portal.azure.com/) with your credentials.
-
Search for Kubernetes services and then select it in the dropdown list.
-
Click +Add.
-
On the Create an AKS Kubernetes service page, on the Basics tab page, add details to the following required fields for this Kubernetes service:
a. In Project Details, select your Azure Subscription (the default is Microsoft Azure).
b. In Resource Group area, select the appropriate group or click Create new and provide a name.
c. In Cluster details, enter a Kubernetes cluster name.
d. Select a Region that is appropriate for your deployment.
e. Select the default Kubernetes version that is version 1.13.10 or later.
f. For DNS name prefix, enter a prefix that your organization requires or use the default prefix. Azure creates the prefix based on the Kubernetes cluster name that you provided.
g. In Primary node pool specify the size of your VMs for this service.
Select VMs of type D8Sv3 (8 vcpus, 32 GiB memory). Change the filters if you cannot find this type using the search function.
h. Specify a Node count. Note that the cost varies with different VM configurations.
Pega recommends standard deployments use at least two nodes.
-
Click Next: Scale.
-
In the Scale tab page, use the default settings: Virtual nodes and VM Scale sets both set to Disabled.
-
Click Next: Authentication.
-
In the Authentication tab page, add details to the following required fields for this Kubernetes service:
a. In Cluster Infrastructure area/Service principal, select a service principal:
-
If you do not have an existing service principal leave the field at the default to create a new service principal.
-
If you have an existing service principal, click Configure service principal, and then,in the Configure service principal window, select Use existing and enter the Service principal client ID and client secret.
b. In Kubernetes authentication and authorization, leave Enable RBAC toggled to Yes.
-
-
Click Next: Networking.
-
In the Networking tab page, add details to the following required fields for this Kubernetes service:
a. Ensure that HTTP application routing is Disabled.
b. Ensure that Networking configuration is set to Advanced.
c. In Configure virtual networks, leave the default network and address settings unless you have specific, advanced networking requirements.
-
Click Next: Monitoring.
-
In the Monitoring tab page, in Azure Monitor, accept the defaults to Enable container monitoring to use the default analytics workspace to store monitoring data.
-
Click Next: Tags.
-
In the Tags tab page, add any tags with which you want to identify resources such as owner, user, and organization name by using the Name and Value tags.
Tags can help clarify billing details for your AKS resources.
-
Click Next: Review + create.
Azure runs a validation and when validated, your service is ready to be created.
-
Check your configurations on the Create and Review tab.
Azure validates your configuration.
-
Click Create.
A deployment progress page displays the status of your deployment until it is complete, which takes about 15 minutes. When complete, the Azure UI displays all of the resources created for your AKS cluster in Deployment details:
AKS deployments require you to install Pega Platform software in an SQL database. After creating an SQL database, obtain the database and server name to customize your pega.yaml Helm chart with this information.
-
In a web browser, login to Microsoft Azure Portal (https://portal.azure.com/) with your credentials.
-
Search for SQL Databases and select it in the dropdown list.
-
Click +Add.
-
On the Create SQL Database page, in the Basics tab page, add details to the following required fields for this database server:
-
In Project details, select your Azure Subscription.
-
In Resource Group, select the same group you specified or created for your AKS cluster.
-
In Database details, enter a database server name.
-
In Server, click Create new.
-
In the New server window, enter a name, security details, select the same Region as in your AKS cluster, and then click OK.
-
Set Want to use SQL elastic pool? with the default: No.
-
In Compute + storage server, click configure database and then select Gen5 compute hardware and a minimum of 4 vCores and 32 GB storage.
-
Click Next: Networking.
-
On the Networking tab page, add details to the following required fields for this database server:
a. In the Network connectivity area, for a Connectivity method, select Public endpoint.
b. In the Firewall rules area, for Allow Azure services and resources to access this server, select Yes.
c. In the Firewall rules area, for Add current client IP address, select Yes.
-
Click Next: Additional settings.
-
On the Additional settings tab page, use the following settings for this database server:
-
Data source: None
-
Database collation: use the default
-
Enable Advanced data security: Not now
-
-
Click Next: Tags.
-
On the Tags tab page, add any tags with which you want to identify resources such as owner, user, and organization name by using the Name and Value tags.
Tags can help clarify billing details for your AKS resources.
-
Click Next: Review + create.
-
On the Create and Review tab.
Azure validates your configuration for your parameters.
-
Click Create.
A deployment progress page displays the status of your server creation until it is complete, which takes about 5 minutes. When complete, the Azure UI displays all of the resources created for your SQL database deployment details:
Create an Application Gateway for the deployment load balancer. After creating the Application Gateway, note the name and resource group in which you created the Application Gateway. You must add these details to the Addons helm chart you configured in your local Linux system or your local Windows 10 system.
-
In a web browser, log in to Microsoft Azure Portal (https://portal.azure.com/) with your credentials.
-
Search for Application Gateway and select it in the dropdown list.
-
Click +Add.
-
On the Create an Application Gateway page, on the Basics tab page, add details to the following required fields:
a. Select the Resource Group in which you created your cluster.
b. In Instance Details, enter an unique name and choose an appropriate region.
c. In Configure virtual network, select the Virtual Network in which you created your cluster, then select a different subnet from the one you selected for cluster.
Note: Selecting the same subnet in this field is not supported and results in an error.d. Click Next: Frontends.
-
In Frontends tab page, add details:
a. For Frontend IP address type, select Public.
b. In Public IP address, click on Create new:
The Add a public IP address option opens.
c. Select an unique name and click Ok.
d. Click Next : Backends.
-
In Backends tab page, add details:
a. Click Add a backend pool and do the following:
-
In the Add a backend pool dialogue box, enter a unique <backend pool name>.
-
In Add backend pool without targets select Yes.
b. Click Next : Configuration.
-
With the Frontends and Backends configurations complete, create Routing rules that include - Listener, Backend targets, and an HTTP setting.
-
Click on Add a rule.
a. In Add a routing rule dialog, enter a unique Rule name.
b. Configure Listener settings.
- Enter a unique Listener Name.
- For Frontend IP, select Public.
- For Protocol, select HTTP.
- For as Port, enter 80.
- Leave the remaining settings at the default value.
- Click the Backend targets tab.
c. Configure Backend targets settings.
- For Backend Pool, select Target type.
- For Backend Target, select the backend pool that you created in Step 6.
- For HTTP Setting, click Create new.
d. Configure Add an HTTP Setting.
- Enter an unique HTTP Setting Name.
- For Backend Protocol, select HTTP.
- For Backend port, enter Give 80.
- Leave the remaining settings at the default value.
-
Click Next : Tags.
-
Add any necessary, required tags.
-
Click Next : Review + Create.
-
Click Create.
A deployment progress page displays the status of your server creation until it is complete, which takes about 5 minutes. When complete, the Azure UI displays all of the resources created for your Application Gateway details:
After you finalize your SQL database configuration and you are ready to deploy, locate the the SQL Server name for YOUR_DB_HOST and the SQL database name for YOUR_DB_NAME for this database URL string in the “pega” Helm chart:
jdbc:sqlserver://**YOUR_DB_HOST**:1433;databaseName=**YOUR_DB_NAME**;selectMethod=cursor;sendStringParametersAsUnicode=false:
-
In the upper left corner of your Azure portal, click the Portal menu.
-
In the Favorites section, select SQL databases.
-
In the Name column, select the database name that you just created to display it details.
-
Locate YOUR_DB_NAME and YOUR_DB_HOST.
You need these names to update your pega.yaml Helm chart.
To deploy Pega Platform by using Helm, customize the pega.yaml Helm chart that holds the specific settings for your deployment needs and then run a series of Helm commands to complete the deployment.
An installation with deployment will take about 90 minutes total, because a Pega Platform installation in your PostgreSQL database takes up to an hour.
To deploy Pega Platform, configure the parameters in the pega.yaml Helm chart to your deployment resource. Pega maintains a repository of Helm charts that are required to deploy Pega Platform by using Helm, including a generic version of this chart. To configure parameters this file, download it from the repository to your local system, edit it with a text editor, and then save it with the same filename. To simplify the instruction, you can download the file to the \gke-demo folder you have already created on your local system.
Configure the parameters so the pega.yaml Helm chart matches your deployment resources in these areas:
-
Specify that this is an AKS deployment.
-
Credentials for your DockerHub account in order to access the required Docker images.
-
Access your Azure SQL database.
-
Install the version of Pega Platform that you built into your Docker installation image.
-
Specify host names for your web and stream tiers.
- To download the pega.yaml Helm chart to the <local filepath>\aks-demo, enter:
$ helm inspect values pega/pega > pega.yaml
- Use a text editor to open the pega.yaml file and update the following parameters in the chart based on your AKS requirements:
| Chart parameter name | Purpose | Your setting |
|---|---|---|
| provider: | Specify an AKS deployment. | provider:"aks" |
| actions.execute: | Specify a “deploy” deployment type. | execute: "deploy" |
| Jdbc.url: | Specify the server and database name for your Pega Platform installation. |
|
| Jdbc.driverClass: | Specify the driver class for this type of database. | driverClass: "com.microsoft.sqlserver.jdbc.SQLServerDriver" |
| Jdbc.dbType: | Specify the database type. | dbType: "mssql” |
| Jdbc.driverUri: | Specify the database driver Pega Platform uses during the deployment. For AKS, we can obtain the URL of the required 7.4.1. driver file that is publicly available in the referenced Maven repository. | driverUri: "https://repo1.maven.org/maven2/com/microsoft/sqlserver/mssql-jdbc/7.4.1.jre11/mssql-jdbc-7.4.1.jre11.jar" |
| Jdbc: username: password: | Set the security credentials for your database server to allow installation of Pega Platform into your database. |
|
| jdbc.rulesSchema: jdbc.dataSchema: | Set the names of both your rules and the data schema to the values that Pega Platform uses for these two schemas. | rulesSchema: "rules" dataSchema: "data" |
| docker.registry.url: username: password: | Map the host name of a registry to an object that contains the “username” and “password” values for that registry. For more information, search for “index.docker.io/v1” in Engine API v1.24. |
|
| docker.pega.image: | Refer to the latest Pega Platform deployment image on DockerHub. |
|
| upgrade: | Do not set for installations or deployments. | upgrade: for non-upgrade, keep the default value. |
| tier.name: ”web” tier.ingress.domain: | Set a host name for the pega-web service of the DNS zone. |
|
| tier.name: ”stream” tier.ingress.domain: | Set the host name for the pega-stream service of the DNS zone. |
|
| installer.image: | Specify the Docker image you built to install Pega Platform. |
|
| installer. adminPassword: | Specify a password for your initial log in to Pega Platform. | adminPassword: "<initial password>" |
- Save the file.
A Helm installation and a Pega Platform installation are separate processes. The Helm install command uses Helm to install your deployment as directed in the Helm charts, one in the charts\addons folder and one in the charts\pega folder.
In this document, you specify that the Helm chart always “deploys” by using the setting, actions.execute: “deploy”. In the following tasks, you overwrite this function on your initial Helm install by specifying --set global.actions.execute:install-deploy, which invokes an installation of Pega Platform using your installation Docker image and then
automatically followed by a deploy. In subsequent Helm deployments, you should not use the override argument, --set global.actions.execute=, since Pega Platform is already installed in your database.
- Do one of the following:
- Open Windows PowerShell running as Administrator on your local system and change the location to the top folder of your aks-demo folder that you created in Preparing your local Windows 10 system.
$ cd <local filepath>\aks-demo
-
Open a Linux bash shell and change the location to the top folder of your aks-demo directory that you created in Preparing your local Linux system.
$ cd /home/<local filepath>/aks-demo
-
To use the Azure CLI to log into your account, enter:
$ az login
A new web browser window opens, which prompts you to log into your Azure account.
-
Log into the Azure account that you want use to deploy Pega Platform.
After you log into your Azure home page, ensure that you see confirmation information in your command prompt. For example, in a Windows PowerShell you'll see confirmation of your credentials similar to this screen shot.
If you cannot log into your Azure home page or see that the Azure CLI does not recognize your account correctly, contact your Microsoft account representative.
-
In the upper right corner of your web browser, click Portal.
You are brought to your Azure home page.
-
In the Recent resources area, click your cluster to review the name and the resource group with which it is associated.
-
To prepare your environment using the Azure CLI, enter:
$ az aks get-credentials --resource-group <resource-group-name> --name <cluster-name>
Merged "runbook-demo" as current context in <local filepath>\<cluster-name>.kube\config-
To use the kubectl command to view the VM nodes created when you created the AKS cluster, enter:
$ kubectl get nodes
-
To establish a required cluster role binding setting so that you can launch the Kubernetes dashboard, enter:
$ kubectl create clusterrolebinding dashboard-admin -n kube-system --clusterrole=cluster-admin --serviceaccount=kube-system:kubernetes-dashboard -
To launch the Kubernetes dashboard to view your AKS resources before you deploy Pega Platform by replacing the names specific to your AKS cluster, enter:
$ az aks browse --resource-group <resource-group-name> --name <cluster-name>
You can now view your deployment details using the Kubernetes dashboard. Use this dashboard to review the status of your deployment. Without a deployment, only AKS resources display. The dashboard does not display your AKS cluster name or your resource name, which is expected behavior.
To continue using the Kubernetes dashboard to see the progress of your deployment, keep this PowerShell or Linux shell open.
- Do one of the following:
-
Open a new Windows PowerShell running as Administrator on your local system and change the location to the top folder of your aks-demo folder that you created in Create a local folder to access all of the configuration files.
$ cd \<local filepath>\aks-demo -
Open a new Linux bash shell and change the location to the top folder of your aks-demo directory that you created in Create a local folder to access all of the configuration files.
$ cd /home/<local filepath>/aks-demo
- To create namespaces in preparation for the pega.yaml and addons.yaml deployments, enter:
$ kubectl create namespace mypega
namespace/mypega created
$ kubectl create namespace pegaaddons
namespace/pegaaddons created-
(Optional: To support HTTPS connectivity with Pega Platform) To pass the appropriate certificate to the ingress using a Kubernetes secret, enter:
$ kubectl create secret tls <secret-name> --cert <cert.crt-file> --key <private.key-file> --namespace <namespace-name>
To use a secrets file, make the following changes in the pega.yaml file for the exposed tiers in your deployment:
ingress:
domain: "web.dev.pega.io"
tls:
enabled: true
secretName: <secret-name>
useManagedCertificate: false-
To ensure the certificate is working in the cluster, enter:
$ kubectl get secrets --namespace <namespace-name> -
To install the addons chart, which you updated in Preparing your AKS resources, enter:
$ helm install addons pega/addons --namespace pegaaddons --values addons.yamlThe pegaddons namespace contains the deployment’s load balancer and the metric server configurations that you configured in the addons.yaml Helm chart. A successful pegaaddons deployment returns details of deployment progress. For further verification of your deployment progress, you can refresh the Kubernetes dashboard and look in the pegaaddons Namespace view.
- To deploy Pega Platform for the first time by specifying to install Pega Platform into the database specified in the Helm chart when you install the pega.yaml Helm chart, enter:
$ helm install mypega pega/pega --namespace mypega --values pega.yaml --set global.actions.execute=install-deployFor subsequent Helm installs, use the command helm install mypega pega/pega --namespace mypega --values pega.yaml to deploy Pega Platform and avoid another Pega Platform installation.
A successful Pega deployment immediately returns details that show progress for your deployment.
-
Refresh the Kubernetes dashboard that you opened in step 9. If you closed the dashboard, open a new command prompt running as Administrator and relaunch the web browser as directed in Step 9.
-
In the dashboard, in Namespace select the mypega view and then click on the Pods view.
Note: A deployment takes about 15 minutes for all resource configurations to initialize; however a full Pega Platform installation into the database can take up to an hour.
To follow the progress of an installation, use the dashboard. For subsequent deployments, you do not need to do this. Initially, while the resources make requests to complete the configuration, you will see red warnings while the configuration is finishing, which is expected behavior.
-
To view the status of an installation, on the Kubernetes dashboard, select Jobs, locate the pega-db-install job, and click the logs icon on the right side of that row.
After you open the logs view, you can click the icon for automatic refresh to see current updates to the install log.
-
To see the final deployment in the Kubernetes dashboard after about 15 minutes, refresh the mypega namespace pods.
A successful deployment does not show errors across the various workloads. The mypega Namespace Overview view shows charts of the percentage of complete tiers and resources configurations. A successful deployment has 100% complete Workloads.
After you complete your deployment, as a best practice, associate the host name of the pega-web tier ingress with the IP address that the deployment load balancer assigned to the tier during deployment. The host name of the pega-web tier ingress used in this demo, aks.web.dev.pega.io, is set in the pega.yaml file in the following lines:
tier:
- name: "web"
service:
# Enter the domain name to access web nodes via a load balancer.
# e.g. web.mypega.example.com
domain: "**aks.web.dev.pega.io**"To log in to Pega Platform with this host name, assign the host name with the same IP address that the deployment load balancer assigned to the web tier. This final step ensures that you can log in to Pega Platform with your host name, on which you can independently manage security protocols that match your networking infrastructure standards.
You can view the networking endpoint that is associated with your AKS deployment using the kubectl command.
$ kubectl get services --namespace mypega
The pega-web tier external endpoint (the IP address and port number) are displayed. Port 80 is used for HTTP traffic, which means that you cannot use HTTPS encryption to access the web-tier in a web browser; instead, use the domain name that you configured for the pega-web tier ingress.
To manually associate the host name of the pega-web tier ingress with the tier's external endpoint, use the DNS lookup management system of your choice. As an example, if your organization has a AKS DNS zone configured to manage your DNS lookups, you can create a new record set with the pega-web tier the host name and add the IP address of the pega-web tier.
The mypega-web node is the only tier with an externally exposed IP address. Note the external IP address that the load-balancer gives to the web node: this is the IP address which in order to log into Pega Platform with your host name.
-
In a web browser, login to Microsoft Azure Portal (https://portal.azure.com/) with your credentials.
-
Search for DNS zones and select it in the dropdown list.
You are brought to the DNS zones for your Azure account.
-
In the Name column, click on the DNS zone for your deployment.
-
To associate the IP address of the pega-web tier with domain name of the pega-web tier ingress that you configured during your deployment, add a Record set to your DNS zone for this host name:
a. Click +Record set
b. In the Name field, enter "<the host name for your web service tier>".
c. In the Type field, select A.
d. In Alias record set the configuration remains No.
e. Set TTL to 5 and TTL Unit to Minutes.
f. In the IP Address field, enter the IP from the pega-web tier.
g. Click OK.
The new record set appears in the list of record sets for this Azure DNS zone.
With the ingress host name name associated with this IP address in your DNS service, you can log in to Pega Platform with a web browser using the URL: http://\<pega-web tier ingress host name>/prweb.
