MODSIDECAR-13: Options for handling modules which call OKAPI

Overview

User story: https://folio-org.atlassian.net/browse/MODSIDECAR-13

Some modules (FE and BE) make API calls directly to OKAPI. On the new platform, these things are going to break. We need to look at the options and decide how we want to resolve this issue.

Okapi permissions usage

Permission	Interface	Required by modules	Notes

Permission	Interface	Required by modules	Notes
okapi.env.list	`GET /_/env`	ui-developer	`mgr-applications` or `mgr-tenant-entitlements` does not store env variables for deploy, so it can be performed by grabbing `env` section from module descriptors
okapi.proxy.modules.list	`GET /_/proxy/modules`	ui-developer	can be provided by `mgr-applications`
okapi.proxy.tenants.modules.list	`GET /_/proxy/tenants/{tenantId}/modules`	ui-developer mod-bulk-operations mod-data-export-worker	a list of installed modules can be provided by `mgr-tenant-entitlements`, module descriptors can be retrieved from `mgr-applications` `mod-bulk-operations` uses this API to retrieve mod-users `moduleId` and then perform request for custom-fields (`x-okapi-module-id` is required). Request is performed with `filter=mod-users` `mod-data-export-worker` the same as `mod-bulk-operations`
okapi.proxy.tenants.modules.post	`POST /_/proxy/tenants/{tenantId}/modules`	ui-developer	This API cannot be provided, cause mgr-components cannot perform installation of a single module
okapi.proxy.tenants.modules.enabled.delete	`DELETE /_/proxy/tenants/{tenantId}/modules/{moduleId}`	ui-developer	This API cannot be provided, cause mgr-components cannot perform uninstallation of a single module
okapi.discovery.get	`GET /_/discovery/modules/{serviceId}/{instanceId}`	ui-developer	Can be provided by `mgr-applications`
okapi.version.get	`GET /_/version`	ui-developer	There is no okapi in the system, this interface cannot be supported

Note: UI-Developer is not included in the production deployment, according to the README.md file

mod-permissions requires perms.users.assign.okapi permission to assign okapi permissions to the user. This permission is hardcoded in the codebase and required in permissionsDesired section, without this permission - okapi permissions cannot be assigned.

Okapi interface provision using mgr-components

mgr-tenant-entitlement

If the module requires okapi interface API

allowed okapi endpoints are stored in mgr-tenant-entitlements in Json (key is the permission id, values - is the Authorization resource(permission + endpoint)
mgr-tenant-entitlements generates and adds Keycloak resources (for instance, GET /_/proxy/tenants/{tenantId}/modules)
mgr-tenant-entitlements generates corresponding capabilities (for instance, view + Tenant Modules with assigned endpoint GET /_/proxy/tenants/{tenantId}/modules)

mgr-applications

mgr-applications will collect (using HTTP calls) okapi interfaces from the mgr-components and will include them in the module bootstrap information. This service will provide endpoints with new field pathOverwrite, so sidecar can overwrite the path to call mgr-components:

{
  "methods": [ "GET" ],
  "pathPattern": "/_/proxy/tenants/{tenantId}/modules",
  "pathOverwrite": "/entitlements/{tenantId}/modules"
  "permissionsRequired": [ "okapi.proxy.tenants.modules.list" ]
}

mod-roles-keycloak

Requires the same prevention measure to prevent assigning system (okapi) capability to anyone.

folio-module-sidecar

To cover all cases except ui-developer, all modules can call sidecar for GET /_/proxy/tenants/{tenantId}/modules, and sidecar will proxy request according to the diagram.

In-place solution to support okapi interfaces

Requires a lot of changes in all modules, including manager components

Can be difficult to maintain in the future cause of the complexity of this approach

Okapi API Facade

This module can be part of app-platform-minimal and it will work as a light-weight router to mgr-components.

In comparison with the first approach - there is no need to modify the existing codebase in mgr-applications, mgr-tenant-entitlements, and folio-module-sidecar. This module will belong to the app-platform-minimal and it will provide supported okapi interface, or all of them, but only partially implemented. Other calls to the service will return 501 Not Implemented.

Straight-forward solution which aligns with the Folio microservice approach

Lightweight, this service won’t require connection to the database, enabled tenants will be handled by sidecar

Okapi modules are defined in module information, all the data will be handled by mgr-components

Additional microservice to deploy

Excluding Okapi interfaces from the system

mod-data-export-worker and mod-bulk-operations use the same approach to retrieve custom fields by calling okapi to identify the version of deployed mod-users for specific tenants.

If one tenant can have only 1 version of the module - we can set up Kong Gateway routes to include only the module name instead of the module version, and Okapi request becomes obsolete.

Okapi modules are defined in module information, all the data will be handled by mgr-components

Okapi call no longer required by module

Requires change of community codebase

Works only with Kong and sidecar

Conclusion

Partially okapi interfaces can be supported by the platform, excluding all interfaces related to the module installation (application installation is only supported) and deployment (for example, env variables).

UI-developer implementation relies on okapi interfaces, so there is no guarantee that the functionality of this module can be fully supported