Advanced DPK: Building a PIA Domain

With the DPK, you can build many configurations: full systems like the PeopleSoft Images, a web server, a combination of domains, or deploy the middleware software only. The goal of the DPK is to build you a server for you from a single set of configuration files.

But, what if you want to spin up a temporary web domain and test something without impacting your standard configuration? You can add the temporary domain to the psft_customizations.yaml file, but the DPK will shut down every domain on the server before it builds the new domain. That’s not a good solution.

Behind the DPK are new Puppet types that provide interfaces to create domains using Puppet. If you look in the file puppet\etc\modules\pt_config\tests\test_pia_create.pp, you can see this in action. The test creates variables and array’s to pass into the pt_webserver_domain Puppet type. Calling pt_webserver_domain will create a new PIA domain. Let’s explore this Puppet type and see how we can use it to create temporary domain

I want to say, use this method only if you have a good understanding of Puppet. This post is showing how to build PIA domains directly so we can better understand how the DPK works.

Custom YAML files

In the test_pia_create.pp manifest, the arrays are created in the manifest. We’ll use a YAML file to store our data instead. I find writing arrays in Puppet to be tedious and can break easily. Hiera and YAML files are much easier to work with, and we can use this manfiest for more domains in the future.

hrdev.yaml

hrdev.yaml is a small YAML file that stores data for a single PIA domain. It is important to keep the structure of the pia_domain_list section so we can easily take the YAML data and pass it into the pt_webserver_domain type. In the hrdev.yaml file, you can update any settings you want to configure the domain the way you want.

pia_domain_list:
  hrdev:
    os_user:            psadm
    ps_cfg_home_dir:    e:/psoft/hrdev-8.55.06
    gateway_user:       administrator
    gateway_user_pwd:   'Passw0rd'
    auth_token_domain:  .psadmin.io

    webserver_settings:
      webserver_type:           weblogic
      webserver_home:           e:/psoft/pt/bea
      webserver_admin_user:     system
      webserver_admin_user_pwd: 'Passw0rd'
      webserver_admin_port:     10020
      webserver_http_port:      10020
      webserver_https_port:     10030

    config_settings:
      Servers/PIA/WebServer/PIA/WebServerLog/PIA: 
        LoggingEnabled:         true

    site_list:
      hrdev:
        appserver_connections: app-d1:10010
        domain_conn_pwd:       'Passw0rd'

        webprofile_settings:
          profile_name:        DEV
          profile_user:        PTWEBSERVER
          profile_user_pwd:    'Passw0rd'
        report_repository_dir: e:/psreports

YAML Hashes and Arrays

YAML files can store data in various ways. The two common types the DPK uses are hashes and arrays. Hashes are key: value pairs, and can also contain nested hashes. The config_settings and pia_site_list sections are an example of a nested hash.

The DPK types use Arrays but the psft_customizations.yaml file (other others) use hashes. Hashes are often easier to work with because they are more descriptive. Thankfully, the DPK comes with some helper functions to convert a nested hash into a nested array.

Custom PIA Manifest

Next, we’ll start writing a Puppet manifest that will load hrdev.yaml and prepare our PIA domain. To start, let’s load our data and get the pia_domain_list hash into a variable:

$tempWebServer = loadyaml('c:\temp\hrdev.yaml')
$pia_domain_list = $tempWebServer['pia_domain_list']

Next, we’ll loop through the pia_domain_list hash and prepare the pt_webserver_domain DPK type to create our PIA domain.

$pia_domain_list.each |$domain_name, $pia_domain_info| {

The $domain_name value is the key of the hash, and $pia_domain_info is the nested hash. Those values will be accessible inside our loop. Next, we’ll take the webserver_settings, pia_site_list, and config_settings (if it exists in the YAML file) sections and turn them into nested arrays. The PeopleTools team delivers an excellent function hash_of_hash_to_array_of_array() function that does the heavy lifting.

$webserver_settings = $pia_domain_info['webserver_settings']
  $webserver_settings_array  = join_keys_to_values($webserver_settings, '=')

  $pia_site_list         = $pia_domain_info['site_list']
  $pia_site_list_array   = hash_of_hash_to_array_of_array($pia_site_list)

  $config_settings = $pia_domain_info['config_settings']
  if $config_settings {
    $config_settings_array = hash_of_hash_to_array_of_array($config_settings)
  }

Last, we’ll instantiate the pt_webserver_domain Puppet type with our configuration data.

pt_webserver_domain { "${domain_name}":
  ensure                => hiera('ensure'),
  ps_home_dir           => hiera('ps_home_location'),
  os_user               => hiera('domain_user'),
  ps_cfg_home_dir       => $pia_domain_info['ps_cfg_home_dir'],
  webserver_settings    => $webserver_settings_array,
  config_settings       => $config_settings_array,
  gateway_user          => $pia_domain_info['gateway_user'],
  gateway_user_pwd      => $pia_domain_info['gateway_user_pwd'],
  auth_token_domain     => $pia_domain_info['auth_token_domain'],
  site_list             => $pia_site_list_array,
}

Running the Manifest

Save the piaDomain.pp manifest to your c:\programdata\puppetlabs\puppet\etc\manifests folder, and the hrdev.yaml file to c:\temp folder. From the puppet\etc\manfiests folder, run puppet apply piaDomain.pp --trace --debug. The PIA build process can take 5-10 minutes to run, but at the end you’ll have a PIA domain built using the DPK and Puppet.

Both hrdev.yaml and piaDomain.pp are on Github if you want to download the files and test.

Building Blocks

If you want to spin up a single PIA domain, this may feel like overkill. The value in learning Puppet and the DPK isn’t to build a single domain, it’s a building block to quickly (and consistently) build many domains. The piaDomains.pp manifest can scale to multiple domains and all you have to do is update the YAML file.

Not everyone may need (or want) to dig into the DPK this deep. But for anyone who wants more control over their environment build with the DPK, using the Puppet types that come with the DPK will be an invaluable skill.

If you are building an app server domain with this method, use this bug fix to ensure the app server features are correctly enabled.