experimental: new roles for APEX und ORDS

README.md

@@ -21,9 +21,9 @@
 
 ### Next Steps
 
-1. Read the full documentation <https://github.com/oravirt/ansible-oracle/tree/master/doc>
-1. How to develop in ansible-oracle <https://github.com/oravirt/ansible-oracle/blob/master/doc/development.adoc>
-1. List of roles in ansible-oracle <https://github.com/oravirt/ansible-oracle/blob/master/doc/roles.adoc>
+1. [APEX and ORDS in `ansible-oracle`](doc/guides/apex_ords.adoc)
+2. [How to develop in ansible-oracle](doc/development.adoc)
+3. [List of roles in ansible-oracle](doc/roles.adoc)
 
 
 ## Pre-requisites

changelogs/fragments/apex.yml

@@ -0,0 +1,3 @@
+---
+major_changes:
+  - "oraapex: New role to install APEX in databases - experimental (oravirt#473)"

changelogs/fragments/apex_download.yml

@@ -0,0 +1,3 @@
+---
+major_changes:
+  - "orasw_download_patches: added support for downloading apex installation archives (oravirt#473)"

changelogs/fragments/beginner.yml

@@ -0,0 +1,3 @@
+---
+major_changes:
+  - "beginner_patching: Inventory for ORDS + APEX (oravirt#473)"

changelogs/fragments/doc1.yml

@@ -0,0 +1,3 @@
+---
+major_changes:
+  - "ansible-oracle Documentation fixes (oravirt#473)"

changelogs/fragments/molecule.yml

@@ -0,0 +1,3 @@
+---
+major_changes:
+  - "molecule: Added APEX and ORDS to dbfs-ol9 (oravirt#473)"

changelogs/fragments/ords.yml

@@ -0,0 +1,3 @@
+---
+major_changes:
+  - "ORDS: new experimental role to install and configure ORDS on OracleLinux (oravirt#473)"

doc/featurelist.adoc

@@ -35,7 +35,7 @@ Redhat Enterprise Linux
 |6 <<table1footnote,^[1]^>> +
 7 <<table1footnote,^[1]^>> +
 8 +
-9 (experimental!) <<table1footnote,^[5]^>>
+9
 
 |SuSE Linux Enterprise Server<<table1footnote,^[3]^>>
 |15, 15.3
@@ -138,6 +138,10 @@ a|OneOff Patches<<table1footnote,^[11]^>>
 |automatic datapatch execution<<table1footnote,^[11]^>>
 |Patch Download from Oracle
 
+|Oracle APEX (experimental!)
+a|Installation of APEX in PDB. Not supported for CDB or nonCDB.
+|{supportedfrom19}
+
 |Environment script
 a|dynamic shell environment link:https://github.com/opitzconsulting/oracle-scripts[`ocenv`] for Oracle
 |{supportedfrom12}
@@ -154,6 +158,8 @@ a|dynamic shell environment link:https://github.com/opitzconsulting/oracle-scrip
   Please do not use this feature in production environments.
 [[table1footnote]]^3^::
   Limited support. Not tested for Oracle Restart & Grid-Infrastructure
+[[table1footnote]]^4^::
+  Only tested with PDB on 19c+. May be work in nonCDB as well but noch in CDB.
 [[table1footnote]]^5^::
   in development and not implemented at the moment.
 [[table1footnote]]^6^::

doc/guides/apex_ords.adoc

