Upgrade Okta Access Gateway Clusters to Version 2024.9 and Above

Upgrading an Okta Access Gateway (OAG) High Availability (HA) environment to version 2024.9 or above requires specific procedures to prevent application access issues. Administrators must upgrade all nodes within the same maintenance window due to PHP package updates, or follow a specific workaround if a single window is not possible.

• Okta Identity Engine (OIE)
• Okta Classic Engine
• Okta Access Gateway (OAG)

How do administrators upgrade to version 2024.9 and above from older versions?

As recommended in the release notes, administrators must upgrade all nodes in a cluster within the same maintenance window. For example, upgrade all workers followed by the admin node. Okta upgraded the PHP package to 2024.9, requiring all applications to update with new PHP references. During the upgrade, the OAG Admin node updates all applications with the new PHP references, and the High Availability (HA) flow sends the updated configurations to all workers. If administrators do not upgrade worker nodes, application access issues occur. If administrators only update worker nodes, the updated workers refer to old PHP code that no longer exists because they do not receive the updated configuration from the admin node.

Upgrade Nodes in Separate Maintenance Windows

If administrators cannot upgrade all nodes in the same maintenance window, perform the following workaround steps to upgrade the cluster.

1. Upgrade the worker nodes by following the steps in the release notes.
2. After the upgrade and post-reboot process completes on the worker nodes, select sync from admin to trigger the application configuration update.

NOTE: Okta recommends these steps when administrators cannot upgrade the complete cluster in a single maintenance window. The worker processes all configurations received from the admin node. This flow takes approximately 5 to 15 minutes or more, depending on the number of applications. When the upgrade completes on the admin node, Okta triggers an application update, and all workers receive the configurations again. This does not impact operations because the workers already serve the updated configurations. These steps are administrative tasks and fall outside the scope of Okta Support. Contact Okta Support if application access issues occur after or during the upgrade.

How do administrators upgrade to version 2024.10 and above from version 2024.9?

Once the cluster runs version 2024.9, upgrading to future releases does not require upgrading in the same maintenance window because the applications already contain the updated PHP references. Administrators must upgrade the admin node last, after completing the upgrade on all worker nodes. This ensures the worker nodes can parse any new application configuration improvements sent from the admin node.