Merge pull request #109 from catenax-ng/main

Documentation housekeeping and release of IRS 2.5.1
eclipse-tractusx · Apr 28, 2023 · 5dcfbe8 · 5dcfbe8
2 parents 86dbf8a + a2f4ddc
commit 5dcfbe8
Show file tree

Hide file tree

Showing 12 changed files with 43 additions and 71 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -5,12 +5,13 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
-### Changed
-- Replaced Discovery Service mock with real implementation
 
 ### Known knowns
 - PLACEHOLDER REMOVE IF EMPTY: risks that were introduced or discovered in the release and are known but not resolved
-
+- 
+## [2.5.1] - 2023-04-28
+### Changed
+- Replaced Discovery Service mock with real implementation
 
 ## [2.5.0] - 2023-04-17
 ### Added
@@ -205,7 +206,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Unresolved
 - **Select Aspects you need**  You are able to select the needed aspects for which you want to collect the correct endpoint information.
 
-[Unreleased]: https://github.com/eclipse-tractusx/item-relationship-service/compare/2.5.0...HEAD
+[Unreleased]: https://github.com/eclipse-tractusx/item-relationship-service/compare/2.5.1...HEAD
+[2.5.1]: https://github.com/eclipse-tractusx/item-relationship-service/compare/2.5.0...2.5.1
 [2.5.0]: https://github.com/eclipse-tractusx/item-relationship-service/compare/2.4.0...2.5.0
 [2.4.1]: https://github.com/eclipse-tractusx/item-relationship-service/compare/2.4.0...2.4.1
 [2.4.0]: https://github.com/eclipse-tractusx/item-relationship-service/compare/2.3.2...2.4.0

diff --git a/charts/irs-helm/CHANGELOG.md b/charts/irs-helm/CHANGELOG.md
@@ -5,11 +5,17 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
+
+## [5.2.0] - 2023-04-28
 ### Added
 - New config entries for portal user, used to call discovery service
   - `portal.oauth2.clientId`
   - `portal.oauth2.clientSecret`
 
+### Changed
+- Updated IRS version to 2.5.1
+
+
 ## [5.1.1] - 2023-04-17
 ### Fixed
 - Added missing config keys in the spring config map template

diff --git a/charts/irs-helm/Chart.yaml b/charts/irs-helm/Chart.yaml
@@ -38,14 +38,14 @@ type: application
 # This is the chart version. This version number should be incremented each time you make changes
 # to the chart and its templates, including the app version.
 # Versions are expected to follow Semantic Versioning (https://semver.org/)
-version: 5.1.1
+version: 5.2.0
 
 
 # This is the version number of the application being deployed. This version number should be
 # incremented each time you make changes to the application. Versions are not expected to
 # follow Semantic Versioning. They should reflect the version the application is using.
 # It is recommended to use it with quotes.
-appVersion: "2.5.0"
+appVersion: "2.5.1"
 
 
 dependencies:

diff --git a/docs/src/docs/administration/configuration.adoc b/docs/src/docs/administration/configuration.adoc
@@ -14,7 +14,7 @@ include::irs-spring-config.adoc[leveloffset=+1]
 
 [source,yaml]
 ----
-include::../../../../charts/irs-helm/values.yaml[lines=83..248]
+include::../../../../charts/irs-helm/values.yaml[lines=104..287]
 ----
 
 <1> Use this to enable or disable the monitoring components

diff --git a/docs/src/docs/administration/installation.adoc b/docs/src/docs/administration/installation.adoc
@@ -31,7 +31,7 @@ Create a new Helm chart and use the IRS as a dependency.
 dependencies:
   - name: irs-helm
     repository: https://eclipse-tractusx.github.io/item-relationship-service
-    version: 3.x.x
+    version: 5.x.x
   - name: irs-edc-consumer # optional
     repository: https://eclipse-tractusx.github.io/item-relationship-service
     version: 1.x.x

diff --git a/docs/src/docs/administration/troubleshooting.adoc b/docs/src/docs/administration/troubleshooting.adoc
@@ -28,4 +28,4 @@ It can also happen if the persistent volume claim is deleted / recreated.
 
 === Different Job model versions maintenance
 
