You can simplify IT operations and automate system management tasks by deploying Pega Platform™ on Pivotal Cloud Foundry (PCF) as a service broker. You can use the Cloud Foundry BOSH command-line interface to deploy the Pega service broker. After you deploy the Pega service broker, application developers can use the Pega service broker to deploy Pega Platform clusters on PCF.

Pega also supports using the PCF Ops manager to deploy your Pega service broker. For more information, see Deploying Pega Platform on PCF with Ops Manager.

To explore the latest information about the Cloud Choice deployment solution using Kubernetes across client-managed environments, see Cloud Choice.

Customization

There are three levels of customization for the Pega Platform deployment on Cloud Foundry:

• To streamline customization, Pega provides service plans that set the default number of web nodes, search nodes, and decisioning nodes. For more information, see Deploying Pega Platform as a Pivotal Cloud Foundry Service Broker.
• To customize your environment, edit the pega-service-adapter-deployment.yml manifest. For service updates, this manifest includes the settings used when deploying the previous service. The settings in the pega-service-adapter-deployment.yml manifest change the default settings in the service plans. For more information, see Customizing the Pega Service Broker manifest.
• To create cluster-specific customizations, the application developer can edit the custom_properties.json file. The values in the custom_properties.json file override the settings in the pega-service-adapter-deployment.yml manifest and the service plan. When an array is included in the properties section of the file, the array overwrites the entire array defined in the manifest. The arrays are not merged. For more information, see Deploying Pega Platform clusters on Cloud Foundry.

Overview

Follow these general steps to deploy Pega Platform clusters on Cloud Foundry. Each step links to a task with more details.

1. The system administrator creates the environment, edits the configuration files, and creates the Pega Service Broker:

   1. Review the Pivotal documentation for Pivotal On-Demand Services SDK for background information.

   2. Prepare your environment. Obtain all the required files from Pega and Pivotal. For more information, see Preparing your environment.

   3. Edit the Pega Service Broker manifest to customize your settings. For more information, see Customizing the Pega Service Broker manifest.

      If you do not edit the Pega Service Broker manifest, the placeholder values in the service plans will override all other customization settings and your deployment will fail.

   4. Deploy the Pega Service Broker. For more information, see Deploying the Pega Service Broker to BOSH.

   5. Connect Cloud Foundry to the Pega Service Broker to add the Pega Service Broker to the marketplace. After the Pega Service Broker is available, other users can deploy clusters. For more information, see Connecting Cloud Foundry to the Pega Service Broker.

2. After the service is available, application developers can customize and deploy Pega Platform clusters. For more information, see Deploying Pega Platform clusters on Cloud Foundry.

Preparing your environment

Before you continue, follow these steps:

1. Ensure that the Cloud Foundry release is deployed to BOSH. Use the BOSH Command Line Interface (CLI).

2. Upload Ubuntu Xenial stemcell version 97 or later from Pivotal.

3. Download and extract the Pega Platform distribution file Pega-Service-BOSH-Release-xxx.zip from Pega for Pivotal Cloud Foundry

4. Review the Pivotal requirements: Operating an On-Demand Broker.

5. Upload the three BOSH releases required by the service broker. Run the following BOSH commands:

   bosh upload release on-demand-service-broker-xxx.tgz
   bosh upload release pegaplatform-release-xxx.tgz
   bosh upload release pega-service-adapter-release-xxx.tgz

Customizing the Pega Service Broker manifest

Customize the Pega Service Broker manifest to set default values for deploying clusters such as network values, availability zones, and service plans. The values in the manifest override the values in the service plan.

To make it easier to edit the file, every required placeholder value starts with "YOUR_" and is followed by example text. The system administrator performs these steps.

1. Open the pega-service-adapter-deployment.yml manifest in a text editor.

2. In the pega-broker instance group, replace the placeholders for the VM type, persistent disk type, and availability zone to configure the Pega Service Broker. Valid settings depend on the IaaS. For more information about valid settings, use the BOSH cloud-config command.

   Specify at least one instance. Do not change the instance group name.

   Example:

   name: pega-broker
   instances: 1
   vm_type: t2.micro
   persistent_disk_type: 10240
   stemcell: xenial
   azs: az1

3. Configure the user name and password to use for communication between Cloud Foundry and the Pega Service Broker, for example:

   name: broker
   release: *broker-release
   properties:
      port: 8080
      username: my-user-name
      password: my-password

