Skip to content

autoupgrade: minor Changes #637

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
Rendanic merged 1 commit into from
Oct 24, 2026
Merged

autoupgrade: minor Changes #637

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 7 additions & 0 deletions changelogs/fragments/autoupgrade-update.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
---
minor_changes:
- "autoupgrade: autoupgrade_run_local executes AutoUpgrade on the Ansible controller (default true) or on the target host (false) for all task files"
- "autoupgrade: install.yml checks the Python module pexpect on the host executing AutoUpgrade (pexpect is not installed by the role)"
- "autoupgrade: install.yml creates oracle_base on the target host - AutoUpgrade can be used before the installation of the Oracle software"
- "autoupgrade: autoupgrade_download_latest downloads the latest autoupgrade.jar on the Ansible controller, or on the target host when oracle_sw_copy is false"
- "autoupgrade: autoupgrade_download_gold_image_rename renames downloaded Gold Images to autoupgrade_download_gold_image_prefix + release (e.g. db_home_19.32.zip) and creates a symlink with the original filename"
62 changes: 47 additions & 15 deletions doc/guides/autoupgrade.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -27,7 +27,7 @@ The variables of the role are described in link:../../roles/autoupgrade/README.m
* Database server: e.g. the JDK from an `ORACLE_HOME` (`autoupgrade_java_home`)
* Ansible controller: `java` from `PATH` or `autoupgrade_local_java_home`
- Python module `pexpect` on the host executing AutoUpgrade for the keystore management
(used by `ansible.builtin.expect`)
(used by `ansible.builtin.expect`). It is checked by `install.yml`, but not installed by the role.
- My Oracle Support account (`mos_username`, `mos_password`) for downloading patches
- Downloads with AutoUpgrade are supported for the releases 19, 21, 23 and 26 (AutoUpgrade 26.6)

