customize

Extending / Customizing PORS

Custom inventory names / environments

PORS comes with 3 static names for managing your environments: production|staging|development. If that does not fit your naming schemes simply add new environment names!

First of all you need to define an environment name. Avoid dashes within, Ansible doesn't like that ;)
As an example we use here the new environment name testing:

1. ensure you are the PORS user: sudo su - pors
2. First create the needed custom directories:
   • mkdir /opt/pors_data/custom/filter_plugins
   • mkdir -p /opt/pors_data/custom/roles/common/templates/
3. Next is to copy a current plugin file to a new one while matching the new environment name. In this case to "linked_apps_testing.py":

   • cp /opt/pors/filter_plugins/linked_apps_development.py /opt/pors_data/custom/filter_plugins/linked_apps_testing.py

   • Ensure you copy it to the /opt/pors_data/custom/filter_plugins directory! Never change something in /opt/pors
4. Now replace all occurrences of the copied environment with the new one (here change to: testing):

   • sed -i 's/development/testing/g' /opt/pors_data/custom/filter_plugins/linked_apps_testing.py

5. Copy a current template to a new one while matching the new environment name. In this case to "ae_deploy_apps_testing.yml.j2":

   • cp /opt/pors/roles/common/templates/ae_deploy_apps_development.yml.j2 /opt/pors_data/custom/roles/common/templates/ae_deploy_apps_testing.yml.j2

6. Now replace all occurrences of the copied environment with the new one (here change to: testing):

   • sed -i 's/list_development/list_testing/g' /opt/pors_data/custom/roles/common/templates/ae_deploy_apps_testing.yml.j2

7. initialize the inventory from the shipped staging or from your already set /opt/pors_data/inventories (here we copy from the shipped EXAMPLES../staging to testing):

   • cp -a /opt/pors/EXAMPLES/inventories/staging /opt/pors_data/inventories/testing

8. change environment variables to the new environment name (here from staging to testing):
   • to be sure not missing anything you can parse through all files like that:
     

     grep -r staging /opt/pors_data/inventories/testing/
     ensure you change all occurrences of staging with your new environment (here testing)

   • when using a static hosts file:

     cp /opt/pors_data/inventories/testing/hosts.example-static /opt/pors_data/inventories/testing/hosts
     sed -i 's/^target_env=.*/target_env=testing/g' /opt/pors_data/inventories/testing/hosts

   • when using dynamic hosts file:

     cp /opt/pors_data/inventories/testing/hosts_dynamic.XXXXXXX.yml.example /opt/pors_data/inventories/testing/hosts_dynamic.XXXXX.yml
     sed -i 's/target_env: .*/target_env: testing/g' /opt/pors_data/inventories/testing/hosts_dynamic\*

   • other files you might want to look at within /opt/pors_data/inventories/testing/group_vars/all/
     • outputs.conf.yml
     • vm_deploy.yml
9. Initialize your vault
10. recommended: add the new environment to /etc/profile.d/pors.sh with a new alias name (e.g. pors-testing)
11. optional: you might want to copy existing apps from /opt/pors_repo/<environment>/apps to /opt/pors_repo/testing/
12. optional: you might want to change your vm_recipes

Every inventories sub-directory will be detected by PORS on start and then can be used to separate on every level you need.

Roles / Playbooks / Plugins

PORS comes with a whole bunch of roles and playbooks but sometimes that is not enough - or the way how PORS handles things does not met your requirements.

For this it is highly recommended to NOT do any changes within the main PORS installation directory (usually /opt/pors) but instead make use of custom roles and playbooks folders.

The default paths for any custom stuff are:

/opt/pors_data/custom/roles
/opt/pors_data/custom/playbooks
/opt/pors_data/custom/filter_plugins
/opt/pors_data/custom/callback_plugins

There is no need to do anything when you stick with these paths!

If you want to user other paths you have to adjust the default PORS .ansible.cfg within your home dir and add accordingly:

• roles_path if using a custom /roles path.
• callback_plugins if using a custom PORS installation directory
• ...

Hint: the playbooks dir must not be specified anywhere as you would call your own playbooks with the full path anyways. This might change in the future so better keep the above path naming to avoid future issues.

