Skip to content

Commit

Permalink
Incorporate new review edits and DNS lookup services to the GKE and P…
Browse files Browse the repository at this point in the history 
…KS articles (pegasystems#62)

* Updated project documentation
* Updated runbooks for Azure, Google, and Pivotal 

Co-authored-by: Adam Talbot <[email protected]>
Co-authored-by: Dave Casavant <[email protected]>
  • Loading branch information
@taz-mon @pega-talba @dcasavant
3 people committed Jan 10, 2020
1 parent 678753f commit 013e6c7
Show file tree
Hide file tree
Showing 8 changed files with 101 additions and 209 deletions.
5 changes: 4 additions & 1 deletion .gitignore
View file
Original file line number Diff line number Diff line change
Expand Up @@ -17,4 +17,7 @@

# IntelliJ IDEA
**/.idea
**/*.iml
**/*.iml

# VS Code
.vscode/*
2 changes: 1 addition & 1 deletion charts/pega/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -389,7 +389,7 @@ Parameter | Description | Default value
`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](https://www.elastic.co/guide/en/elasticsearch/reference/current/important-settings.html) 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 requires `vm.max_map_count` to be configured to an appropriate value. This may be configured manually on your system and if so, you may bypass this privileged init container. For more information, see the [ElasticSearch documentation](https://www.elastic.co/guide/en/elasticsearch/reference/current/vm-max-map-count.html). | `true`
`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](https://www.elastic.co/guide/en/elasticsearch/reference/current/vm-max-map-count.html). | `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`

Additional env settings supported by ElasticSearch may be specified in a `custom.env` block as shown in the example below.
Expand Down
97 changes: 31 additions & 66 deletions docs/Deploying-Pega-on-AKS.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -69,14 +69,13 @@ 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 opensource packaging tools on Windows or Linux to install applications onto your local system.
- You use open source packaging tools on Windows or Linux to install applications onto your local system.

The following account and application versions are required for use in this
document:
The following account 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 you create using this document. You should also have sufficient Microsoft Azure account permissions and knowledge to:

- Create an AKS service, a SQL Database, and a storage resource.
- 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.
Expand Down Expand Up @@ -113,9 +112,7 @@ resources.

### Create an AKS cluster

In order to deploy Pega using a AKS cluster, you must create the cluster in an existing project in your Microsoft Azure account. The deployment will place the required configuration files into this cluster during the deployment steps in the section [Deploy Pega Platform using the command line](#deploy-pega-platform-using-the-command-line). For now, you will create a
simple cluster with two VMs with sufficient memory and CPU resources to support
a deployment of Pega Platform that can perform under high workloads.
In order to deploy Pega using a AKS cluster, you must create the cluster in an existing project in your Microsoft Azure account. The deployment will place the required configuration files into this cluster during the deployment steps in the section [Deploy Pega Platform using the command line](#deploy-pega-platform-using-the-command-line). For now, you will create a simple cluster with two VMs with sufficient memory and CPU resources to support a deployment of Pega Platform that can perform under high workloads.

To create your AKS cluster:

Expand Down Expand Up @@ -145,9 +142,7 @@ To create your AKS cluster:
1. Select the default **Kubernetes version**. Pega requires that you select
version 1.13.10 or later.

1. For **DNS name prefix**, entire a prefix your organization requires or, if
not required, use the default, which Azure creates based on the **Kubernetes
cluster name** you provided.
1. For **DNS name prefix**, enter a prefix your organization requires or, if not required, use the default, which Azure creates based on the **Kubernetes cluster name** you provided.

1. In Primary node pool specify the size of your VMs for this service.

Expand Down Expand Up @@ -199,20 +194,20 @@ function.
1. Click **Next: Monitoring**.

1. In the **Monitoring** tab page, in **Azure Monitor**, accept the defaults to
**Enable container monitoring** and to use the default analytics workspace
**Enable container monitoring** to use the default analytics workspace
to store monitoring data.

1. Click **Next: Tags**.

1. In the **Tags** tab page, add any tags with which you want to identify
resources such as owner, user, organization name using the **Name** and
resources such as owner, user, and organization name using the **Name** and
**Value** tags.

Tags can help clarify billing details for your AKS resources.

1. Click **Next: Review + create**.

Azure runs a validation and when validated, your service is ready to create.
Azure runs a validation and when validated, your service is ready to be created.

1. Check your configurations on the **Create and Review** tab.

Expand Down Expand Up @@ -287,7 +282,7 @@ AKS deployments require you to install Pega Platform software into an SQL databa
1. Click **Next: Tags**.

1. In the **Tags** tab page, add any tags with which you want to identify
resources such as owner, user, organization name using the **Name** and
resources such as owner, user, and organization name using the **Name** and
**Value** tags.

Tags can help clarify billing details for your AKS resources.
Expand Down Expand Up @@ -333,11 +328,9 @@ will use these names when you update your values Helm chart.
Installing and deploying Pega Platform using Helm charts – 90 minutes
---------------------------------------------------------------------

In order to deploy Pega Platform using Helm, you must customize the “pega” Helm
chart that holds the specific settings for your deployment needs and then run a series of Helm commands to complete the deployment.
In order to deploy Pega Platform using Helm, you must customize the “pega” 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 followed by a deployment will take about 90 minutes total, since
it takes about an hour for Pega Platform to completely install in your SQL database.
An installation followed by a deployment will take about 90 minutes total, since it takes about an hour for Pega Platform to completely install in your SQL database.

### Update the Helm chart values

Expand Down Expand Up @@ -404,7 +397,7 @@ 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 tesks, 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
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.

1. Do one of the following:
Expand All @@ -413,7 +406,7 @@ automatically followed by a deploy. In subsequent Helm deployments, you should n

`$ cd <local filepath>\aks-demo`

- Open a Linux bash shell and change the location to the top folder of your pks-demo directory that you created in [Preparing your local Linux system](https://github.com/pegasystems/pega-helm-charts/blob/master/docs/prepping-local-system-runbook-linux.md).
- 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](https://github.com/pegasystems/pega-helm-charts/blob/master/docs/prepping-local-system-runbook-linux.md).

`$ cd /home/<local filepath>/aks-demo`

Expand Down Expand Up @@ -491,7 +484,7 @@ $ kubectl create namespace pegaaddons
namespace/pegaaddons created
```

12. To install the addons chart, which you already updated during the prepping a local system for your deployment, enter:
12. To install the addons chart, which you updated in [Preparing your local system](#Prepare-your-local-system-–-45-minutes), enter:

```yaml
$ helm install addons pega/addons --namespace pegaaddons --values addons.yaml
Expand All @@ -514,8 +507,6 @@ A successful Pega deployment immediately returns details that show progress for
15. In the dashboard, use the **Namespace** pulldown to change the view to **mypega**
and click on the **Pods** view.

![](media/055d24b4ac0c0dfcb9c68cec334ce42a.png)

Note: A deployment takes about 15 minutes for all of the resource configurations to complete; 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 will not need to do this. Initially, some of the resources are making requests to complete the configuration; therefore, you will see red warnings while the configuration is finishing. This is expected behavior.
Expand All @@ -531,69 +522,43 @@ A successful deployment will not show errors across the various workloads. The *
Logging into Pega Platform – 10 minutes
---------------------------------------

After you have completed your deployment, you must associate the hostname of the pega-web tier with the IP address that the deployment load balancer gave to the tier. This final step ensures that you can log onto Pega Platform using your hostname, on which you can independently manage security protocols that match your networking infrastructure standards.

### Logging in using the IP address

To view the Pega deployment components, enter:

`$ kubectl get services --namespace mypega`

![](media/f329e9f92feed8cb5959d91db246aa84.png)

The pega-web tier external IP address and port number are displayed. Port 80 is used for http traffic, which means you can’t use https encryption when accessing
the web-tier in a browser; instead, Pega recommends using the domain name of the web tier.

### Logging in using the domain name of the web tier

You must manually set the IP address of the web tier domain name in order to log
into Pega Platform domain name that is set during the deployment.

The example of a domain name of the web tier used in this demo is
**aks.web.dev.pega.io**, which you set in the values.yaml file here:
After you complete your deployment, it is a best practice to associate the hostname of the pega-web tier ingress with the IP address that the deployment load balancer assigned to the tier during deployment. The hostname of the pega-web tier ingress used in this demo is **aks.web.dev.pega.io**, is set in the pega.yaml file in the lines:

```yaml
tier:
-name: "web"
# Enter the domain name to access web nodes via a load balancer.
# e.g. web.mypega.example.com
- 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**"
# Enter the domain name to access web nodes via a load balancer.
# e.g. web.mypega.example.com
domain: "**aks.web.dev.pega.io**"
```
When you set this to be "\<the hostname for your web service tier\>" as directed
in [Update the Helm chart values](#update-the-helm-chart-values), you will
manually associate "\<the hostname for your web service tier\>" with the IP
address of the web tier domain name. In order to sign into Pega using "\<the hostname for your web service tier\>",
you must assign the domain name with the same IP address that the deployment
load balancer has assigned to the web tier.
In order to sign into Pega Platform using this hostname, you must assign it with the same IP address that the deployment load balancer has assigned to the web tier. This final step ensures that you can log onto Pega Platform using your hostname, on which you can independently manage security protocols that match your networking infrastructure standards.
1. From your command prompt, review the IP addresses that are in the mypega service
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 you can’t use https encryption when accessing the web-tier in a browser; instead, Pega recommends using the domain name you configured for the pega-web tier ingress.

To manually associate the hostname 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 hostname 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 hostname.

2. In a browser, login to Microsoft Azure Portal (https://portal.azure.com/)
1. In a browser, login to Microsoft Azure Portal (https://portal.azure.com/)
with your credentials.

3. Search for **DNS zones** and select it in the dropdown list.
2. Search for **DNS zones** and select it in the dropdown list.

You are brought to the DNS zones for your AKS cluster.
You are brought to the DNS zones for your Azure account.

![](media/3c7f4a5c3c21c6577a4dbab5f5cfa79d.png)

4. In the **Name** column, click on the **In the DNS zone** for your deployment.
3. In the **Name** column, click on the **DNS zone** for your deployment.

The DNS zone page displays.
4. 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 hostname:

5. To associate the IP address of the web tier (see step 1) with the domain name
you configured during your deployment, you must add a **Record set** to your
DNS zone for **"\<the hostname for your web service tier\>"**:

a. Click **+Record** set

b. In the **Name** field, enter **"\<the hostname for your web service
Expand All @@ -613,6 +578,6 @@ The DNS zone page displays.

![](media/ccb6329a621c6f11970e25531cfa1857.png)

With the domain name set to this IP address, you can log into Pega Platform with a browser using the URL: http://\<the hostname for your web service tier>/prweb
With the ingress hostname name associated with this IP address in your DNS service, you can log into Pega Platform with a browser using the URL: http://\<pega-web tier ingress hostname>/prweb.

![](media/25b18c61607e4e979a13f3cfc1b64f5c.png)
Loading

0 comments on commit 013e6c7

Please sign in to comment.