diff --git a/docs/development/Release.md b/docs/development/Release.md index 3992c0a1d..5f2fbd74d 100644 --- a/docs/development/Release.md +++ b/docs/development/Release.md @@ -38,5 +38,11 @@ The Eclipse Bot is able to approve dependencies automatically, if the license ca from maven central. 2. Create the Eclipse IP Issues or ask an Eclipse Commiter to do this for you. +## 4. Update OpenAPI docs + +As part of the [kits documentation provided for docusaurus](../kit/development-view/page00_development_view.md) we provide an OpenAPI reference. +This refers to the [EDC API](https://github.com/eclipse-edc/Connector/tree/main/resources/openapi) and needs to be updated to the current release. +The yaml files found there are then converted with the [docusaurus openapi plugin](https://www.npmjs.com/package/docusaurus-plugin-openapi-docs). + [maven-shield]: https://img.shields.io/badge/Apache%20Maven-URL-blue [maven-url]: https://maven.apache.org diff --git a/docs/kit/adoption-view/images/domain-model.png b/docs/kit/adoption-view/images/domain-model.png new file mode 100644 index 000000000..de9562a11 Binary files /dev/null and b/docs/kit/adoption-view/images/domain-model.png differ diff --git a/docs/kit/adoption-view/images/edc_architecture.png b/docs/kit/adoption-view/images/edc_architecture.png new file mode 100644 index 000000000..99b5525ea Binary files /dev/null and b/docs/kit/adoption-view/images/edc_architecture.png differ diff --git a/docs/kit/adoption-view/images/edc_overview.png b/docs/kit/adoption-view/images/edc_overview.png new file mode 100644 index 000000000..3d9418446 Binary files /dev/null and b/docs/kit/adoption-view/images/edc_overview.png differ diff --git a/docs/kit/adoption-view/page_adoption-view.md b/docs/kit/adoption-view/page_adoption-view.md new file mode 100644 index 000000000..b48a23789 --- /dev/null +++ b/docs/kit/adoption-view/page_adoption-view.md @@ -0,0 +1,48 @@ +--- +id: Adoption View +title: Adoption View +description: 'Connector Kit' +sidebar_position: 1 +--- + +The ConnectorKit provides a connector framework, based on the [Eclipse Dataspace Connector][edc-url] for sovereign, cross-enterprise data exchange. + +![EDC Overview](images/edc_overview.png) + +Trust, interoperability and data sovereignty, these are the objectives and values for secure and sustainable peer-to-peer data exchange between organizations and companies. The claim is data sovereignty: Whoever makes data available retains control and decides individually who is involved in the data exchange, how, when, where and under what conditions. + +A corresponding concept was developed in the context of [Gaia-X][gaiax-url] and the [International Data Space Association][idsa-url]. The essential software component is the connector. + +With the [EDC][edc-url], a new central communication component was created, which implements the following architectural principles: + +- Simple, maintaining a small and efficient core with as few external dependencies as possible +- Interoperable, independent of platforms and ecosystems +- Decentralized, software components with the necessary capabilities for participating in a data room are located on the partners' side, data is only exchanged between the agreed points. +- Data protection is more important than data sharing, data to be transmitted are fundamentally linked to policies via contracts; a transfer without a contract is not possible. +- Separation of metadata and data enables high throughput rates for the actual data transfer. +- Consistent semantics for the data is the basis for the consistency of digital value creation. +- As far as possible, all processes, starting with determining the identity, through ensuring the contractually agreed regulations to data transmission, are automated. +- Existing standards and protocols ([GAIA-X][gaiax-url] and [IDSA][idsa-url]) are used as far as possible. + +The [EDC][edc-url] as a connector implements a framework agreement for sovereign, cross-organizational data exchange. The International Data Spaces Standard (IDS) and relevant principles in connection with [GAIA-X][gaiax-url] were implemented. The connector is designed to be extensible to support alternative protocols and to be integrated into different ecosystems. + +The objective is to set up a decentralized software component on the part of the respective partner, which bundles the skills required to participate in a data room and enables peer-to-peer connections between participants. +The focus here is particularly on the data sovereignty of the independent companies. +The functionality required for this is bundled in the open-source project "Eclipse Dataspace Connectors", to which the Catena-X partners contribute as part of the Eclipse Foundation. + +The main difference between the EDC and the previous connectors of the [IDSA][idsa-url] is the separation of the communication into a channel for the metadata and one for the actual data exchange. The channel for the data supports various transmission protocols via so-called data plane extensions. The metadata is transmitted directly via the EDC interface, while the actual data exchange then takes place via the appropriate channel extension. In this way, a highly scalable data exchange is made possible. + +![EDC Architecture](images/edc_architecture.png) + +The architecture of the EDC combines various services that are necessary for the above principles: + +- An interface to the Identity Provider service, currently [IDSA][idsa-url]'s [Dynamic Attribute Provisioning System][daps-url]. This central service provides the identity and the corresponding authentication of the participants in the data exchange. (There is no authorization at this point). Decentralized solutions will also be supported in the future. +- The provision of possible offers (contract offering) which, on the one hand, stipulates the data offered and the associated terms of use (policies) in corresponding contracts. +- An interface for manual selection of data and associated contract offers. +- The actual data transfer via the data plane extension +- The connection of software systems on the customer and provider side + +[edc-url]: https://github.com/eclipse-edc/Connector +[gaiax-url]: https://www.data-infrastructure.eu/GAIAX/Navigation/EN/Home/home.html +[idsa-url]: https://internationaldataspaces.org/ +[daps-url]: https://www.dataspaces.fraunhofer.de/en/software/identity_provider.html diff --git a/docs/kit/adoption-view/page_domain_model.md b/docs/kit/adoption-view/page_domain_model.md new file mode 100644 index 000000000..5143889f9 --- /dev/null +++ b/docs/kit/adoption-view/page_domain_model.md @@ -0,0 +1,64 @@ +--- +id: Domain Model +title: Domain Model +description: 'Connector Kit' +sidebar_position: 2 +--- + +![domain-model](images/domain-model.png) + +> The shown picture illustrates only a generic view of the Domain Model and is not intended to show all aspects of the project. + +## Asset + +An asset represents data (databases, files, cache information, etc.) which should be published and shared between +organizations. For each asset, a [`DataAddress`](#data-address) needs to be resolvable. + +## Data address + +A data address is a pointer into the physical storage location where an asset will be stored. + +## Contract + +A contract always contains one or more [`Assets`](#asset) and a single [`Policy`](#policy). The contract construct is +used to define the arrangement between two parties ("consumer" and "provider"). Regarding this arrangement, the contract +passes several stages which are explained below: + +### Contract definition + + Contract definitions associate a policy with assets. A `ContractDefinition` object contains an access policy, a contract + policy, and an asset selector which links the contract to one or more assets. + +### Contract offer + + The contract offer is a dynamic representation of the [`ContractDefinition`](#contract-definition) + for a specific consumer and serves as protocol's data transfer object (DTO) for a particular contract negotiation. + Contract offers are not persisted and will be regenerated on every request. The connector acting as data provider will + generate contract offers only for contract definitions dedicated to the organization or data space participant + operating the requesting connector acting as data consumer. A contract offer is always related to a single asset of + the `ContractDefinition` object (e.g. for a `ContractDefinition` containing three `Asset` objects, the connector will + generate three `ContractOffer` objects). + +### Contract negotiation + + A `ContractNegotiation` captures the current state of the negotiation of a contract (`ContractOffer` -> + `ContractAgreement`) between two parties. This process is inherently asynchronous. + +### Contract agreement + + A contract agreement represents the agreed-upon terms of access and usage of an asset's data between two data space + participants, including a start and an end date and further relevant information. + +## Policy + +Contract policies represent permitted and prohibited actions over a certain asset. These actions can be limited further +by constraints (temporal or spatial) and duties ("e.g. deletion of the data after 30 days"). + +## Transfer process + +After a successful contract negotiation, a `DataRequest` is sent from a consumer connector to a provider connector to +initiate the data transfer. It references the requested [`Asset`](#asset) and [`ContractAgreement`](#contract-agreement) +as well as information about the [data destination](#data-address). + +Similar to the `ContractNegotiation`, this object captures the current state of a data transfer. This process is +inherently asynchronous, so the `TransferProcess` objects are stored in a backing data store (`TransferProcessStore`). diff --git a/docs/kit/development-view/page00_development_view.md b/docs/kit/development-view/page00_development_view.md new file mode 100644 index 000000000..5a8962382 --- /dev/null +++ b/docs/kit/development-view/page00_development_view.md @@ -0,0 +1,24 @@ +# Development View + +## Project Overview + +TractusX is an initiative of companies under the umbrella of the Eclipse Foundation. +It is a pilot for the larger initiative of CatenaX. +A broader overview of the project can be found on the initiative's [Github page][tractusx-edc-link] +or the homepage of the [Eclipse Foundation](https://projects.eclipse.org/projects/automotive.tractusx). + +## The EDC + +The Eclipse Dataspace Connector is one of the core components facilitating TractusX. + +:::note TractusX EDC or Core EDC? + +This documentation is for TractusX EDC. +It includes the Core EDC with all of its functionality. +However, this core is supplemented by extensions that allow for the use of additional backends and connection types. +Furthermore, the provided Helm charts, build configuration and tests allow for a smoother deployment. +::: + +You can find the repository for the TractusX EDC [here][tractusx-edc-link]. + +[tractusx-edc-link]: https://github.com/eclipse-tractusx/tractusx-edc diff --git a/docs/kit/development-view/page01_eclipse_foundation.md b/docs/kit/development-view/page01_eclipse_foundation.md new file mode 100644 index 000000000..5d865ff76 --- /dev/null +++ b/docs/kit/development-view/page01_eclipse_foundation.md @@ -0,0 +1,35 @@ +# The Eclipse Foundation + +## Eclipse Development Process + +This Eclipse Foundation open project is governed by the Eclipse Foundation +Development Process and operates under the terms of the Eclipse IP Policy. + +* +* + +## Eclipse Contributor Agreement + +In order to be able to contribute to Eclipse Foundation projects you must +electronically sign the Eclipse Contributor Agreement (ECA). + +* + +The ECA provides the Eclipse Foundation with a permanent record that you agree +that each of your contributions will comply with the commitments documented in +the Developer Certificate of Origin (DCO). Having an ECA on file associated with +the email address matching the "Author" field of your contribution's Git commits +fulfills the DCO's requirement that you sign-off on your contributions. + +For more information, please see the Eclipse Committer Handbook: + + +## License + +Code in TractusX EDC is published under the [Apache License](https://github.com/eclipse-tractusx/tractusx-edc/blob/main/LICENSE). + +## Contact + +Contact the project developers via the project's "dev" list. + +* diff --git a/docs/kit/development-view/page02_repository_structure.md b/docs/kit/development-view/page02_repository_structure.md new file mode 100644 index 000000000..7ac6b20d9 --- /dev/null +++ b/docs/kit/development-view/page02_repository_structure.md @@ -0,0 +1,26 @@ +# Repository Structure + +The repository for TractusX EDC can be found [here](https://github.com/eclipse-tractusx/tractusx-edc). +It contains the following components: + +## EDC Extensions + +The core EDC is extensible by design. +TractusX EDC provides such extensions. +These extensions and their documentation are available +[here](https://github.com/eclipse-tractusx/tractusx-edc/blob/main/edc-extensions/README.md). + +## Gradle Files for EDC Builds + +Builds of TractusX EDC are performed via Gradle. +To allow for different configurations, different builds are provided. +For example separate secrets backends are supported, but require separate builds of EDC. +Therefor, different builds are available for both +[data plane](https://github.com/eclipse-tractusx/tractusx-edc/blob/main/edc-dataplane/README.md) +and [control plane](https://github.com/eclipse-tractusx/tractusx-edc/blob/main/edc-controlplane/README.md), + +## Helm Charts for EDC Deployment + +To facilitate deployment of these different builds and their prerequisites, +Helm charts are provided. The charts and their documentation can be found +[here](https://github.com/eclipse-tractusx/tractusx-edc/blob/main/charts/README.md). diff --git a/docs/kit/development-view/page03_project_structure.md b/docs/kit/development-view/page03_project_structure.md new file mode 100644 index 000000000..43de01233 --- /dev/null +++ b/docs/kit/development-view/page03_project_structure.md @@ -0,0 +1,21 @@ +# Project Structure + +## Issue Tracking + +Issues are maintained in [GitHub Issues](https://github.com/eclipse-tractusx/tractusx-edc/issues). + +## Reporting Vulnerabilities + +Vulnerabilities in the TractusX code base are best reported directly to the +[Eclipse Foundation](https://www.eclipse.org/security/). + +## Git Flow + +The TractusX EDC repository uses a Git Flow, with `main` as the development branch and `releases` as the release branch. +Other branches should follow the naming conventions of `feature/x` or `hotfix/x`, though this is not strictly enforced. + +## Tooling + +We use Java 11 with Gradle for dependencies and builds. +We use [Spotless](https://github.com/diffplug/spotless) for code formatting. +Releases are in the form of Docker containers and Helm charts. diff --git a/docs/kit/operation-view/page00_operation_view.md b/docs/kit/operation-view/page00_operation_view.md new file mode 100644 index 000000000..3c5651b62 --- /dev/null +++ b/docs/kit/operation-view/page00_operation_view.md @@ -0,0 +1,24 @@ +# Software Operation View + +## Introduction + +The following documentation will guide you through the TractusX EDC deployment. +You will be setting up multiple controllers and enabling communication between them. + +:::note TractusX EDC or Core EDC? + +The following guide assumes the use of the TractusX EDC. +It includes the Core EDC with all of its functionality. +However, this core is supplemented by extensions that allow for the use of additional backends and connection types. +Furthermore, the provided Helm charts, build configuration and tests allow for a smoother deployment. +::: + +## Connector Components + +In a usual EDC environment, each participant would operate at least one connector. +Each of these connectors consists of a control plane and a data plane. +The control plane functions as administration layer and is responsible for resource management, contract negotiation and administering data transfer. +The data plane does the heavy lifting of transferring and receiving data streams. + +Each of these planes comes in several variants, allowing for example secrets to be stored in Azure Vault or a Hashicorp Vault. +The setup on the following pages assumes the use of Hashicorp Vault for secrets and PostgreSQL for data storage. diff --git a/docs/kit/operation-view/page02_technical_prerequisites.md b/docs/kit/operation-view/page02_technical_prerequisites.md new file mode 100644 index 000000000..83ed7e76b --- /dev/null +++ b/docs/kit/operation-view/page02_technical_prerequisites.md @@ -0,0 +1,43 @@ +# Technical Prerequisites + +## Obtaining Releases + +The most recent release of TractusX EDC can be obtained under `https://github.com/eclipse-tractusx/tractusx-edc/releases`. +To create your own build, you can clone the repository at `https://github.com/eclipse-tractusx/tractusx-edc` and consult the provided README.md. +This can be useful if you want to use non-standard extensions or configuration. + +## Container Environment + +TractusX releases come in the form of Docker containers and corresponding Helm charts. +As such, recent versions of the following are required. + +- Docker +- Kubernetes +- Helm + +Seeing as these are standard tools, TractusX EDC will run on any cloud environment that can accept Helm charts. + +## Backend Dependencies + +The EDC requires backend services for persistence of data and secrets. The following backends are currently supported. + +Data Storage: + +- PostgreSQL database +- In memory database + +Secret Storage: + +- Hashicorp Vault +- Azure Vault + +The default setup assumes data storage via PostgreSQL database. +In memory storage is only recommended for running tests. +Hashicorp Vault is the default secret provider, because it is platform-agnostic. + +Helm charts are provided to set up these services locally. +**These are not suited for production environments.** + +## All-in-one deployment + +An all-in-one deployment is no longer in scope and will not be provided. diff --git a/docs/kit/operation-view/page03_local_setup_controlplane.md b/docs/kit/operation-view/page03_local_setup_controlplane.md new file mode 100644 index 000000000..93c52606f --- /dev/null +++ b/docs/kit/operation-view/page03_local_setup_controlplane.md @@ -0,0 +1,141 @@ +# Setting up a local EDC Control Plane + +## Basics + +The EDC is split into control and data plane. +The data plane handles the actual data transfer between parties. +The control plane manages the following: + +- Resource Management (e.g. Assets, Policies & Contract Definitions CRUD) +- Contract Offering & Contract Negotiation +- Data Transfer Coordination / Management + +The EDC control plane can run as a single container on your local machine. +The following is a short overview of the necessary steps to start up the default configuration. + +## Building + +TractusX EDC is build with Gradle. The following command creates the default control plane as a docker container: + +```shell +./gardlew :edc-controlplane:edc-controlplane-postgresql-hashicorp-vault:dockerize +``` + +## Example Configuration + +The following commands can be used to create the necessary configuration files for the EDC container. +They assume sane - but unsafe - defaults. An explanation of the respective parameters can be found [here](https://github.com/eclipse-tractusx/tractusx-edc/blob/main/edc-controlplane/edc-controlplane-postgresql-hashicorp-vault/README.md). + +:::danger +The following configuration is for testing purposes only. Do not use it in production. +::: + +### Example configuration.properties + +```shell +# Create configuration.properties +export CONFIGURATION_PROPERTIES_FILE=$(mktemp /tmp/configuration.properties.XXXXXX) +cat << 'EOF' > ${CONFIGURATION_PROPERTIES_FILE} + +web.http.default.port=8080 +web.http.default.path=/api +web.http.management.port=8181 +web.http.management.path=/data +web.http.control.port=9999 +web.http.control.path=/api/controlplane/control +web.http.protocol.port=8282 +web.http.protocol.path=/api/v1/ids + +edc.receiver.http.dynamic.endpoint=http://backend-service + +edc.ids.title=Eclipse Dataspace Connector +edc.ids.description=Eclipse Dataspace Connector +edc.ids.id=urn:connector:edc +edc.ids.security.profile=base +edc.ids.endpoint=http://localhost:8282/api/v1/ids +edc.ids.maintainer=http://localhost +edc.ids.curator=http://localhost +edc.ids.catalog.id=urn:catalog:default +ids.webhook.address=http://localhost:8282/api/v1/ids + +edc.hostname=localhost + +edc.api.auth.key=password + +# OAuth / DAPS related configuration +edc.oauth.token.url=https://daps.catena-x.net +edc.oauth.certificate.alias=key-to-daps-certificate-in-keyvault +edc.oauth.private.key.alias=key-to-private-key-in-keyvault +edc.oauth.client.id=daps-oauth-client-id + +# HashiCorp vault related configuration +edc.vault.hashicorp.url=http://vault +edc.vault.hashicorp.token=55555555-6666-7777-8888-999999999999 +edc.vault.hashicorp.timeout.seconds=30 + +# Control- / Data- Plane configuration +edc.transfer.proxy.endpoint=http://dataplane-public-endpoint/public +edc.transfer.proxy.token.signer.privatekey.alias=token-signer-private-key + +# Postgresql related configuration +edc.datasource.asset.name=asset +edc.datasource.asset.url=jdbc:postgresql://postgres.svc.cluster.local:5432/edc_asset +edc.datasource.asset.user=user +edc.datasource.asset.password=pass +edc.datasource.contractdefinition.name=contractdefinition +edc.datasource.contractdefinition.url=jdbc:postgresql://postgres.svc.cluster.local:5432/edc_contractdefinition +edc.datasource.contractdefinition.user=user +edc.datasource.contractdefinition.password=pass +edc.datasource.contractnegotiation.name=contractnegotiation +edc.datasource.contractnegotiation.url=jdbc:postgresql://postgres.svc.cluster.local:5432/edc_contractnegotiation +edc.datasource.contractnegotiation.user=user +edc.datasource.contractnegotiation.password=pass +edc.datasource.policy.name=policy +edc.datasource.policy.url=jdbc:postgresql://postgres.svc.cluster.local:5432/edc_policy +edc.datasource.policy.user=user +edc.datasource.policy.password=pass +edc.datasource.transferprocess.name=transferprocess +edc.datasource.transferprocess.url=jdbc:postgresql://postgres.svc.cluster.local:5432/edc_transferprocess +edc.datasource.transferprocess.user=user +edc.datasource.transferprocess.password=pass +EOF +``` + +### Example logging.properties + +```shell +# Create logging.properties +export LOGGING_PROPERTIES_FILE=$(mktemp /tmp/logging.properties.XXXXXX) +cat << 'EOF' > ${LOGGING_PROPERTIES_FILE} +.level=INFO +org.eclipse.edc.level=ALL +handlers=java.util.logging.ConsoleHandler +java.util.logging.ConsoleHandler.formatter=java.util.logging.SimpleFormatter +java.util.logging.ConsoleHandler.level=ALL +java.util.logging.SimpleFormatter.format=[%1$tY-%1$tm-%1$td %1$tH:%1$tM:%1$tS] [%4$-7s] %5$s%6$s%n +EOF +``` + +### Example opentelemetry.properties + +```shell +# Create opentelemetry.properties +export OPENTELEMETRY_PROPERTIES_FILE=$(mktemp /tmp/opentelemetry.properties.XXXXXX) +cat << 'EOF' > ${OPENTELEMETRY_PROPERTIES_FILE} +otel.javaagent.enabled=false +otel.javaagent.debug=false +EOF +``` + +## Running the Control Plane + +Once the configuration is created, the container can be run directly via docker. + +```shell +docker run \ + -p 8080:8080 -p 8181:8181 -p 8182:8182 -p 8282:8282 -p 9090:9090 -p 9999:9999 \ + -v ${CONFIGURATION_PROPERTIES_FILE:-/dev/null}:/app/configuration.properties \ + -v ${LOGGING_PROPERTIES_FILE:-/dev/null}:/app/logging.properties \ + -v ${OPENTELEMETRY_PROPERTIES_FILE:-/dev/null}:/app/opentelemetry.properties \ + -i edc-controlplane-postgresql-hashicorp-vault:latest +``` diff --git a/docs/kit/operation-view/page04_local_setup_dataplane.md b/docs/kit/operation-view/page04_local_setup_dataplane.md new file mode 100644 index 000000000..729a2371b --- /dev/null +++ b/docs/kit/operation-view/page04_local_setup_dataplane.md @@ -0,0 +1,98 @@ +# Setting up a local EDC Data Plane + +## Basics + +The EDC is split into control and data plane. +The data plane handles the actual data transfer between parties. +The control plane manages the following: + +- Resource Management (e.g. Assets, Policies & Contract Definitions CRUD) +- Contract Offering & Contract Negotiation +- Data Transfer Coordination / Management + +The EDC data plane can run as a single container on your local machine. +The following is a short overview of the necessary steps to start up the default configuration. + +## Building + +TractusX EDC is build with Gradle. The following command creates the default data plane as a docker container: + +```shell +./gardlew :edc-dataplane:edc-dataplane-hashicorp-vault:dockerize +``` + +## Example Configuration + +The following commands can be used to create the necessary configuration files for the EDC container. +They assume sane - but unsafe - defaults. An explanation of the respective parameters can be found [here](https://github.com/eclipse-tractusx/tractusx-edc/blob/main/edc-dataplane/edc-dataplane-hashicorp-vault/README.md). + +:::danger + +The following configuration is for testing purposes only. Do not use it in production. +::: + +### Example configuration.properties + +```shell +# Create configuration.properties +export CONFIGURATION_PROPERTIES_FILE=$(mktemp /tmp/configuration.properties.XXXXXX) +cat << 'EOF' > ${CONFIGURATION_PROPERTIES_FILE} + +web.http.default.port=8080 +web.http.default.path=/api +web.http.public.port=8185 +web.http.public.path=/public +web.http.control.port=9999 +web.http.control.path=/api/dataplane/control + +# Validation endpoint of controlplane +edc.dataplane.token.validation.endpoint=http://controlplane:9999/api/controlplane/control/token + +# EDC hostname +edc.hostname=localhost + +# HashiCorp vault related configuration +edc.vault.hashicorp.url=http://vault +edc.vault.hashicorp.token=55555555-6666-7777-8888-999999999999 +edc.vault.hashicorp.timeout.seconds=30 +EOF +``` + +### Example logging.properties + +```shell +# Create logging.properties +export LOGGING_PROPERTIES_FILE=$(mktemp /tmp/logging.properties.XXXXXX) +cat << 'EOF' > ${LOGGING_PROPERTIES_FILE} +.level=INFO +org.eclipse.edc.level=ALL +handlers=java.util.logging.ConsoleHandler +java.util.logging.ConsoleHandler.formatter=java.util.logging.SimpleFormatter +java.util.logging.ConsoleHandler.level=ALL +java.util.logging.SimpleFormatter.format=[%1$tY-%1$tm-%1$td %1$tH:%1$tM:%1$tS] [%4$-7s] %5$s%6$s%n +EOF +``` + +### Example opentelemetry.properties + +```shell +# Create opentelemetry.properties +export OPENTELEMETRY_PROPERTIES_FILE=$(mktemp /tmp/opentelemetry.properties.XXXXXX) +cat << 'EOF' > ${OPENTELEMETRY_PROPERTIES_FILE} +otel.javaagent.enabled=true +otel.javaagent.debug=false +EOF +``` + +## Running + +Once the configuration is created, the container can be run directly via docker. + +```shell +docker run \ + -p 8080:8080 -p 8185:8185 -p 9999:9999 -p 9090:9090 \ + -v ${CONFIGURATION_PROPERTIES_FILE:-/dev/null}:/app/configuration.properties \ + -v ${LOGGING_PROPERTIES_FILE:-/dev/null}:/app/logging.properties \ + -v ${OPENTELEMETRY_PROPERTIES_FILE:-/dev/null}:/app/opentelemetry.properties \ + -i edc-dataplane-hashicorp-vault:latest +``` diff --git a/docs/kit/operation-view/page06_kubernetes_setup.md b/docs/kit/operation-view/page06_kubernetes_setup.md new file mode 100644 index 000000000..67930be5e --- /dev/null +++ b/docs/kit/operation-view/page06_kubernetes_setup.md @@ -0,0 +1,22 @@ +# Setup in Kubernetes via Helm + +## Introduction + +While the local setup described earlier is sufficient to test basic EDC functionality, it is not appropriate for any actual environments. +For a more complete setup, Helm charts are provided. + +## Setup + +To set up an example environment, you can use the following Helm commands: + +```shell +helm repo add tractusx-edc https://eclipse-tractusx.github.io/charts/dev +helm install my-release tractusx-edc/tractusx-connector-memory --version 0.3.3 +``` + +## Configuration + +The Helm chart used above can be found [here](https://github.com/eclipse-tractusx/tractusx-edc/tree/main/charts). +Configuring that deployment requires the same parameters as the local setup described previously. +Helm expects these parameters in the relevant `values.yaml`. +Similar example configurations can be found with the respective charts under the above link. diff --git a/docs/kit/operation-view/page08_api.md b/docs/kit/operation-view/page08_api.md new file mode 100644 index 000000000..9f45abe14 --- /dev/null +++ b/docs/kit/operation-view/page08_api.md @@ -0,0 +1,64 @@ +# EDC API Examples + +## API Spec + +The API spec of the EDC is constantly evolving. +The full API documentation for each release can be viewed on [management-api](../development-view/openAPI/management-api/management-api.info.mdx). +The following are some example API calls for common use cases. +They assume the default parameters from the previous local setup. + +## Create an Asset + +All objects in EDC are created by posting their JSON-serialized representation to the respective API input. +Since most EDC objects are rather openly defined, most of the properties provided depend on the need of the individual user. +Assets are no exception here. + +URL + +```http request +POST http://localhost:8080/api/v1/assets/ +``` + +Body + +```json +{ + "asset": { + "id": "asset1", + "properties": { + "exampleProperty": "exampleValue" + } + }, + "dataAddress": { + "properties": { + "baseUrl": "https://path.to/the_asset", + "type": "HttpData" + } + } +} +``` + +## Request an Asset Catalog + +To inspect the assets available to an EDC connector, we request its catalog. + +URL + +```http request +POST http://localhost:8080/api/v1/catalog/request +``` + +Body + +```json +{ + "providerUrl": "www.example.provider", + "querySpec": { + "filter": "AvailableWithPolicyXYZ", + "limit": 0, + "offset": 0, + "sortField": "id", + "sortOrder": "ASC" + } +} +``` diff --git a/docs/kit/operation-view/page09_upgrading.md b/docs/kit/operation-view/page09_upgrading.md new file mode 100644 index 000000000..e63a55526 --- /dev/null +++ b/docs/kit/operation-view/page09_upgrading.md @@ -0,0 +1,20 @@ +# Upgrading TractusX EDC + +Among the goals of TractusX EDC is making EDC upgrades as painless as possible. +The changes in each release are documented [here](https://github.com/eclipse-tractusx/tractusx-edc/tree/main/docs/migration). +Usually there are only three steps to each upgrade. + +## Database Migration + +Database migration is simple to accomplish with a PostgreSQL backend. +The [PostgreSQL Migration Extension](https://github.com/eclipse-tractusx/tractusx-edc/tree/main/edc-extensions/postgresql-migration) is the preferred approach. +Alternatively, the `.sql` files therein can be used to manually update the database schema. + +## Updating EDC + +The easy part of the upgrade process is to simply switch the outdated EDC containers with their newer counterparts. + +## Updating Settings + +Check the newest [Migration Documents](https://github.com/eclipse-tractusx/tractusx-edc/tree/develop/docs/migration) +for any changes to the settings structure and apply them to your settings. diff --git a/docs/kit/operation-view/page10_extensions.md b/docs/kit/operation-view/page10_extensions.md new file mode 100644 index 000000000..dce82d153 --- /dev/null +++ b/docs/kit/operation-view/page10_extensions.md @@ -0,0 +1,44 @@ +# EDC Extensions + +The following extensions provide additional functionality to the core EDC. +They are currently only available in TractusX EDC. + +## Business Partner Validation + +This extension allows for validation of business partners within the access policy. + +## Control Plane Adapter + +The goal of this extension is to simplify the process of retrieving data out of EDC. +It returns `EndpointDataReference` object, hiding all the communication details for contract offers, +contract negotiation, transfer process and retrieving the underlying data through the data-planes. + +## CX OAuth2 + +This extension enables OAuth2 authentication between EDC connectors, +instead of the more complex authentication flow used by core EDC. + +## Data Encryption + +The EDC encrypts sensitive information inside a token it sends to other applications (potentially cross-company). +This extension implements the encryption of this data and should be used with secure keys and algorithms at all times. + +## Data Plane Selector + +This control plane extension makes it possible to configure one or more data plane instances. +During a transfer the control plane will look for an instance with matching capabilities to transfer data. + +## Hashicorp Vault + +This extension allows for usage of Hashicorp Vault for secret storage. +It is the default used in TractusX EDC. + +## PostrgreSQL Migration + +While the core EDC is able to interact with PostgreSQL databases, +it does not automate migrations between schema versions. +This extension adds that functionality. + +## Transfer Process SFTP + +This extension allows for the use of SFTP backends for the data plane (but is not included in the provided control- and data plane).