Kepler migration checklist

As part of Relativity's architecture modernization, all Kepler services run in RelativityOne will be migrated to RelativityOne's modernized compute platform, starting in mid-Q3 2022. In some cases, you may need to prepare your Kepler Services for the migration. This topic describes the preparation you may need to perform.

Note: This migration preparation only applies to custom applications that host their own custom Kepler services, leveraging the Kepler framework. It does not apply to consuming Relativity-owned Kepler services. Only certain applications will be impacted by this migration.

Determining if your Kepler service is affected

Kepler services running on RelativityOne Compute must comply with new requirements to ensure proper functioning of the service. Services which do not comply may suffer from degraded performance or broken functionality. See Kepler requirements for RelativityOne Compute for more details.

Note: Kepler services functioning as Workload Discovery endpoints must also comply with these requirements. However, given the nature of these changes and the function of Workload Discovery, it is unlikely that these types of endpoints will require any updates.

Kepler requirements for RelativityOne Compute

Requirement Notes
Be stateless

The current web server-based architecture relies on a "sticky session", which means that once a user logs into Relativity all subsequent web requests are always routed to the same running instance of your Kepler service. Once Kepler services are hosted in the new compute platform this behaviour will no longer occur.

Your Kepler service must be stateless because the request to your Kepler service may be served by multiple instances during the same session, and your application could be terminated during auto-scaling operations, node maintenance, or an underlying infrastructure outage.

Tolerate cold in-memory cache hits

The removal of sticky sessions means that Kepler services which rely on in-memory caching may have adverse impacts. For example, in-memory caching of items related to the logged in user may result in more cold cache hits since multiple requests from the same user are no longer guaranteed to go to the same instance of the Kepler service.

Kepler services must ensure they continue to function correctly despite the loss of sticky session and an increase in number of cold cache hits. Kepler services that are negatively impacted should consider an alternative caching solution.

Use fully qualified domain names (FQDN) when interacting with files

Referencing files via non-FQDN paths such as \\files\t02\.... will cease to function once migrated to RelativityOne Compute. All interactions with files on the fileshare must use FQDN paths in order to be able to correctly locate the file.

Additionally, files must not be stored outside of the current user's temp directory. Attempting to access files outside of the user space will be restricted and may cause unexpected results.

Do not use IProgress and SignalR

Kepler services will no longer support IProgress events as part of the Kepler service library functionality. This change is necessary because progress events utilize SignalR, and SignalR requires sticky sessions which will not be supported in the new RelativityOne compute platform.

Kepler services should be refactored so that they do not rely on SignalR, including consumption of SignalR from a Relativity-owned service. Current service interfaces that define Progress events will be replaced with no-op as to not break the existing .NET contracts.

Do not assume the service will run with admin permissions

Kepler services will be hosted under a Windows user with restricted permissions. If your Kepler service relies on admin permissions in Web Servers, it must be adjusted to cater for the permissions/actions that are no longer permitted, as listed below.

Note: This only applies to the permissions of the Kepler service itself. This does not impact end-user permissions accessing the Kepler service.

  • Debug programs
  • Act as part of the operating system
  • Create a page file
  • Access files outside of current user’s temp directory
  • Impersonate a client after authentication
  • Load and unload device drivers
  • Manage auditing and security log
  • Obtain an impersonation token for another user in the same session
  • Profile single process
  • Replace a process level token
  • Take ownership of files or other objects
  • NTFS permission to read/write directories belonging to other users
Do not rely on libraries which are not supported in Docker

Open source or third-party libraries which are not compatible with Docker containers (ephemeral and headless environments) will cease to function once migrated to RelativityOne Compute.

Please refactor your code or find alternate libraries that are supported. One example of an unsupported library is MediaToolkit - this library should be replaced with direct use of an essential build of ffmpeg (for example v5.0.1 available from here)

Frequently Asked Questions

  • What is the recommended overall workflow for making these updates?
    • Multiple valid paths exist for developers to make these updates, and, depending on the complexity of your Kepler services, certain steps may be more significant for you than others. However, this is the general workflow we suggest using to ensure your services are ready for migration:
      1. Review in detail the requirements listed on this page and evaluate them against each of your Kepler services. You should have a good understanding of which Kepler services will be affected and the approach that you want to use in making them ready for migration.
      2. Make any required changes using your existing development process. Typically, this will be on a DevVM where you can quickly iterate and test with Relativity’s Local Debugger. You should also confirm Relativity Logging is implemented and correctly capturing important messages from your agent.
      3. Fully test the behaviour of your services to ensure they are working as expected.
      4. Install your Kepler service into an EA Sandbox environment and request for it to be migrated to K8s if it is not already migrated. Fully test your service running in Kubernetes, especially keeping an eye on logging, performance and functional correctness.

        Note: Sandboxes are scheduled to be available for migrations by mid-August 2022.

      5. Return to Step 2 as needed, based on your findings while running in Kubernetes.
  • Will Relativity API Helpers still be available?
    • Yes, these helpers will remain unchanged and may still be used to get information about the user.
  • How do I get more support if I am stuck? 
    • Our first recommendation is usually to add more Relativity Logging to your Kepler service to pinpoint the error message – without strong logging, it is very difficult for us to provide support. If that does not help identify the issue, though, please contact support for additional help.