To upgrade a database to version 16:

1. For each Oracle Linux Automation Manager 2.2 nodes, sign in to a terminal.
2. Stop Oracle Linux Automation Manager.

   sudo systemctl stop ol-automation-manager

3. Log in to the local or remote user account that hosts the database.

   sudo su - postgres

4. Export the database using the following command that creates a script file containing all the necessary SQL commands and input data to restore the databases. For example, this command creates the olam.dump file in the chosen backup directory.

   pg_dumpall > /var/tmp/olam.dump

5. Exit the user account that hosts the database.

   exit

6. Stop the database server.

   sudo systemctl stop postgresql

7. Remove ( and optionally backup ) existing database data directory. For example, the following command removes and creates a backup file in the home directory.

   sudo mv /var/lib/pgsql/data/ ~/data.old

8. Remove the current version of the database.

   sudo dnf remove postgresql

9. Enable the postgresql 16 module stream.

   sudo dnf module reset postgresql
   sudo dnf module enable postgresql:16

   Note:

   For more information about the Postgresql 16 life cycle, see the appendix discussing the application life cycle for stream modules in Oracle Linux: Managing Software on Oracle Linux.
10. Install the database.

    sudo dnf install postgresql-server

11. Initialize the database:

    sudo postgresql-setup --initdb

12. In the /var/lib/pgsql/data/postgresql.conf file, switch the password storage mechanism from md5 to scram-sha-256. For example, the following command makes the switch for you:

    sudo sed -i "s/#password_encryption.*/password_encryption = scram-sha-256/"  /var/lib/pgsql/data/postgresql.conf

13. Start the database and import the /var/tmp/olam.dump file.

    sudo systemctl start postgresql
    sudo su - postgres
    psql -d postgres -f /var/tmp/olam.dump
    exit

14. Reapply the password to the database user account:

    sudo -u postgres psql
    \password awx

15. Enter and confirm the password for the awx user.

    Enter new password for user "awx": 
    Enter it again: 
    exit

16. Run the following command to see if the database is available:

    sudo su - postgres -c "psql -l |grep awx"

    Output similar to the following is displayed:

    awx | awx | UTF8 | libc | en_US.UTF-8 | en_US.UTF-8 | | |

17. As the root user, in the /var/lib/pgsql/data/pg_hba.conf file add the following line:

    host  all  all 0.0.0.0/0 scram-sha-256

18. As the root user, in the /var/lib/pgsql/data/postgresql.conf file in the # CONNECTIONS AND AUTHENTICATION section, a line with the text listen_addresses = followed by the IP address or host name of the database in single quotes. For example:

    listen_addresses = '<IP address or host name>'
    
    #listen_addresses = 'localhost'         # what IP address(es) to listen on;
                                            # comma-separated list of addresses;
                                            # defaults to 'localhost'; use '*' for all
                                            # (change requires restart)
    #port = 5432                            # (change requires restart)

    In the previous example, <IP address or hostname> is the IP address or host name of the database.

19. If you have a remote database, check that the 5432/tcp port is open on the host running the database. For example, the following commands shows that the ports parameter has the correct port open:

    sudo firewall-cmd --list-all

    public (active)
    target: default
    icmp-block-inversion: no
    interfaces: enp1s0
    sources:
    services: cockpit dhcpv6-client ssh
    ports: 5432/tcp
    protocols:
    forward: no
    masquerade: no
    forward-ports:
    source-ports:
    icmp-blocks:
    rich rules:

20. If the remote database host isn't open, run the following command:

    sudo firewall-cmd --add-port=5432/tcp --permanent
    sudo firewall-cmd --reload

21. Calculate and update the memory requirements parameters using the following:

    max_connections = 1024
    shared_buffers = total_mem_mb*0.3
    work_mem = total_mem_mb*0.03
    maintenance_work_mem = total_mem_mb*0.04

    In the previous example, total_mem_mb is the total memory size in megabytes of the system hosting the database server. For example, if the total available memory on the system were 18 000 MB, then this worksheet would include the following:

    max_connections = 1024
    shared_buffers = 18000*0.3
    work_mem = 18000*0.03
    maintenance_work_mem = 18000*0.04

    The final numbers to add are as follows:

    max_connections = 1024
    shared_buffers = 5400MB
    work_mem = 540MB
    maintenance_work_mem = 720MB

22. Add the calculated values to the /var/lib/pgsql/data/postgresql.conf file.
23. Start the database server.

    sudo systemctl restart postgresql

24. Restart all Oracle Linux Automation Manager 2.2 servers.

    sudo systemctl start ol-automation-manager

25. Verify that Oracle Linux Automation Manager functionality continues as before the database upgrade. See Viewing the Service Mesh for various ways to perform these checks.

To migrate a single host instance deployment of Oracle Linux Automation Manager (hybrid node) to a clustered deployment (control, execution, and hop node clusters), do the following:

1. In a terminal on the hybrid node, stop Oracle Linux Automation Manager.

   sudo systemctl stop ol-automation-manager

2. Create a database dump file.

   sudo su - postgres
   pg_dumpall > /var/tmp/olam.dump