4. Enter the URL, user name, and password to configure access to BOSH, for example:

   bosh:
      url: http://example.com:1234/my_BOSH_URL
      authentication:
         uaa:
            client_id: my_BOSH_username
            client_secret: my_BOSH_password

5. Enter the URL, user name, and password to configure access to Cloud Foundry, for example:

   cf:
      url: http://example.com:5678/my_CF_URL
      authentication:
         url: my_CF_authentication_url
            username: my_CF_username
            password: my_CF_password

6. In the service_deployment section, replace YOUR_STEMCELL_VERSION with the version number of the Ubuntu Xenial stemcell that you obtained from Pivotal, for example:
   version: 97.22
7. Configure at least one service plan: basic, intermediate, or advanced. The description of each plan is in the pega-service-adapter-deployment.yml manifest.
   1. Locate the section for your service plan.
   2. Replace all required properties marked as YOUR_ with the values for your system. Use the following table as a guide.

   Property name	Action
   jdbc_driver_class	Replace YOUR_DRIVER_CLASS with the JDBC driver for your database: IBM Db2 for Linux, UNIX, and Windows: com.ibm.db2.jcc.DB2Driver Microsoft SQL Server: com.microsoft.sqlserver.jdbc.SQLServerDriver Oracle: oracle.jdbc.OracleDriver PostgreSQL: org.postgresql.Driver
   jdbc_url	Replace YOUR_JDBC_URL with the URL for the Pega Platform database: IBM Db2 for Linux, UNIX, and Windows: jdbc:db2://host:port/dbname Microsoft SQL Server: jdbc:sqlserver://host:port;databaseName=dbName;selectMethod=cursor;sendStringParametersAsUnicode=false Oracle: Use either the service name or the SID: jdbc:oracle:thin:@host:port/service-name jdbc:oracle:thin:@host:port:SID ​PostgreSQL:jdbc:postgresql://host:port/dbname
   jdbc_user jdbc_password	Replace YOUR_JDBC_USER and YOUR_JDBC_PASSWORD with the user name and password used to connect to the database.
   jdbc_conn_props	Optional: Enter any custom connection properties.
   jdbc_rules_schema	Replace YOUR_RULES_SCHEMA with the name of your rules schema.
   jdbc_data_schema	Replace YOUR_DATA_SCHEMA with the name of your data schema.
   max_total_connections	Optional: Enter the number of total connections in the connection pool.
   max_idle_connections	Optional: Enter the maximum number of idle connections in the connection pool.
   max_wait_millis	Optional: Enter the number of milliseconds to wait for a database to become available. For infinite wait times, enter -1.
   additional_datasource_settings	Optional: Enter a space-delimited list of setting names and values in the format setting="value", for example: validationQuery="SELECT 1" validationQueryTimeout="5"
   jdbc_driver_downloads:    uri    user    password       secret	Replace YOUR_JDBC_DOWNLOAD_URL with the URI source from which to download a JDBC driver over HTTP, HTTPS, FTP, or FTPS, for example: https://jdbc.postgresql.org/download/postgresql-9.4.1212.jar If using basic authentication or FTP, also enter the user name and secret value to download the JDBC driver.
   ping_timeout	Optional: Specify the number of seconds to wait for a ping response before the server is considered unresponsive. In most cases, the default value of 1000 should be sufficient. If the Pega Platform application server fails to start within the specified amount of time, increase the value. If the value specified is too low, BOSH will try to deploy each Pega Platform instance type two times before failing completely.
   memory    max_heap    min_heap	Optional: Set the minimum and maximum Java heap size for each Pega Platform node. The recommended system heap size is 4096 MB - 8192 MB based on memory usage and garbage collection frequency.

