Merge branch 'release/2.1.0'

Version 2.1.0
  - New Feature #1: Added documentation / instructions under docs/*.md for the most common tasks you can do with Pythia
  - New Feature #13: Implemented Export / Import mechanism over Datapump Network_link
  - Fixed Issue #7: Updated README(s) and added Features to the list
  - Fixed Issue #11: All not needed Variables are moved from vars/main.yml to defaults/main.yml. Making them better overwriteable

Version 2.0.1
  - Fixed Issue #9: Tempfiles will now be dropped / deleted, when Target DB already exists and you specify to override the Target DB

Author: thedatabaseme

Changelog.txt

@@ -1,5 +1,11 @@
 Changelog of Pythia:
 
+Version 2.1.0
+  - New Feature #1: Added documentation / instructions under docs/*.md for the most common tasks you can do with Pythia
+  - New Feature #13: Implemented Export / Import mechanism over Datapump Network_link
+  - Fixed Issue #7: Updated README(s) and added Features to the list
+  - Fixed Issue #11: All not needed Variables are moved from vars/main.yml to defaults/main.yml. Making them better overwriteable
+
 Version 2.0.1
   - Fixed Issue #9: Tempfiles will now be dropped / deleted, when Target DB already exists and you specify to override the Target DB
 

README.md

@@ -3,9 +3,14 @@ Pythia is a Role for ansible that helps you to automate the following tasks when
 
   - Install Oracle RDBMS (Starting with Version 18) on a target system
   - Create a Database on top of a new or an existing RDBMS
+  - Adjust all needed Kernel Parameters to run an Oracle Database
+  - Creates OS Users and Groups implicitly
   - Install Patches on top of a new and existing RDBMS and or Database
   - Runs SQL Scripts against a specified Oracle Database
   - Upgrade a Oracle DB to a new Version
+  - Duplicate a Database with RMAN "duplicate from active database"
+  - Datapump Export / Import over NETWORK_LINK
+  - Install Oracle Client
 
 Thereby several Prerequisites are fullfilled and or checked. E.G.
 
@@ -34,10 +39,10 @@ Installation and Configuration
 
   1. Clone the Repository to your Ansible Controlserver: git clone https://github.com/theoracleme/pythia.git
   2. Setup a Fileshare, that includes the Oracle Software you want to install and mount it to the Ansible Controlserver.
