Update Access Gateway OS

Okta Access Gateway v2020.09.2 and earlier versions were built on top of CentOS 7, which is approaching End-of-Life. Access Gateway will continue to support earlier versions of CentOS but may discontinue upgrades for these versions in the future. Access Gateway 2020.10.1 and later OVAs are based on CentOS 8 which includes numerous security, kernel and related upgrades.

This document describes the process of upgrading an Access Gateway cluster to the latest version using Admin renomination.

Before you begin

  • Ensure you have sufficient capacity to add a new Access Gateway instance.  During the uprade process, new instances of Access Gateway will be added, replacing old instances. Sufficient capacity (memory, disk and VM resources) must be available to add a single new instance of Access Gateway. As instances are added old instances will are removed.
  • Ensure you have access to and can administer load balancers. During this OS upgrade Access Gateway instances will be replaced with instances running a newer version of the base operating system. You must be able to remove and add instances to your Access Gateway cluster and its associated load balancer.
  • Ensure that you have access to and can make changes to DNS. During the admin renomination process a new instance of Access Gateway will be added as the cluster admin. This instance will replace the existing admin instance and will need to be registered in DNS with the same name as the current admin instance.

Upgrade process overview

Access Gateway clusters built using OVAs running Access Gateway version 2020.09.3 and earlier cannot directly upgrade their underlying OS. In order to perform the upgrade the following process must by carefully followed:



While recommended, you are not required to update to a newer version of the underlying operating system. You can update an older version of the underlying OS to Access Gateway v2020.10.5 and later. Okta reserves the right to stop or limit support for older versions of the underlying operating system at any time.

  1. Determine if the upgrade process is required. Only Access Gateway instances prior to Access Gateway 2020.10.5 need to perform the upgrade process. If your Access Gateway cluster was build using version 2020.10.5 or later you can upgrade normally. See Upgrade Access Gateway nodes
  2. Add a Access Gateway 2020.10.5 Cluster admin - Using the admin renomination process add a new admin node. See Perform admin renomination.
  3. Point the existing admin DNS instance name to the IP address of the new admin node.
  4. Decommission the old admin node - Once the renominated admin node is up and running, decommission the older admin node by removing it from any load balancers, and then stopping and deleting the VM.
  5. Replace cluster members - For each existing cluster member:
    1. Remove the existing cluster member from the load balancer.
    2. Add a new cluster member running Access Gateway 2020.10.5 or later to your virtual environment.
    3. Add the new replacement instance to the load balancer.
    4. Decommission the old, now replaced node.
    5. Repeat for each member of the cluster.


While replacing nodes within a cluster should be done in a timely fashion Access Gateway can function in a mixed version environment. Take the time necessary to plan out and upgrade your environment thoughtfully.

Related topics

Determine Access Gateway version

About admin renomination

Perform admin renomination

Upgrade Access Gateway nodes