8. Optional: Add lines to specify the storage locations for processing files without manual intervention. The settings depend on the file share type:

   • NFS Volume Share

     Property name	Action
     file_spec	Enter the file specification destination storage reference for Pega Platform applications such as file listeners and BIX. The actual storage location differs based on system settings. The value must include only lowercase letters and numbers, and must be a single word. Example: For BIX, enter pegacloudrepository. For file listeners, enter file://Destination:/directory to watch the directory inside the Destination file storage location.
     mount_options	Optional: Add additional mount options to be provided to the mount command during deployment.
     remote_host	Enter the host name or IP address of the remote host where the NFS share is located. This host must be accessible from the virtual machine.
     remote_path	Enter the remote path to the NFS share.

     Example:

     file_store:
       nfs:
       - file_spec: ‘file://cloud:/’
         mount_options: ‘timeo=10,intr,lookupcache=positive,soft’
         remote_host: ‘10.3.8.99’
         remote_path: ‘/share/pega’

   • Amazon Web Services S3 BLOB Share

     Property name	Action
     file_spec	Enter the file specification destination storage reference for Pega applications such as file listeners and BIX. The actual storage location differs based on system settings. The value must include only lowercase letters and numbers, and must be a single word. Example: For BIX, enter pegacloudrepository. For file listeners, enter file://Destination:/directory to watch the directory inside the Destination file storage location.
     bucket	Enter the AWS bucket name.
     access_key	Enter your AWS access key. The key is optional if you are using EC2 instances with attached IAM roles; otherwise it is required.
     secret_access_key	Enter your AWS secret key. The key is optional if you are using EC2 instances with attached IAM roles; otherwise it is required.
     root_path	Optional: Enter the root path under the bucket for this share.
     kms_encryption_key_id	Optional: To read or write encrypted files, enter the Amazon Key Management System (KMS) encryption key ID. For more information, see the Amazon KMS documentation.

     Example:

     file_store:
       aws_s3:
         - file_spec: ‘file://cloud:/’
           bucket: ‘something.s3.amazonaws.com’
           access_key: ‘BLDAI44QH8DHCEXAMPLE’
           secret_access_key: ‘je7MtGbClwBF/2Zp9Utk/h3yCo8nvbEXAMPLEKEY’
           root_path: ‘customer/data’
           kms_encryption_key_id: ‘db3ca323-2833-5924-9ada-87c2164ed822’

   • Microsoft Azure BLOB Share

     Property name	Action
     file_spec	Enter the file specification destination storage reference for Pega applications such as file listeners and BIX. The actual storage location differs based on system settings. The value must include only lowercase letters and numbers, and must be a single word. Example: For BIX, enter pegacloudrepository. For file listeners, enter file://Destination:/directory to watch the directory inside the Destination file storage location.
     bucket	Enter the Azure container name.
     user_name	Enter your Azure user name.
     secret_access_key	Enter your Azure secret access key.
     root_path	Optional: Enter the root path under the bucket for this share.

     Example:

     file_store:
       azureblob:
         - file_spec: ‘file://cloud:/’
           bucket: ‘https://myaccount.blob.core.windows.net/mycontainer’
           user_name: ‘someuser’
           secret_access_key: ‘Eby8vdM02xNOcqFlqUwJPLlmEtlCDXJ1OUzFT50uSRZ6IFsuFq2UVErCz4I6tq/K1SZFPTOtr/KBHBeksoGMGw==’
           root_path: ‘/pega’

9. Optional: In the context_settings section, specify name/value (java.lang.String) pairs to be bound to the JNDI context during deployment. You can configure Data-Admin-System settings or prconfig.xml settings to override standard behavior, for example:

   context_settings:
   - name: setting1
     value: value1
   - name: setting2
     value: value2
   

10. Optional: In the additional_jvm_arguments section, add lines to specify additional JVM command-line arguments. You can specify any number of arguments. Do not specify either the maximum heap size (-Xmx) or minimum heap size (-Xms); set those values later in this procedure. Enter the argument to be passed to the JVM as it would appear on the command line, for example:

    additional_jvm_arguments:
       - argument: -Dsome.prop1=true
       - argument: -Dsome.prop2=false

