Preconfigure the Patching Environment

Patching operations rely on the same logic as upgrades, and are also run from the Upgrader service, but use RPM packages provided through ULN channels instead of an ISO image. When the data center ULN mirror has been updated, and the appliance has been synchronized with the mirror, 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 patch workflow setup in the next phase of patch preparation.

During preconfiguration, the yum configuration is updated. Assuming the active software version before upgrade is at least 3.0.2-b1185392, the pca-prerequisite script is installed and run.

Note:

If the active software version is older than 3.0.2-b1185392, no prerequisite script is run. The upgradePreConfig and preUpgrade commands ensure that new software packages, latest Upgrader code, and upgrade plan are in place to perform system and component upgrades, but the workflow is different.

Operations performed by this script include:

validating current and new software versions
installing the latest preUpgrade functionality
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 ULN.
- Location: Enter the path to the ULN mirror in the data center, using its fully qualified domain name.
- ISO Checksum: This parameter applies to upgrades from an ISO image and can be ignored.
- 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 forces the request to use a non-standard ULN channel. Do not use this option unless Oracle explicitly instructs you to do so.
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

Look up the URL of the data center ULN mirror.

Enter the upgrade preconfiguration command.

Syntax (entered on a single line):

upgradePreConfig 
option=ULN
location=<path-to-uln-mirror>

Example:

upgradePreConfig option=ULN location=https://host.example.com/yum
Data:
  Service request has been submitted. Upgrade Job Id = 1692849609034-prepare-45676 Upgrade Request Id = UWS-edfa3b32-c32a-4b67-8df5-2357096052bf

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

PCA-ADMIN> getUpgradeJobs
  id                               upgradeRequestId                           commandName   result
  --                               ----------------                           -----------   ------
  1630938939109-compute-7545       UWS-61736806-7e5a-4648-9259-07c54c39cacb   compute       Passed
  1632849609034-kubernetes-35545   UWS-edfa3b32-c32a-4b67-8df5-2357096052bf   kubernetes    Passed
  1692849609034-prepare-45676      UWS-edfa3b32-c32a-4b67-8df5-2357096052bf   prepare       Passed

PCA-ADMIN> getUpgradeJob upgradeJobId=1692849609034-prepare-45676
Status: Success
Data:
  Upgrade Request Id = UWS-edfa3b32-c32a-4b67-8df5-2357096052bf
  Name = prepare
  Start Time = 2022-06-14T06:35:56
  End Time = 2022-11-06T06:35:58
  Pid = 45676
  Host = pcamn02
  Log File = /nfs/shared_storage/pca_upgrader/log/pca-upgrader_prepare_environment_2022_11_16-06.35.56.log
[...]

Proceed to the next upgrade preparation phase.