Now you can place your custom roles and playbooks without interfering with the main PORS installation directory (so upgrading PORS will not break your customizations).

Hooks

PORS allows to hook into some of its processes. This is useful if you want to extend functionality in PORS without changing the main code base (or waiting until it gets included).

General execution order

System / VM-Deployment

1. /opt/pors_data/custom/roles/custom_system/tasks (TASKS hook, see next topic)
2. /opt/pors_data/custom/playbooks (PLAYBOOK hook, see next topic)
3. system_base (/opt/pors_data/inventories/<environment>/group_vars/all/system_base.yml)

Splunk installation (not part of VM deployment)

1. /opt/pors_data/custom/roles/custom_post_install_splunk/tasks (Splunk installation hook, see next topic)

System/VM-Deployment

TASKS hook

When a system gets deployed by PORS you can add tasks once it has booted and setup. That means PORS will deploy, add disks, format disks, reboots and once booted and before doing anything else you can add your own tasks.

Activation:
/opt/pors_data/inventories/<environment>/group_vars/all/hooks.yml -> set hook_system_tasks = True

From now on PORS will execute /opt/pors_data/custom/roles/custom_system/tasks/main.yml which you need to create first of course. It gets included as an ansible role so you do not need to care about hosts, users etc (usually). All jobs here will be executed as user root so keep that in mind.

Hint: Best practice is using the main.yml to just include the real tasks yml files.

PLAYBOOK hook

Additionally or instead of using custom tasks PORS also allows to specify one or multiple playbooks during the VM deployment. That means PORS will deploy, add disks, format disks, reboots and once booted and before doing anything else you can add your own playbooks.

Pre-Requisites:

• ensure your playbooks hosts: key is either set to all or use hosts: "{{ server_hostname }}" (recommended)

Activation:

• /opt/pors_data/inventories/<environment>/group_vars/all/hooks.yml -> set

hook_system_playbook: "playbook1.yml subdir/playbook2.yml"

Your playbook(s) must be in /opt/pors_data/custom/playbooks or a sub directory within (see above for a config example then). The playbook must be added in the above format (space separated) in order to make it work and the execution order is from left to right.

From now on PORS will execute the defined playbooks just as you would do manually so ensure they are properly set and configured.

Splunk installation hook

Regardless how a system has been deployed (by PORS or any other) you can use PORS to install splunk. A splunk installation itself will not configure (e.g. a splunk role) or is doing any other specific splunk configuration but some basic configuration happens always like adding the defined splunk.secret file.

This hook will run after the splunk tar has been unpacked and before doing anything else (i.e. even before starting splunk the first time). The defined splunk user has been added already as well so if needed you can do tasks as that user as well (see next lines).

Activation:
/opt/pors_data/inventories/<environment>/group_vars/all/hooks.yml -> set hook_post_install_splunk = True

From now on PORS will execute /opt/pors_data/custom/roles/custom_post_install_splunk/tasks/main.yml which you need to create first of course. It gets included as an ansible role so you do not need to care about hosts, users etc (usually). All jobs here will be executed as user root so keep that in mind or/and use become + become_user to change to the splunk user.

Hint: Best practice is using the main.yml to just include the real tasks yml files.

CRIBL logstream installation hook

Regardless how a system has been deployed (by PORS or any other) you can use PORS to install cribl logstream. A logstream installation itself will not configure or is doing any other specific logstream configurations.

This hook will run after the logstream tar has been unpacked and before doing anything else (i.e. even before starting logstream the first time). The defined logstream user has been added already as well so if needed you can do tasks as that user as well (see next lines).

Activation:
/opt/pors_data/inventories/<environment>/group_vars/all/hooks.yml -> set hook_post_install_cribl = True

From now on PORS will execute /opt/pors_data/custom/roles/custom_post_install_cribl/tasks/main.yml which you need to create first of course. It gets included as an ansible role so you do not need to care about hosts, users etc (usually). All jobs here will be executed as user root so keep that in mind or/and use become + become_user to change to the splunk user.

Hint: Best practice is using the main.yml to just include the real tasks yml files.