Chapter 2. Zero-migration architecture

Zero-migration architecture is a core design principle of Open Liberty, which supports full compatibility between runtime versions. With zero-migration architecture, you can move to the latest version of Open Liberty with minimal impact to your current applications and configurations.

One of the major challenges for teams that work with runtime servers is the need to continually update to the latest release of the runtime. These updates are often required to resolve security vulnerabilities or bugs that can cause outages. Updating the runtime version can be difficult because new releases also introduce API or behavior changes, sometimes for functions that are not critical for your particular applications. Both the Open Liberty runtime and Open Liberty features are released in numbered versions. Changes in behavior and API support are delivered in new feature versions, which you can decide whether to adopt according to your needs. With zero migration, your existing APIs and behaviors are supported in new runtime versions, and new APIs and behaviors are added in new features and feature versions. Your existing, unmodified configuration and application files work with an updated version of Open Liberty, without unexpected changes in application behavior.

2.1. User configuration files

If all the configured features are installed, a single set of configuration files works across multiple versions of Open Liberty without modifications. User configuration files do not require modification when the runtime is updated to a new version. Open Liberty ignores any configuration settings that do not apply to the active version of the runtime.

2.2. Open Liberty features

Open Liberty features are encoded into the server configuration, which does not change during an upgrade. When behavior changes are introduced, such as when a Java specification mandates a behavior change, the change is introduced in a new version of the feature. Existing applications and their configuration can continue to use the old behavior with the older feature version, while new applications can use newer feature versions with the new behavior.

For example, Open Liberty supports both the Servlet 3.1 and Servlet 4.0 specifications. The Servlet 4.0 specification includes clarifications to previous servlet versions that can result in changes in application behavior. Open Liberty restricts any such behavior changes to the servlet-4.0 feature and retains the existing behavior in the servlet-3.1 feature. If your application is configured for the Servlet 3.1 specification, you can continue to use the servlet-3.1 feature across runtime updates, regardless of how many other servlet specification levels are supported. You don’t need to change your application unless you decide to configure the servlet-4.0 feature instead. For more information, see Feature overview.

2.2.1. Considerations for using new features

Upgrading to a new version of a feature that you are already using might impact your existing applications. For example, if you currently use the servlet-3.1 feature and you want to use the servlet-4.0 feature, your existing servlet applications might require modification to work correctly with the servlet 4.0 feature. Alternatively, you can keep the application in a server that is configured with the original version and create a different server configuration with the new feature version for new applications.

Some features interact closely with other features and require that you enable a particular feature version when they are both configured in the same server. Some features require specific versions of prerequisite software, for example, the Java SDK.

2.3. Exceptions to zero migration

Although Open Liberty is designed to ensure that no breaking changes occur between runtime versions, in some rare cases they are unavoidable. Such exceptions to zero migration fall into one of the following categories:

  • Security fixes
    If your application requires a security-related fix that cannot be safely implemented in the context of existing behavior, then you might need to modify your application or configuration.
  • Third-party API requirements
    Open Liberty does not control APIs from the third-party class loader configuration. As a result, updates to third-party components are not guaranteed to be compatible with an earlier version of the runtime.
  • Undocumented configuration properties
    Some configuration options for Open Liberty are not part of the runtime documentation. These configuration options can be determined by looking at the source code, or through trial and error, based on external sources of information. If options are not documented as a part of Open Liberty, then they are not considered part of Open Liberty. Such options might not be fully implemented and might cause issues if they are used. Since they are not documented, they can be removed or changed at any time and are not covered by zero migration.
  • Incompatible Java changes
    Historically, new Java SE versions make few incompatible changes to the Java language. In the rare case that a breaking change is included in a new Java version, Open Liberty attempts to minimize the impact of these changes on applications. However, these attempts might not always be successful and breaking Java changes can sometimes adversely affect your application.

Zero-migration architecture saves developers and enterprises time and money by avoiding the need to migrate existing configuration and application files. Developers can focus on their applications, rather than managing runtime updates, while they continue to benefit from improved performance and administration for their existing server configurations.