@@ -0,0 +1,205 @@
+:toc:
+:toc-placement!:
+:toclevels: 4
+toc::[]
+
+:sectnums:
+:sectnumlevels: 4
+
+== Setup APEX and ORDS
+
+IMPORTANT: The installation of APEX and ORDS with `ansible-oracle` is currently _experimental_.
+
+=== Requirements
+
+==== APEX
+
+- RDBMS 19c or newer
+- APEX 20.x or newer is mandatory for RDBMS 19c
+- Tested with APEX 23.2, 24.1 - may work with older versions as well
+- Installation is tested with PDB only.
+- CDB and nonCDB is not supported at the moment.
+- Download ZIP from Oracle with Playbook `patch_download.yml` supported for Version 22.1 or newer
+- APEX only with ORDS - no old APEX Listener
+
+Important Notes:
+
+- Primary Note for Oracle APEX Upgrades (Doc ID 1088970.1)
+
+Known Issues:
+
+- ADMIN password of INTERNAL Workspace is wrong after APEX upgrade
+  Silent script to reset ADMIN password depends on APEX Relöease. +
+  There was no reliable solution found for the moment...
+
+==== ORDS
+
+- OracleLinux 8 or 9 only
+- Installation with ords.rpm from `public-yum.oracle.com`
+- Limited database configuration - see documentation
+
+=== APEX Configuration
+
+IMPORTANT: Install APEX before ORDS - otherwise, the ORDS will not detect and configure APEX. +
+ORDS is only tested with existing APEX installation.
+
+==== Mandatory variables
+
+The following global variables are needed for an APEX installation.
+
+.Mandatory variables
+[options="header,footer"]
+|=======================
+|Value |Description
+|`oraapex_default_admin_password` | The parameter is mandatory, because it is the only way to configure a password for the admin user at the moment.
+|=======================
+
+.Optional variables
+[options="header,footer"]
+|=======================
+|Value |Description
+|`oraapex_base`
+| Default: `{{ oracle_base }}/product` +
+The unzip is done into `{{ oraapex_base }}/apex_<APEX Version>`
+|`oraapex_default_tablespace`
+| Default: `SYSAUX` +
+Could be set in each PDB.
+|`oraapex_default_files_tablespace`
+| Default: `SYSAUX` +
+Could be set in each PDB.
+|`oraapex_default_temp_tablespace`
+| Default: `TEMP` +
+Could be set in each PDB.
+|=======================
+
+==== APEX in PDB
+
+APEX can be installed in each PDB.
+
+.mandatory Variables in `oracle_pdbs`
+[options="header,footer"]
+|=======================
+|Value |Description
+| `apex_state`
+| State for APEX installation. +
+Only `present` supported at the moment.
+| `apex_version`
+| Version of APEX. +
+Is used to download the Archive from Oracle.
+|=======================
+
+.optional Variables in `oracle_pdbs`
+[options="header,footer"]
+|=======================
+|Value |Description
+| `oraapex_tablespace`
+| Custom APEX Tablespace.
+| `oraapex_files_tablespace`
+| Custom APEX Tablespace for files.
+| `oraapex_temp_tablespace`
+| Custom APEX temporary Tablespace.
+| `apex_patchid`
+| Patchid for _PSE BUNDLE FOR APEX_
+|=======================
+
+IMPORTANT: The example shows the minimum attributes for an APEX installation. +
+That's not the minimum needed to create a PDB.
+
+.Example `oracle_pdbs`
+----
+oracle_pdbs:
+  - cdb: CDB1
+    pdb_name: PDB1
+    state: present
+    apex_state: present
+    apex_version: 24.1
+    apex_patchid: 36695709
+----
+
+IMPORTANT: `oraapex` does not use the default passwords from `ansible-oracle`. +
+You have to define them in `dbpasswords`.
+
+The user `APEX_PUBLIC_ROUTER` is new in APEX 24.1. +
+`oraapex` checks for an existing password regardless of the version of APEX.
+
+.Example `dbpasswords` for APEX in a PDB with mandatory values for `oraapex`
+----
+dbpasswords:
+  CDB1:
+    PDB1:
+      apex_public_router: ords123
+      apex_public_user: ords123
+      apex_rest_public_user: ords123
+      ords_public_user: ords123
+----
+
+IMPORTANT: Do not forget to download the APEX Patch when `apex_patchid` is set in `oracle_pdbs`. +
+`opatch_install` is very important, because these Patches are not applied with OPatch.
+
+.Example `oracle_sw_patches`
+----
+oracle_sw_patches:
+  - filename: p36695709_2410_Generic.zip
+    patchid: 36695709
+    version: 24.1
+    description: PSE BUNDLE FOR APEX 24.1
+    opatch_needed: false
+----
+
+==== Playbook execution
+
+The installation of APEX is part of `playbooks/manage_db.yml`. +
+This allows the creation of custom Tablespaces, Profiles etc. for APEX, without the need to use a dedicated Playbook.
+
+
+=== ORDS Configuration
+
+IMPORTANT: The configuration of ORDS is limited to the following variables at the moment.
+
+.Mandatory variables in `oraords_db_pools`
+[options="header,footer"]
+|=======================
+|Value |Description
+| db_pool | Database Pool
+| pdb_name | PDB-Name of Target
+| service | Database Service Name
+| port | Listener Port
+| host | Database Hostname
+|=======================
+
+.Optional variables in `oraords_db_pools`
+[options="header,footer"]
+|=======================
+|Value |Description
+| feature_db_api | true / false (Default)
+| feature_rest_enabled_sql | true / false (Default)
+| feature_sdw | true / false (Default)
+|=======================
+
+----
+oraords_db_pools:
+  - db_pool: default
+    pdb_name: PDB1
+    admin_user: sys
+    service: pdb1
+    port: 1521
+    host: "{{ inventory_hostname }}"
+    feature_db_api: true
+    feature_rest_enabled_sql: true
+    feature_sdw: true
+----
+
+The passwords for Admin- and ORDS-User are defined in `oraords_db_pools_password`. +
+They are set in a dedicated variable to prevent `no_log=true` in loops over `oraords_db_pools`. +
+Referencing `dbpasswords` helps to reduce redundancy for passwords.
+
+----
+oraords_db_pools_password:
+  default:
+    admin_password: "{{ dbpasswords['DB1']['sys'] }}"
+    ords_password: "{{ dbpasswords['DB1']['PDB1']['ords_public_user'] }}"
+----
+
+==== Playbook execution
+
+The Playbook `playbooks/manage_ords.yml` is used to install ORDS.

