This article provides best practices for upgrading an Okta Access Gateway High Availability (HA) environment to 2024.9 or above.  

• Okta Access Gateway(OAG)

Upgrade to 2024.9 and above from versions below 2024.9

• As recommended in the release notes, all the nodes in a cluster must be upgraded within the same maintenance window, for example, upgrade all workers followed by the admin node, while upgrading a cluster from versions below 2024.9 to 2024.9 and above. The explanation below will help in understanding why it is required: 
  • PHP has been upgraded to 2024.9, so all the applications need to be updated with the new PHP references. As part of the upgrade, the OAG Admin node will update all the applications with the updated PHP references. The HA flow will then send the updated configs to all the workers. In case worker nodes are not upgraded, then users may notice application access issues. The issue can also happen when only worker nodes get updated, but not the admin, since the updated config has not been received. The updated worker will refer to the old PHP code that no longer exists.

• What to do when all the nodes cannot be upgraded in the same maintenance window? 
  • In case all the nodes cannot be upgraded in the same maintenance window, the following workaround can be used: 
    1. Upgrade worker node(s). Make sure to follow the steps thoroughly from the release notes. 
    2. After the upgrade (post reboot) on the worker node(s) is completed, select sync from admin to trigger the application's config update. 
  • NOTE:
    • The steps above are recommended when the complete cluster cannot be upgraded in a single maintenance window. 
    • The worker will process all the configs received from the admin, so the complete flow may take ~5 ( to 15 or more) minutes if there is a large number of applications. 
    • When the upgrade completes on Admin, an application update will be triggered, and all the workers will get the configs again. This will not impact any operation since the workers are already serving the updated configs.
    • The outlined steps are Administrative tasks and do not fall under the break-fix scenario. The steps execution is not scoped under Okta Support.
    • Okta support can be contacted if there are any issues accessing the applications after the upgrade or while executing the upgrade. 

Upgrade to 2024.10 and above from 2024.9

• Once the cluster is on 2024.9, upgrading to future releases will not require upgrading in the same maintenance window. This is because the applications will already have the updated PHP references.
• However, it is a must to upgrade the Admin node at the end, for example, after the upgrade on all the worker nodes is completed. This is required so the worker node can parse any new improvement in the application config that is coming from Admin.