From ed121f286c88b1c0c964fde19a74442ee720d513 Mon Sep 17 00:00:00 2001 From: Thorsten Bruhns Date: Fri, 13 Sep 2024 20:06:28 +0000 Subject: [PATCH] ansible-oracle Documentation --- README.adoc | 32 ------ README.md | 6 +- changelogs/fragments/doc1.yml | 3 + doc/featurelist.adoc | 8 +- doc/guides/apex_ords.adoc | 205 ++++++++++++++++++++++++++++++++++ 5 files changed, 218 insertions(+), 36 deletions(-) delete mode 100644 README.adoc create mode 100644 changelogs/fragments/doc1.yml create mode 100644 doc/guides/apex_ords.adoc diff --git a/README.adoc b/README.adoc deleted file mode 100644 index a8aeccbdd..000000000 --- a/README.adoc +++ /dev/null @@ -1,32 +0,0 @@ -:toc: -:toc-placement!: -toc::[] -:sectnums: -:sectnumlevels: 4 - -== `ansible-oracle` -* Automated installation of - ** Oracle RAC databases - ** RAC One Node database and - ** single instance Oracle databases -* Start with one or more clean Linux machine(s), end up with a fully configured Oracle database system - -== Documentation - -Read link:doc/featurelist.adoc[here] for a detailed list of features of `ansible-oracle`. - -=== Getting started -* link:doc/vagrant.adoc[Vagrant Setup on Windows]: Preparation for beginner -* link:doc/guides/beginner.adoc[Beginner]: Guiding you through your first setup - -=== Next steps -* How to link:doc/development.adoc[develop in ansible-oracle] -* List of link:doc/roles.adoc[roles in ansible-oracle] -* Running link:doc/ansible.adoc[Ansible in Docker-Container] -* Running link:doc/[Read the full documentation] - - -## Pre-requisites -* Ansible Version >= 2.14. -* Oracle Linux (or any RHEL-based Linux System) >= 8 -* Oracle Database/Grid Infrastructure 21.3.0.0, 19.3.0.0 diff --git a/README.md b/README.md index 55b0bf075..42fe239fb 100644 --- a/README.md +++ b/README.md @@ -21,9 +21,9 @@ ### Next Steps -1. Read the full documentation -1. How to develop in ansible-oracle -1. List of roles in ansible-oracle +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 diff --git a/changelogs/fragments/doc1.yml b/changelogs/fragments/doc1.yml new file mode 100644 index 000000000..c6b30b440 --- /dev/null +++ b/changelogs/fragments/doc1.yml @@ -0,0 +1,3 @@ +--- +major_changes: + - "ansible-oracle Documentation fixes (oravirt#473)" diff --git a/doc/featurelist.adoc b/doc/featurelist.adoc index d167468e1..e54412dcf 100644 --- a/doc/featurelist.adoc +++ b/doc/featurelist.adoc @@ -35,7 +35,7 @@ Redhat Enterprise Linux |6 <> + 7 <> + 8 + -9 (experimental!) <> +9 |SuSE Linux Enterprise Server<> |15, 15.3 @@ -138,6 +138,10 @@ a|OneOff Patches<> |automatic datapatch execution<> |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^:: diff --git a/doc/guides/apex_ords.adoc b/doc/guides/apex_ords.adoc new file mode 100644 index 000000000..ce15c2356 --- /dev/null +++ b/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_` +|`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.