diff --git a/conforming/README.md b/conforming/README.md index 7ce1179a..e82a9129 100644 --- a/conforming/README.md +++ b/conforming/README.md @@ -52,7 +52,8 @@ The conforming agent will be configurable to support the following http/s based mvn package ``` -This will generate +This will generate + - a [plugin jar](target/original-conforming-agent-1.10.15-SNAPSHOT.jar) containing all necessary components to be dropped into a Jakarta-Compatible Web Server. - a [standalone jar](target/conforming-agent-1.10.15-SNAPSHOT.jar) including the Jakarta-Reference Implementation (Glassfish). @@ -106,19 +107,20 @@ You may manipulate any of the following environment variables to configure the i Note that there is no builtin security (ssl/auth) for the exposed endpoints. This must be provided by hiding them in an appropriate service network layer. -| ENVIRONMENT VARIABLE | Required | Example | Description | List | -|--- |--- |--- |--- | --- | -| JAVA_TOOL_OPTIONS | | -agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=*:8090 | JMV (Debugging option) | X | +| ENVIRONMENT VARIABLE | Required | Example | Description | List | +|----------------------|----------|----------------------------------------------------------------------|------------------------|------| +| JAVA_TOOL_OPTIONS | | -agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=*:8090 | JMV (Debugging option) | X | ### Notice for Docker Image DockerHub: https://hub.docker.com/r/tractusx/conforming-agent Eclipse Tractus-X product(s) installed within the image: -GitHub: https://github.com/eclipse-tractusx/knowledge-agents/tree/main/conforming -Project home: https://projects.eclipse.org/projects/automotive.tractusx -Dockerfile: https://github.com/eclipse-tractusx/knowledge-agents/blob/main/conforming/src/main/docker/Dockerfile -Project license: Apache License, Version 2.0 + +- GitHub: https://github.com/eclipse-tractusx/knowledge-agents/tree/main/conforming +- Project home: https://projects.eclipse.org/projects/automotive.tractusx +- Dockerfile: https://github.com/eclipse-tractusx/knowledge-agents/blob/main/conforming/src/main/docker/Dockerfile +- Project license: Apache License, Version 2.0 **Used base image** @@ -158,7 +160,7 @@ In your values.yml, you configure your specific instance of the conforming agent # Conforming Agent ############################################################################################## -my-conforming-agent: +my-conforming-agent: securityContext: *securityContext nameOverride: my-conforming-agent fullnameOverride: my-conforming-agent @@ -174,11 +176,5 @@ my-conforming-agent: - default tls: enabled: true - secretName: my-conforming-tls + secretName: my-conforming-tls ``` - - - - - - diff --git a/provisioning/README.md b/provisioning/README.md index 02c55c16..6259cdaf 100644 --- a/provisioning/README.md +++ b/provisioning/README.md @@ -70,7 +70,7 @@ com.dremio.jdbc.Driver-tables.HI_TEST_OEM = CX_RUL_SerialPartTypization_Vehicle, com.dremio.jdbc.Driver-unique.HI_TEST_OEM.CX_RUL_SerialPartTypization_Vehicle = UC_VEHICLE com.dremio.jdbc.Driver-unique.HI_TEST_OEM.CX_RUL_SerialPartTypization_Component = UC_COMPONENT com.dremio.jdbc.Driver-unique.HI_TEST_OEM.CX_RUL_AssemblyPartRelationship = UC_ASSEMBLY -... +... ``` * the ability to optimize to a specific virtualization engine although using a generic REST-based JDBC driver from Apache Calcite @@ -80,12 +80,12 @@ jdbc.url=jdbc\:avatica\:remote\:url=http://data-backend:8888/druid/v2/sql/avatic jdbc.driver=org.apache.calcite.avatica.remote.Driver org.apache.calcite.avatica.remote.Driver-metadataProvider = it.unibz.inf.ontop.dbschema.impl.DruidMetadataProvider org.apache.calcite.avatica.remote.Driver-typeFactory = it.unibz.inf.ontop.model.type.impl.DefaultSQLDBTypeFactory -org.apache.calcite.avatica.remote.Driver-symbolFactory = it.unibz.inf.ontop.model.term.functionsymbol.db.impl.DefaultSQLDBFunctionSymbolFactory +org.apache.calcite.avatica.remote.Driver-symbolFactory = it.unibz.inf.ontop.model.term.functionsymbol.db.impl.DefaultSQLDBFunctionSymbolFactory ``` ### Security -Besides the authentication of the Ontop engine at the relational database via jdbc (one url/user per endpoint), there are no +Besides the authentication of the Ontop engine at the relational database via jdbc (one url/user per endpoint), there are no additional (row-level) security mechanism. Hence we recommend to apply a role-based approach. @@ -98,7 +98,7 @@ For any accessing role: For the sample deployments, we use single agent container with an embedded database (H2) and/or a second database virtualization container (Dremio Community Edition) using preloaded files. -Practical deployments will +Practical deployments will * scale and balance the agent containers (for which the lifecycle hooks are already provided). * use an enterprise-level database (Postgres Service) or database virtualization infrastructure (Dremio Enterprise, Denodo, Teii) that are backed by an appropriate storage system (ADSL, S3, Netapp). @@ -166,16 +166,16 @@ You may manipulate any of the following environment variables to configure the i Note that there is no builtin security (ssl/auth) for the exposed endpoints. This must be provided by hiding them in an appropriate service network layer. -| ENVIRONMENT VARIABLE | Required | Example | Description | List | -|--- |--- |--- |--- | --- | -| JAVA_TOOL_OPTIONS | | -agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=*:8090 | JMV (Debugging option) | X | -| ONTOP_PORT | | 8080 (default) | A port number | X | -| ONTOP_ONTOLOGY_FILE | | /input/ontology.ttl (default) | Path to ontology file (ttl or xml) | X | -| ONTOP_MAPPING_FILE | | /input/mapping.obda (default) | Path to mapping file (obda) | X | -| ONTOP_PROPERTIES_FILE | | /input/settings.properties (default) | Path to settings file (properties) | X | -| ONTOP_PORTAL_FILE | | /input/portal.toml | Path to portal config (toml) | X | -| ONTOP_CORS_ALLOWED_ORIGINS | | * (default) | CORS domain name | | -| ONTOP_DEV_MODE | | true (default) | Redeploy endpoint on file changes | X | +| ENVIRONMENT VARIABLE | Required | Example | Description | List | +|----------------------------|----------|----------------------------------------------------------------------|------------------------------------|------| +| JAVA_TOOL_OPTIONS | | -agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=*:8090 | JMV (Debugging option) | X | +| ONTOP_PORT | | 8080 (default) | A port number | X | +| ONTOP_ONTOLOGY_FILE | | /input/ontology.ttl (default) | Path to ontology file (ttl or xml) | X | +| ONTOP_MAPPING_FILE | | /input/mapping.obda (default) | Path to mapping file (obda) | X | +| ONTOP_PROPERTIES_FILE | | /input/settings.properties (default) | Path to settings file (properties) | X | +| ONTOP_PORTAL_FILE | | /input/portal.toml | Path to portal config (toml) | X | +| ONTOP_CORS_ALLOWED_ORIGINS | | * (default) | CORS domain name | | +| ONTOP_DEV_MODE | | true (default) | Redeploy endpoint on file changes | X | Here is an example which exposes two endpoints for two different roles (database users, restricted mappings but same ontology) @@ -270,10 +270,11 @@ WHERE { DockerHub: https://hub.docker.com/r/tractusx/provisioning-agent Eclipse Tractus-X product(s) installed within the image: -GitHub: https://github.com/eclipse-tractusx/knowledge-agents/tree/main/provisioning -Project home: https://projects.eclipse.org/projects/automotive.tractusx -Dockerfile: https://github.com/eclipse-tractusx/knowledge-agents/blob/main/provisioning/src/main/docker/Dockerfile -Project license: Apache License, Version 2.0 + +- GitHub: https://github.com/eclipse-tractusx/knowledge-agents/tree/main/provisioning +- Project home: https://projects.eclipse.org/projects/automotive.tractusx +- Dockerfile: https://github.com/eclipse-tractusx/knowledge-agents/blob/main/provisioning/src/main/docker/Dockerfile +- Project license: Apache License, Version 2.0 **Used base image** @@ -313,7 +314,7 @@ In your values.yml, you configure your specific instance of the remoting agent l # Data Binding Agent ####################################################################################### -my-provider-agent: +my-provider-agent: securityContext: *securityContext nameOverride: my-provider-agent fullnameOverride: my-provider-agent @@ -326,14 +327,14 @@ my-provider-agent: cpu: 500m # you should employ 512Mi per endpoint memory: 1Gi - bindings: + bindings: # disables the default sample binding dtc: null # real production mapping - telematics2: + telematics2: port: 8081 path: /t2/(.*) - settings: + settings: jdbc.url: 'jdbc:postgresql://intradb:5432/schema' jdbc.user: jdbc.password: @@ -369,7 +370,7 @@ my-provider-agent: target <{vehicle_id}> cx-vehicle:hasPart <{gearbox_id}> . source SELECT vehicle_id, gearbox_id FROM vehicles - ]] + ]] ingresses: - enabled: true # -- The hostname to be used to precisely map incoming traffic onto the underlying network service @@ -384,8 +385,3 @@ my-provider-agent: enabled: true secretName: my-provider-tls ``` - - - - - diff --git a/remoting/README.md b/remoting/README.md index 484cf153..39abeb27 100644 --- a/remoting/README.md +++ b/remoting/README.md @@ -96,25 +96,25 @@ When a concrete query is sent to the RDF4J controller, a [Remoting SAIL Connecti is setup which evaluates the query with the help of the stateful [Query Executor](src/main/java/org/eclipse/tractusx/agents/remoting/QueryExecutor.java). With the help of the Remoting Sail Configuraiton, The Query Executor instantiates all function nodes as [Invocations](src/main/java/org/eclipse/tractusx/agents/remoting/Invocation.java). During processing, input and output variables are accessed and stored in a BindingSet Collection for which the Query Executor implements the [IBindingHost](src/main/java/org/eclipse/tractusx/agents/remoting/IBindingHost.java). ```sparql -PREFIX xsd: -PREFIX prognosis: +PREFIX xsd: +PREFIX prognosis: -SELECT ?name ?invocation ?prediction ?support -WHERE { +SELECT ?name ?invocation ?prediction ?support +WHERE { VALUES (?name) { "Schorsch"^^xsd:string } - ?invocation a prognosis:Prognosis; - prognosis:name ?name; + ?invocation a prognosis:Prognosis; + prognosis:name ?name; prognosis:prediction ?prediction; prognosis:support ?support. } ``` Currently, there are two principle methods of function bindings available -* Class Binding ([Service Config](src/main/java/org/eclipse/tractusx/agents/remoting/config/ServiceConfig.java).targetUri follows the pattern "class:#") +* Class Binding ([Service Config](src/main/java/org/eclipse/tractusx/agents/remoting/config/ServiceConfig.java).targetUri follows the pattern "class:#") * REST Binding ([Service Config](src/main/java/org/eclipse/tractusx/agents/remoting/config/ServiceConfig.java)targetUri follows the pattern "https?://") For REST Binding, we support the following outgoing request formats/content types (being configured via [Service Config](src/main/java/org/eclipse/tractusx/agents/remoting/config/ServiceConfig.java).method). Note that responses are always interpreted as XML or JSON depending on the response content type. -* GET: Input arguments are mapped to URL query parameters. +* GET: Input arguments are mapped to URL query parameters. * POST-XML: Input Arguments are mapped into an XML document body with content-type "application/xml" T * POST-JSON: Input Arguments are mapped into an JSON document body with content-type "application/json" * POST-JSON-MF: Input Arguments are mapped into JSON-based files send in a multi-part request with content-type multipart/form-data (and XXX as boundary and "application/json" as Content-Disposition) @@ -124,7 +124,7 @@ Invocations can be batched. Normally ([Service Config](src/main/java/org/eclipse there is some [Argument Config](src/main/java/org/eclipse/tractusx/agents/remoting/config/ArgumentConfig.java).formsBatchGroup set to true, several tuples/bindings can be sent in a single invocation (usually in an array or by using flexible argument paths using '{}' path elements). In that case, we also expect the responses to contain several individual results which are mapped/joined with the original input bindings using the ResultConfig.correlationInput reference. Invocation can be asynchronous. That means that the called backend will not return a proper response, just a successful notification code. Instead we send the public URL of the builtin [CallbackController](src/main/java/org/eclipse/tractusx/agents/remoting/callback/CallbackController.java) which is configured in the callbackAddress property of the remoting repository (and is transmitted in the callbackAddressProperty of the ServiceConfig). In order to correlate outgoing (batch) requests with asynchronous responses sent to the CallbackController, we rely on setting a unique request identifier specified in ServiceConfig.invocationIdProperty and comparing it with the content of the ResultConfig.callbackProperty - + ## Deployment ### Compile, Test & Package @@ -133,7 +133,7 @@ Invocation can be asynchronous. That means that the called backend will not retu mvn package ``` -This will generate +This will generate - a [standalone jar](target/remoting-agent-1.10.15-SNAPSHOT.jar) containing all necessary rdf4j components to build your own repository server. - a [pluging jar](target/original-remoting-agent-1.10.15-SNAPSHOT.jar) which maybe dropped into an rdf4j server for remoting support. @@ -188,19 +188,20 @@ You may manipulate any of the following environment variables to configure the i Note that there is no builtin security (ssl/auth) for the exposed endpoints. This must be provided by hiding them in an appropriate service network layer. -| ENVIRONMENT VARIABLE | Required | Example | Description | List | -|--- |--- |--- |--- | --- | -| JAVA_TOOL_OPTIONS | | -agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=*:8090 | JMV (Debugging option) | X | +| ENVIRONMENT VARIABLE | Required | Example | Description | List | +|----------------------|----------|----------------------------------------------------------------------|------------------------|------| +| JAVA_TOOL_OPTIONS | | -agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=*:8090 | JMV (Debugging option) | X | ### Notice for Docker Image DockerHub: https://hub.docker.com/r/tractusx/remoting-agent Eclipse Tractus-X product(s) installed within the image: -GitHub: https://github.com/eclipse-tractusx/knowledge-agents/tree/main/remoting -Project home: https://projects.eclipse.org/projects/automotive.tractusx -Dockerfile: https://github.com/eclipse-tractusx/knowledge-agents/blob/main/remoting/src/main/docker/Dockerfile -Project license: Apache License, Version 2.0 + +- GitHub: https://github.com/eclipse-tractusx/knowledge-agents/tree/main/remoting +- Project home: https://projects.eclipse.org/projects/automotive.tractusx +- Dockerfile: https://github.com/eclipse-tractusx/knowledge-agents/blob/main/remoting/src/main/docker/Dockerfile +- Project license: Apache License, Version 2.0 **Used base image** @@ -240,7 +241,7 @@ In your values.yml, you configure your specific instance of the remoting agent l # API Binding Agent ############################################################################################## -my-remoting-agent: +my-remoting-agent: securityContext: *securityContext nameOverride: my-remoting-agent fullnameOverride: my-remoting-agent @@ -285,9 +286,9 @@ my-remoting-agent: cx-fx:supportsInvocation prognosis:Prognosis; ] ]. - + # Function declaration - + prognosis:Prognosis rdf:type cx-fx:Function; dcterms:description "Prognosis is a sample simulation function with input and output bindings."@en ; dcterms:title "Prognosis" ; @@ -296,31 +297,26 @@ my-remoting-agent: cx-common:authenticationKey "Dummy-Key"; cx-fx:input prognosis:name; cx-fx:result prognosis:hasResult. - + prognosis:name rdf:type cx-fx:Argument; dcterms:description "Name is an argument to the Prognosis function."@en ; dcterms:title "Name"; cx-fx:argumentName "name". - + prognosis:hasResult rdf:type cx-fx:Result; cx-fx:output prognosis:prediction; cx-fx:output prognosis:support. - + prognosis:prediction rdf:type cx-fx:ReturnValue; dcterms:description "Prediction (Value) is an integer-based output of the Prognosis function."@en ; dcterms:title "Prediction" ; cx-fx:valuePath "age"; cx-fx:dataType xsd:int. - + prognosis:support rdf:type cx-fx:ReturnValue; dcterms:description "Support (Value) is another integer-based output of the Prognosis function."@en ; dcterms:title "Support" ; cx-fx:valuePath "count"; cx-fx:dataType xsd:int. - -``` - - - - +```