folio-module-sidecar
- 1 Overview
- 2 Sidecar initializing and runtime
- 3 Sidecar Runtime
- 3.1 Sidecar filters
- 3.1.1 Ingress request filters in details
- 3.1.1.1 1. SelfRequestFilter
- 3.1.1.2 2. KeycloakSystemJwtFilter
- 3.1.1.3 3. KeycloakJwtFilter
- 3.1.1.4 4. KeycloakTenantFilter
- 3.1.1.5 5. TenantFilter
- 3.1.1.6 6. KeycloakImpersonationFilter
- 3.1.1.7 7. KeycloakAuthorizationFilter
- 3.1.1.8 8. SidecarSignatureFilter
- 3.1.1.9 9. DesiredPermissionsFilter
- 3.1.2 Egress Request Filters in details
- 3.1.2.1 1. SidecarSignatureRemover
- 3.1.1 Ingress request filters in details
- 3.1 Sidecar filters
- 4 Module Prefix strategies
- 5 Signing Key Rotation
- 6 Sidecar communication example
- 7 Deployment
- 7.1 Java-based Docker image
- 7.1.1 Minimal memory requirements
- 7.1.2 Algorithm for calculation
- 7.1.2.1 Example
- 7.1.3 Minimal CPU Requirements
- 7.2 Native Docker Image
- 7.1 Java-based Docker image
Overview
The Sidecar architectural pattern is a design pattern used in software engineering to enhance or extend the functionality of a main application by attaching a secondary application or service to it. This secondary application, known as the "sidecar," runs alongside the main application and provides supporting features such as monitoring, logging, configuration, or networking services.
In this pattern, the sidecar is tightly coupled with the main application, sharing the same lifecycle and always deployed together. However, the sidecar's runtime environment remains independent, allowing it to be developed and maintained separately from the main application.
The Sidecar pattern is commonly used in microservices architectures, where each microservice can have its sidecar to handle cross-cutting concerns. This allows developers to implement these concerns consistently and avoid duplicating code across services. It also simplifies the main application code by offloading auxiliary tasks to the sidecar.
GitHub repository: https://github.com/folio-org/folio-module-sidecar
folio-module-sidecar
uses Quarkus as a framework:
It allows building native image
(only non-FIPS-compliant docker images because some of the BouncyCastle FIPS libraries: Quarkus FIPS Security)FIPS-compliant
Lightweight and quick (compared to other solutions like Spring Boot Native Image, Envoy)
Java-based
Vertx under the hood, providing general router for ingress and egress requests and WebClient for external calls
folio-module-sidecar
provides the following functionality:
Ingress requests handling
incoming requests from API Gateway or another module to the current Folio moduleEgress requests handling
outcoming requests from the current Folio module to another Folio moduleAuthentication
based onx-okapi-token
orAuthorization
headerAuthorization
based on Keycloak policies and permissionsSelf-requests
based onx-okapi-sidecar-signature
header valueUser impersonation
Consortia support and cross-tenant requestsHTTP Transactional logging
Sidecar initializing and runtime
Bootstrap process
During startup, folio-module-sidecar
calls the following modules according to the sequence diagram:
Sidecar, as shown on the diagram, calls mgr-components to be part of the Eureka system:
It calls
mgr-applications
to construct egress and egress request caches, that store routing entries from module descriptor by id and for other related module descriptors, defined by optional and required interface dependencies.For egress requests there is a support to call API Gateway if the egress routing entry is not matched, it is controlled via environment variables:
SIDECAR_FORWARD_UNKNOWN_REQUESTS
andSIDECAR_FORWARD_UNKNOWN_REQUESTS_DESTINATION
which by default pointing to the Kong API Gateway.
It calls
mgr-tenant-entitlements
andmgr-tenants
to find out for which tenants sidecar is enabled, requests, containing tenant id, that is not cached in sidecar will be rejected with400 Bad Request Application is not enabled for tenant: {{tenantName}}
Sidecar Runtime
During runtime, folio-module-sidecar
receives events from the message bus (Apache Kafka) containing:
Tenant entitlement, revoke, and upgrade events. This information is used to update the active tenant's cache to support the following cases:
During the application uninstallation (revoke) - all related sidecars must be disabled for the affected tenant
During the application upgrade process - all upgraded (new) modules must be enabled for the tenant and all deprecated modules must be disabled for the affected tenant
Discovery information change information:
Sidecar can update an egress request location cache if discovery information is changed in
mgr-applications
Sidecar also caches authorized requests for the JWT using
session_state
claim if present until the token is expired:If a user performs logout or logout all operations -
folio-module-sidecar
can clean affected caches and forbid the next request using cached JWT
Sidecar filters
The filter approach is a way to intercept and process HTTP requests and responses before they reach a point when the request must be forwarded to the underlying Folio module. In request, they are responsible for all functionality and executed in chain.
Ingress request filters in details
1. SelfRequestFilter
Description
This filter is responsible for validating if a request is a module self-request. These types of requests are allowed without authentication and authorization.