3. Complete the procedures for setting up a remote database in Setting Up a Local or Remote Database with the following exceptions:
   1. Before starting the procedure, copy over the dump file to the remote database. For example, using scp.
   2. After starting and checking the status of the database in step 7 and 8, import the dump file:

      sudo su - postgres
      psql -d postgres -f /dirwithbackup/olam.dump
      exit

   3. Skip steps 9 through 11 for creating the database user account and creating the database because these are already part of the dump file.
   4. Continue the procedure at step 12 until you restart the database.
4. On the remote database, reapply the password to the database user account:

   sudo -u postgres psql
   \password awx

5. Enter and confirm the password for the awx user.

   Enter new password for user "awx": 
   Enter it again: 
   exit

6. If the single instance hybrid node had a local database, do the following for a remote database configuration:
   1. Return to the Oracle Linux Automation Manager server, and create a custom settings file. For example:

      sudo touch /etc/tower/conf.d/olam.py

   2. Add the following DATABASES fields to the custom settings file:

      DATABASES = {
          'default': {
              'ATOMIC_REQUESTS': True,
              'ENGINE': 'awx.main.db.profiled_pg',
              'NAME': 'awx',
              'USER': 'awx',
              'PASSWORD': 'password',
              'HOST': 'database hostname or ip address',
              'PORT': '5432',
          }
      }

      In the previous example, database hostname or ip address is the hostname or IP address of the remote database. If hostname is used, the host must be resolvable. password is the password for your remote database, if you have configured one.

7. Set the ownership and file permissions for the custom settings file:

   sudo chown awx:awx /etc/tower/conf.d/filename.py
   sudo chmod 0640 /etc/tower/conf.d/filename.py

   In the previous example, filename is the name of the custom settings file. For example,

   sudo chown awx:awx /etc/tower/conf.d/olam.py
   sudo chmod 0640 /etc/tower/conf.d/olam.py

8. Stop the local database.

   sudo systemctl stop postgresql

9. Open the ports used for the Service Mesh.

   sudo firewall-cmd --add-port=27199/tcp --permanent
   sudo firewall-cmd --reload

10. Start Oracle Linux Automation Manager.

    sudo systemctl start ol-automation-manager

11. Backup and remove the existing database data directory. For example, the following command creates a backup file in the home directory and then removes the database:

    sudo mv /var/lib/pgsql/data/ ~/data.old
    sudo dnf remove postgresql 

12. Run the following command:

    sudo su -l awx -s /bin/bash

13. Run the following commands.

    awx-manage deprovision_instance --hostname=<hostname or IP address>
    awx-manage unregister_queue --queuename default
    awx-manage unregister_queue --queuename tower 
    awx-manage provision_instance --hostname=<hostname or IP address> --node_type=control
    awx-manage register_queue --queuename=controlplane --hostnames=<hostname or IP address>
    awx-manage add_receptor_address --instance=<hostname or ip address> --address=<hostname or ip address> --port=<listener_port> --canonical
    exit

    In the previous example, hostname or IP address is the hostname or IP address of the system running Oracle Linux Automation Manager. The host name or IP address must match the host name or IP addressed used when you configured the /etc/receptor/receptor.conf file node ID (see Configuring and Starting the Control Plane Service Mesh). If hostname is used, the host must be resolvable. You only need to unregister tower if it exists and is no longer used. listener_port is the port number of the node, for example, 27199.

14. In the custom settings file (for example, /etc/tower/conf.d/olam.py), append the DEFAULT_EXECUTION_QUEUE_NAME and DEFAULT_CONTROL_PLANE_QUEUE_NAME fields:

    DEFAULT_EXECUTION_QUEUE_NAME = 'execution'
    DEFAULT_CONTROL_PLANE_QUEUE_NAME = 'controlplane'

15. If you have playbooks designed to run longer than the default reaper timeout of 60 seconds, add the REAPER_TIMEOUT_SEC parameter to the custom settings file to increase the timeout. For example,

    REAPER_TIMEOUT_SEC=<longest_playbook_time>

    In the previous example, <longest_playbook_time> is number of seconds that exceeds the duration of the longest playbook runtime.

16. Restart Oracle Linux Automation Manager.

    sudo systemctl restart  ol-automation-manager.service

17. The original upgraded node is now converted into a control node. You must now add one more execution node for the upgraded cluster to be fully functional. For all other members of the cluster, follow the procedures described in Preparing the Database and Hosts, except for setting up a remote database, because this is already completed. Then, follow the procedures for installing and configuring all other hosts as part of the cluster, as described in Installing Oracle Linux Automation Manager in a Clustered Deployment.

Test any Oracle Linux Automation Engine release 2.2 playbooks to verify whether they function with Oracle Linux Automation Manager release 2.3. You might need to update playbooks because the upstream projects have made changes such as, the number of modules, some modules have become collections, and some modules have been merged into other modules or collections.

Verify that the playbooks are using the correct versions of python as described in Oracle Linux Automation Manager 2.3: Release Notes. For custom execution environments, review the overview section in Oracle Linux Automation Manager 2.3: Private Automation Hub User's Guide.