-Currently, the IRS only supports one version of the Job model at a time. This means that if Job model is changed, old models stored in minio will no longer be supported and returned from IRS endpoints. The IRS application will work as usual, old versions of Job can stay in the minio and don't need to be removed - the IRS will simply ignore them. If you want to clear the minio from old models - the only way to achieve that is to delete them all and register a new Jobs.
+Currently, the IRS only supports one version of the Job model at a time. This means that if the Job model is changed in a newer IRS version, old models stored in minio will no longer be supported and returned from IRS endpoints. The IRS application will work as usual, old versions of Job can stay in Minio and don't need to be removed - the IRS will simply ignore them. If you want to clear the minio from old models, the only way to achieve that is to delete them all and register new Jobs.
diff --git a/docs/src/docs/arc42/building-block-view/level-1.adoc b/docs/src/docs/arc42/building-block-view/level-1.adoc
@@ -33,21 +33,25 @@ The result is an item graph in which each node represents a digital item of the
 |The *RecursiveJobHandler* handles the job execution recursively until a given abort criteria is reached or the complete item graph is build.
 
 |*TransferProcessManager*
-a| The TransferProcessManager handles the outgoing requests to the AASProxy.
+a| The TransferProcessManager handles the outgoing requests to the various data services.
+A job is processed in this order:
 
 1. Initiation of the job and preparation of the stream of *DataRequests*
 2. *RecursiveJobHandler* requesting for AAS via the Digital Twin registry.
-3. Analyzing the structure of the AAS response by collecting the AssemblyPartRelationship Aspects
-4. Requesting for SubmodelEndpoints for given AssemblyPartRelationship children
+3. Analyzing the structure of the AAS response by collecting the traversal aspect.
+4. Requesting submodel data for given items of next level.
 5. Recursively iteration over step 2-4 until an abort criterion is reached.
-6. Assembles the complete item graph
+6. Assembles the complete item graph.
 
 |*BlobStore*
 |The BlobStore is the database where the relationships and tombstones are stored for a requested item.
 
 |*JobStore*
 |The JobStore is the database where the jobs with the information about the requested item are stored.
 
-|*AASProxy*
-|The AASProxy is the interface to the EDC Network. It provides an interface for the Asset Administration Shells and for the Submodels.
+|*Digital Twin Client*
+|The Digital Twin Client is the interface to the Digital Twin Registry. It provides an interface for the Asset Administration Shells.
+
+|*EDC Client*
+|The EDC Client is used to communicate with the EDC network, negotiate contracts and retrieve submodel data.
 |===
diff --git a/docs/src/docs/arc42/building-block-view/level-2.adoc b/docs/src/docs/arc42/building-block-view/level-2.adoc
@@ -2,7 +2,7 @@
 
 == IRS controller
 
-The IRS REST controller to provide a RESTful web service.
+The IRS REST controller is used to provide a RESTful web service.
 
 === Component diagram
 
@@ -63,7 +63,7 @@ include::../../../uml-diagrams/building-block-view/level-2-int-recursive-job-han
 |Interface for storing data blobs.
 |===
 
-== TransferProcessManagment
+== TransferProcessManagement
 
 The TransferProcessManager creates executions and provides them to the executor service. Each execution contains HTTP requests to the asset administration shell registry and to the submodel interface.
 

diff --git a/docs/src/docs/arc42/cross-cutting/development-concepts.adoc b/docs/src/docs/arc42/cross-cutting/development-concepts.adoc
@@ -30,5 +30,5 @@ The IRS utilizes the configuration mechanism provided by Spring Boot. Configurat
 
 For local testing purposes, there is an additional configuration file called `+application-local.yml+`. Values can be overriden there to support the local dev environment.
 
-Other profiles should be avoided. Instead, any value that might need to change in a runtime environment must be overridable using environment variables. The operator must have total control over the configuration of the IRS.
+Other profiles should be avoided. Instead, the configuration can be overwritten using Spring's external configuration mechanism (see https://docs.spring.io/spring-boot/docs/2.1.9.RELEASE/reference/html/boot-features-external-config.html). The operator must have total control over the configuration of the IRS.
 
diff --git a/docs/src/docs/arc42/cross-cutting/safety-security.adoc b/docs/src/docs/arc42/cross-cutting/safety-security.adoc
@@ -5,8 +5,8 @@
 The IRS is secured using OAuth2.0 / Open ID Connect. Every request to the IRS API requires a valid bearer token.
 JWT token should also contain two fields:
 
