How folio-org/folio-module-sidecar works
Main Components
• Sidecar Application (the core Quarkus application)
• That it implements both inbound (Ingress) and outbound (Egress) routing.
• That it handles security (JWT validation, Keycloak integrations), performs health checks, and hosts a configurable routing mechanism.
• Underlying Module (specified by environment variables such as MODULE_URL, MODULE_NAME, MODULE_VERSION)
• Target module that the sidecar routes requests to.
• External Integrations
• Okapi and its role in module configuration (obtaining Module Descriptors).
• Authentication and Token Management: Keycloak for JWT validation, token introspection, impersonation, and authorization.
• Manager services: integration with mgr-applications (AM), mgr-tenant-entitlements (TE), mgr-tenants (TM) for bootstrap/discovery.
• Secure storage: abstract integration for AWS SSM or Vault for secure credential storage.
• Kafka: components consuming discovery, logout, tenant entitlement, and other events.
Architectural Interactions
• Ingress Flow:
• Path transformation or header enrichment: illustrate extraction of a tenant or user ID to add to HTTP headers.
• Forward request to the “Underlying Module”.
• Egress Flow:
• That it retrieves credentials from the “Credential Service” (with subcomponents for asynchronous secure store access).
• Communication to external systems such as Keycloak (for service accounts) and potentially to an API Gateway (if forwarding unknown requests).
• Event/Discovery Flow:
• Kafka integrations: components like DiscoveryConsumer, TenantEntitlementConsumer, and LogoutConsumer.
• How they listen for events and update the dynamic routing configurations.
• Health and Monitoring:
• A “Health Check” component that periodically verifies the status of the sidecar, including health utilities and route validation.
Architectural Patterns and Principles
• Microservice Architecture – showing the sidecar as a thin intermediary separating the underlying module from direct traffic.
• Configurable Routing – dynamic discovery and cache updates using event consumers and lookup mechanisms.
• Integration of multiple clients (HTTP clients for Keycloak, Okapi, and manager components), using properties and configuration classes for these dependencies.
Relevant Technologies and Frameworks
• Quarkus: as the application framework powering the module with live reload, native compile capabilities, and production build options.
• Maven: as the build tool (if needed, can be annotated in a “Build & Deployment” section).
• Docker and containerization: for running both JVM-based and native versions, as well as FIPS compliant builds.
• Kafka: for asynchronous event processing.
• Keycloak: for authentication and authorization duties.
• Secure Storage Options: AWS SSM/Vault indicated by the secure store configurations.
• Optional integration with Okapi module descriptors and FOLIO’s ecosystem.
Elements
• Clear labels for each component (e.g., Ingress Handler, Egress Handler, Credential Service, Health Check, Dynamic Routing Lookup).
• From clients to Ingress Handler, then to Underlying Module after security checks.
• From Sidecar to external Keycloak server for token exchanges.
• From Sidecar to Kafka consumers for configuration updates.
• Feedback loops (e.g., caching mechanisms or health check triggers).
• Another group for external integrations (Keycloak, manager services, Okapi, secure store, API gateway).