From d3f62b8453030290d59c78cbefc3ca480faf1189 Mon Sep 17 00:00:00 2001 From: Andrew Lacy Date: Sat, 25 Nov 2023 18:43:55 +0000 Subject: [PATCH 1/2] Documentation updates --- README.adoc | 44 ++- README.md | 31 +- changelogs/fragments/docs.yml | 3 + CHANGELOG.md => doc/CHANGELOG.md | 0 .../README-ansible.adoc | 6 +- doc/chocolatey.puml | 2 +- doc/development.adoc | 14 +- doc/{feauturelist.adoc => featurelist.adoc} | 16 +- doc/guides/advanced.adoc | 46 ++- doc/guides/beginner.adoc | 49 +++- doc/missing_documentation.md | 274 ++++++++++++++++++ doc/roles.adoc | 34 ++- doc/vagrant.adoc | 24 +- doc/vagrant_basics.md | 90 ++++++ 14 files changed, 532 insertions(+), 101 deletions(-) create mode 100644 changelogs/fragments/docs.yml rename CHANGELOG.md => doc/CHANGELOG.md (100%) rename README-ansible.adoc => doc/README-ansible.adoc (70%) rename doc/{feauturelist.adoc => featurelist.adoc} (90%) create mode 100644 doc/missing_documentation.md create mode 100644 doc/vagrant_basics.md diff --git a/README.adoc b/README.adoc index f8358a8ec..a9354f8ad 100644 --- a/README.adoc +++ b/README.adoc @@ -4,33 +4,29 @@ 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 -== Feauturelist and Supported options in `ansible-oracle` +== Documentation -* Installs Oracle RAC, RAC One Node and normal single instances. -* Start with one or more clean machine(s), end up with a fully -configured RAC Cluster. +Read link:doc/featurelist.adoc[here] for a detailed list of features of `ansible-oracle`. -Read link:doc/feauturelist.adoc[here] for a full list of all feautures 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 -== Getting started - -The documentation has been split in different parts: - -* link:doc/vagrant.adoc[Vagrant Setup on Windows]: - -=== Usage examples - -* Usage examples: -** link:doc/guides/beginner.adoc[Beginner] + -Start link:doc/guides/beginner.adoc[here] for 1st test of ansible-oracle. -//// -** advanced Users -** Experts + -Start here, when the setup for advanced Users works fine for you. - -* TODO: Running link:doc/ansible.adoc[Ansible in Docker-Container] -//// +=== 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.9. (Version 2.12 or newer of Ansible is recommended) +* Oracle Linux (or any RHEL-based Linux System) >= 7 +* Oracle Database/Grid Infrastructure 21.3.0.0, 19.3.0.0 diff --git a/README.md b/README.md index 72427d4ac..f4674910c 100644 --- a/README.md +++ b/README.md @@ -1,19 +1,38 @@ # ansible-oracle + _IMPORTANT_ *This an a beta release of `ansible-oracle`.* Use Version 3.x for production instead of this version. -Read documentation at for more details. -* Installs Oracle RAC, RAC One Node and normal single instances. -* Start with one or more clean machine(s), end up with a fully -configured RAC Cluster. +* 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 + +## Features +1. Full list of features of ansible-oracle +1. More details + + +## Getting Started +1. Vagrant setup on Windows +1. Beginner + +### Next Steps +1. Read the full documentation +1. How to develop in ansible-oracle +1. List of roles in ansible-oracle + ## Pre-requisites -* Ansible >= 2.14 +* Ansible Version >= 2.14 - 2.12 is recommended + Version 2.14 or newer of Ansible is recommended * Oracle Linux (or any RHEL-based Linux System) >= 7 * Oracle Database/Grid Infrastructure 21.3.0.0, 19.3.0.0 diff --git a/changelogs/fragments/docs.yml b/changelogs/fragments/docs.yml new file mode 100644 index 000000000..8ddf610ea --- /dev/null +++ b/changelogs/fragments/docs.yml @@ -0,0 +1,3 @@ +--- +minor_changes: + - "Documentation updates (oravirt#389)" diff --git a/CHANGELOG.md b/doc/CHANGELOG.md similarity index 100% rename from CHANGELOG.md rename to doc/CHANGELOG.md diff --git a/README-ansible.adoc b/doc/README-ansible.adoc similarity index 70% rename from README-ansible.adoc rename to doc/README-ansible.adoc index 4a3266823..70616c734 100644 --- a/README-ansible.adoc +++ b/doc/README-ansible.adoc @@ -2,12 +2,12 @@ :toc-placement!: toc::[] -IMPORTANT: This documentation is work in progress! +IMPORTANT: This documentation is a work in progress! -= Ansible as Docker Container += Ansible as a Docker Container The development and test of `ansible-oracle` is done in a Docker Container. -This allows a simple switch between versions and an easy implementation at a customer side, because you can use a reserved version of Ansible for `ansible-oracle`. +This allows a simple switch between ansible versions and an easy implementation at a customer site, because you can use your own chosen version of Ansible for `ansible-oracle`. Requirements: diff --git a/doc/chocolatey.puml b/doc/chocolatey.puml index e3f15e797..6c45d5903 100644 --- a/doc/chocolatey.puml +++ b/doc/chocolatey.puml @@ -6,7 +6,7 @@ System_Boundary(host, "Host System", "PC/Notebook") { System_Boundary(tools, "Tools") { Component(gitbash, "git+bash", "git+bash for Windows") Component(vagrant, "Vagrant", "Hashicorp Vagrant") - Component(virtualbox, "VirtualBox", "VirtualBox") + Component(virtualbox, "VirtualBox", "Oracle VirtualBox") Component_Ext(vscode, "VSCode", "Visual Studio Code") Component_Ext(conemu, "ConEmu", "ConEmu") } diff --git a/doc/development.adoc b/doc/development.adoc index 66349cbd1..3e840b4a3 100644 --- a/doc/development.adoc +++ b/doc/development.adoc @@ -1,6 +1,8 @@ :toc: :toc-placement!: +:toclevels: 4 toc::[] + :sectnums: :sectnumlevels: 4 @@ -18,7 +20,7 @@ You need an Ansible-Controller with an Editor or IDE of your own choice. === Create Fork on github and contribute to the project -link:https://docs.github.com/en/get-started/quickstart/contributing-to-projects[github] has a great documentation with details about creating a fork and branch to contribute to `ansible-oracle`. +link:https://docs.github.com/en/get-started/quickstart/contributing-to-projects[github] has some great documentation with details about creating a fork and branch to contribute to `ansible-oracle`. IMPORTANT: The `github-Actions` will automatically start, when the branchname starts with `pr` or in each Pull-Request. + Please use a branch with 'pr'--prefix, when `ansible-lint` should be checked for each commit. @@ -42,7 +44,7 @@ pre-commit run === Ansible Navigator -IMPORTANT: python3 should point to Python >=3.9, otherwise ansible-navigator and ansible-lint could not beused. + +IMPORTANT: python3 should point to Python >=3.9, otherwise `ansible-navigator` and `ansible-lint` could not be used. + The `activate` script is used to change the Python environment in current shell. .configure venv for ansible-oracle @@ -70,7 +72,7 @@ ansible-navigator 3.3.0 === Using ansible-doctor -IMPORTANT: `ansible-doctor` has har dmodule dpendencies with conflicts between `ansible-lint`. +IMPORTANT: `ansible-doctor` has module dpendencies with conflicts between `ansible-lint`. We have to use a dedicated venv for `ansible-doctor' .configure venv for ansible-oracle @@ -109,8 +111,6 @@ cd ansible-oracle === Start Ansible-Container -IMPORTANT: Replaced by `ansible-navigator` and `venv`. - === Start Playbook IMPORTANT: Don't forget to set the working branch in `requirements.yml`. + @@ -137,7 +137,7 @@ ansible-galaxy collection install --force -r requirements.yml && ansible-playboo === Important Information -The ansible-oracle project introduced `antsibull-changelog` for managing the `CHANGELOG.rst` based on fragments in `changelogs/gragments`. +The ansible-oracle project introduced `antsibull-changelog` for managing the `CHANGELOG.rst` based on fragments in `changelogs/fragments`. The ID should point to the PR and the filename describe the PR in short form. The fragments are part of the PR. @@ -168,7 +168,7 @@ Changelogs for Collections: https://github.com/ansible-community/antsibull-chang `antsibull-changelog release` reads `galaxy.yml` to get the release version automatically. The execution is aborted, when a release with the version is existing in `CHANGELOG.rst`. -NOTE: The whole release process should be donw with a dedicated Pull-Request. +NOTE: The whole release process should be done with a dedicated Pull-Request. ---- antsibull-changelog release diff --git a/doc/feauturelist.adoc b/doc/featurelist.adoc similarity index 90% rename from doc/feauturelist.adoc rename to doc/featurelist.adoc index 4deab96cc..d408068be 100644 --- a/doc/feauturelist.adoc +++ b/doc/featurelist.adoc @@ -1,11 +1,11 @@ -## Supported feautures in ansible-oracle +## Supported features in ansible-oracle WARNING: Please check the official Compatibilty List from Oracle for RDBMS and Restart/Grid-Infrastructure. + `ansible-oracle` only supports combinations from Oracle with exceptions from the following table. IMPORTANT: All Editions from Oracle are supported. -See documentation from Oracle for differences between Enterprise and Stadard Edtion (SE, SE One and SE2) +See documentation from Oracle for differences between Enterprise and Standard Edtion (SE, SE One and SE2) :supportedfrom112: 11.2.0.3 <> \ @@ -25,7 +25,7 @@ See documentation from Oracle for differences between Enterprise and Stadard Edt :supportedfrom19: 19c + \ 21c -.Feauturelist +.Featurelist [options="header" cols="1,2,2" valign="top"] |======================= |Group |Option |Version @@ -150,13 +150,13 @@ a|dynamic shell environment link:https://github.com/opitzconsulting/oracle-scrip Was supported by `ansible-oracle`. It is not tested anymore. [[table1footnote]]^2^:: Still in development and not fully tested at the moment. - Breaking changes in new commits are possivle. + - Please do not use it in production environments. + Breaking changes in new commits are possible. + + Please do not use this feature in production environments. [[table1footnote]]^3^:: Limited support. Not tested for Oracle Restart & Grid-Infrastructure [[table1footnote]]^4^:: - 2.9 is minimum version with limited support for Ansible Collections. + - Please use 2.10 as a minimum. + 2.9 is the absolute minimum version, with limited support for Ansible Collections. + + Please use 2.10 as a minimum version of ansible. [[table1footnote]]^5^:: in development and not implemented at the moment. [[table1footnote]]^6^:: @@ -170,6 +170,6 @@ a|dynamic shell environment link:https://github.com/opitzconsulting/oracle-scrip Ansible 2.9 has limited support for Collections. You should use 2.10 or newer. [[table1footnote]]^10^:: - Use the Golden-Image feauture as a work arround. + Use the Golden-Image feature as a workaround. [[table1footnote]]^11^:: Supported for Single-Instance, Oracle Restart and Oracle Grid-Infrastructure. diff --git a/doc/guides/advanced.adoc b/doc/guides/advanced.adoc index a20f9b3a7..784565ad5 100644 --- a/doc/guides/advanced.adoc +++ b/doc/guides/advanced.adoc @@ -1,10 +1,14 @@ -WARNING: *This guid is work in progress!* - :toc: :toc-placement!: :toclevels: 4 toc::[] +:sectnums: +:sectnumlevels: 4 + + +WARNING: *This guide is a work in progress!* + == Advanced Guide @@ -12,11 +16,12 @@ IMPORTANT: The setup of Vagrant, VirtualBox and SSH is not part of this document Please follow the link:../vagrant.adoc[documentation]. === Overview - +==== Architecture overview :puml: http://www.plantuml.com/plantuml/proxy?src=https://raw.githubusercontent.com/Rendanic/ansible-oracle/tbrdoc/doc image::{puml}/guides/advanced.puml[Architecturview] +==== Defaults .Used defaults in this guide [options="header,footer"] |======================= @@ -45,7 +50,7 @@ git clone https://github.com/oravirt/ansible-oracle.git IMPORTANT: It is highly recommended to use the following structure. + Do not change this until you really know what you are doing. -All installation medias are searched in `oracle_stage_remote` on the database server. +All installation media are searched in `oracle_stage_remote` on the database server. WARNING: It is assumend that `oracle_stage_remote` is set to `/sw` @@ -117,12 +122,23 @@ cd ~/git/ansible-oracle/ansible-oracle/example/beginner VAGRANT_EXPERIMENTAL=disks vagrant up ---- +===== What happens when I start vagrant? + +1. Using the vagrantfile, an Oracle Linux VM is installed (2x CPU, 4096MB RAM, 150GB HDD). IP = 192.168.56.161 +1. A mount point /vagrant is available in the Oracle Linux VM. This is a shared folder from your Windows machine. +1. Your ssh key is used to connect to the VM in a secure way +1. docker is installed in the Oracle Linux VM +1. docker-compose is installed in the Oracle Linux VM +1. The ansible-oracle repository is cloned to the Oracle Linux VM +1. A docker container "Ansible Container" is built with docker-compose. This runs in the Oracle Linux VM +1. No Oracle database is yet installed. See below + === Working inside the VM ==== Connect to VM -IMPORTANT: All furter steps are done inside the VM. + -The SSH-Setup from previous chapter must be completed before! +IMPORTANT: The next steps are done inside the VM. + +The SSH-Setup from the previous chapter must be completed before continuing! .Connect into VM with SSH from `git+bash` ---- @@ -131,8 +147,8 @@ ssh -A vagrant@192.168.56.161 ==== Note about Installation media -The installation media is mounted with vboxsf from Vagrant into the VM at `/vagrant`. + -You can check this. +The installation media is mounted with vboxsf from Vagrant into the Linux VM, mounted as `/vagrant`. + +Use the following command to check this... .check for Installation media ---- @@ -142,7 +158,8 @@ You can check this. ---- ==== Start Ansible-Container inside VM - +IMPORTANT: Check the prompt shown in this documentation, as to whether you should start the commands in the shell or inside the Ansible-Container. + +`ansible@ansible-oracle` is for working inside the container. .Start Ansible-Container ---- cd ~/git/ansible-oracle/docker @@ -161,7 +178,7 @@ ansible@ansible-oracle:/git/ansible-oracle/example/beginner/ansible$ ---- -IMPORTANT: The collection are installed once and stored on the docker volume. +IMPORTANT: The collection is installed once and stored on the docker volume. .Install Collections ---- @@ -206,7 +223,8 @@ The execution takes ~60 minutes. cd /git/ansible-oracle/example/beginner/ansible ansible-playbook -i inventory/ -e hostgroup=dbfs playbooks/single-instance-fs.yml ---- - +The Database creation is now complete. + +See the following chapter for details about how to work with the VM. === How to work with installed database ==== Login as vagrant @@ -233,7 +251,7 @@ execute ocenv to source Oracle Environment ==== Start ocenv -.Initialize ocenv +.Initialize ocenv to set the environment variables ---- [oracle@beginner-dbfs-151-192-168-56-161 ~]$ ocenv ---- @@ -285,8 +303,8 @@ PDBs [oracle@beginner-dbfs-151-192-168-56-161] [DB1] [~] ---- -==== Login -.SQLPlus login +==== Database Login +.Start SQLPlus ---- [oracle@beginner-dbfs-151-192-168-56-161] [DB1] [~] $ sql diff --git a/doc/guides/beginner.adoc b/doc/guides/beginner.adoc index d51642f2e..0c0bf9a55 100644 --- a/doc/guides/beginner.adoc +++ b/doc/guides/beginner.adoc @@ -13,11 +13,23 @@ Please follow the link:../vagrant.adoc[documentation]. === Overview +==== Architecture overview :puml: http://www.plantuml.com/plantuml/proxy?src=https://raw.githubusercontent.com/oravirt/ansible-oracle/master/doc image::{puml}/guides/beginner.puml[Architecturview] -.Used defaults in this guide + +==== What are we going to do? +With one command, the following will happen... + +- An Oracle Linux VM will be created. +- A docker container is setup in this Linux VM. +- Why do we need a docker container? Ansible runs in the docker container to configure the Oracle Linux VM and install the Oracle database. See link:../README-ansible.adoc[Details of Ansible as a Docker Container] for more information +- The Oracle database installation is started from the docker container. See details below. + + +==== Defaults +.Defaults used in this guide [options="header,footer"] |======================= |Value |Description @@ -88,12 +100,24 @@ cd ~/git/ansible-oracle/example/beginner/vagrant VAGRANT_EXPERIMENTAL=disks vagrant up ---- +===== What happens when I start vagrant? + +1. Using the vagrantfile, an Oracle Linux VM is installed (2x CPU, 4096MB RAM, 150GB HDD). IP = 192.168.56.161 +1. A mount point /vagrant is available in the Oracle Linux VM. This is a shared folder from your Windows machine. +1. Your ssh key is used to connect to the VM in a secure way +1. docker is installed in the Oracle Linux VM +1. docker-compose is installed in the Oracle Linux VM +1. The ansible-oracle repository is cloned to the Oracle Linux VM +1. A docker container "Ansible Container" is built with docker-compose. This runs in the Oracle Linux VM +1. No Oracle database is yet installed. See below + + === Working inside the VM ==== Connect to VM -IMPORTANT: All furter steps are done inside the VM. + -The SSH-Setup from previous chapter must be completed before! +IMPORTANT: The next steps are done inside the VM. + +The SSH-Setup from the previous chapter must be completed before continuing! .Connect into VM with SSH from `git+bash` ---- @@ -102,8 +126,8 @@ ssh -A vagrant@192.168.56.161 ==== Note about Installation media -The installation media is mounted with vboxsf from Vagrant into the VM at `/vagrant`. + -You can check this. +The installation media is mounted with vboxsf from Vagrant into the Linux VM, mounted as `/vagrant`. + +Use the following command to check this... .check for Installation media ---- @@ -114,7 +138,7 @@ You can check this. ==== Start Ansible-Container inside VM -IMPORTANT: Check the prompt while starting the commands in shell or inside the Ansible-Container. + +IMPORTANT: Check the prompt shown in this documentation, as to whether you should start the commands in the shell or inside the Ansible-Container. + `ansible@ansible-oracle` is for working inside the container. .Start Ansible-Container @@ -135,7 +159,7 @@ ansible@ansible-oracle:/git/ansible-oracle/example/beginner/ansible$ ---- -IMPORTANT: The collection are installed once and stored on the docker volume. +IMPORTANT: The collection is installed once and stored on the docker volume. .Install Collections ---- @@ -181,11 +205,11 @@ cd /git/ansible-oracle/example/beginner/ansible ansible-playbook -i inventory/ -e hostgroup=dbfs playbooks/single-instance-fs.yml ---- -The Database creation has been completed. + +The Database creation is now complete. + See the following chapter for details about how to work with the VM. -=== How to work with installed database +=== How to work with the installed database ==== Login as vagrant @@ -211,7 +235,7 @@ execute ocenv to source Oracle Environment ==== Start ocenv -.Initialize ocenv +.Initialize ocenv to set the environment variables ---- [oracle@beginner-dbfs-151-192-168-56-161 ~]$ ocenv ---- @@ -263,9 +287,8 @@ PDBs [oracle@beginner-dbfs-151-192-168-56-161] [DB1] [~] ---- -==== Start SQLPlus - -.SQLPlus login +==== Database Login +.Start SQLPlus ---- [oracle@beginner-dbfs-151-192-168-56-161] [DB1] [~] $ sql diff --git a/doc/missing_documentation.md b/doc/missing_documentation.md new file mode 100644 index 000000000..c5b4cf9ef --- /dev/null +++ b/doc/missing_documentation.md @@ -0,0 +1,274 @@ +# ansible-oracle missing documentation + +## concept guide +- why use a container for ansible-oracle? +- do I have to use a container? installed on each RDBMS machine, how should this work? +- why ansible and not some other IaC? +- ok, now I have used ansible-oracle and the database is installed, how do I run the DB and make changes, do I need ansible-oracle for that too? Can I use ansible-oracle for operations? How exactly do I do this. Document this. +- can I do patches with ansible-oracle? +- can I upgrade with ansible-oracle? +- what are best practices around + -- single install + -- install e.g. 500 Oracle DBs + -- install Single instance with GI + -- convert GI on SI to RAC + -- upgrading + -- operations with ansible-oracle +- explain concepts around ansible collection +- meaning of files and directories +- venv, differnt versions of python / ansible +- ansible controller +- why rendanic Linux, why not standard OL? (security concerns) + +## should I use ansible-oracle or ansible-oracle-inventory ? +- ansible-oracle is only meant for development, use the ansible-oracle-inventory to install oracle +- right now, I work in the ansible-oracle to +1. improve documentation +1. improve the examples +later I will probably move to using the ansible-oracle-inventory project + +## Install many oracle DBs +To install many Oracle DBs, we do not install a local ansible-controller, but use a central ansible controller. For example... +- awx opensource +- ansible tower +- redhat automation program + +## Understanding ansible inventory +- https://docs.ansible.com/ansible/latest/playbook_guide/playbooks_variables.html + +## why not use ansible-oracle? +1. Currently no support for +- Windows +- Sun Solaris +- HP-UX +- ARM +- AIX +- SLES12/15 +- OL5 / RHEL5 +- OL6 / RHEL6 + +ansible-oracle currently works for OL7/8, RHEL7/8 + +2. Some customers wish to understand exactly what is going on. Often in preparation of cust using the automated method themselves. + + + +## logging +- first beginner installation, runing from ansible-container to OL VM took 7 hours +- no timing in log on-screen +- where can I find the log files? + + +## beginner +- explain concepts/details around the following... + - hardening + - perfstat + - oracle home + - PDB or CDB? + - rman scripts + - what is ocenv? + - systemctl script + - licensing options, chopt + - Update orabasetab file to disable Read-Only Oracle home + - SQL Zauberkasten + - glogin.sql + - explain why the installation has so many extra steps and what they do + - PLAY RECAP - what does this mean? How ddo I understand if ansible-oracle was successful?***************************************************************************************************************************************************************** +beginner-dbfs-151-192-168-56-161.nip.io : ok=254 changed=119 unreachable=0 failed=0 skipped=154 rescued=0 ignored=1 +- how do I know how long the installation took in total? + +- how to connect with winscp to Oracle Linux 8? + 1. ssh key + 1. only vagrant user? + 1. which IP? 127.0.0.1 which port? + 1. also 192,168.56.xxx + - directory structure of new Oracle install + - adump or audit? + - rman_backup.sh why bin directory? --> scripts + - rest of rman config in /u01/app/oracle/rman/ ?? + - /u01/stage/19.3.0.0/ ?? + - /u01/stage/rsp/ --> /tmp + + - operations (Betrieb) of new Oracle, explain rman, perfstat, etc +- how to configure ansible-orcle with examples +- why does sqlus "/ as sysdba" npt work? How to set my environment variables? + +## developer documentation +- roles documentation is available +- modules? +- inventory? + +- my installation took a long time, 7 hours +- where are the log files +- how can I speed it up? + +- something went wrong, how can I debug it? +- I found a bug, how can I get it fixed? +- when is support for v23 coming? +- how can I get support for feature XXXX? + + +## FAQ +- how can I change the Oracle DB version to be installed +- how can I install an RU patch? + - see MOS 555.1 and 888.1 RU, MRP + 10 patches + - db_homes.yml + - apply_patches_db: false +- how can I change the oracle_home? + - db-homes.yml? + - ocenv + - main.yml oracle_base +- how can I change the IP of the beginner Oracle Linux VM (beginner-dbfs-151-192-168-56-161.nip.io) + + +## ideas +- orachk installation (AHF). and run at the end and produce HTML report +- update sql developer version +- install dbsat +- install db diff +- OL8 not OL7 as the default example +- why special randanic linux? why not std OL8? + + + +# step-by-step guide to install and use ansible-oracle on a VM, but no docker container +- how exactly to install, os packages, git commands +- what to change (home,version, patches, etc.) +- how to run the playbook +- how to debug, log files +- documentation rhel7/8 OL 7/8 SLES12/15 + +## Inventory +create a new directory under inventory (e.g. copy the existing "dbfs" directory and rename it) +- change host.yml to match your host to be installed +- in directory group_vars +1. choose configuration options in host.yml (disk layout, memory usage, etc.) +1. software_src.yml choose e.g. source directory, local or nfs, unzip (Y/N), etc. +1. dev_sec.yml choose hardening options +in directory "has", you can see other possibilities +1. database.yml, exact sizing of Tablepsaces, memory, etc. +1. asm.yml (setup ASM disks) + + + +# Operations with dev-sec enabled +## su - oracle +- su is allowed only for root. Simply use... +sudo su - oracle + +# Bugs in ansible-oracle +- path does not include Oracle binaries for oracle user (source ~/.profile_db19_si_se2 missing in .bash_profile) +- patch download does not work "Error 401--Unauthorized" + + +# Security +- dev-sec hardening, source, description +- SELINUX disabled for installation and permanently disabled + +# explain skipped / ignored, etc. +PLAY RECAP ****************************************************************************************************************************************************************** +beginner-dbfs-patching-151-192-168-56-162.nip.io : ok=171 changed=6 unreachable=0 failed=1 skipped=109 rescued=0 ignored=2 + +Playbook run took 0 days, 0 hours, 2 minutes, 21 seconds + + + + + +## how to add patches +D:\ala\ansible-oracle\example\beginner_patching\ansible\inventory\group_vars\all\db-homes.yml +in section oracle_sw_patches, add a list of all the patches that can be installed.... + - filename: p35320081_190000_Linux-x86-64.zip + patchid: 35320081 + version: 19.3.0.0 + description: 19.20.0 RDBMS RU patch + creates: 35320081/README.txt + + +now in the db_homes_config, add a new home + db1920_si_se2: &db1920_si_se2 + version: 19.3.0.0 + oracle_home: /u01/app/oracle/product/19/db1920-si-se2 + edition: SE2 + opatch_minversion: 12.2.0.1.37 + state: present + opatchauto: [] + opatch: + - patchid: 35320081 + # Database Release Update 19.20.0.0.230718 + patchversion: 19.20.0.0.230718 + stop_processes: true + state: present + + +## bugs found +1. download patches, never works +1. download patches, not same list as to be installed ?? +1. change patches, install home not changed +1. install EE or SE? +1. reboot test, oracle not started +1. su - oracle, ocenv does not set PATH or ORACLE_SID +1. +ansible@ansible-oracle:/git/ansible-oracle/example/beginner/ansible$ ansible-playbook -i inventory/ -e hostgroup=dbfs playbooks/single-instance-fs.yml +[DEPRECATION WARNING]: "include" is deprecated, use include_tasks/import_tasks instead. This feature will be removed in version 2.16. Deprecation warnings can be disabled +by setting deprecation_warnings=False in ansible.cfg. + +TASK [opitzconsulting.ansible_oracle.orahost : ansible.builtin.include] **************************************************************************************************** +[DEPRECATION WARNING]: "include" is deprecated, use include_tasks/import_tasks/import_playbook instead. This feature will be removed in version 2.16. Deprecation warnings +can be disabled by setting deprecation_warnings=False in ansible.cfg. +included: /ansible/galaxy/ansible_collections/opitzconsulting/ansible_oracle/roles/orahost/tasks/RedHat-7.yml for beginner-dbfs-151-192-168-56-161.nip.io + + +major can break change +minor +bugfix + + +# symantec versioning is used for ansible-oracle +see https://semver.org/lang/de/ +- major can break change +- minor, new features +- bugfix, bugfixes only + +# examples +- beginner_patching +- local_linux +1. vagrant - testUmgebung +1. customer linux, simple install + + + +## special cases +- partitions +- EE mit packs + + +## steps in examples +1. ansible-controller in custoemr environment? +if not, install locally on oracle DB server +options +1. script for RHEL7/RHEL8/SLES12/SLES15 (und bald RHEL9) +1. docker container or podman? contains ansible-controller, +https://github.com/ansible/ansible-runner +if existing ansible-controller, it will be complicated... + + +### problems ansible-container +1. docker or podman? + +### problems script +1. rhel7, old version ansible, old version python +1. SLES generally, default versions of ansible are old, python? +https://endoflife.date/sles + +both solutions? +script avoids docker/podman +docker/podman allows older Linux + + +1. partitions +1. special wishes? + +## usage goal of ansible-oracle +ansible-oracle only for installation +with Betrieb, throw away ansible-oracle diff --git a/doc/roles.adoc b/doc/roles.adoc index a3296f74e..d0ef7066a 100644 --- a/doc/roles.adoc +++ b/doc/roles.adoc @@ -1,33 +1,38 @@ :toc: :toc-placement!: +:toclevels: 4 toc::[] +:sectnums: +:sectnumlevels: 4 + == Roles === common -This will configure stuff common to all machines +These roles are used to configure settings common to all machines * Install some generic packages * Configure ntp === orahost -This will configure the host specific Oracle stuff: +Configures the host-specific Oracle settings: * Add a user & group * Create directory structures * Handle filesystem storage (partition devices, creates vg/lv and a -filesystem (ext4, xfs, btrfs) etc). If you want to create your database +filesystem (ext4, xfs, btrfs) etc). + +If you want to create your database on a filesystem (instead of ASM) this is where you define the layout. -* Install required packages +* Install required OS packages * Change kernel paramemeters * Set up pam.d/limits config * Configures Hugepages (as a percentage of total RAM) * Disables transparent hugepages * Disables NUMA (if needed) * Configures the interconnect network (if needed) -* Configures Oracle ASMLib +* Configures Oracle ASMLib (if needed) === orahost-ssh @@ -38,14 +43,14 @@ Configures passwordless ssh between clusternodes if setting up RAC === orahost-storage -This role configures storage that shoud be used by ASM. +This role configures storage to be used by ASM. * Partitions devices (using parted) -* Create ASMlib labels or sets up udev-rules for device name persistence +* Create ASMlib labels or sets up udev-rules for device-name persistence === oraswgi-install -This role will install and configure Oracle Grid Infrastructure (RAC/SI) +This role installs and configures Oracle Grid Infrastructure (RAC/SI) * Adds a .profile_grid to the oracle user * Sets up directory structures @@ -55,7 +60,7 @@ location (e.g nfs share) === oraasm-manage-diskgroups -This role will statefully manage the lifecycle of an ASM diskgroup +This role statefully manages the lifecycle of an ASM diskgroup * Uses the *oracle_asmdg* module * Create/delete diskgroup. @@ -64,7 +69,7 @@ This role will statefully manage the lifecycle of an ASM diskgroup === oraswdb-install -This role will install the oracle database server(s). It is possible to +This role installs the oracle database server(s). It is possible to run more than 1 database from each home. It performs both Single Instance/RAC installations. @@ -96,14 +101,16 @@ Statefully manage patches in a DB environment === cxoracle -Installs cx_Oracle in preparation for using +* Installs cx_Oracle in preparation for using https://github.com/oravirt/ansible-oracle-modules[ansible-oracle-modules] +See https://oracle.github.io/python-cx_Oracle/ === orahost-cron -Configures cron schedules if needed +* Configures cron schedules if needed === orahost-logrotate +Logs grow. Log rotation solves the problem of always-growing logs. === oradb-manage-<*> @@ -118,6 +125,3 @@ https://github.com/oravirt/ansible-oracle-modules[ansible-oracle-modules] * *oradb-manage-grants* * *oradb-manage-redo* * *oradb-manage-services* -:toc: -:toc-placement!: -toc::[] diff --git a/doc/vagrant.adoc b/doc/vagrant.adoc index c9477a519..79f69d6cc 100644 --- a/doc/vagrant.adoc +++ b/doc/vagrant.adoc @@ -1,5 +1,6 @@ :toc: :toc-placement!: +:toclevels: 4 toc::[] :sectnums: @@ -7,8 +8,7 @@ toc::[] == Overview -IMPORTANT: This documentation is a short description to install all needed tools for ansible-oracle on a Windows based hostsystem. + -Please read further notes for more informations. +IMPORTANT: This documentation describes the installation of the required tools for ansible-oracle on a Windows based hostsystem. :puml: http://www.plantuml.com/plantuml/proxy?src=https://raw.githubusercontent.com/oravirt/ansible-oracle/master/doc @@ -23,18 +23,18 @@ The free space is needed in your home directory in Windows. ** Admin priviledges on Host machine ** Hyper-V disabled ** no WSL/WSL2 for installation + -You could try it by your own, but the documentation expect that Hyper-V is completly disabled and no WSL/WSL2 is used. +While you may try it, the documentation states that Hyper-V should be completely disabled and that no WSL/WSL2 is used. -WARNING: There are a lot issues wehn Hyper-V is active on host machine. + -Please switch Hyper-V completly off, before starting the boxes with Vagrant. + -Really working solutions with Vagrant + VirtualBox and Hyper-V are welcome. +WARNING: There are many issues when Hyper-V is active on the host machine. + +Please switch Hyper-V off completely, before starting the boxes with Vagrant. + +If you do find a really good working solution with Vagrant + VirtualBox and Hyper-V, feedback is welcome. == Installation === Disable Hyper-V in Windows WARNING: There are numerous problems with Vagrant & VirtualBox when Hyper-V is enabled. + -It could work, but it is recommended to disable it for `ansible-oracle`. +It is therefore recommended to disable it for `ansible-oracle`. IMPORTANT: All commands require a cmd.exe with admin rights. @@ -44,7 +44,7 @@ bcdedit ---- The output should contain a line with `hypervisorlaunchtype`. + -If the line is not shown or `Off`, Hyper-V is completly disabled. +If the line is not shown or `Off`, Hyper-V is completely disabled. .Output [quote,output from bcdedit] @@ -73,7 +73,7 @@ shutdown -r -t 0 === Chocolatey IMPORTANT: The installation of Chocolatey is not mandatory for `ansible-oracle`. + -All tools could be installed manually. Make sure, that all are executable from `git+bash`. + +All tools could be installed manually. Please ensure, that they are all executable from `git+bash`. + *It is highly recommended to use Chocolatey with `ansible-oracle`.* IMPORTANT: See the link:https://chocolatey.org/install[Homepage of chocolatey] for more details. @@ -95,7 +95,7 @@ choco install git vagrant virtualbox IMPORTANT: This step is optional. This is a really good alternative terminal to `cmd.exe` for windows. + -It is not recommended for `ansible-oracle` but you should give it a try and enfoy it - especially when VSCode is not used. +It is not recommended for `ansible-oracle` but you should give it a try and enjoy it - especially when VSCode is not used. link:https://conemu.github.io[Homepage of ConEmu] @@ -210,3 +210,7 @@ This is an experimental plugin which is needed to resize the 1. disk of a vagran ---- vagrant plugin install vagrant-disksize ---- + + +== See also +* link:vagrant_basics.md[Basic command and setup of Vagrant]: Preparation for beginner diff --git a/doc/vagrant_basics.md b/doc/vagrant_basics.md new file mode 100644 index 000000000..dfb8a47be --- /dev/null +++ b/doc/vagrant_basics.md @@ -0,0 +1,90 @@ +# What is vagrant? +Vagrant is a tool that makes it EASIER and FASTER to setup virtual machines. Vagrant Boxes are pre-built base images (e.g. Oracle Linux) that can be imported into Vagrant as a starting point. For our use-case, we will use Vagrant together with Virtualbox and Oracle Linux + + +## Installation +1. Download and install Vagrant +1. Download and install Oracle Virtualbox + +## Let's start +Using Tim Halls's guide, let's play +https://oracle-base.com/articles/vm/vagrant-a-beginners-guide + +1. hmm, cannot download that first OL box, let's see the oracle doc https://yum.oracle.com/boxes/ +1. Note also that the default provider for vagrant has changed to libvirt (was virtualbox), so we will need to add "--provider virtualbox" to our vagrant add commands + + +## Download Vagrant boxes +- Instead of downloading a large DVD image, we can download a small vagrant box. +- We can manually download a new box using the vagrant box add command. +- We only need to do this once for each vagrant box (e.g. one time for Oracle Linux 7 and one time for Oracle Linux 8). +- This download process would also happen automatically if required, when you reference a new box in a Vagrantfile + +In a DOS command prompt... +```cmd +vagrant box add --provider virtualbox https://oracle.github.io/vagrant-projects/boxes/oraclelinux/7.json +vagrant box add --provider virtualbox https://oracle.github.io/vagrant-projects/boxes/oraclelinux/8.json +``` + +## Some vagrant addons +1. allows us to resize disks (optional) + +In a DOS command prompt... +```cmd +vagrant plugin install vagrant-disksize +``` +1. ensure the virtualbox guest additions is updated, required to ensure that the guest additions are automatically updated for all new vagrant boxes + +In a DOS command prompt... +```cmd +vagrant plugin install vagrant-vbguest +``` + +1. Automatically update the /etc/hosts + +In a DOS command prompt... +```cmd +vagrant plugin install vagrant-hostsupdater +``` +## Create the initial vagrantfile +To create the virtual machine, we first of all create a new directory, change to it and create the initial "vagrantfile" + +In a DOS command prompt... +```cmd +mkdir D:\vagrant\vol7db19 +cd /D D:\vagrant\vol7db19 +vagrant init +``` + +## Start the VM +edit the vagrantfile (see Tim Hall's website above) and when ready with our configuration, we can install, create and start the VM with the following command... + +In a DOS command prompt... +```cmd +vagrant up +``` + + +## Changing the vagrantfile +if you change the vagrantfile, destroy and recreate your virtual machine + +In a DOS command prompt... +```cmd +vagrant destroy -f +vagrant up +``` + +## accessing the VM +1. use the command "vagrant ssh" to access the VM per shh in your DOS command prompt +1. or connect with ssh to 127.0.0.1, port 2222 with your favourite tool + +## Removing Vagrant boxes +- We can remove any old boxes we are no longer using, with the vagrant box remove command. +- These boxes will be automatically downloaded again if required. +- It is best not to remove them, if still used regularly, as it takes a few minutes to download them + +In a DOS command prompt... +```cmd +vagrant box remove oraclelinux/7 +vagrant box remove oraclelinux/8 +``` From 0f9499d5338990e5e240a34030def9a0b870d10e Mon Sep 17 00:00:00 2001 From: Thorsten Bruhns Date: Sat, 25 Nov 2023 19:21:39 +0000 Subject: [PATCH 2/2] updated featurelist.adoc --- doc/featurelist.adoc | 23 +++++++++-------------- 1 file changed, 9 insertions(+), 14 deletions(-) diff --git a/doc/featurelist.adoc b/doc/featurelist.adoc index d408068be..e6abbe9f2 100644 --- a/doc/featurelist.adoc +++ b/doc/featurelist.adoc @@ -35,6 +35,7 @@ Redhat Enterprise Linux |6 <> + 7 + 8 + +9 (experimental!) <> |SuSE Linux Enterprise Server<> |15, 15.3 @@ -50,9 +51,8 @@ Redhat Enterprise Linux .5+|Software |Ansible -|2.9 <> + -2.10 + -2.12 (used for all tests) +|2.14 or newer <> + + |Oracle RDBMS |{supportedfrom112} @@ -63,12 +63,11 @@ Redhat Enterprise Linux |{supportedfrom12} |cxOracle for Python -|Python 2, 3 +|Python 3 .3+|ASM |ASM Filter Driver (ASMFD) -|19c (experimental! <>) + -21c (experimental! <>) +|{supportedfrom19} |ASMlib |{supportedfrom12} @@ -128,15 +127,16 @@ e|Database Services <> |Timezone Upgrades |{supportedfrom12} -.3+|Database Patching +.4+|Database Patching |Release Updates<> -.3+|{supportedfrom12} +.4+|{supportedfrom12} a|OneOff Patches<> - Install - Remove with unique patch id option |automatic datapatch execution<> +|Patch Download from Oracle |Environment script a|dynamic shell environment link:https://github.com/opitzconsulting/oracle-scripts[`ocenv`] for Oracle @@ -154,9 +154,6 @@ 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^:: - 2.9 is the absolute minimum version, with limited support for Ansible Collections. + - Please use 2.10 as a minimum version of ansible. [[table1footnote]]^5^:: in development and not implemented at the moment. [[table1footnote]]^6^:: @@ -166,9 +163,7 @@ a|dynamic shell environment link:https://github.com/opitzconsulting/oracle-scrip [[table1footnote]]^8^:: only create/drop PDB [[table1footnote]]^9^:: - `ansible-oracle` is based on a Collection. + - Ansible 2.9 has limited support for Collections. - You should use 2.10 or newer. + Ansible 2.14 or newer is mandatory since `ansible-oracle` Version 4.2. [[table1footnote]]^10^:: Use the Golden-Image feature as a workaround. [[table1footnote]]^11^::