Upgrade Airlock IAM at runtime (rolling upgrade)

Upgrading at runtime, also referred to as rolling upgrade, is the process of activating a new version of Airlock IAM without interrupting IAM operation.

Airlock IAM supports rolling upgrades to a certain extent under specific circumstances.

Preconditions for rolling upgrades

  • Rolling upgrades of Airlock IAM are possible if the following preconditions are met:
  • At least two IAM instances are active at a time in an active-active setup.
  • IAM session state is stored in an external Redis cluster and not in memory.
  • The IAM version to upgrade to supports rolling updates. This is the case starting with IAM 8.2 and onwards unless otherwise stated in the release notes.
  • The used database is supported for rolling updates by the schema upgrade scripts provided with Airlock IAM.

Step 1 – Upgrade database schema

Before upgrading the IAM instances, the database schema must be updated for the new release. To do so, use the database schema scripts provided on Relational databases for IAM.

Not all database schema changes are designed to work with both the old and the new IAM version. Database schema change scripts may need to be specially crafted for use with rolling updates.

Especially, do not use database schema upgrade scripts older than those for IAM 8.2 for updates at runtime.

Carefully read the note regarding each database upgrade script.

Step 2 – Upgrade IAM instances

Upgrading at runtime is based on running multiple IAM instances and then upgrading each instance in a way that at least one instance is available at all times, e.g. upgrading each instance after another. This can be done manually in a traditional active-active setup or automatically, e.g., in a Kubernetes setup.

During the upgrade phase, some IAM instances are running the old and some are running the new version. To make it possible to migrate the session state, a so-called blue-green deployment model is required: it makes sure that once the state of an IAM session has been migrated to the new version, no subsequent request of that session is sent to an IAM instance running the old version.

The used reverse proxy, ingress controller, or load balancer must ensure the blue-green deployment. This cannot be enforced by Airlock IAM.

If the used reverse proxy, ingress controller, or load balancer is capable of session-sticky load-balancing, starving out old IAM instances is possible as an alternative to blue-green deployment.


  • Note the following limitations regarding updates at runtime:
  • Depending on the included changes, database schema updates may not be available for updates at runtime. This applies especially to H2 and MSSQL databases.
  • Updating at runtime requires blue-green deployments. Session-sticky load balancing in combination with "starving out" IAM instances may be used as an alternative.
  • While user and admin sessions are preserved when upgrading, ongoing flows (authentication, self-services, etc.) may be aborted during the update.
  • Single HTTP requests may result in failures while upgrading.
  • Upgrades are only supported from a lower to a higher version number and not vice versa.
  • Note the limitations of Storing session state in an external Redis session repository.