-  3. Configure the Fileshare as "Staging Area" by changing the "local_stage_directory" variable in the vars/main.yml
-  4. Configure all Variables fitting your environment. A description for all Variables can be found in the Roles README.md or the vars/main.yml File.
-  5. Configure the vars/rdbms_dict.yml, vars/patch_dict.yml and vars/sid_directories.yml to suite your needs. A description for all Variables can be found in the Dictionary File or the README.md.
-     Further Informations about what to change, can also be found in the INSTALL.md
+  3. Configure the Fileshare as "Staging Area" by changing the "local_stage_directory" variable in the `vars/main.yml`
+  4. Configure all Variables fitting your environment. A description for all Variables can be found in the Roles README.md or the `vars/main.yml` File.
+  5. Configure the `vars/rdbms_dict.yml`, `vars/patch_dict.yml` and `vars/sid_directories.yml` to suite your needs. A description for all Variables can be found in the Dictionary File or the README.md.
+     Further Informations about what to change, can also be found in the [INSTALL.md](https://github.com/thedatabaseme/pythia/blob/master/INSTALL.md)
   6. Define your Hosts or Hostgroups in the Ansible Host Inventory. (e.G. hosts)
   7. Place User-Defined SQL Scripts under the files/default directory of the Role. 
 
@@ -49,21 +54,22 @@ Example Playbook Runs
 **More detailed Examples and instructions can be found under the docs folder**
 
 Pythia works with tags to combine the actions of installation, configuration, patching and so on. The following Tags are defined:
-  - rdbms: Specifies, that you want a RDBMS installed. When tagging rdbms, you also may want to specify the Variable oracle_version when starting the playbook with "rdbms" tag.
-  - db: Specifies, that you want to install a Database on top a new RDBMS (when specifying "rdbms" as a tag alongside with the "db" tag) or an already installed RDBMS on the target system. You may also want to specify the Variable oracle_version when starting the playbook with the "db" tag. You need to specify the oracle_sid Variable when calling the playbook for naming the new Database.
-  - patch: Specifies, that you want to install a Patch on top of a new RDBMS (when specifying "rdbms" as a tag alongside with the "patch" tag) or an already installed RDBMS. When specifying the "patch" tag, you need to also specify the "install_patch" Variable when running the playbook. While running under the "patch" tag, the Patch Archive will be uncompressed to the target system. The Patch Files will be deleted after successfully installing the Patch.
-  - patchonly: Like "patch" tag but implies, that the Patch Archive already exists on the target system. No cleanup will be done after the Patch Installation.
+  - rdbms: Specifies, that you want a RDBMS installed. When tagging rdbms, you also may want to specify the Variable oracle_version when starting the playbook with `rdbms` TAG.
+  - db: Specifies, that you want to install a Database on top a new RDBMS (when specifying `rdbms` as a TAG alongside with the `db` TAG) or an already installed RDBMS on the target system. You may also want to specify the Variable oracle_version when starting the playbook with the `db` TAG. You need to specify the `oracle_sid` Variable when calling the playbook for naming the new Database.
+  - patch: Specifies, that you want to install a Patch on top of a new RDBMS (when specifying `rdbms` as a TAG alongside with the `patch` TAG) or an already installed RDBMS. When specifying the `patch` TAG, you need to also specify the `install_patch` Variable when running the playbook. While running under the `patch` TAG, the Patch Archive will be uncompressed to the target system. The Patch Files will be deleted after successfully installing the Patch.
+  - patchonly: Like `patch` TAG but implies, that the Patch Archive already exists on the target system. No cleanup will be done after the Patch Installation.
   - cleanup: Forces a cleanup after sucessfull Patch Installation. Also forces that the created backup Files under the RDBMS that are created by OPatch when patching are deleted. Handle with caution if you may want to rollback the Patch.
-  - listener: Only creates a listener for the Specified Database with the oracle_sid Variable.
-  - sqlscript: Triggers, that SQL Scripts (.sql) under files/default (or specified by local_sql_stage_directory) directory will be executed against the specified oracle_sid. Be aware, the Scripts will be executed without any precheck. Bad SQL can cause immense harm.
-  - rpm: Triggers that additional RPMs have to be installed. When specifying "rpm" tag, you need also to specify the "install_rpm" Variable when running the playbook. The RPM will be transfered to the target system. After installing the RPM, the file will be removed.
-  - autostart: Controls that the automatic startup of the Database you specified will be implemented. When specifying the autostart tag, you also must specify the oracle_sid Variable when calling the Playbook.
-  - hugepage: Triggers, that Hugepages have to be configured. Can only be triggered when also tagging db. Hugepages will be calculated by given sga_max_size (Default 2G)
-  - converttohugepage: Converts a non Hugepage configured System to use Hugepages. Disables transparent_hugepages. Needs sga_max_size Variable set to the absolute Size (in GB) of all SGA's on the System
-  - prepare: Prepares the Target System for an upcomming Oracle Installation. Can be combined with the hugepage Tag and needs sga_max_size (Default 2G) specified to calculate Shared Memory and Hugepages
-  - client: Specifies, that you want to install an Oracle Client. When tagging client, you also may to want to specify the Variable client_version when starting the playbook with "client" tag.
-  - duplicate: Specifies, that you want to duplicate a Source Database to a Target Database. Uses RMAN duplicate from active Database. You need to specify the duplicate_source_host, duplicate_target_host, duplicate_source_sid and duplicate_target_sid Variable. As HOSTS you need to specify the Target Host.  
-  - upgrade: Specifies that you want to upgrade a Database to a new Version. You need to specify the Variables oracle_source_version, oracle_target_version, oracle_sid and upgrade_mode when starting the Playbook with the "upgrade" tag.
+  - listener: Only creates a listener for the Specified Database with the `oracle_sid` Variable.
+  - sqlscript: Triggers, that SQL Scripts (.sql) under `files/default` (or specified by `local_sql_stage_directory`) directory will be executed against the specified `oracle_sid`. Be aware, the Scripts will be executed without any precheck. Bad SQL can cause immense harm.
+  - rpm: Triggers that additional RPMs have to be installed. When specifying `rpm` TAG, you need also to specify the `install_rpm` Variable when running the playbook. The RPM will be transfered to the target system. After installing the RPM, the file will be removed.
+  - autostart: Controls that the automatic startup of the Database you specified will be implemented. When specifying the autostart TAG, you also must specify the `oracle_sid` Variable when calling the Playbook.
+  - hugepage: Triggers, that Hugepages have to be configured. Can only be triggered when also tagging `db`. Hugepages will be calculated by given `sga_max_size` (Default 2G)
+  - converttohugepage: Converts a non Hugepage configured System to use Hugepages. Disables transparent_hugepages. Needs `sga_max_size` Variable set to the absolute Size (in GB) of all SGA's on the System
+  - prepare: Prepares the Target System for an upcomming Oracle Installation. Can be combined with the `hugepage` TAG and needs `sga_max_size` (Default 2G) specified to calculate Shared Memory and Hugepages
+  - client: Specifies, that you want to install an Oracle Client. When tagging `client`, you also may to want to specify the Variable `client_version` when starting the playbook with `client` TAG.
+  - duplicate: Specifies, that you want to duplicate a Source Database to a Target Database. Uses RMAN duplicate from active Database. You need to specify the `duplicate_source_host`, `duplicate_target_host`, `duplicate_source_sid` and `duplicate_target_sid` Variable. As HOSTS you need to specify the Target Host.  
+  - upgrade: Specifies that you want to upgrade a Database to a new Version. You need to specify the Variables `oracle_source_version`, `oracle_target_version`, `oracle_sid` and `upgrade_mode` when starting the Playbook with the `upgrade` TAG.
+  - datapump: Specifies, that you want to do an Datapump Export / Import over NETWORK_LINK. You need to specify the `datapump_source_host`, `datapump_target_host`, `datapump_source_sid` and `datapump_target_sid` Variable. As HOSTS you need to specify the Target Host.
 
 Example: Install Oracle RDBMS with Version 19c and Enterprise Edition on Host "ansibletest", install the 19.5 RU (Patch ID: 30125133). Build a Database named "ORA19" on top:
 
@@ -107,3 +113,10 @@ Also you're able to specify, that the SPFILE of your maybe existing Target Datab
 Example: Upgrade an Oracle Database in Version 18 to Oracle Database in Version 19 on Host "ansibletest":
 
     - ansible-playbook /etc/ansible/pythia/pythia.yml -e "oracle_source_version=18EE oracle_target_version=19EE oracle_sid=ORAUPGRD upgrade_mode=deploy HOSTS=ansibletest" --tags "upgrade" -k -K -u <username>
+
+Example: Do a Datapump Export / Import over NETWORK_LINK. Source Database named EXPSRC to a Database named EXPDST on the host "vmdbsoradatapumptarget". As HOST, the Target Host must be specified:
+Attention!: The Passwords for the Source and Target Database is needed for the datapump process. The Password has to be provided within the vault.yml (using ansible-vault) as vault_datapump_<SOURCESID> and vault_datapump_<TARGETSID>
+
+    - ansible-playbook /etc/ansible/pythia/pythia.yml -e "HOSTS=vmdbsoradatapumptarget datapump_source_host=vmdbsdatapumpsource datapump_target_host=vmdbsoradatapumptarget datapump_source_sid=EXPSRC datapump_target_sid=EXPDST datapump_full=False datapump_schema_list='USER1,USER2'" --tags "datapump" -k -K -u <username> --vault-password-file /etc/ansible/vault_password.pwd
+
+    - ansible-playbook /etc/ansible/pythia/pythia.yml -e "HOSTS=vmdbsoradatapumptarget datapump_source_host=vmdbsdatapumpsource datapump_target_host=vmdbsoradatapumptarget datapump_source_sid=EXPSRC datapump_target_sid=EXPDST" --tags "datapump" -k -K -u <username> --vault-password-file /etc/ansible/vault_password.pwd

docs/01_GENERAL.md

@@ -1,5 +1,36 @@
 # General Informations
-In this section, you can find some more in detail examples using Pythia. For instance, how to do a duplicate with Pythia.
+In this section, you can find some more in detail examples using Pythia. 
+
+
+## TAGs
+
+Pythia is based on working with (Ansible) TAGs. When creating the command to run Pythia, you have to hand over at least one of the Tags (also listed in the [README.md](https://github.com/thedatabaseme/pythia/blob/master/roles/pythia/README.md)). You can mostly combine the TAGs as you like. So for instance, you may combine the TAGs rdbms, db and patch, to get an RDBMS installed, a Database on top of this and of course, you want to have it patched. All in one command.
+
+  - rdbms: Specifies, that you want a RDBMS installed. When tagging rdbms, you also may want to specify the Variable oracle_version when starting the playbook with "rdbms" tag.
+  - db: Specifies, that you want to install a Database on top a new RDBMS (when specifying "rdbms" as a tag alongside with the "db" tag) or an already installed RDBMS on the target system. You may also want to specify the Variable oracle_version when starting the playbook with the "db" tag. You need to specify the oracle_sid Variable when calling the playbook for naming the new Database.
+  - patch: Specifies, that you want to install a Patch on top of a new RDBMS (when specifying "rdbms" as a tag alongside with the "patch" tag) or an already installed RDBMS. When specifying the "patch" tag, you need to also specify the "install_patch" Variable when running the playbook. While running under the "patch" tag, the Patch Archive will be uncompressed to the target system. The Patch Files will be deleted after successfully installing the Patch.
+  - patchonly: Like "patch" tag but implies, that the Patch Archive already exists on the target system. No cleanup will be done after the Patch Installation.
+  - cleanup: Forces a cleanup after sucessfull Patch Installation. Also forces that the created backup Files under the RDBMS that are created by OPatch when patching are deleted. Handle with caution if you may want to rollback the Patch.
+  - listener: Only creates a listener for the Specified Database with the oracle_sid Variable.
+  - sqlscript: Triggers, that SQL Scripts (.sql) under files/default (or specified by local_sql_stage_directory) directory will be executed against the specified oracle_sid. Be aware, the Scripts will be executed without any precheck. Bad SQL can cause immense harm.
+  - rpm: Triggers that additional RPMs have to be installed. When specifying "rpm" tag, you need also to specify the "install_rpm" Variable when running the playbook. The RPM will be transfered to the target system. After installing the RPM, the file will be removed.
+  - autostart: Controls that the automatic startup of the Database you specified will be implemented. When specifying the autostart tag, you also must specify the oracle_sid Variable when calling the Playbook.
+  - hugepage: Triggers, that Hugepages have to be configured. Can only be triggered when also tagging db. Hugepages will be calculated by given sga_max_size (Default 2G)
+  - converttohugepage: Converts a non Hugepage configured System to use Hugepages. Disables transparent_hugepages. Needs sga_max_size Variable set to the absolute Size (in GB) of all SGA's on the System
+  - prepare: Prepares the Target System for an upcomming Oracle Installation. Can be combined with the hugepage Tag and needs sga_max_size (Default 2G) specified to calculate Shared Memory and Hugepages
+  - client: Specifies, that you want to install an Oracle Client. When tagging client, you also may to want to specify the Variable client_version when starting the playbook with "client" tag.
+  - duplicate: Specifies, that you want to duplicate a Source Database to a Target Database. Uses RMAN duplicate from active Database. You need to specify the duplicate_source_host, duplicate_target_host, duplicate_source_sid and duplicate_target_sid Variable. As HOSTS you need to specify the Target Host.
+  - upgrade: Specifies that you want to upgrade a Database to a new Version. You need to specify the Variables oracle_source_version, oracle_target_version, oracle_sid and upgrade_mode when starting the Playbook with the "upgrade" tag.
+
+
+## Extra Variables
+
+Beside from specifying a TAG, you need to provide at least these Variable (regardless of which TAG you have specified). You may specify the HOSTS Variable directly in the Playbook, as an Extra Variable or in your Inventory. In these Instructions, we will always hand them over as Extra Variables.
+
+  - HOSTS: Within this Variable, you provide a list of Hosts, you want to get Pythia to do her magic work for you.
+
+
+## Workflow
 
 Pythia works in the following order. This is important to know, which steps will be done in which order.
 
@@ -58,4 +89,13 @@ Pythia works in the following order. This is important to know, which steps will
                 |                |
                 |  Duplicate DB  |
                 |                |
-                +----------------+
+                +----------------+
+
+
+## Further Documentation
+
+We try to provide a detailed documentation for each usecase of Pythia. Please have a look into these:
+
+  - [Install an Oracle Database RDBMS](https://github.com/thedatabaseme/pythia/blob/master/docs/02_INSTALL_RDBMS.md)
+  - [Create a Database](https://github.com/thedatabaseme/pythia/blob/master/docs/03_CREATE_DB.md)
+  - [Install Patches and Updates](https://github.com/thedatabaseme/pythia/blob/master/docs/04_INSTALL_PATCH.md)