Expand Down Expand Up @@ -60,13 +60,14 @@ Each area of AutoUpgrade has its own task file, which must be called with `tasks
[options="header,footer"]
|=======================
|Playbook |Description
|`playbooks/autoupgrade_install.yml` | Install AutoUpgrade on the database servers. `hostgroup` is mandatory.
|`playbooks/autoupgrade_install.yml` | Install AutoUpgrade. `hostgroup` is mandatory. Use `autoupgrade_run_local: false` for the database servers.
|`playbooks/autoupgrade_download_patches.yml` | Download patches with AutoUpgrade.
|=======================

.Install AutoUpgrade on database servers
----
ansible-playbook -i inventory/ -e hostgroup=dbservers playbooks/autoupgrade_install.yml
ansible-playbook -i inventory/ -e hostgroup=dbservers -e autoupgrade_run_local=false \
playbooks/autoupgrade_install.yml
----

.Download patches and the latest autoupgrade.jar
Expand All @@ -77,21 +78,41 @@ ansible-playbook -i inventory/ -e hostgroup=dbservers -e autoupgrade_download_la

=== Execution on Ansible controller or database server

AutoUpgrade is always executed on the database server as `oracle_user` - with one exception:

The download of patches (`download_patches.yml`) including the keystore and the installation needed for the download
is executed on the Ansible controller by default (`autoupgrade_download_run_local: true`).
`autoupgrade_run_local` defines, where AutoUpgrade is executed.
The switch is valid for all task files.

.Execution of AutoUpgrade
[options="header,footer"]
|=======================
|Task file |`autoupgrade_download_run_local` |Executed on |Directory |Java
|`install.yml` (direct call) | ignored | database server as `oracle_user` | `autoupgrade_home` | `autoupgrade_java_home`
|`download_patches.yml` | `true` (default) | Ansible controller, `run_once`, no `become` | `autoupgrade_local_home` | `autoupgrade_local_java_home`
|`download_patches.yml` | `false` | database server as `oracle_user` | `autoupgrade_home` | `autoupgrade_java_home`
|`autoupgrade_run_local` |Executed on |Directory |Java
|`true` (default) | Ansible controller, `run_once`, no `become` | `autoupgrade_local_home` | `autoupgrade_local_java_home`
|`false` | target host as `oracle_user` | `autoupgrade_home` | `autoupgrade_java_home`
|=======================

IMPORTANT: The download on the Ansible controller is executed only once (`run_once`) with the variables
IMPORTANT: AutoUpgrade is executed on the Ansible controller by default. +
Set `autoupgrade_run_local: false` for the execution on the database servers, e.g. for the installation on the database servers.

.Install AutoUpgrade on the database servers and download patches on the Ansible controller
----
ansible-playbook -i inventory/ -e hostgroup=dbservers -e autoupgrade_run_local=false \
playbooks/autoupgrade_install.yml

ansible-playbook -i inventory/ -e hostgroup=dbservers playbooks/autoupgrade_download_patches.yml
----

The host executing AutoUpgrade needs:

- Java (see `autoupgrade_java_home` / `autoupgrade_local_java_home`)
- Python module `pexpect` for the Python interpreter used by Ansible (keystore console).
`install.yml` checks it at the beginning and fails with a clear message.
The role does not install `pexpect` - install it e.g. with the package `python3-pexpect` or with `pip`.
- With `autoupgrade_run_local: false`: `autoupgrade_download_dir` must be a directory on the target host,
writable for `oracle_user`. The default `oracle_sw_source_local` is a directory on the Ansible controller.
- With `autoupgrade_run_local: false`: `oracle_user` must exist (playbook `os`).
`oracle_base` and `oracle_base/cfgtoollogs` are created by `install.yml` with the same attributes as in `oraswdb_install`.
AutoUpgrade can be used before the installation of the Oracle software, e.g. for downloading the patches.

IMPORTANT: With `autoupgrade_run_local: true` the tasks are executed only once (`run_once`) with the variables
of the *first host* in the play. +
`oracle_sw_patches`, `db_homes_installed`, `db_homes_config`, `oracle_install_version_gi` and
`autoupgrade_download_patches` must be the same for all hosts in the play - e.g. defined in `group_vars/all`
Expand All @@ -113,8 +134,19 @@ On the Ansible controller `oracle_sw_copy` is ignored and the file is always tak
==== Download the latest version

`autoupgrade_download_latest: true` downloads the latest `autoupgrade.jar` from Oracle (`autoupgrade_jar_url`)
into the software repository on the Ansible controller before the installation.
The download is done once (`run_once`) and requires `is_sw_source_local: true`.
into the software repository before the installation.
The target depends on the location of the installation media:

.Target for the download of the latest version
[options="header,footer"]
|=======================
|Installation media |Download on |Target
|`oracle_sw_copy: true` or `autoupgrade_run_local: true` | Ansible controller, `run_once`, no `become`. Requires `is_sw_source_local: true`. | `autoupgrade_jar_filesource` or `oracle_sw_source_local`/`autoupgrade_jar`
|`oracle_sw_copy: false` | target host as `oracle_user` | `autoupgrade_jar_filesource` or `oracle_stage_remote`/`autoupgrade_jar`
|=======================

IMPORTANT: With `oracle_sw_copy: false` the target directory must exist on the target host and must be writable for `oracle_user`. +
On a shared NFS directory each host downloads the file.

==== Update an existing installation

Expand All @@ -123,7 +155,7 @@ An existing `autoupgrade.jar` is not replaced by default. +

.Update AutoUpgrade on all database servers with the latest version from Oracle
----
ansible-playbook -i inventory/ -e hostgroup=dbservers \
ansible-playbook -i inventory/ -e hostgroup=dbservers -e autoupgrade_run_local=false \
-e autoupgrade_download_latest=true -e autoupgrade_force_update=true \
playbooks/autoupgrade_install.yml
----
Expand Down
113 changes: 76 additions & 37 deletions roles/autoupgrade/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -18,10 +18,11 @@ Each area of AutoUpgrade has its own task file, which must be called with `tasks
- [autoupgrade_download_dir](#autoupgrade_download_dir)
- [autoupgrade_download_filename_regex](#autoupgrade_download_filename_regex)
- [autoupgrade_download_gold_image](#autoupgrade_download_gold_image)
- [autoupgrade_download_gold_image_prefix](#autoupgrade_download_gold_image_prefix)
- [autoupgrade_download_gold_image_rename](#autoupgrade_download_gold_image_rename)
- [autoupgrade_download_latest](#autoupgrade_download_latest)
- [autoupgrade_download_patches](#autoupgrade_download_patches)
- [autoupgrade_download_platform](#autoupgrade_download_platform)
- [autoupgrade_download_run_local](#autoupgrade_download_run_local)
- [autoupgrade_download_supported_releases](#autoupgrade_download_supported_releases)
- [autoupgrade_download_use_oracle_sw_patches](#autoupgrade_download_use_oracle_sw_patches)
- [autoupgrade_force_update](#autoupgrade_force_update)
Expand All @@ -40,6 +41,7 @@ Each area of AutoUpgrade has its own task file, which must be called with `tasks
- [autoupgrade_local_home](#autoupgrade_local_home)
- [autoupgrade_local_java_home](#autoupgrade_local_java_home)
- [autoupgrade_log_dir](#autoupgrade_log_dir)
- [autoupgrade_run_local](#autoupgrade_run_local)
- [Discovered Tags](#discovered-tags)
- [Dependencies](#dependencies)
- [License](#license)
Expand Down Expand Up @@ -96,14 +98,52 @@ autoupgrade_download_gold_image: ''
autoupgrade_download_gold_image: "NO"
```

### autoupgrade_download_gold_image_prefix

Prefix for the new filename of a Gold Image (`autoupgrade_download_gold_image_rename: true`).

#### Default value

```YAML
autoupgrade_download_gold_image_prefix: db_home_
```

### autoupgrade_download_gold_image_rename

Rename downloaded Gold Images after the download.

AutoUpgrade creates unique filenames with a timestamp, e.g. `db_goldimage_19_32_20261021112350.zip`.
The file is renamed to `autoupgrade_download_gold_image_prefix` + release + `.zip`:

| Gold Image (AutoUpgrade) | Renamed file |
| --- | --- |
| `db_goldimage_19_32_<timestamp>.zip` (19.32) | `db_home_19.32.zip` |
| `db_goldimage_23_26_3_<timestamp>.zip` (23.26.3) | `db_home_26.03.zip` |

A symlink with the original filename is created for the renamed file.
AutoUpgrade finds the file under the original name and skips a new download.
The symlinks can be removed for cleanup. They are not created again.

Release and filename are taken from `patches_info.json` in `autoupgrade_download_dir`.
An existing file with the new name is never replaced.

#### Default value

```YAML
autoupgrade_download_gold_image_rename: false
```

### autoupgrade_download_latest

Download the latest `autoupgrade.jar` from `autoupgrade_jar_url` into the software
repository on the Ansible controller before the installation.
repository before the installation.

Target is `autoupgrade_jar_filesource` or `oracle_sw_source_local`/`autoupgrade_jar`.
The download is done once (`run_once`) on `localhost` without `become`.
Requires `is_sw_source_local: true`.
The target depends on the location of the installation media:

| Installation media | Download to |
| --- | --- |
| `oracle_sw_copy: true` or `autoupgrade_run_local: true` | Ansible controller (`run_once`, no `become`): `autoupgrade_jar_filesource` or `oracle_sw_source_local`/`autoupgrade_jar`. Requires `is_sw_source_local: true`. |
| `oracle_sw_copy: false` | target host as `oracle_user`: `autoupgrade_jar_filesource` or `oracle_stage_remote`/`autoupgrade_jar`. The directory must exist and be writable for `oracle_user`. |

Existing installations are only replaced with `autoupgrade_force_update: true`.

Expand Down Expand Up @@ -155,35 +195,6 @@ Default platform for the download, when `platform` is not set in `autoupgrade_do
autoupgrade_download_platform: LINUX.X64
```

### autoupgrade_download_run_local

Execute the download of patches (`download_patches.yml`) on the Ansible controller.
This includes the keystore (`keystore.yml`) and the installation of AutoUpgrade
needed for the download.

`true`: Tasks are delegated to `localhost` with `run_once` and without `become`.
`autoupgrade_local_home` is used instead of `autoupgrade_home`.

`false`: The download is executed on the target host as `oracle_user`.

All other task files (e.g. `install.yml`) are always executed on the target host.

_Important_

With `true` the download is executed only once (`run_once`) with the variables
of the first host in the play (`oracle_sw_patches`, `db_homes_installed`, `db_homes_config`,
`oracle_install_version_gi`, `autoupgrade_download_patches`).
These variables must be the same for all hosts in the play - e.g. defined in `group_vars/all`
for the whole environment.
When they are defined per host, limit the playbook to one host (`--limit <host>`)
or execute it for each host.

#### Default value

```YAML
autoupgrade_download_run_local: true
```

### autoupgrade_download_supported_releases

Releases supported by AutoUpgrade for downloading patches.
Expand Down Expand Up @@ -214,7 +225,7 @@ AutoUpgrade does not accept Release Updates by patch number. The keyword is deri

The result is added to `autoupgrade_download_patches`.

See `autoupgrade_download_run_local` for multiple hosts in the play.
See `autoupgrade_run_local` for multiple hosts in the play.
Only entries from `oracle_sw_patches` are used, where `filename` matches
`autoupgrade_download_filename_regex` and the release from `version` is in
`autoupgrade_download_supported_releases`. Others (e.g. APEX, cvupack) are ignored with a warning.
Expand Down Expand Up @@ -393,7 +404,7 @@ autoupgrade_keystore_timeout: 300
### autoupgrade_local_home

Directory for `autoupgrade.jar` and the generated AutoUpgrade config files
on the Ansible controller (`autoupgrade_download_run_local: true`).
on the Ansible controller (`autoupgrade_run_local: true`).

#### Default value

Expand All @@ -403,7 +414,7 @@ autoupgrade_local_home: "{{ lookup('ansible.builtin.env', 'HOME') }}/autoupgrade

### autoupgrade_local_java_home

JAVA_HOME used for AutoUpgrade on the Ansible controller (`autoupgrade_download_run_local: true`).
JAVA_HOME used for AutoUpgrade on the Ansible controller (`autoupgrade_run_local: true`).
`java` from `PATH` is used, when `autoupgrade_local_java_home` is empty.

#### Default value
Expand All @@ -425,6 +436,34 @@ autoupgrade_log_dir: >-
}}
```

### autoupgrade_run_local

Execute AutoUpgrade on the Ansible controller instead of the target host.
The switch is valid for all task files (`install.yml`, `keystore.yml`, `download_patches.yml`).

`true` (default): Tasks are delegated to `localhost` with `run_once` and without `become`.
`autoupgrade_local_home` and `autoupgrade_local_java_home` are used.
This is useful for downloading patches into the software repository on the Ansible controller.

`false`: Tasks are executed on the target host as `oracle_user`,
e.g. for the installation of AutoUpgrade on database servers.

_Important_

With `true` the tasks are executed only once (`run_once`) with the variables
of the first host in the play (`oracle_sw_patches`, `db_homes_installed`, `db_homes_config`,
`oracle_install_version_gi`, `autoupgrade_download_patches`).
These variables must be the same for all hosts in the play - e.g. defined in `group_vars/all`
for the whole environment.
When they are defined per host, limit the playbook to one host (`--limit <host>`)
or execute it for each host.

#### Default value

```YAML
autoupgrade_run_local: true
```

## Discovered Tags

**_always_**
Expand Down
Loading
Loading