11. Optional: In the additional_datasources section, enter additional JDBC data sources for external databases. The database must be the same type as the database you specified in step 10. Use the properties in the following table:

    Property name	Action
    pega_db_name	Enter the database name. This value corresponds to a portion of the data source JNDI name. The corresponding Data-Admin-DB-Name that refers to this data source must have the same database name, and must refer to the JNDI reference at java:comp/env/jdbc/database_name
    driver_class	Enter the JDBC driver class for your database: IBM Db2 for Linux, UNIX, and Windows: com.ibm.db2.jcc.DB2Driver Microsoft SQL Server: com.microsoft.sqlserver.jdbc.SQLServerDriver Oracle: oracle.jdbc.OracleDriver PostgreSQL: org.postgresql.Driver
    database_url	Enter the JDBC connection URL: IBM Db2 for Linux, UNIX, and Windows: jdbc:db2://host:port/dbname Microsoft SQL Server: jdbc:sqlserver://>host:port;databaseName=dbName;selectMethod=cursor;sendStringParametersAsUnicode=false Oracle: Use either the service name or the SID: jdbc:oracle:thin:@host:port/service-name jdbc:oracle:thin:@host:port:SID ​PostgreSQL:jdbc:postgresql://host:port/dbname
    user password.secret	Enter the user name and password used to connect to the database.
    connection_props	Optional: Enter any custom connection properties. For Apache Tomcat, the connection properties correspond to the connectionProperties attribute.
    default_schema	Enter the schema name for unqualified object references.
    max_total_connections	Optional: Enter the number of total connections in the connection pool.
    max_idle_connections	Optional: Enter the maximum number of idle connections in the connection pool.
    max_wait_millis	Optional: Enter the number of milliseconds to wait for a database to become available. For infinite wait times, enter -1.
    additional_datasource_settings	Optional: Enter a space-delimited list of setting names and values in the format setting="value", for example: validationQuery="SELECT 1" validationQueryTimeout="5"

12. Optional: In the log_forwarding_settings section, configure Cloud Foundry to forward log files. Pega Platform uses rsyslog for log forwarding. You can configure the release to forward logs to any tool that can consume syslog. All Pega Platform logs are read to the VM local0 log facility and forwarded to the target. Use the properties in the following table:

    Property name	Action
    enabled	Set to true to enable log forwarding.
    address	Enter the name or IP address of the target system.
    port	Enter the port name or number to use when connecting to the target system.
    protocol	Enter the type of protocol to use: 'tcp' 'udp' 'relp'

13. Repeat steps 7 - 12 to configure any other plans you want.

14. Optional: In the update section, configure watch timeouts. Use the properties in the following table:

    Property name	Action
    canaries	Enter the number of canary instances.
    canary_watch_time	Enter the maximum number of milliseconds that Cloud Foundry waits for a healthy message from a preliminary canary job. If Cloud Foundry does not receive a healthy message before the time-out, the job fails and Cloud Foundry does not load other jobs.
    update_watch_time	Enter the number of milliseconds that Cloud Foundry waits for a healthy message from a preliminary job that runs after a tile update. If Cloud Foundry does not receive a healthy message before the time-out, Cloud Foundry abandons the tile update.
    max_in_flight	Enter the number of non-canary instances to update in parallel.

15. Save and close the file.

Deploying the Pega Service Broker to BOSH

The Pega Service Broker allows you to deploy multiple clusters of Pega Platform instances. The system administrator performs these steps.

1. From the BOSH command line, run the following command to target the Pega Service Broker deploy: 
   bosh -d pegasystems-on-demand deploy path/pega-service-adapter-deployment.yml

2. After you see a success message, run the following command to display the service IP address; note the IP address of the pega-broker:
   bosh instances

Connecting Cloud Foundry to the Pega Service Broker

After you obtain the IP address of the Pega Service Broker service, use that IP address to connect Cloud Foundry to the Pega Service Broker. The system administrator performs these steps.

1. Log in to the Cloud Foundry command line as an administrator.
2. Define a name space for your Cloud Foundry deployment. Select the organization and space into which you deploy applications. Enter the following command:
   cf target -o organization -s space
   for example: cf target -o pega -s dev
3. Run the following command to create a service broker:

   cf create-service-broker pega-broker YOUR_BROKER_USER YOUR_BROKER_PASSWORD http://IP_address:port

   where:

   • pega-broker – The name of the Pega Service Broker from the Pega Service Broker manifest.
   • YOUR_BROKER_USER and YOUR_BROKER_PASSWORD – The Pega Service Broker user name and password from the Pega Service Broker manifest.
   • IP_address – The pega-broker IP address from step 3 of Deploying the Pega Service Broker to BOSH.
   • port – The port number specified in the Pega Service Broker manifest. If you did not edit the port number in the manifest, the default port is 8080.
4. Run the following command to enable access to the Pega Service Broker plans. The service file name is specified in the Pega Service Broker manifest; the default is pega-service:
   cf enable-service-access pega-service
5. Run the following command to confirm that the deployment worked and to view the services offered by the Pega Service Broker. Make note of the service plan details.
   cf marketplace
6. Verify that pega-service appears in the service list.

Next step

After the service is available, customize and deploy Pega Platform clusters. For more information, see Deploying Pega Platform clusters on Cloud Foundry.