example/beginner_patching/ansible/inventory/group_vars/all/db-homes.yml

@@ -63,6 +63,17 @@ oracle_sw_patches:
     patchid: 30839369
     version: 21.0.0.0
     description: Latest cluvfy
+    opatch_needed: false
+  - filename: p36695709_2410_Generic.zip
+    patchid: 36695709
+    version: 24.1
+    description: PSE BUNDLE FOR APEX 24.1
+    opatch_needed: false
+  - filename: p35895964_2320_Generic.zip
+    patchid: 35895964
+    version: 23.2
+    description: PSE BUNDLE FOR APEX 23.2
+    opatch_needed: false
   - filename: p36582781_190000_Linux-x86-64.zip
     patchid: 36582781
     version: 19.3.0.0

example/beginner_patching/ansible/inventory/host_vars/beginner-dbfs-patching-151-192-168-56-162.nip.io/databases.yml

@@ -72,7 +72,7 @@ oracle_databases:
       - {name: log_buffer, value: '64M', scope: spfile, state: present}
       # - {name: pga_aggregate_target, value: '1024M', scope: both, state: present, dbca: false}
       - {name: pga_aggregate_target, value: '1G', scope: both, state: present}
-      - {name: sga_target, value: '3096M', scope: spfile, state: present}
+      - {name: sga_target, value: '2048M', scope: spfile, state: present}
       - {name: recyclebin, value: 'off', scope: spfile, state: present}
       - {name: streams_pool_size, value: '152M', scope: spfile, state: present}
       # "_cursor_obsolete_threshold" for 12.2+
@@ -108,6 +108,11 @@ oracle_pdbs:
     cdb: *oracle_db_name
     pdb_name: PDB1
     state: present
+    apex_state: present
+    apex_version: 24.1
+    apex_patchid: 36695709
+    # apex_version: 23.2
+    # apex_patchid: 35895964
     profiles: "{{ oracle_default_profiles }}"
     statspack:
       purgedays: 14

example/beginner_patching/ansible/inventory/host_vars/beginner-dbfs-patching-151-192-168-56-162.nip.io/ords.yml

@@ -0,0 +1,20 @@
+---
+# Images are pulled from CDN at Oracle.
+# oraords_apex_image_path: /u01/app/oracle/product/apex_24.1/apex/images/
+# oraords_apex_image_context: /i
+
+oraords_db_pools:
+  - db_pool: default
+    pdb_name: PDB1
+    admin_user: sys
+    service: pdb1
+    port: 1521
+    host: "{{ inventory_hostname }}"
+    feature_db_api: true
+    feature_rest_enabled_sql: true
+    feature_sdw: true
+
+oraords_db_pools_password:
+  default:
+    admin_password: "{{ dbpasswords['DB1']['sys'] }}"
+    ords_password: "{{ dbpasswords['DB1']['PDB1']['ords_public_user'] }}"

example/beginner_patching/ansible/inventory/host_vars/beginner-dbfs-patching-151-192-168-56-162.nip.io/password.yml

@@ -1,7 +1,17 @@
 ---
-# todo: Password ist noch fehlerhaft...
-# dbpasswords:
-#   DB1:
-#     SYS: Oracle123
-#     PDB1:
-#       PDBROOT: pdb
+default_dbpass: Oracle_123
+
+dbpasswords:
+  DB1:
+    sys: Oracle_123
+    system: Oracle_123
+    dbsnmp: Oracle_456
+
+    PDB1:
+      pdbadmin: Oracle_456
+      ords_public_user: ords123
+      apex_public_router: ords123
+      apex_public_user: ords123
+      apex_rest_public_user: ords123
+
+oraapex_default_admin_password: Oracle_Apex_1

extensions/molecule/dbfs-ol9/converge.yml

@@ -37,3 +37,6 @@
 
 - name: Converge manage_db
   ansible.builtin.import_playbook: opitzconsulting.ansible_oracle.manage_db
+
+- name: Converge manage_ords
+  ansible.builtin.import_playbook: opitzconsulting.ansible_oracle.manage_ords