Preconfigure the Upgrade Environment

When the ISO files have been downloaded from My Oracle Support, and made available to the appliance over HTTP, a series of preconfiguration tasks must be performed. Although these operations make no changes to the system, they ensure that the environment meets all requirements for a correct upgrade workflow setup in the next phase of upgrade preparation.

During preconfiguration, the new appliance software ISOs are downloaded to the appliance internal storage. The primary ISO is mounted so the pca-prerequisite script can be installed and run. When all script operations are done, the ISO is unmounted again.

Caution:

Until the appliance upgrade is fully completed, ensure that the latest ISOs remain available in the location you specify.

Caution:

The Upgrader allows up to 10 hours to download the ISO images before it times out. This corresponds with 50GB of data downloaded over a connection with at least 20Mbps of bandwidth. Ensure that the download connection meets this minimum requirement. For optimal performance, a higher bandwidth is recommended.

Operations performed by the pca-prerequisite script include:

validating current and new software versions
installing the latest preUpgrade functionality
copying the latest Upgrader code to the appliance
writing environment parameters to a yaml file for use in the next preparation phase
generating a new upgrade history file

This entire preconfiguration process is launched by an appliance administrator with a single command.

Unprovisioned Compute Nodes

If the Private Cloud Appliance contains unprovisioned compute nodes, they can cause errors during upgrade or patching, and might experience provisioning issues later. Therefore, when a record exists in the node database, the compute node must be provisioned and added to a fault domain, otherwise the upgrade or patching process cannot proceed.

If you need to upgrade or patch the appliance software on a system with compute nodes that cannot be provisioned, these database records must be removed. Contact Oracle for assistance.

For more information about provisioning, refer to "Performing Compute Node Operations" in the chapter Hardware Administration of the Oracle Private Cloud Appliance Administrator Guide.

Prerequisite Version

The latest Upgrader code automatically enforces prerequisite software versions on your Private Cloud Appliance. In the early stages of upgrade or patch preparation, the Upgrader service validates the currently installed appliance software version against the new target version. The preparation process (upgradePreConfig) documented in this section will only proceed if validation is successful.

If the appliance is not running at least the minimum required version, the Upgrader exits the process and rolls back the environment to its previous state. View the details of the failed upgrade job:

PCA-ADMIN> getupgradejob upgradeJobId=1700153626051-prepare-40046
Data:
  Log File = /nfs/shared_storage/pca_upgrader/log/pca-upgrader_prepare_environment_2023_11_16-16.53.46.log
  Arguments = [...]
  Status = Failed
[...]
  Tasks 23 - Name = Check Prerequisite Build Version
  Tasks 23 - Description = Check current build version not lower than prerequisite version
  Tasks 24 - Name = Check Prerequisite Build Version
  Tasks 24 - Message = (("Caught exception while checking prerequisite build number 
  Exception: Command: ['/usr/bin/python3', '/var/lib/pca-upgrader/prerequisite_build_validator.py', 
  'rack=PCA', 'upgrade=ISO'] failed (1): stderr: b'' stdout: b'PCA version is lower than prerequisite build, 
  must upgrade to prerequisite build 3.0.2-b892153 to proceed further upgrade\\n'",), {})
  Tasks 24 - Status = Failed

You must first install the prerequisite version, which is indicated by the error message in the upgrade job output.

Using the Service Web UI

In the navigation menu, go to the Maintenance section and click Upgrade Plan. This provides an overview of current and target component versions.
Click Upgrade & Patching to display the Upgrade Jobs page.
In the top-right corner of the Upgrade Jobs page, click Create Upgrade or Patch.

The Create Request window appears. Choose Upgrade as the Request Type.
Select the appropriate upgrade request type: Upgrade PreConfig.
Fill out the upgrade request parameters:
- Option: Enter ISO.
- Location: Enter the path to the location where the ISO image is stored. If this version consists of multiple ISOs, point to the primary pca-3.0.2-<build_no>.iso file.
- ISO Checksum: Enter the checksum required to verify the integrity of the ISO image. The checksum is provided alongside the ISO image in a file named <iso_image>.sha256sum.
- Log Level: Optionally, select a specific log level for the upgrade log file. The default log level is "Information". For maximum detail, select "Debug".
- Advanced Options JSON: Optionally, add a JSON string to provide additional command parameters.
- Alternative ULN Channel: This parameter applies to patching and can be ignored.
Click Create Request.

The new upgrade request appears in the Upgrade Jobs table. The preconfiguration steps are performed as described at the start of this section.

Using the Service CLI

Gather the information that you need to run the command:
- the location of the ISO image to upgrade from
  
  Enter the path to where the ISO image is stored. If this version consists of multiple ISOs, point to the primary pca-3.0.2-<build_no>.iso file.
  
  All ISO content will be unpacked on the shared storage accessible from the management nodes. Secondary ISO images are detected and processed automatically, but they must be stored in the same source directory.
- the checksum used to verify the ISO image
  
  The checksum is provided alongside the ISO image. Its file name is the ISO image name with .sha256sum appended. The system uses the checksum to verify that the data in the ISO images is intact and valid for this upgrade.

Enter the upgrade preconfiguration command.

Syntax (entered on a single line):

upgradePreConfig 
option=ISO
location=<path-to-iso>
isoChecksum=<iso-file-checksum>

Example:

PCA-ADMIN> upgradePreConfig  option=ISO \
location=http://host.example.com/pca-<version>-<build>.iso \
isoChecksum=4a7778d45b3996319ee67c772fbbc0320a9806a942490a1cfe6b37930372809e
Status: Success
JobId: 105524a2-24a2-4b52-91c4-5cd8832552d2
Data: Service request has been submitted. Upgrade Job Id = 1737483518274-prepare-28393 Upgrade Request Id = UWS-e37208d4-d433-4e16-8140-de38c0757c9d

Use the request ID and the job ID to check the status of the upgrade process.

PCA-ADMIN> getUpgradeJobs
Data: 
  id                            Upgrade Request Id                                Command Name   Result   
  --                            ------------------                                ------------   ------   
  1737483518274-prepare-28393   UWS-e37208d4-d433-4e16-8140-de38c0757c9d          prepare        Passed

PCA-ADMIN> getUpgradeJob upgradeJobId=1737483518274-prepare-28393
Status: Success
Data:
  Upgrade Request Id = UWS-e37208d4-d433-4e16-8140-de38c0757c9d
  Name = prepare
  Pid = 28393
  Host = pcamn02
  Log File = /nfs/shared_storage/pca_upgrader/log/pca-upgrader_prepare_environment_2025_01_21-18.18.38.log
  Arguments = {"component_names":null,"diagnostics":false,"display_task_plan":false,"dry_run_tasks":false,"expected_iso_checksum":null,"fail_halt":false,"fail_upgrade":null,"image_location":"https://host.example.com/pca-<version>-<build>.iso","online_upgrade":null,"precheck_status":false,"repo_config_override":null,"result_override":null,"task_time":0,"test_run":false,"upgrade":false,"upgrade_to":null,"user_uln_base_url":null,"verify_only":false,"host_ip":null,"log_level":null,"switch_type":null,"epld_image_location":null,"checksum":"4a7778d45b3996319ee67c772fbbc0320a9806a942490a1cfe6b37930372809e","composition_id":null,"request_id":"UWS-e37208d4-d433-4e16-8140-de38c0757c9d","uln":null,"patch":null}
  Status = Passed
  Execution Time(sec) = 776
  Tasks 1 - Name = Validate Image Location
  Tasks 1 - Description = Verify that the image exists at the specified location and is correctly named
[...]

Proceed to the next upgrade preparation phase.