diff --git a/docs/tutorials/e2e/CHANGELOG.md b/docs/tutorials/e2e/CHANGELOG.md index 926309322df..e7eeddd92a4 100644 --- a/docs/tutorials/e2e/CHANGELOG.md +++ b/docs/tutorials/e2e/CHANGELOG.md @@ -4,6 +4,16 @@ All notable changes to this tutorial will be documented in this file. +## [1.1.0] - 2024-12-19 + +### Changed + +:::note +Most of the content is redundant to [umbrella repository](https://github.com/eclipse-tractusx/tractus-x-umbrella) and related [description](https://github.com/eclipse-tractusx/tractus-x-umbrella/blob/main/docs/README.md) +::: + +- Delete redundant content and forward to umbrella helm chart description + ## [1.0.0] - 2024-06-24 ### Added diff --git a/docs/tutorials/e2e/boost/boost.md b/docs/tutorials/e2e/boost/boost.md index bc0e2475113..b40838a891b 100644 --- a/docs/tutorials/e2e/boost/boost.md +++ b/docs/tutorials/e2e/boost/boost.md @@ -5,6 +5,30 @@ sidebar_position: 5 In the `Boost Chapter`, you will configure and register your components so that they are discoverable in your local data space deployment. You will then take on the role of a data provider, build your first data pipeline, add your first `assets`, `policies` and create a `contract offer` in the EDC. As a data consumer you will discover the data that you have previously created and initiate a data transfer. After completing this step, you have all the foundational knowledge you need to get started with active participation in a use-case. +In this **Boost Chapter**, you will create and request different assets and learn how the management-api works. The following steps will guide you through the process: + +1. **Data Provider Role**: + - Build your first data pipeline. + - Add your first `assets`, `policies`, and create a `contract offer`. + +2. **Data Consumer Role**: + - Discover the data you previously created. + - Initiate a data transfer. + +By the end of this chapter, you will have the foundational knowledge needed to share data within your data space. + +:::note + +This chapter is described within the guides for the Tractus-X umbrella charts following the [link](https://github.com/eclipse-tractusx/tractus-x-umbrella/blob/main/docs/README.md) + +Important chapters are: + +- [Data Exchange](https://github.com/eclipse-tractusx/tractus-x-umbrella/blob/main/docs/user/guides/data-exchange.md) + - [Provide Data](https://github.com/eclipse-tractusx/tractus-x-umbrella/blob/main/docs/user/guides/data-exchange/provide-data.md) + - [Consume Data](https://github.com/eclipse-tractusx/tractus-x-umbrella/blob/main/docs/user/guides/data-exchange/consume-data.md) + +::: + ## Notice This work is licensed under the [CC-BY-4.0](https://creativecommons.org/licenses/by/4.0/legalcode). diff --git a/docs/tutorials/e2e/boost/consumeData.md b/docs/tutorials/e2e/boost/consumeData.md deleted file mode 100644 index 7215ee8ef45..00000000000 --- a/docs/tutorials/e2e/boost/consumeData.md +++ /dev/null @@ -1,301 +0,0 @@ ---- -title: Consume data -sidebar_position: 3 ---- - -This step continues the journey of our data consumer Alice. After the data provider Bob has successfully provided his data as a contract definition in his catalog. Alice will now consume the data. - -We will use plain CLI tools (`curl`) for this, but feel free to use graphical tools such as Postman or Insomnia. - -## Request the catalog - -To see Bob's data offerings, Alice must request access to his catalog. The catalog shows all the assets that Alice can consume from Bob. - -So Alice requests Bob's catalog using the following `curl` commands: - -```shell -curl --location 'http://dataconsumer-1-controlplane.tx.test/management/v2/catalog/request' \ ---header 'Content-Type: application/json' \ ---header 'X-Api-Key: TEST1' \ ---data-raw '{ - "@context": {}, - "protocol": "dataspace-protocol-http", - "counterPartyAddress": "http://dataprovider-controlplane.tx.test/api/v1/dsp", - "querySpec": { - "offset": 0, - "limit": 100 - } -}' | jq -``` - -The response shows all available data offerings in Bob's catalog. Bob has already told Alice that he gave the Asset the ID 3, and added a simple description to make it easier for Alice to identify. - -Alice finds the Asset with the ID 3 and the description "Product EDC Demo Asset 3" in the catalog. Now that she is sure which Asset she wants to consume, she wants to start the data transfer. - -## Negotiate a contract - -:::info -Dont forget to change the `offerId`with the one you received in the previous step in your catalog request. -::: - -But before she can transfer the data, she must negotiate the contract with Bob. To do this, she uses the following `curl` command: - -```shell -curl --location 'http://dataconsumer-1-controlplane.tx.test/management/v2/contractnegotiations' \ ---header 'Content-Type: application/json' \ ---header 'X-Api-Key: TEST1' \ ---data-raw '{ - "@context": { - "odrl": "http://www.w3.org/ns/odrl/2/" - }, - "@type": "NegotiationInitiateRequestDto", - "connectorAddress": "http://dataprovider-controlplane.tx.test/api/v1/dsp", - "protocol": "dataspace-protocol-http", - "providerId": "BPNL00000003AYRE", - "offer": { - "offerId": "Mw==:Mw==:NTYzYWRkYTItNmEzMy00YTNhLWFmOTQtYjVjOWM0ZDMyODA1", - "assetId": "3", - "policy": { - "@type": "odrl:Set", - "odrl:permission": [], - "odrl:prohibition": [], - "odrl:obligation": [], - "odrl:target": "3" - } - } -}' | jq -``` - -The response should look like this: - -```json -{ - "@type": "edc:IdResponse", - "@id": "65356596-dd7c-4ad4-8fc6-8512be6f0ec2", - "edc:createdAt": 1715669329095, - "@context": { - "dct": "http://purl.org/dc/terms/", - "tx": "https://w3id.org/tractusx/v0.0.1/ns/", - "edc": "https://w3id.org/edc/v0.0.1/ns/", - "dcat": "https://www.w3.org/ns/dcat/", - "odrl": "http://www.w3.org/ns/odrl/2/", - "dspace": "https://w3id.org/dspace/v0.8/" - } -} -``` - -In the response, Alice gets a UUID (attribute is `@id`). This is the ID of the created contract negotiation. Alice can now use this ID to see the current status of the negotiation and - if the negotiation was successful - the ID of the created contract agreement. - -:::tip -Make sure to replace `` in the URL with the UUID you just received. in the current case the UUID is `65356596-dd7c-4ad4-8fc6-8512be6f0ec2`. So the curl command should look like this: - -```shell -curl --location 'http://dataconsumer-1-controlplane.tx.test/management/v2/contractnegotiations/65356596-dd7c-4ad4-8fc6-8512be6f0ec2' \ ---header 'X-Api-Key: TEST1' | jq -``` - -::: - -```shell -curl --location 'http://dataconsumer-1-controlplane.tx.test/management/v2/contractnegotiations/' \ ---header 'X-Api-Key: TEST1' | jq -``` - -- If the negotiation was **successful**, Alice will see an ouput as shown below. -- If the negotiation was **unsuccessful**, the negotiation state (`edc:state`) will be `TERMINATED` and no contract agreement ID will be present. - -```json -{ - "@type": "edc:ContractNegotiation", - "@id": "65356596-dd7c-4ad4-8fc6-8512be6f0ec2", - "edc:type": "CONSUMER", - "edc:protocol": "dataspace-protocol-http", - "edc:state": "FINALIZED", - "edc:counterPartyId": "BPNL00000003AYRE", - "edc:counterPartyAddress": "http://dataprovider-controlplane.tx.test/api/v1/dsp", - "edc:callbackAddresses": [], - "edc:createdAt": 1715669329095, - "edc:contractAgreementId": "Mw==:Mw==:N2RhZGI3OGMtYzUxNC00OTkzLWI3MzktNDE3YmJhMDNkMDU4", - "@context": { - "dct": "http://purl.org/dc/terms/", - "tx": "https://w3id.org/tractusx/v0.0.1/ns/", - "edc": "https://w3id.org/edc/v0.0.1/ns/", - "dcat": "https://www.w3.org/ns/dcat/", - "odrl": "http://www.w3.org/ns/odrl/2/", - "dspace": "https://w3id.org/dspace/v0.8/" - } -} -``` - -Alice now has a contract with Bob and can begin transferring the asset's data. - -## Starting the data transfer - -Alice wants to send the data to her backend application (""). So she uses the following command to direct the data from Asset 3 to her desired data sink. - -:::warning - -For testing purposes, you should replace `` with your own test API or use [webhook.site](https://webhook.site/) as your backend system. -If you do not change this, you will not be able to view the received token, which is required for requesting the data! -If you are using webhook.site, please make sure that you use "Your unique URL" and that you do not transfer any sensitive information to webhook. - -Replace `` with the contract agreement ID you received in the previous step. -::: - -```shell -curl --location 'http://dataconsumer-1-controlplane.tx.test/management/v2/transferprocesses' \ ---header 'Content-Type: application/json' \ ---header 'X-Api-Key: TEST1' \ ---data-raw '{ - "@context": { - "odrl": "http://www.w3.org/ns/odrl/2/" - }, - "assetId": "3", - "connectorAddress": "http://dataprovider-controlplane.tx.test/api/v1/dsp", - "connectorId": "BPNL00000003AYRE", - "contractId": "", - "dataDestination": { - "type": "HttpProxy" - }, - "privateProperties": { - "receiverHttpEndpoint": "" - }, - "protocol": "dataspace-protocol-http", - "transferType": { - "contentType": "application/octet-stream", - "isFinite": true - } -}' | jq -``` - -The response in this case looks like this: - -```json -{ - "@type": "edc:IdResponse", - "@id": "9d6a0507-25f5-4a81-8885-a47bc3809451", - "edc:createdAt": 1715669899367, - "@context": { - "dct": "http://purl.org/dc/terms/", - "tx": "https://w3id.org/tractusx/v0.0.1/ns/", - "edc": "https://w3id.org/edc/v0.0.1/ns/", - "dcat": "https://www.w3.org/ns/dcat/", - "odrl": "http://www.w3.org/ns/odrl/2/", - "dspace": "https://w3id.org/dspace/v0.8/" - } -} -``` - -Just to make sure everything worked, Alice uses another `curl` command to check if the transfer was successful. - -In the response, Alice gets a UUID. This is the ID of the created transfer. Alice can now use this ID to see the current status of the transfer. - -:::tip -Make sure to replace `` in the URL with the UUID you just received. In our case, the UUID is `9d6a0507-25f5-4a81-8885-a47bc3809451`. So the curl command should look like this: - -```shell -curl --location 'http://dataconsumer-1-controlplane.tx.test/management/v2/transferprocesses/9d6a0507-25f5-4a81-8885-a47bc3809451' \ ---header 'X-Api-Key: TEST1' | jq -``` - -::: - -```shell -curl --location 'http://dataconsumer-1-controlplane.tx.test/management/v2/transferprocesses/' \ ---header 'X-Api-Key: TEST1' | jq -``` - -- If the transfer was **successful**, Alice will see an ouput as shown below. -- If the transfer was **unsuccessful**, the transfer state (`edc:state`) will be `TERMINATED`. - -```json -{ - "@id": "9d6a0507-25f5-4a81-8885-a47bc3809451", - "@type": "edc:TransferProcess", - "edc:correlationId": "9d6a0507-25f5-4a81-8885-a47bc3809451", - "edc:state": "STARTED", - "edc:stateTimestamp": 1715669901450, - "edc:type": "CONSUMER", - "edc:assetId": "3", - "edc:contractId": "Mw==:Mw==:N2RhZGI3OGMtYzUxNC00OTkzLWI3MzktNDE3YmJhMDNkMDU4", - "edc:callbackAddresses": [], - "edc:dataDestination": { - "@type": "edc:DataAddress", - "edc:type": "HttpProxy" - }, - "edc:connectorId": "BPNL00000003AYRE", - "@context": { - "dct": "http://purl.org/dc/terms/", - "tx": "https://w3id.org/tractusx/v0.0.1/ns/", - "edc": "https://w3id.org/edc/v0.0.1/ns/", - "dcat": "https://www.w3.org/ns/dcat/", - "odrl": "http://www.w3.org/ns/odrl/2/", - "dspace": "https://w3id.org/dspace/v0.8/" - } -} -``` - -The response shows her that she has a `STARTED` transfer with the type `CONSUMER` of the asset with the ID `3`. -Note, that a consumer pull transfer will **not** advance to the `COMPLETED` state, but instead will stay in state `STARTED`. -This means, that Alice can now request the data using the information received by her backend. - -:::info - -If you used webhook.site as your backend system, you can now go to [webhook.site](https://webhook.site/) and see the received token. - -::: - -## Consume the data - -In her backend (as already mentioned [webhook.site](https://webhook.site/)) you will now find the following (as an example) entry - -![Consume data backend](/tutorials/e2e/consume_data_backend.png) - -```json -{ - "id": "9d6a0507-25f5-4a81-8885-a47bc3809451", - "endpoint": "http://dataprovider-dataplane.tx.test/api/public", - "authKey": "Authorization", - "authCode": "eyJhbGciOiJSUzI1NiJ9.eyJleHAiOjE3MTU2NzA1MDEsImRhZCI6IjFFQ29ReDRBTy9acmJ6dXEwUlpSY0tYd1hQeW81UmdPZndyRWtIWnpZSStQVGhIUmFuelczeGpXcU5vTzFJa3ZOWUV6SGpEWU5iVEJ5VDgzbzdtVlVsUWZhYUpKSm5CMVJGbFQ1SXM0NHpZQ0RJYWZKNHhmQzZTOFNKaWxjV0x1WURoc24xRjdha2xSZllnemRIMjR3WnJycS9JU0pPZjFzVHNQSHNtcE9PaWZ2S2ZyaElFemtJSEs3OFZUTFBMd0krWmNEK3VZc1FCQkt5NlEvZFBCSkZodWsyMXFiOVU1V3dZWWpPYkZSQjdzUmpZYkNsSlpyaTZzVWFXQU1WOXVsQ2JGS2NPM2xxMERPaWRuQjNqSXJ4blh4Y3JjVHl3MEkzV3JjN2k2ZG1nejlXMTFvYTR5VUpJWU92R1lkdWNXdk1pemk3b01mck5SdXE0SVJ1djR6ai9Cemcxb2NZalB5Y0RvK2I2M0RheWpyWmVNS1c4OGNRUnlvUDdpbExsMVNVVmFlRUxZQ3lieitCYUxpd2x1d0lpcWxFckJrTDNlOXptNGpJYz0iLCJjaWQiOiJNdz09Ok13PT06TjJSaFpHSTNPR010WXpVeE5DMDBPVGt6TFdJM016a3ROREUzWW1KaE1ETmtNRFU0In0.AOt6rXbcK44RD7XNCMN16zjvurzdkMNCki3HkvZ_VJ43eDkCDDbquDSvW0SmEnp9cqhjMbUqnO-iGJheI4TbkIc9dxFouJGtHvKFAjOG7LFSErwvH0yNXus1TPN41BCp_jP1tpH63s3PuRqgdzzn1axkJ57aGo9ibqnKRm7ZhM8pgkReWQpHwlFz3QuOMFWHNmPm_HMePPsUxZM7OpARwgShGMqATHEJmoIff2S1yLLeN0k97JT4BzL7xwM9VB-Yssq1rWxBp3GITcBta5R1EVjzaEZseYn_wxFFmVlXQtu_lkvbgihEsvCgtXI_c-EGZl_gTVe9DMfq4cM2XXfE8A", - "properties": {} -} -``` - -Alice can now request the data using the provided information as follows: - -```shell -curl -X GET -H ': ' -``` - -:::warning -In this example, we can not use the endpoint URL as is, because we are working with a local Kubernetes cluster and can not use the cluster internal URL. Therefore, we have to use the ingress URL instead. -::: - -In this example, this results in the following request: - -```shell -curl -X GET -H 'Authorization: eyJhbGciOiJSUzI1NiJ9.eyJleHAiOjE3MTU2NzA1MDEsImRhZCI6IjFFQ29ReDRBTy9acmJ6dXEwUlpSY0tYd1hQeW81UmdPZndyRWtIWnpZSStQVGhIUmFuelczeGpXcU5vTzFJa3ZOWUV6SGpEWU5iVEJ5VDgzbzdtVlVsUWZhYUpKSm5CMVJGbFQ1SXM0NHpZQ0RJYWZKNHhmQzZTOFNKaWxjV0x1WURoc24xRjdha2xSZllnemRIMjR3WnJycS9JU0pPZjFzVHNQSHNtcE9PaWZ2S2ZyaElFemtJSEs3OFZUTFBMd0krWmNEK3VZc1FCQkt5NlEvZFBCSkZodWsyMXFiOVU1V3dZWWpPYkZSQjdzUmpZYkNsSlpyaTZzVWFXQU1WOXVsQ2JGS2NPM2xxMERPaWRuQjNqSXJ4blh4Y3JjVHl3MEkzV3JjN2k2ZG1nejlXMTFvYTR5VUpJWU92R1lkdWNXdk1pemk3b01mck5SdXE0SVJ1djR6ai9Cemcxb2NZalB5Y0RvK2I2M0RheWpyWmVNS1c4OGNRUnlvUDdpbExsMVNVVmFlRUxZQ3lieitCYUxpd2x1d0lpcWxFckJrTDNlOXptNGpJYz0iLCJjaWQiOiJNdz09Ok13PT06TjJSaFpHSTNPR010WXpVeE5DMDBPVGt6TFdJM016a3ROREUzWW1KaE1ETmtNRFU0In0.AOt6rXbcK44RD7XNCMN16zjvurzdkMNCki3HkvZ_VJ43eDkCDDbquDSvW0SmEnp9cqhjMbUqnO-iGJheI4TbkIc9dxFouJGtHvKFAjOG7LFSErwvH0yNXus1TPN41BCp_jP1tpH63s3PuRqgdzzn1axkJ57aGo9ibqnKRm7ZhM8pgkReWQpHwlFz3QuOMFWHNmPm_HMePPsUxZM7OpARwgShGMqATHEJmoIff2S1yLLeN0k97JT4BzL7xwM9VB-Yssq1rWxBp3GITcBta5R1EVjzaEZseYn_wxFFmVlXQtu_lkvbgihEsvCgtXI_c-EGZl_gTVe9DMfq4cM2XXfE8A' http://dataprovider-dataplane.tx.test/api/public | jq -``` - -:::info -Currently the response for this curl commoand is - -```json -{ - "userId": 1, - "id": 3, - "title": "fugiat veniam minus", - "completed": false -} -``` - -## Notice - -This work is licensed under the [CC-BY-4.0](https://creativecommons.org/licenses/by/4.0/legalcode). - -- SPDX-License-Identifier: CC-BY-4.0 -- SPDX-FileCopyrightText: 2023 sovity GmbH -- SPDX-FileCopyrightText: 2023 SAP SE -- SPDX-FileCopyrightText: 2023 msg systems AG -- SPDX-FileCopyrightText: 2023 Materna Information & Communications SE -- Source URL: [https://github.com/eclipse-tractusx/eclipse-tractusx.github.io](https://github.com/eclipse-tractusx/eclipse-tractusx.github.io) diff --git a/docs/tutorials/e2e/boost/dtrTutorial.md b/docs/tutorials/e2e/boost/dtrTutorial.md deleted file mode 100644 index 84fd0c782f2..00000000000 --- a/docs/tutorials/e2e/boost/dtrTutorial.md +++ /dev/null @@ -1,433 +0,0 @@ ---- -title: DTR Tutorial -sidebar_position: 5 ---- - -## Tutorial Goal - -Alongside the connector, the Digital Twin Registry (DTR) is an important decentral component deployed by each data provider exchanging digital twins in Catena-X. They must register them in a DTR so that consumers can find relevant data in the provider's data offers. - -This tutorial focuses on the working with the DTR. You will learn what the DTR is, how to deploy it and go through a complete use case scenario by depositing a DTR in the EDC, registering a digital twin in the DTR, and showing how external parties can find and consume the digital twin. - -## Introduction - -Catena-X uses the Asset Administration Shell (AAS) to represent digital twins. Such a digital twin is basically a shell with an ID (usually a UUID) that makes it uniquely identifiable. Also it contains IDs ("specificAssetIds") that connect the shell with the original asset it represents (e.g. the "manufacturerPartId"). The shell also contains SubmodelDescriptors which reference to submodels that contain the actual data of specific aspects of the asset. - -The Digital Twin Registry (DTR) contains a list of all registered digital twins of the owner and therefore acts as an address book for Digital Twins. With the DTR of a data provider, a data consumer can therefore find digital twin and also get directed to the desired submodels of the twin. - -Further details can be found in the [Digital Twin KIT][dt-kit] or the [sldt-digital-twin-registry][sldt-dtr] Github repository. - -In this tutorial, Bob will assume the role of an automotive supplier that manufactures gearboxes and acts as the data provider. Alice represents an OEM that uses these gearboxes. Alice's goal is to calculate the product carbon footprint (PCF) of a car, and she also needs the carbon footprints of the individual parts to calculate the total footprint. Therefore, Alice is the data consumer in this tutorial. - -The steps of the tutorial are as follows - -- Bob registers a DTR at his EDC -- Bob registers a Digital Twin at his DTR -- Alice finds and consumes the Digital Twin - -This tutorial will guide you through the steps outlined above. For a deeper understanding, more detailed documentation will be linked. - -### High Level Architecture - -## Exchange Digital Twins - -### Register a DTR in your EDC - -#### Create the DTR asset - -To ensure that Bob's DTR becomes visible for Alice and to start the data exchange between them, Bob has to create a data asset. - -Action (Bob): Create a data asset using the following command: - -(note: that the "asset:prop:type" is standardized with "data.core.digitalTwinRegistry" for the Digital Twin Registry.) - -```curl --location 'http://dataprovider-controlplane.tx.test/management/v3/assets' \ ---header 'Content-Type: application/json' \ ---header 'X-Api-Key: TEST2' \ ---data-raw '{ - "@context":{ - "edc":"https://w3id.org/edc/v0.0.1/ns/", - "cx-common":"https://w3id.org/catenax/ontology/common#", - "cx-taxo":"https://w3id.org/catenax/taxonomy#", - "dct":"http://purl.org/dc/terms/" - }, - "@id":"{{ASSET_ID}}", - "properties":{ - "dct:type":{ - "@id":"cx-taxo:DigitalTwinRegistry" - } - }, - "dataAddress":{ - "@type":"DataAddress", - "type":"HttpData", - "baseUrl":"{{BACKEND_SERVICE}}", - "proxyPath":"true", - "proxyBody":"true", - "proxyMethod":"false", - "proxyQueryParams":"true", - "oauth2:clientId":"satest02", - "oauth2:clientSecretKey":"{{REGISTRY_CLIENT_SECRET_KEY}}", - "oauth2:tokenUrl":"http://centralidp.tx.test/auth/realms/CX-Central/protocol/openid-connect/token", - "oauth2:scope":"{{REGISTRY_TOKEN_SCOPE}}" - } -}' -``` - -As per the current standards, there is no need to proxy the HTTP method. If there is (for instance due to a proprietary query endpoint), the data provider must ensure thatthat the technical user that the registered credentials abstract does NOT have the power to manipulate the DTR's data (for instance via the `PUT /shell-descriptors/{{aasId}}` API. - -#### Create a policy - -After Bob has created an data asset, he must define a BPN-restrictive policy in order to give Alice access to the asset. This policy is not standardized and can be chosen according to its needs. Bob wants to define the policy that only Alice can see the DTR Asset. - -Action (Bob): Defines the access policy using the following command: - -```curl -{ - "@context": { - "odrl": "http://www.w3.org/ns/odrl/2/" - }, - "@type": "PolicyDefinitionRequestDto", - "@id": "{{POLICY_ID}}", - "policy": { - "@type": "Policy", - "odrl:permission" : [{ - "odrl:action" : "USE", - "odrl:constraint" : { - "@type": "LogicalConstraint", - "odrl:or" : [{ - "@type" : "Constraint", - "odrl:leftOperand" : "BusinessPartnerNumber", - "odrl:operator" : { - "@id": "odrl:eq" - }, - "odrl:rightOperand" : "{{CONSUMER_BPN}}" - }] - } - }] - } -} -``` - -#### Contract Definition - -To offer the DTR in his EDC Catalog, Bob has to create a contract definition. This contains linking the data asset with the policy. - -Action (Bob): Create the contract policy using the following command: - -```curl -{ - "@context": {}, - "@id": "{{CONTRACT_DEFINITION_ID}}", - "@type": "ContractDefinition", - "accessPolicyId": "{{ACCESS_POLICY_ID}}", - "contractPolicyId": "{{CONTRACT_POLICY_ID}}", - "assetsSelector" : { - "@type" : "CriterionDto", - "operandLeft": "{{EDC_NAMESPACE}}id", - "operator": "=", - "operandRight": "{{ASSET_ID}}" - } -} -``` - -The DTR Asset from Bob is now available for Alice to request via contract negotiation. Currently it is still empty. Therefore Bob will register his first digital twin in the next step of this tutorial. - -Continue the tutorial in [Register a Digital](#register-a-digital-twin) Twin. - -### Register a Digital Twin - -The basic steps for providing digital twins with the DTR contain: - -- Create a compliant submodel -- Store the submodel on a submodel server -- Register/create a digital twin at the DTR -- Reference the Submodel in the digital twin - -#### Create a submodel - -Submodels needs to be compliant to the domain specified standards. Bob has already prepaired the submodel he wants to share with Alice. Thefore the first step is already taken care of. - -#### Host/store a submodel - -Bob also needs to store his submodels somewhere. Usually a submodel server is used for this task. For this tutorial a service called "backend-data-service" (short BDS) is provided. This service fulfills the role of the submodel server. It can store any text based data (e.g. JSON, XML, plain text) under a specific ID. This data can be received again, by using the same ID. Bob will use this service to host his data. - -Action (Bob): Store submodel on the BDS using the following command: - -```curl -id="bobs-data" -bdsBaseUrl="http://localhost/bobs-bds" -clusterInternalBdsBaseUrl="http://bobs-bds-bds" - -curl -i -X POST "${bdsBaseUrl}/data/${id}" -H "Content-Type: application/json" --data-raw '{ - "diameter": 380, - "length": 810, - "width": 590, - "weight": 85, - "height": 610 -}' -``` - -#### Create Contract Definition at EDC with the submodel - -Bob has now stored his submodel on the BDS. However, because he wants to preserve data sovereignty over his data, he cannot directly provide access to the BDS. Instead, the data exchange shall take place via the EDC. - -Therefore Bob needs to create an according contract definition. This follows the same three steps as explained in "Create DTR Asset" of creating an data asset, creating a policy and finally creating the contract definition. - -Info: - -edcManagementBaseUrl="" -edcApiKey="password" - -```bash -# Asset -# assetId="$(uuidgen)" -assetId="0bc6a8af-8682-4dba-86b1-0433f9762e42" -clusterInternalBdsBaseUrl="http://bobs-bds-bds:8080" -bdsDataId="bobs-data" -assetUrl="${clusterInternalBdsBaseUrl}/data/${bdsDataId}" - -# Policy -# policyId="$(uuidgen)" -policyId="1bc6a8af-8682-4dba-86b1-0433f9762e42" - -# Contract Definition -# contractDefinitionId="$(uuidgen)" -contractDefinitionId="2bc6a8af-8682-4dba-86b1-0433f9762e42" -``` - -Action (Bob): Create a data asset with the following commands: - -```curl -curl -i -X POST "${edcManagementBaseUrl}/v3/assets" -H "X-Api-Key: ${edcApiKey}" -H "Content-Type: application/json" --data-raw "{ - \"@context\": {}, - \"@id\": \"${assetId}\", - \"properties\": { - \"description\": \"Product EDC Demo Asset\" - }, - \"dataAddress\": { - \"@type\": \"DataAddress\", - \"baseUrl\": \"${assetUrl}\", - \"type\": \"HttpData\" - } -}" | jq -``` - -Action (Bob): Create a Policy with the following commands: - -```curl -curl -i -X POST "${edcManagementBaseUrl}/v2/policydefinitions" -H "X-Api-Key: ${edcApiKey}" -H "Content-Type: application/json" --data-raw "{ - \"@context\": { - \"odrl\": \"http://www.w3.org/ns/odrl/2/\" - }, - \"@type\": \"PolicyDefinitionRequestDto\", - \"@id\": \"${policyId}\", - \"policy\": { - \"@type\": \"Policy\", - \"odrl:permission\": [{ - \"odrl:action\": \"USE\", - \"odrl:constraint\": { - \"@type\": \"LogicalConstraint\", - \"odrl:or\": [] - } - }] - } -}" | jq -``` - -Action (Bob): Create a contract definition with the following commands: - -```curl -curl -i -X POST "${edcManagementBaseUrl}/v2/contractdefinitions" -H "X-Api-Key: ${edcApiKey}" -H "Content-Type: application/json" --data-raw "{ - \"@context\": {}, - \"@id\": \"${contractDefinitionId}\", - \"@type\": \"ContractDefinition\", - \"accessPolicyId\": \"${policyId}\", - \"contractPolicyId\": \"${policyId}\", - \"assetsSelector\" : { - \"@type\" : \"CriterionDto\", - \"operandLeft\": \"https://w3id.org/edc/v0.0.1/ns/id\", - \"operator\": \"=\", - \"operandRight\": \"${assetId}\" - } -}" | jq -``` - -The submodel is now stored at the BDS and made available through a contract definition at the EDC. - -### Access control to Digital Twins Based on the BPN (Business Partner Number)/ TenantId - -The digital twin registry offers two functionalities for managing access control to digital twins (Shells) based on the Business Partner Number (BPN). -On application start, the provider can configure which kind of access control will be activated. - -1. Classic implementation (default is true). This implementation is used for this tutorial: - 1. The visibility of `specificAssetIds` in the Digital Twin Registry based on the Business Partner Number (BPN) (Which is send via header Edc-Bpn) can be controlled with the attribute `externalSubjectId`. Hence, the `externalSubjectId` is identified with the BPN. - 2. The communication between consumer and provider is via EDC. Before the provider EDC sends the request to the DTR, the property Edc-Bpn with the BPN of the consumer will be set by the provider EDC. -2. Granular access control implementation: - 1. The granular access control implementation is provided as an alternative option to enforce visibility rules of the *Digital Twin* details. These can be: - 1. The visibility of the *Digital Twin* as a whole - 2. The visibility of certain `specificAssetId` names and values of the *Digital Twin* - 3. The visibility of certain `submodelDescriptors` of the *Digital Twin* - 4. Restricting access to *Digital Twin* details which are `"PUBLIC_READABLE"` - (only showing the `id`, the public readable `specificAssetId` names and values, the `createdDate` and the filtered `submodelDescriptors` ) - 5. To enable granular access control (instead of the classic implementation), the `registry.useGranularAccessControl` configuration HELM chart property must be set to `"true"`. - -For more details see: [DTR Access control to Digital Twins Based on the BPN (Business Partner Number)/ TenantId](https://github.com/eclipse-tractusx/sldt-digital-twin-registry/blob/main/docs/README.md#:~:text=dev%40eclipse.org-,Access,-control%20to%20Digital) - -#### Register/create a Digital Twin at the DTR - -Now that Bob has stored his submodel at the BDS and offered it at the EDC for sovereign data exchange, he wants to make it findable via the DTR. This contains two steps: - -- Register/create a Digital Twin at the DTR -- Reference the submodel in the Digital Twin - -The registration of a digital twin in Catena-X is equivalent to the creation of a new digital twin. Thus, Bob should always ensure that there is no digital twin created for the respective “specificAssetIds” yet to avoid duplicates. - -Action (Bob): Create a new digital twin at the DTR with the following command: - -```curl -POST /shell-descriptors -{ - "id": "urn:uuid:e5c96ab5-896a-1234-8761-efd74777ca97", - "idShort": "myAas", - "specificAssetIds": [ - { - "name": "manufacturerPartId", - "value": "123-345-567103", - "externalSubjectId": { - "type": "ExternalReference", - "keys": [ - { - "type": "GlobalReference", - "value": "{{BPN of the party privileged}}" - } - ] - } - } - ] -} - ``` - -Bob has now successfully created/registered a Digital Twin at his DTR. Right now the Digital Twin is pretty empty, except the AAS-ID and the specificAssetIds. -Thus, the next step for Bob is to reference his submodel in the Digital Twin to make it findable for consumers. - -#### Reference a Submodel in the Digital Twin - -In order to reference the submodel in the digital twin, submodel descriptors can be added to the digital twin. - -When adding a submodel to an existing digital twin, it is important to use the correct AAS-Id. This has to be added for the parameter "id", e.g. "id": "e5c96ab5-896a-482c-8761-efd74777ca97". - -To reference the endoint of the submodel we use the DSP protocol. Thus you have to provide the subprotocolBody with the Id of the asset as well as the dspEndpoint of the EDC. - -```curl -POST /shell-descriptors/{{aasId}} - -{ - "id": "e5c96ab5-896a-482c-8761-efd74777ca97", - "semanticId": { - "type": "ExternalReference", - "keys": [ - { - "type": "GlobalReference", - "value": "urn:bamm:io.catenax.material_for_recycling:1.1.0#MaterialForRecycling" - } - ] - }, - "endpoints": [ - { - "interface": "SUBMODEL-3.0", - "protocolInformation": { - "href": "https://edc.data.plane/mypath/submodel", - "endpointProtocol": "HTTP", - "endpointProtocolVersion": [ - "1.1" - ], - "subprotocol": "DSP", - "subprotocolBody": "id=123;dspEndpoint=http://edc.control.plane/api/v1/dsp", - "subprotocolBodyEncoding": "plain", - "securityAttributes": [ - { - "type": "NONE", - "key": "NONE", - "value": "NONE" - } - ] - } - } - ] -} -``` - -Bob has now successfully added a submodel descriptor to the digital twin and made the Submodel accessible for comsumption. In the next step of the tutorial Alice will find and consume the digital twin and its submodel. - -#### Registering new Submodels at existing Digital Twins - -If you want to add a submodel to an already existing digital twin, you just need to reference the ID (UUID )of the digital twin in the submodel to link the two. - -Lets also go through this process. … - -### Find and consume a Digital Twin - -Alice, the data consumer, now wants to fetch Bob's digital twin. Since she knows Bob, she knows his BPN. With this BPN, she can now determine Bob's EDC endpoint using the EDC Discovery Service. The Discovery Services are not part of this tutorial. So the tutorial starts with Alice already knowing Bob's EDC endpoint. - -In general, Alice's only responsibility is to deploy a connector, negotiate for access and terms of usage and finally fetch the data from the right offers. -A detailed interaction flow is detailed in the [Digital Twin KIT - Fetching a supplier's twin](https://eclipse-tractusx.github.io/docs-kits/kits/Digital%20Twin%20Kit/Software%20Development%20View/dt-kit-interaction-patterns#1-fetching-a-suppliers-twin). - -But step by step. First of all, Alice wants to see Bob's DTR. - -Action (Alice): Use the following API POST to find Bob's DTR Asset. - -`POST /catalog/request with filter looking for DTR` - -You will receive the `dcat:Dataset for Bob's DTR`. A negotiation for the DTR can now take place. You retrieve a token for this, which you get back in return if the negotiation is successful. - -![Step1](/tutorials/e2e/dtr-access-token.png) - -In the second step, Alice can use this access token to access Bob's DTR directly and perform a lookup there. As feedback, she receives the AAS IDs that she is authorised to see. - -Action (Alice): Use the following API GET to receive the provided AAS Ids: - -`GET /lookup/shells?assetIds=xyz` - -Alice receives a list of AAS Ids that she is allowed to see. This should include the digital twin created in the previous tutorial steps. - -![Step2](/tutorials/e2e/dtr-get-aas-ids.png) - -Now Alice can get the AAS descriptors because she now has the AAS IDs. - -Action (Alice): Use the following API GET to the shell descriptors for the AAS ID. - -`GET /shell-descriptors/{{aas-id}} with aas-id encoded base64url` - -In response, Alice receives the AAS descriptor she needs. This contains the submodel descriptors. These contain the location of the submodels. - -![Step3](/tutorials/e2e/dtr-get-descriptor.png) - -Now the process is repeating itself. Alice performs a catalog request again and can now use the dataset IDs as a filter. - -Action (Alice): Use the following API POST to receive Bob's catalog with the Dataset-ID as a filter: - -`POST /catalog/request with filter looking for Dataset-ID` - -A negotiation for the Submodel Server can now take place. Alice retrieves a token for this, which she gets back in return if the negotiation is successful. - -![Step4](/tutorials/e2e/dtr-get-token.png) - -The relevant endpoint on the submodel server can now be accessed directly, which returns the actual data in response. - -Action (Alice): Use the following API GET to receive the data: - -![Step5](/tutorials/e2e/dtr-get-data.png) - -**Congratulations, you've got a first digital twin from a customer!!!** - -## Notice - -This work is licensed under the [CC-BY-4.0](https://creativecommons.org/licenses/by/4.0/legalcode). - -- SPDX-License-Identifier: CC-BY-4.0 -- SPDX-FileCopyrightText: 2024 sovity GmbH -- SPDX-FileCopyrightText: 2024 msg systems AG -- Source URL: - -[dt-kit]: https://eclipse-tractusx.github.io/docs-kits/kits/Digital%20Twin%20Kit/Software%20Development%20View/dt-kit-software-development-view/ -[sldt-dtr]: https://github.com/eclipse-tractusx/sldt-digital-twin-registry/tree/main/docs diff --git a/docs/tutorials/e2e/boost/provideData.md b/docs/tutorials/e2e/boost/provideData.md deleted file mode 100644 index c5a4c33309d..00000000000 --- a/docs/tutorials/e2e/boost/provideData.md +++ /dev/null @@ -1,494 +0,0 @@ ---- -title: Provide data -sidebar_position: 2 ---- - -## Create first data asset - -In this step we will focus on inserting data into our provider connector using -the [Management API](https://app.swaggerhub.com/apis/eclipse-edc-bot/management-api). We will use plain -CLI tools (`curl`) for this, but feel free to use graphical tools such as Postman or Insomnia. - -:::note - -Alice acts here as a data consumer and Bob as a data provider. - -- Bob -> -- Alice -> - -::: - -Alice, as a data consumer, wants to consume data from Bob. Bob, as a data provider, needs to create an asset for Alice. -Action (Bob): Create this asset using the following `curl` command: - -```shell -curl --location 'http://dataprovider-controlplane.tx.test/management/v3/assets' \ ---header 'Content-Type: application/json' \ ---header 'X-Api-Key: TEST2' \ ---data-raw '{ - "@context": {}, - "@type": "Asset", - "@id": "3", - "properties": { - "description": "Product EDC Demo Asset 3" - }, - "dataAddress": { - "@type": "DataAddress", - "type": "HttpData", - "baseUrl": "https://jsonplaceholder.typicode.com/todos/3" - } -}' | jq -``` - -Just to be sure, that the asset was created succesfully, Bob can check the asset using the following `curl` command: - -```shell -curl -X POST http://dataprovider-controlplane.tx.test/management/v2/assets/request -H "x-api-key: TEST2" -H "content-type: application/json" | jq -``` - -The result shows the already existing assets and the newly created asset. - -```json -[ - { - "@id": "registry-asset", - "@type": "edc:Asset", - "edc:properties": { - "edc:type": "data.core.digitalTwinRegistry", - "edc:description": "Digital Twin Registry Endpoint of IRS DEV", - "edc:id": "registry-asset" - }, - "edc:dataAddress": { - "@type": "edc:DataAddress", - "edc:proxyPath": "true", - "edc:type": "HttpData", - "edc:proxyMethod": "true", - "edc:proxyQueryParams": "true", - "edc:proxyBody": "true", - "edc:baseUrl": "http://umbrella-dataprovider-dtr:8080/api/v3.0" - }, - "@context": { - "dct": "http://purl.org/dc/terms/", - "tx": "https://w3id.org/tractusx/v0.0.1/ns/", - "edc": "https://w3id.org/edc/v0.0.1/ns/", - "dcat": "https://www.w3.org/ns/dcat/", - "odrl": "http://www.w3.org/ns/odrl/2/", - "dspace": "https://w3id.org/dspace/v0.8/" - } - }, - { - "@id": "urn:uuid:dc641d45-95e7-4284-a472-43f30255d0cb", - "@type": "edc:Asset", - "edc:properties": { - "edc:description": "IRS EDC Test Asset", - "edc:id": "urn:uuid:dc641d45-95e7-4284-a472-43f30255d0cb" - }, - "edc:dataAddress": { - "@type": "edc:DataAddress", - "edc:proxyPath": "true", - "edc:type": "HttpData", - "edc:proxyMethod": "false", - "edc:proxyQueryParams": "false", - "edc:proxyBody": "false", - "edc:baseUrl": "http://umbrella-dataprovider-submodelserver:8080" - }, - "@context": { - "dct": "http://purl.org/dc/terms/", - "tx": "https://w3id.org/tractusx/v0.0.1/ns/", - "edc": "https://w3id.org/edc/v0.0.1/ns/", - "dcat": "https://www.w3.org/ns/dcat/", - "odrl": "http://www.w3.org/ns/odrl/2/", - "dspace": "https://w3id.org/dspace/v0.8/" - } - }, - { - "@id": "3", - "@type": "edc:Asset", - "edc:properties": { - "edc:description": "Product EDC Demo Asset 3", - "edc:id": "3" - }, - "edc:dataAddress": { - "@type": "edc:DataAddress", - "edc:type": "HttpData", - "edc:baseUrl": "https://jsonplaceholder.typicode.com/todos/3" - }, - "@context": { - "dct": "http://purl.org/dc/terms/", - "tx": "https://w3id.org/tractusx/v0.0.1/ns/", - "edc": "https://w3id.org/edc/v0.0.1/ns/", - "dcat": "https://www.w3.org/ns/dcat/", - "odrl": "http://www.w3.org/ns/odrl/2/", - "dspace": "https://w3id.org/dspace/v0.8/" - } - } -] -``` - -## Request catalog - -Bob tells Alice, that he created an asset, and she should now be able to request it. In the next step, Alice requests a contract offer catalog. In the catalog, all contract offers for Alice are listed. - -Action (Alice): Execute a request using the following `curl` commands: - -```shell -curl --location 'http://dataconsumer-1-controlplane.tx.test/management/v2/catalog/request' \ ---header 'Content-Type: application/json' \ ---header 'X-Api-Key: TEST1' \ ---data-raw '{ - "@context": {}, - "protocol": "dataspace-protocol-http", - "counterPartyAddress": "http://dataprovider-controlplane.tx.test/api/v1/dsp", - "querySpec": { - "offset": 0, - "limit": 100 - } -}' | jq -``` - -The requested catalog looks like this: - -```json -{ - "@id": "be17c3e7-3156-46db-8934-f1ea92d1f2a3", - "@type": "dcat:Catalog", - "dcat:dataset": [ - { - "@id": "registry-asset", - "@type": "dcat:Dataset", - "odrl:hasPolicy": { - "@id": "MTcxODBlMTAtNmFjNS00NTYzLWE2MTUtNGM1MjQ5ZTUxMTU5:cmVnaXN0cnktYXNzZXQ=:NzE0ODk2YjMtY2VlYy00NmY5LWE5ZTgtY2NiMWI1NGUzOTgy", - "@type": "odrl:Set", - "odrl:permission": { - "odrl:target": "registry-asset", - "odrl:action": { - "odrl:type": "USE" - }, - "odrl:constraint": { - "odrl:or": { - "odrl:leftOperand": "PURPOSE", - "odrl:operator": { - "@id": "odrl:eq" - }, - "odrl:rightOperand": "ID 3.0 Trace" - } - } - }, - "odrl:prohibition": [], - "odrl:obligation": [], - "odrl:target": "registry-asset" - }, - "dcat:distribution": [ - { - "@type": "dcat:Distribution", - "dct:format": { - "@id": "HttpProxy" - }, - "dcat:accessService": "49a693e0-835d-457a-99b4-e781f2bd643d" - }, - { - "@type": "dcat:Distribution", - "dct:format": { - "@id": "AmazonS3" - }, - "dcat:accessService": "49a693e0-835d-457a-99b4-e781f2bd643d" - } - ], - "edc:type": "data.core.digitalTwinRegistry", - "edc:description": "Digital Twin Registry Endpoint of IRS DEV", - "edc:id": "registry-asset" - }, - { - "@id": "urn:uuid:dc641d45-95e7-4284-a472-43f30255d0cb", - "@type": "dcat:Dataset", - "odrl:hasPolicy": { - "@id": "MTIzYjJlM2QtNTUxOC00ZWViLWFmMGItNTU5ZTYxZGY3Zjhk:dXJuOnV1aWQ6ZGM2NDFkNDUtOTVlNy00Mjg0LWE0NzItNDNmMzAyNTVkMGNi:YzBhOGFhOTQtNzg4OS00Y2MxLTkzNmMtMWYwMTNkODc3Nzk4", - "@type": "odrl:Set", - "odrl:permission": { - "odrl:target": "urn:uuid:dc641d45-95e7-4284-a472-43f30255d0cb", - "odrl:action": { - "odrl:type": "USE" - }, - "odrl:constraint": { - "odrl:or": { - "odrl:leftOperand": "PURPOSE", - "odrl:operator": { - "@id": "odrl:eq" - }, - "odrl:rightOperand": "ID 3.0 Trace" - } - } - }, - "odrl:prohibition": [], - "odrl:obligation": [], - "odrl:target": "urn:uuid:dc641d45-95e7-4284-a472-43f30255d0cb" - }, - "dcat:distribution": [ - { - "@type": "dcat:Distribution", - "dct:format": { - "@id": "HttpProxy" - }, - "dcat:accessService": "49a693e0-835d-457a-99b4-e781f2bd643d" - }, - { - "@type": "dcat:Distribution", - "dct:format": { - "@id": "AmazonS3" - }, - "dcat:accessService": "49a693e0-835d-457a-99b4-e781f2bd643d" - } - ], - "edc:description": "IRS EDC Test Asset", - "edc:id": "urn:uuid:dc641d45-95e7-4284-a472-43f30255d0cb" - } - ], - "dcat:service": { - "@id": "49a693e0-835d-457a-99b4-e781f2bd643d", - "@type": "dcat:DataService", - "dct:terms": "connector", - "dct:endpointUrl": "http://dataprovider-controlplane.tx.test/api/v1/dsp" - }, - "edc:participantId": "BPNL00000003AYRE", - "@context": { - "dct": "http://purl.org/dc/terms/", - "tx": "https://w3id.org/tractusx/v0.0.1/ns/", - "edc": "https://w3id.org/edc/v0.0.1/ns/", - "dcat": "https://www.w3.org/ns/dcat/", - "odrl": "http://www.w3.org/ns/odrl/2/", - "dspace": "https://w3id.org/dspace/v0.8/" - } -} -``` - -## Create first access policy - -Let´s see if Alice can see the Asset (ID: 3). - -:::info -As you can see in the response, the data offer "Product EDC Demo Asset 3" (asset ID: 3) does not appear. Unfortunately, Alice sees some contract offers but she cannot find the contract offer from Bob. -::: - -Alice calls Bob and says she can´t see the asset. Bob remembers that he did not create an access policy. An access policy defines who is allowed to see a data offering. - -Action (Bob): Create the access policy using the following `curl` command: - -```shell -curl --location 'http://dataprovider-controlplane.tx.test/management/v2/policydefinitions' \ ---header 'Content-Type: application/json' \ ---header 'X-Api-Key: TEST2' \ ---data-raw '{ - "@context": { - "odrl": "http://www.w3.org/ns/odrl/2/" - }, - "@type": "PolicyDefinitionRequestDto", - "@id": "3-1", - "policy": { - "@type": "Policy" - } -}' | jq -``` - -The policy was successfully created, if the response is something like this - -```json -{ - "@type": "edc:IdResponse", - "@id": "3-1", - "edc:createdAt": 1715627034106, - "@context": { - "dct": "http://purl.org/dc/terms/", - "tx": "https://w3id.org/tractusx/v0.0.1/ns/", - "edc": "https://w3id.org/edc/v0.0.1/ns/", - "dcat": "https://www.w3.org/ns/dcat/", - "odrl": "http://www.w3.org/ns/odrl/2/", - "dspace": "https://w3id.org/dspace/v0.8/" - } -} -``` - -## Request catalog - second try - -Now that Bob created an access policy, Alice can once again try to access Bob's asset. - -Action (Alice): Execute the request again using the following `curl` command: - -```shell -curl --location 'http://dataconsumer-1-controlplane.tx.test/management/v2/catalog/request' \ ---header 'Content-Type: application/json' \ ---header 'X-Api-Key: TEST1' \ ---data-raw '{ - "@context": {}, - "protocol": "dataspace-protocol-http", - "counterPartyAddress": "http://dataprovider-controlplane.tx.test/api/v1/dsp", - "querySpec": { - "offset": 0, - "limit": 100 - } -}' | jq -``` - -## Create first contract definition - -Let´s see if Alice can see the Asset. - -Once again Alice cannot find the data offer. This is by design and to be expected since Bob has only created an asset and a policy definition. An asset and a policy can not be displayed to Alice as a consumer without a contract definition. - -:::info - -This is the first lesson in this tutorial: For providing data, a contract definition must be created on the provider side. This must always contain an asset, an access policy, and a contract policy. - -::: - -Contract definitions state how assets and policies are linked together. Contract definitions express under what conditions an asset is published in a data space. Those conditions are comprised of a contract policy and an access policy. Those policies are referenced by ID, that means they must already exist in the policy store before creating the contract definition. - -- **Access policy:** determines whether or not a particular consumer can see an asset in the provider's catalog. For example, we may want to restrict certain assets such that only selected consumers from a list of selected partners can access the asset. This can be done using a unique identifier such as the Business Partner Number (BPN). Other data space participants than those whose BPN is listed in the access policy wouldn't even be able to see the asset in the catalog. -- **Contract policy:** determines the conditions for initiating a contract negotiation for a particular asset. Note that this does not automatically guarantee the successful creation of a contract, it merely expresses the eligibility to start the negotiation. - -Find additional information on transferring data in the [Developer's Handbook](https://github.com/eclipse-edc/docs/blob/main/developer/handbook.md). - -Since an access policy has already been created, a contract policy must be created and linked in a contract definition. - -Action (BoB): Create the contract policy using the following `curl` command: - -```shell -curl --location 'http://dataprovider-controlplane.tx.test/management/v2/policydefinitions' \ ---header 'Content-Type: application/json' \ ---header 'X-Api-Key: TEST2' \ ---data-raw '{ - "@context": { - "odrl": "http://www.w3.org/ns/odrl/2/" - }, - "@type": "PolicyDefinitionRequestDto", - "@id": "3-2", - "policy": { - "@type": "Policy" - } -}' | jq -``` - -And again the policy was successfully created - -```json -{ - "@type": "edc:IdResponse", - "@id": "3-2", - "edc:createdAt": 1715627218849, - "@context": { - "dct": "http://purl.org/dc/terms/", - "tx": "https://w3id.org/tractusx/v0.0.1/ns/", - "edc": "https://w3id.org/edc/v0.0.1/ns/", - "dcat": "https://www.w3.org/ns/dcat/", - "odrl": "http://www.w3.org/ns/odrl/2/", - "dspace": "https://w3id.org/dspace/v0.8/" - } -} -``` - -Action (Bob): Create a contract definition including the asset and the policies you have created. For this, use the following `curl` command: - -```shell -curl --location 'http://dataprovider-controlplane.tx.test/management/v2/contractdefinitions' \ ---header 'Content-Type: application/json' \ ---header 'X-Api-Key: TEST2' \ ---data-raw '{ - "@context": {}, - "@id": "3", - "@type": "ContractDefinition", - "accessPolicyId": "3-1", - "contractPolicyId": "3-2", - "assetsSelector": { - "@type": "CriterionDto", - "operandLeft": "https://w3id.org/edc/v0.0.1/ns/id", - "operator": "=", - "operandRight": "3" - } -}' | jq -``` - -As a check, the result should look like this: - -```json -{ - "@type": "edc:IdResponse", - "@id": "3", - "edc:createdAt": 1715627302307, - "@context": { - "dct": "http://purl.org/dc/terms/", - "tx": "https://w3id.org/tractusx/v0.0.1/ns/", - "edc": "https://w3id.org/edc/v0.0.1/ns/", - "dcat": "https://www.w3.org/ns/dcat/", - "odrl": "http://www.w3.org/ns/odrl/2/", - "dspace": "https://w3id.org/dspace/v0.8/" - } -} -``` - -## Request catalog - third try - -Let´s see if Alice can finally see the Asset. -Action (Alice): Execute the request again using the following `curl` command: - -```shell -curl --location 'http://dataconsumer-1-controlplane.tx.test/management/v2/catalog/request' \ ---header 'Content-Type: application/json' \ ---header 'X-Api-Key: TEST1' \ ---data-raw '{ - "@context": {}, - "protocol": "dataspace-protocol-http", - "counterPartyAddress": "http://dataprovider-controlplane.tx.test/api/v1/dsp", - "querySpec": { - "offset": 0, - "limit": 100 - } -}' | jq -``` - -In the response an additional entry should appear: - -```json -{ - "@id": "3", - "@type": "dcat:Dataset", - "odrl:hasPolicy": { - "@id": "Mw==:Mw==:ZDA5YzE2ZWYtMzkyZC00ODExLWE5NjEtN2U4ZjRhMTU3ZGRh", - "@type": "odrl:Set", - "odrl:permission": [], - "odrl:prohibition": [], - "odrl:obligation": [], - "odrl:target": "3" - }, - "dcat:distribution": [ - { - "@type": "dcat:Distribution", - "dct:format": { - "@id": "HttpProxy" - }, - "dcat:accessService": "49a693e0-835d-457a-99b4-e781f2bd643d" - }, - { - "@type": "dcat:Distribution", - "dct:format": { - "@id": "AmazonS3" - }, - "dcat:accessService": "49a693e0-835d-457a-99b4-e781f2bd643d" - } - ], - "edc:description": "Product EDC Demo Asset 3", - "edc:id": "3" - } -``` - -:::info -Finally Alice can see the Contract Offer from Bob. Congratulations on yor first successful offering of data in your own data space! -::: - -## Notice - -This work is licensed under the [CC-BY-4.0](https://creativecommons.org/licenses/by/4.0/legalcode). - -- SPDX-License-Identifier: CC-BY-4.0 -- SPDX-FileCopyrightText: 2023 sovity GmbH -- SPDX-FileCopyrightText: 2023 SAP SE -- SPDX-FileCopyrightText: 2023 msg systems AG -- Source URL: [https://github.com/eclipse-tractusx/eclipse-tractusx.github.io](https://github.com/eclipse-tractusx/eclipse-tractusx.github.io) diff --git a/docs/tutorials/e2e/boost/restrictData.md b/docs/tutorials/e2e/boost/restrictData.md deleted file mode 100644 index 73349b7cee0..00000000000 --- a/docs/tutorials/e2e/boost/restrictData.md +++ /dev/null @@ -1,372 +0,0 @@ ---- -title: Restricting users from accessing an asset -sidebar_position: 4 ---- - -## Create an asset - -Bob will once again be the data provider. But this time Bob does not want Alice to see the asset. -The first step for Bob will again be to create an asset. - -Action (Bob): Create an asset using the following `curl` command: - -```shell -curl --location 'http://dataprovider-controlplane.tx.test/management/v3/assets' \ ---header 'Content-Type: application/json' \ ---header 'X-Api-Key: TEST2' \ ---data-raw '{ - "@context": {}, - "@type": "Asset", - "@id": "4", - "properties": { - "description": "Product EDC Demo Asset 4" - }, - "dataAddress": { - "@type": "DataAddress", - "type": "HttpData", - "baseUrl": "https://jsonplaceholder.typicode.com/todos/4" - } -}' | jq -``` - -## Create a permissive access policy - -Now that the asset has been created, Bob creates an access policy that defines who can see and therefore access the asset in his catalog. To specify this access, Bob uses the Business Partner Number (BPN). The BPN is a unique identifier for participants of a data space. Bob knows that his exchange partner for this asset has the BPN `BPNL00000003AVTH` and Alice BPN is `BPNL00000003AZQP` - -Action (Bob): Create the access policy using the following `curl` command: - -```shell -curl --location 'http://dataprovider-controlplane.tx.test/management/v2/policydefinitions' \ ---header 'Content-Type: application/json' \ ---header 'X-Api-Key: TEST2' \ ---data-raw '{ - "@context": { - "odrl": "http://www.w3.org/ns/odrl/2/" - }, - "@type": "PolicyDefinitionRequestDto", - "@id": "41", - "policy": { - "@type": "Policy", - "odrl:permission": [ - { - "odrl:action": "USE", - "odrl:constraint": { - "@type": "LogicalConstraint", - "odrl:or": [ - { - "@type": "Constraint", - "odrl:leftOperand": "BusinessPartnerNumber", - "odrl:operator": { - "@id": "odrl:eq" - }, - "odrl:rightOperand": "BPNL00000003AVTH" - } - ] - } - } - ] - } -}' | jq -``` - -The policydefinition is created with the ID `41` - -```json -{ - "@type": "edc:IdResponse", - "@id": "41", - "edc:createdAt": 1715674423858, - "@context": { - "dct": "http://purl.org/dc/terms/", - "tx": "https://w3id.org/tractusx/v0.0.1/ns/", - "edc": "https://w3id.org/edc/v0.0.1/ns/", - "dcat": "https://www.w3.org/ns/dcat/", - "odrl": "http://www.w3.org/ns/odrl/2/", - "dspace": "https://w3id.org/dspace/v0.8/" - } -} -``` - -Bob defined a policy which restricts access to connector(s) with the BusinessPartnerNumber `BPNL00000003AVTH`. As Alice does not own this BPN, she should not be able to access the asset. - -## Create a permissive contract policy - -Since an access policy has already been created, a contract policy must be created and linked in the contract definition. - -Action (Bob): Create the contract policy using the following `curl` command: - -```shell -curl --location 'http://dataprovider-controlplane.tx.test/management/v2/policydefinitions' \ ---header 'Content-Type: application/json' \ ---header 'X-Api-Key: TEST2' \ ---data-raw '{ - "@context": { - "odrl": "http://www.w3.org/ns/odrl/2/" - }, - "@type": "PolicyDefinitionRequestDto", - "@id": "42", - "policy": { - "@type": "Policy", - "odrl:permission": [ - { - "odrl:action": "USE", - "odrl:constraint": { - "@type": "LogicalConstraint", - "odrl:or": [ - { - "@type": "Constraint", - "odrl:leftOperand": "BpnCredential", - "odrl:operator": { - "@id": "odrl:eq" - }, - "odrl:rightOperand": "active" - } - ] - } - } - ] - } -}' | jq -``` - -The response should be something like this - -```json -{ - "@type": "edc:IdResponse", - "@id": "42", - "edc:createdAt": 1715674546763, - "@context": { - "dct": "http://purl.org/dc/terms/", - "tx": "https://w3id.org/tractusx/v0.0.1/ns/", - "edc": "https://w3id.org/edc/v0.0.1/ns/", - "dcat": "https://www.w3.org/ns/dcat/", - "odrl": "http://www.w3.org/ns/odrl/2/", - "dspace": "https://w3id.org/dspace/v0.8/" - } -} -``` - -## Create a contract definition - -Lastly, the asset and the access policy must be linked in a contract definition. -Action (Bob): Create a contract definition including the asset and the policies you have created. For this, use the following `curl` command: - -```shell -curl --location 'http://dataprovider-controlplane.tx.test/management/v2/contractdefinitions' \ ---header 'Content-Type: application/json' \ ---header 'X-Api-Key: TEST2' \ ---data-raw '{ - "@context": {}, - "@id": "4", - "@type": "ContractDefinition", - "accessPolicyId": "41", - "contractPolicyId": "42", - "assetsSelector" : { - "@type" : "CriterionDto", - "operandLeft": "https://w3id.org/edc/v0.0.1/ns/id", - "operator": "=", - "operandRight": "4" - } -}' | jq -``` - -A response should look like this - -```json -{ - "@type": "edc:IdResponse", - "@id": "4", - "edc:createdAt": 1715674670136, - "@context": { - "dct": "http://purl.org/dc/terms/", - "tx": "https://w3id.org/tractusx/v0.0.1/ns/", - "edc": "https://w3id.org/edc/v0.0.1/ns/", - "dcat": "https://www.w3.org/ns/dcat/", - "odrl": "http://www.w3.org/ns/odrl/2/", - "dspace": "https://w3id.org/dspace/v0.8/" - } -} -``` - -## Request catalog - -Let´s see if Alice can see the Asset. - -Action (Alice): Execute a request using the following `curl` command: - -```shell -curl --location 'http://dataconsumer-1-controlplane.tx.test/management/v2/catalog/request' \ ---header 'Content-Type: application/json' \ ---header 'X-Api-Key: TEST1' \ ---data-raw '{ - "@context": {}, - "protocol": "dataspace-protocol-http", - "counterPartyAddress": "http://dataprovider-controlplane.tx.test/api/v1/dsp", - "querySpec": { - "offset": 0, - "limit": 100 - } -}' | jq -``` - -The response doesnt include the cataolog entry for the asset/offer with id4 - -```json -{ - "@id": "3b276870-5cc5-4546-b793-e2c8d39e1010", - "@type": "dcat:Catalog", - "dcat:dataset": [ - { - "@id": "registry-asset", - "@type": "dcat:Dataset", - "odrl:hasPolicy": { - "@id": "ZGM3MjMyYTAtMDRjOC00MTVjLWI2NmQtOGJmNTQ1MWMyYmIy:cmVnaXN0cnktYXNzZXQ=:MjdiYWExMGItMTAzMC00MmY5LWI0YjMtMzJmY2UyODI5NThl", - "@type": "odrl:Set", - "odrl:permission": { - "odrl:target": "registry-asset", - "odrl:action": { - "odrl:type": "USE" - }, - "odrl:constraint": { - "odrl:or": { - "odrl:leftOperand": "PURPOSE", - "odrl:operator": { - "@id": "odrl:eq" - }, - "odrl:rightOperand": "ID 3.0 Trace" - } - } - }, - "odrl:prohibition": [], - "odrl:obligation": [], - "odrl:target": "registry-asset" - }, - "dcat:distribution": [ - { - "@type": "dcat:Distribution", - "dct:format": { - "@id": "HttpProxy" - }, - "dcat:accessService": "7b76c9c5-d7f9-42c1-8784-a2820a60bb0f" - }, - { - "@type": "dcat:Distribution", - "dct:format": { - "@id": "AmazonS3" - }, - "dcat:accessService": "7b76c9c5-d7f9-42c1-8784-a2820a60bb0f" - } - ], - "edc:type": "data.core.digitalTwinRegistry", - "edc:description": "Digital Twin Registry Endpoint of IRS DEV", - "edc:id": "registry-asset" - }, - { - "@id": "urn:uuid:69653fc9-11b5-4321-98ca-e60d2dc35379", - "@type": "dcat:Dataset", - "odrl:hasPolicy": { - "@id": "MDkyNmVhMGUtZWVmMC00OTlmLTliZjktNmE1MGU3MGUzOGQy:dXJuOnV1aWQ6Njk2NTNmYzktMTFiNS00MzIxLTk4Y2EtZTYwZDJkYzM1Mzc5:YWUwOTFiOTYtNGM0Ni00YzE0LWEyZGYtY2Y5NDNlMzY1NDY4", - "@type": "odrl:Set", - "odrl:permission": { - "odrl:target": "urn:uuid:69653fc9-11b5-4321-98ca-e60d2dc35379", - "odrl:action": { - "odrl:type": "USE" - }, - "odrl:constraint": { - "odrl:or": { - "odrl:leftOperand": "PURPOSE", - "odrl:operator": { - "@id": "odrl:eq" - }, - "odrl:rightOperand": "ID 3.0 Trace" - } - } - }, - "odrl:prohibition": [], - "odrl:obligation": [], - "odrl:target": "urn:uuid:69653fc9-11b5-4321-98ca-e60d2dc35379" - }, - "dcat:distribution": [ - { - "@type": "dcat:Distribution", - "dct:format": { - "@id": "HttpProxy" - }, - "dcat:accessService": "7b76c9c5-d7f9-42c1-8784-a2820a60bb0f" - }, - { - "@type": "dcat:Distribution", - "dct:format": { - "@id": "AmazonS3" - }, - "dcat:accessService": "7b76c9c5-d7f9-42c1-8784-a2820a60bb0f" - } - ], - "edc:description": "IRS EDC Test Asset", - "edc:id": "urn:uuid:69653fc9-11b5-4321-98ca-e60d2dc35379" - }, - { - "@id": "3", - "@type": "dcat:Dataset", - "odrl:hasPolicy": { - "@id": "Mw==:Mw==:YjE0ODU2M2MtMWM5MC00NDg4LThmZmItZmJjZjc0NjQzZTE5", - "@type": "odrl:Set", - "odrl:permission": [], - "odrl:prohibition": [], - "odrl:obligation": [], - "odrl:target": "3" - }, - "dcat:distribution": [ - { - "@type": "dcat:Distribution", - "dct:format": { - "@id": "HttpProxy" - }, - "dcat:accessService": "7b76c9c5-d7f9-42c1-8784-a2820a60bb0f" - }, - { - "@type": "dcat:Distribution", - "dct:format": { - "@id": "AmazonS3" - }, - "dcat:accessService": "7b76c9c5-d7f9-42c1-8784-a2820a60bb0f" - } - ], - "edc:description": "Product EDC Demo Asset 3", - "edc:id": "3" - } - ], - "dcat:service": { - "@id": "7b76c9c5-d7f9-42c1-8784-a2820a60bb0f", - "@type": "dcat:DataService", - "dct:terms": "connector", - "dct:endpointUrl": "http://dataprovider-controlplane.tx.test/api/v1/dsp" - }, - "edc:participantId": "BPNL00000003AYRE", - "@context": { - "dct": "http://purl.org/dc/terms/", - "tx": "https://w3id.org/tractusx/v0.0.1/ns/", - "edc": "https://w3id.org/edc/v0.0.1/ns/", - "dcat": "https://www.w3.org/ns/dcat/", - "odrl": "http://www.w3.org/ns/odrl/2/", - "dspace": "https://w3id.org/dspace/v0.8/" - } -} -``` - -:::info - -Bob’s asset (ID: 4) should not be displayed. The access policy successfully restricts Alice from seeing and therefore obtaining Bob’s asset. Now Bob is able to manage who sees which of his sensitive data assets. If Bob decides to enable Alice to see his asset, he can simply adjust the access policy definition and add Alice BPN `BPNL00000003AZQP` to the list of BPNs. - -::: - -## Notice - -This work is licensed under the [CC-BY-4.0](https://creativecommons.org/licenses/by/4.0/legalcode). - -- SPDX-License-Identifier: CC-BY-4.0 -- SPDX-FileCopyrightText: 2023 sovity GmbH -- SPDX-FileCopyrightText: 2023 SAP SE -- SPDX-FileCopyrightText: 2023 msg systems AG -- Source URL: [https://github.com/eclipse-tractusx/eclipse-tractusx.github.io](https://github.com/eclipse-tractusx/eclipse-tractusx.github.io) diff --git a/docs/tutorials/e2e/connect/deployComponents.md b/docs/tutorials/e2e/connect/deployComponents.md index 2cb4dd5c3ba..d03b4b976c8 100644 --- a/docs/tutorials/e2e/connect/deployComponents.md +++ b/docs/tutorials/e2e/connect/deployComponents.md @@ -29,726 +29,27 @@ Make sure that you have understood and carried out all the steps in the `Prerequ ### Using Umbrella Helm Charts -The components (listed in the table in the `Connect chapter`) are deployed using an umbrella chart. It consists of Tractus-X OSS components and provides a basis for running end-to-end tests or creating a sandbox environment of the Catena-X automotive dataspace network. The Chart aims for a completely automated setup of a fully functional network that requires no manual setup steps, as long as only one instance (minikube cluster) is running (see warning above). If several clusters are running, you will need to adjust so configuration files. +The components (listed in the table in the `Connect chapter`) are deployed using an umbrella chart. It consists of Tractus-X OSS components and provides a +basis for running end-to-end tests or creating a sandbox environment of the Catena-X automotive dataspace network. The Chart aims for a completely automated setup of a fully functional network that requires no manual setup steps, as long as only one instance (minikube cluster) is running (see warning above). If several clusters are running, you will need to adjust so configuration files. :::note -This chapter aligns with the README for the Tractus-X umbrella charts following the link: - +This chapter is described within the README for the Tractus-X umbrella charts following the [link](https://github.com/eclipse-tractusx/tractus-x-umbrella/blob/main/docs/README.md) -::: - -:::warning -If you are [not] the only user on your system working with the turorial, means you are working in a multi-user environment, please ensure, that you understand your impact on other minikube profiles of other users and Umbralla namespaces. Please check, if other user are working on the same system by checking the existance of other minikube profiles with the command: - -```bash -minikube profile list -``` - -Please ensure you are explicitly defining the profile with the `-f` parameter and [never] using options like **--all**. To avoid disturbing other we use the environment variable [$USER] any time we specify a name for a minikube profile of an Umbrella namespace. - -So if your minikube cluster will not be the only one running in your system, please - -- use specific names for your cluster profile and namespaces for helm​ - - Proposed name for the cluster profile: **minikube-$USER** - - Proposed name for the umbrella namespace: **umbrella-$USER** ​ - -- Ensure you are using the option `-p`, everytime you calling minikube ​ - -```bash -minikube –p minikube-$USER ​ -``` - -Ensure you are using the option **–n**, every time you calling helm​ - -```bash -helm –n umbrella-$USER -``` - -Before you enable ingress enter:​ - -```bash -minikube profile minikube-$USER​ -``` - -This will ensure that ingress is working in the correct environment of your cluster profile. - -::: - -### Overview - -Perform the following steps to begin deploying the TXD: - -- Get the source -- Start `minikube` bringing up the cluster (profile) -- Enable `Ingress` for local access using the addon for Minikube -- Adjust the configuration files for the Umbrella Helm Chart (this is not required, if you are the only user on a system) -- Use the certifacation manager -- Use helm to deploy the ecosystem -- Check their liveness - -### Get the source from the Tractus-X Github - -For the most bare-bones installation of the dataspace, execute the following commands in a shell: - -```bash -# get the tutorial including the config file for the cluster by cloning the repository locally -git clone [https://github.com/eclipse-tractusx/tractus-x-umbrella.git](https://github.com/eclipse-tractusx/tractus-x-umbrella.git") -``` - -Now we will find the directory [tractus-x-umbrella] under your current working directory. Change into this directory: - -```bash -cd tractus-x-umbrella -``` - -### Start the minikube cluster (profile) - -To start the cluster we just call **minikube start**. If we have more than one instance, we use -p option to set the profile name minikube-$USER. We use the other options to request the appropiate resources. - -```bash -minikube start [-p minikube-$USER] --cpus=4 --memory 6gb -# Start the cluster, if -p option is used with the profile name minikube-$USER -``` - -We now switch the context to minikube profile. This is required to ensure Ingress gets the correct data of the cluster. But it is not needed, if you run only one minikube cluster on your system. - -```bash -minikube profile minikube-$USER -# Switch the context to minikube profile -``` - -You can check your minikube cluster any time by starting the Minikube dashboard: - -```bash -minikube [-p minikube-$USER] dashboard -# if -p option is used, with the profile name minikube-$USER -``` - -### Setting up the local internal netwok - -In order to enable the local access via ingress, use the according addon for Minikube: - -```bash -minikube [-p minikube-$USER] addons enable ingress -# if -p option is used, with the profile name minikube-$USER -``` - -Now add these hostnames to your /etc/hosts. You should ensure that you have access and the /etc/hosts file group entry should be assigend to the group **docker**. Check this with the following commands: - -```bash -ls -al /etc/hosts -# Output should be like: "-rw-r--r-- 1 root docker 414 Jun 16 14:34 /etc/hosts" -``` - -Alternatively configure the DNS Service to be enabled for Ingress. - -:::note - - This requires that you have a DNS on your system running and that you have **root accees** via **sudo** - -::: - -```bash -minikube [-p minikube-$USER] addons enable ingress-dns -# if -p option is used, with the profile name minikube-$USER -``` - -Find out the IP Address of your minikube cluster by entering: - -```bash -minikube [-p minikube-$USER] ip -# if -p option is used, with the profile name minikube-$USER -``` - -In the following steps, replace `192.168.49.2` with your `minikube ip` if it differs. - -#### Linux & Mac - -Create a file in /etc/resolver/minikube-test with the following contents. - -```properties -domain arena.test -nameserver 192.168.49.2 -search_order 1 -timeout 5 -``` - -If you still face DNS issues, add the hosts to your /etc/hosts file: - -```properties -192.168.49.2 centralidp.arena.test -192.168.49.2 sharedidp.arena.test -192.168.49.2 portal.arena.test -192.168.49.2 portal-backend.arena.test -192.168.49.2 managed-identity-wallets.arena.test -192.168.49.2 semantics.arena.test -192.168.49.2 sdfactory.arena.test -192.168.49.2 dataconsumer-1-dataplane.arena.test -192.168.49.2 dataconsumer-1-controlplane.arena.test -192.168.49.2 dataprovider-dataplane.arena.test -192.168.49.2 dataconsumer-2-dataplane.arena.test -192.168.49.2 dataconsumer-2-controlplane.arena.test -``` - -Additional network setup for Mac: - -- Install and start [Docker Mac Net Connect](https://github.com/chipmk/docker-mac-net-connect#installation). - -We also recommend to execute the usage example after install to check proper setup. - -#### Windows - -For Windows edit the hosts file under `C:\Windows\System32\drivers\etc\hosts`: - -```properties -192.168.49.2 centralidp.arena.test -192.168.49.2 sharedidp.arena.test -192.168.49.2 portal.arena.test -192.168.49.2 portal-backend.arena.test -192.168.49.2 managed-identity-wallets.arena.test -192.168.49.2 semantics.arena.test -192.168.49.2 sdfactory.arena.test -192.168.49.2 dataconsumer-1-dataplane.arena.test -192.168.49.2 dataconsumer-1-controlplane.arena.test -192.168.49.2 dataprovider-dataplane.arena.test -192.168.49.2 dataconsumer-2-dataplane.arena.test -192.168.49.2 dataconsumer-2-controlplane.arena.test -``` - -#### Adjusting the Config files for multi user usage - -In case we have to modify the values within the configuartion files as we run in a multi use environment, we need to adjust the domians names within the configuration files. A simple way is to update the file by using **sed** as line editor. - -```bash -# adjust values.yaml -# -DOMAIN_NAME="$USER.test" -CONFIG_FILE="alues-adopter-data-exchange.yaml" -cp values.yaml values.yaml.orig -cat values.yaml.orig | sed s/tx.test/$DOMAIN_NAME/ > values.yaml -echo "file values.yaml updated with actual dommainame $DOMAIN_NAME" -cp $CONFIG_FILE $CONFIG_FILE.orig -cat $CONFIG_FILE.orig | sed s/tx.test/$DOMAIN_NAME/ > $CONFIG_FILE -echo "file $CONFIG_FILE updated with actual dommainame $DOMAIN_NAME" -# Adjust further files: concept/seeds-overall-data.md, init-container/iam/centralidp/CX-Central-realm.json, init --container/iam/sharedidp/CX-operator-realm.json. init-container/iam/sharedidp/CX-operator-users-0.json -# -cd ../.. -echo "Modifing file concept/seeds-overall-data.md, ..." -cp concept/seeds-overall-data.md concept/seeds-overall-data.md.orig -cat concept/seeds-overall-data.md.orig | sed s/tx.test/$DOMAIN_NAME/ > concept/seeds-overall-data.md -echo "Modifing file init-container/iam/centralidp/CX-Central-realm.json ..." -cp init-container/iam/centralidp/CX-Central-realm.json init-container/iam/centralidp/CX-Central-realm.json.orig -cat init-container/iam/centralidp/CX-Central-realm.json.orig | sed s/tx.test/$DOMAIN_NAME/ > init-container/iam/centralidp/CX-Central-realm.json -echo "Modifing file init-container/iam/sharedidp/CX-operator-realm.json ..." -cp init-container/iam/sharedidp/CX-Operator-realm.json init-container/iam/sharedidp/CX-Operator-realm.json.orig -cat init-container/iam/sharedidp/CX-Operator-realm.json.orig | sed s/tx.test/$DOMAIN_NAME/ > init-container/iam/sharedidp/CX-Operator-realm.json -echo "Modifing file init-container/iam/sharedidp/CX-operator-realm.json ..." -cp init-container/iam/sharedidp/CX-Operator-users-0.json init-container/iam/sharedidp/CX-Operator-users-0.json.orig -cat init-container/iam/sharedidp/CX-Operator-users-0.json.orig | sed s/tx.test/$DOMAIN_NAME/ > init-container/iam/sharedidp/CX-Operator-users-0.json -``` - -### Install Helm Charts - -:::warning - -- Due to resource restrictions, it's **not recommended** to install the helm chart with all components enabled. - -- It is to be expected that some pods - which run as post-install hooks, like for instance the **portal-migrations job - will run into errors until another component**, like for instance a database, is ready to take connections. -Those jobs will recreate pods until one run is successful. -- **Persistance is disabled by default** but can be configured in a custom values file. - -::: - -#### Use released chart - -```bash -helm repo add tractusx-dev https://eclipse-tractusx.github.io/charts/dev -``` - -##### :grey_question: Command explanation - -:::info - -`helm install` is used to install a chart in Kubernetes using Helm. - -- `--set COMPONENT_1.enabled=true,COMPONENT_2.enabled=true` Enables the components by setting their respective enabled values to true. -- `umbrella` is the release name for the chart. -- `tractusx-dev/umbrella` specifies the chart to install, with *tractusx-dev* being the repository name and *umbrella* being the chart name. -- `--namespace umbrella` specifies the namespace in which to install the chart. -- `--create-namespace` create a namespace with the name `umbrella`. - -::: - -##### Option 1 - -Install with your chosen components enabled: - -```bash -helm install \ - --set COMPONENT_1.enabled=true,COMPONENT_2.enabled=true,COMPONENT_3.enabled=true \ - umbrella tractusx-dev/umbrella \ - --namespace umbrella \ - --create-namespace -``` - -##### Option 2 - -Choose to install one of the predefined subsets (currently in focus of the **E2E Adopter Journey**): - -###### Data Exchange Subset - -```bash -helm install \ - --set centralidp.enabled=true,managed-identity-wallet.enabled=true,dataconsumerOne.enabled=true,tx-data-provider.enabled=true \ - umbrella tractusx-dev/umbrella \ - --namespace umbrella \ - --create-namespace -``` - -###### Optional - -Enable `dataconsumerTwo` at upgrade: - -```bash -helm install \ - --set centralidp.enabled=true,managed-identity-wallet.enabled=true,dataconsumerOne.enabled=true,tx-data-provider.enabled=true,dataconsumerTwo.enabled=true \ - umbrella tractusx-dev/umbrella \ - --namespace umbrella -``` - -###### Portal Subset - -```bash -helm install \ - --set portal.enabled=true,centralidp.enabled=true,sharedidp.enabled=true \ - umbrella tractusx-dev/umbrella \ - --namespace umbrella \ - --create-namespace -``` - -To set your own configuration and secret values, install the helm chart with your own values file: - -```bash -helm install -f your-values.yaml umbrella tractusx-dev/umbrella --namespace umbrella --create-namespace -``` - -#### Use local repository - -Make sure to clone the [tractus-x-umbrella](https://github.com/eclipse-tractusx/tractus-x-umbrella) repository beforehand. - -Then navigate to the chart directory: - -```bash -cd charts/umbrella/ -``` - -Download the chart dependencies: - -```bash -helm dependency update -``` - -##### grey_question: Command explanation - -> `helm install` is used to install a Helm chart. -> > `-f your-values.yaml` | `-f values-*.yaml` specifies the values file to use for configuration. -> --- -> > `umbrella` is the release name for the Helm chart. -> --- -> > `.` specifies the path to the chart directory. -> --- -> > `--namespace umbrella` specifies the namespace in which to install the chart. -> --- -> > `--create-namespace` create a namespace with the name `umbrella`. - -##### Option 1 - -Install your chosen components by having them enabled in a `your-values.yaml` file: - -```bash -helm install -f your-values.yaml umbrella . --namespace umbrella --create-namespace -``` - -> In general, all your specific configuration and secret values should be set by installing with an own values file. - -##### Option 2 - -Choose to install one of the predefined subsets (currently in focus of the **E2E Adopter Journey**): - -###### Data Exchange Subset - -```bash -helm install -f values-adopter-data-exchange.yaml umbrella . --namespace umbrella --create-namespace -``` +Important chapters are: -**Optional:** - -Enable `dataconsumerTwo` by setting it true in `values-adopter-data-exchange.yaml` and then executing an upgrade: - -```bash -dataconsumerTwo: - enabled: true -``` - -```bash -helm upgrade -f values-adopter-data-exchange.yaml umbrella . --namespace umbrella -``` - -###### Portal Subset - -```bash -helm install -f values-adopter-portal.yaml umbrella . --namespace umbrella --create-namespace -``` - -#### Get to know the Portal - -Perform first login and send out an invitation to a company to join the network (SMTP account required to be configured in custom values.yaml file). - -Proceed with the login to the to verify that everything is setup as expected. - -Credentials to log into the initial example realm (CX-Operator): - -```sh -cx-operator@arena.test -``` - -```sh -tractusx-umbr3lla! -``` - -```mermaid -%%{ - init: { - 'flowchart': { 'diagramPadding': '10', 'wrappingWidth': '', 'nodeSpacing': '', 'rankSpacing':'', 'titleTopMargin':'10', 'curve':'basis'}, - 'theme': 'base', - 'themeVariables': { - 'primaryColor': '#b3cb2d', - 'primaryBorderColor': '#ffa600', - 'lineColor': '#ffa600', - 'tertiaryColor': '#fff' - } - } -}%% - graph TD - classDef stroke stroke-width:2px - classDef addext fill:#4cb5f5,stroke:#b7b8b6,stroke-width:2px - iam1(IAM: centralidp Keycloak):::stroke - iam2(IAM: sharedidp Keycloak):::stroke - portal(Portal):::stroke - subgraph Login Flow - iam1 --- portal & iam2 - end - linkStyle 0,1 stroke:lightblue -``` - -The relevant hosts are the following: - -- -- -- -- - -In case that you have TLS enabled (see [Self-signed TLS setup (Optional)](#self-signed-tls-setup-optional)), make sure to accept the risk of the self-signed certificates for all the hosts before performing the first login: - -- -- -- -- - -### Uninstall Helm Charts - -To teardown your setup, run: - -```shell -helm delete umbrella --namespace umbrella -``` - -:::warning - -If persistance for one or more components is enabled, the persistent volume claims (PVCs) and connected persistent volumes (PVs) need to be removed manually even if you deleted the release from the cluster. - -::: - -### Ingresses - -Currently enabled ingresses: - -- [centralidp.arena.test/auth](http://centralidp.arena.test/auth/) -- [sharedidp.arena.test/auth](http://sharedidp.arena.test/auth/) -- [portal-backend.arena.test](http://portal-backend.arena.test) - - [portal-backend.arena.test/api/administration/swagger/index.html](http://portal-backend.arena.test/api/administration/swagger/index.html) - - [portal-backend.arena.test/api/registration/swagger/index.html](http://portal-backend.arena.test/api/registration/swagger/index.html) - - [portal-backend.arena.test/api/apps/swagger/index.html](http://portal-backend.arena.test/api/apps/swagger/index.html) - - [portal-backend.arena.test/api/services/swagger/index.html](http://portal-backend.arena.test/api/services/swagger/index.html) - - [portal-backend.arena.test/api/notification/swagger/index.html](http://portal-backend.arena.test/api/notification/swagger/index.html) -- [portal.arena.test](http://portal.arena.test) -- [managed-identity-wallets.arena.test/ui/swagger-ui/index.html](http://managed-identity-wallets.arena.test/ui/swagger-ui/index.html) -- [semantics.arena.test/discoveryfinder/swagger-ui/index.html](http://semantics.arena.test/discoveryfinder/swagger-ui/index.html) -- [dataconsumer-1-controlplane.arena.test](http://dataconsumer-1-controlplane.arena.test) -- [dataconsumer-1-dataplane.arena.test](http://dataconsumer-1-dataplane.arena.test) -- [dataprovider-dataplane.arena.test](http://dataprovider-dataplane.arena.test) -- [dataconsumer-2-controlplane.arena.test](http://dataconsumer-2-controlplane.arena.test) -- [dataconsumer-2-dataplane.arena.test](http://dataconsumer-2-dataplane.arena.test) -- [pgadmin4.arena.test](http://pgadmin4.arena.test) - -### Database Access - -This chart also contains a pgadmin4 instance for easy access to the deployed Postgres databases which are only available from within the Kubernetes cluster. - -pgadmin4 is by default enabled with in the predefined subsets for data exchange and portal. - -Address: [pgadmin4.arena.test](http://pgadmin4.arena.test) - -Credentials to login into pgadmin4: - -```sh -pgadmin4@txtest.org -``` - -```sh -tractusxpgdamin4 -``` - -:::info - -The database server connections need to be added manually to pgadmin4. +- [Cluster Setup](https://github.com/eclipse-tractusx/tractus-x-umbrella/blob/main/docs/user/setup) +- [Network Setup](https://github.com/eclipse-tractusx/tractus-x-umbrella/blob/main/docs/user/network) +- [Installation](https://github.com/eclipse-tractusx/tractus-x-umbrella/blob/main/docs/user/installation/README.md) ::: -Default username for all connections: - -```sh -postgres -``` - -Default user for all connections: - -```sh -5432 -``` - -In the following some of the available connections: - -- portal - -Host: - -```sh -portal-backend-postgresql -``` - -Password: - -```sh -dbpasswordportal -``` - -- centralidp - -Host: - -```sh -umbrella-centralidp-postgresql -``` - -Password: - -```sh -dbpasswordcentralidp -``` - -- sharedidp - -Host: - -```sh -umbrella-sharedidp-postgresql -``` - -Password: - -```sh -dbpasswordsharedidp -``` - -- miw - -Host: - -```sh -umbrella-miw-postgres -``` - -Password: - -```sh -dbpasswordmiw -``` - -- dataprovider - -Host: - -```sh -umbrella-dataprovider-db -``` - -Password: - -```sh -dbpasswordtxdataprovider -``` - -- dataconsumer-1 - -Host: - -```sh -umbrella-dataconsumer-1-db -``` - -Password: - -```sh -dbpassworddataconsumerone -``` - -- dataconsumer-2 - -Host: - -```sh -umbrella-dataconsumer-2-db -``` - -Password: - -```sh -dbpassworddataconsumertwo -``` - -### Keycloak Admin Console - -Access to admin consoles: - -- [http://centralidp.arena.test/auth/](http://sharedidp.arena.test/auth/) -- [http://sharedidp.arena.test/auth/](http://sharedidp.arena.test/auth/) - -Default username for centralidp and sharedidp: - -```sh -admin -``` - -Password centralidp: - -```sh -adminconsolepwcentralidp -``` - -Password sharedidp: - -```sh -adminconsolepwsharedidp -``` - -### Seeding - -See [Overall Seeding](https://github.com/eclipse-tractusx/tractus-x-umbrella/blob/main/concept/seeds-overall-data.md). - -### Self-signed TLS setup (Optional) - -Some of the components are prepared to be configured with TLS enabled (see "uncomment the following line for tls" comments in [values.yaml](./values.yaml)). - -If you'd like to make use of that, make sure to to execute this step beforehand. - -Install cert-manager chart in the same namespace where the umbrella chart will be located. - -```bash -helm repo add jetstack https://charts.jetstack.io -helm repo update -``` - -```bash -helm install \ - cert-manager jetstack/cert-manager \ - --namespace umbrella \ - --create-namespace \ - --version v1.14.4 \ - --set installCRDs=true -``` - -Configure the self-signed certificate and issuer to be used by the ingress resources. - -If you have the repository checked out you can run: - -```bash -kubectl apply -f ./charts/umbrella/cluster-issuer.yaml -``` - -or otherwise you can run: - -```bash -kubectl apply -f - <