-- 'view irs' role inside resource_access claim,
-- bpn claim which is equal to the configuration value from 'API_ALLOWED_BPN' property
+- `view_irs` role inside `resource_access` claim,
+- BPN claim which is equal to the configuration value from `API_ALLOWED_BPN` property
 
 === IRS as DTR client
 The IRS acts as a client for the Digital Twin Registry (DTR), which is also secured using OAuth2.0 / Open ID Connect. The IRS uses client credentials to authenticate requests to the DTR. Due to this, the IRS account needs to have access to every item in the DTR, unrelated to the permissions of the account calling the IRS API.

diff --git a/docs/src/uml-diagrams/building-block-view/building-block-view.puml b/docs/src/uml-diagrams/building-block-view/building-block-view.puml
@@ -6,7 +6,7 @@ skinparam shadowing false
     component [**RecursiveJobHandler**] <<Component>> as RecursiveJobHandler
     component [**IrsController**] <<Component>> as IrsController
     component [**JobOrchestrator**] <<Component>> as JobOrchestrator
-    component [**TransferProcessManagment**] <<Component>> as TransferProcessManagment
+    component [**TransferProcessManagment**] <<Component>> as TransferProcessManagement
 
 
     'component [**AASClient**] <<Subsystem>> as AASClient
@@ -15,26 +15,30 @@ skinparam shadowing false
     'component [**SubmodelFacade**] <<Subsystem>> as SubmodelFacade ' --> Level2 View
 
     port "IRS API" as API_PORT
-    port "AAS Proxy" as AAS_PORT
+    port "Digital Twin Client" as AAS_PORT
+    port "EDC Client" as EDC_PORT
 
     () "BlobStore\nInterface" as StoreInterface
 
 
     IrsController <..> JobOrchestrator
-    JobOrchestrator <..> TransferProcessManagment
+    JobOrchestrator <..> TransferProcessManagement
     JobOrchestrator <..> RecursiveJobHandler
-    TransferProcessManagment --( StoreInterface
+    TransferProcessManagement --( StoreInterface
 
 
 }
-component [**AASProxy**] <<System>> as AASProxy
+component [**Digital Twin Registry**] <<System>> as DTR
+component [**EDC**] <<System>> as EDC
 actor IrsApiConsumer
 IrsController -up- API_PORT
 IrsApiConsumer -(0- API_PORT
 
 
-TransferProcessManagment --- AAS_PORT
-AAS_PORT -(0 AASProxy
+TransferProcessManagement --- AAS_PORT
+TransferProcessManagement --- EDC_PORT
+AAS_PORT -(0 DTR
+EDC_PORT -(0 EDC
 
 database "BlobStore" as BlobStore
 StoreInterface -down- BlobStore

diff --git a/uml-diagrams/component-diagram/job-orchistration-component.puml b/uml-diagrams/component-diagram/job-orchistration-component.puml
Original file line number	Diff line number	Diff line change
Expand Up		@@ -28,4 +28,4 @@ It can also happen if the persistent volume claim is deleted / recreated.

		=== Different Job model versions maintenance

		Currently, the IRS only supports one version of the Job model at a time. This means that if Job model is changed, old models stored in minio will no longer be supported and returned from IRS endpoints. The IRS application will work as usual, old versions of Job can stay in the minio and don't need to be removed - the IRS will simply ignore them. If you want to clear the minio from old models - the only way to achieve that is to delete them all and register a new Jobs.
		Currently, the IRS only supports one version of the Job model at a time. This means that if the Job model is changed in a newer IRS version, old models stored in minio will no longer be supported and returned from IRS endpoints. The IRS application will work as usual, old versions of Job can stay in Minio and don't need to be removed - the IRS will simply ignore them. If you want to clear the minio from old models, the only way to achieve that is to delete them all and register new Jobs.
Original file line number	Diff line number	Diff line change
Expand Up		@@ -30,5 +30,5 @@ The IRS utilizes the configuration mechanism provided by Spring Boot. Configurat

		For local testing purposes, there is an additional configuration file called `+application-local.yml+`. Values can be overriden there to support the local dev environment.

		Other profiles should be avoided. Instead, any value that might need to change in a runtime environment must be overridable using environment variables. The operator must have total control over the configuration of the IRS.
		Other profiles should be avoided. Instead, the configuration can be overwritten using Spring's external configuration mechanism (see https://docs.spring.io/spring-boot/docs/2.1.9.RELEASE/reference/html/boot-features-external-config.html). The operator must have total control over the configuration of the IRS.