docs: add walkthrough for multi-connector setup

docs/samples/example-dataspace/README.md

@@ -0,0 +1,119 @@
+# How-To run two connectors and a DAPS
+
+## 1. Prepare environment
+
+This guide will bring up two connectors named "Sokrates" and "Plato", each alongside their dependencies (Hashicorp
+Vault, PostgreSQL) and a DAPS instance that both share.
+
+We've tested this setup with [KinD](https://kind.sigs.k8s.io/), but other runtimes such
+as [Minikube](https://minikube.sigs.k8s.io/docs/start/) may work as well, we just haven't tested them.
+
+Furthermore, this guide assumes:
+
+- the Tractus-X EDC repository is checked out, the working directory for this guide is `docs/samples/example-dataspace`
+- a Kubernetes runtime (e.g. KinD) is already installed and ready-to-use
+- basic knowledge about `helm` and Kubernetes
+- the following tools are available: `yq`, `openssl`, `base64`
+- a POSIX-compliant shell, e.g. `bash` or `zsh` unless stated otherwise
+
+### 1.1 Create certificates for both runtimes
+
+We'll need a x509 certificate in order to communicate with DAPS, as well as a private key and a Data Encryption signing
+key.
+
+```shell
+# SOKRATES key/cert for daps
+openssl req -newkey rsa:2048 -new -nodes -x509 -days 1 -keyout sokrates.key -out sokrates.cert -subj "/CN=test"
+echo "aes_enckey_test" | base64 > sokrates.aes.key
+
+# PLATO key/cert for daps
+openssl req -newkey rsa:2048 -new -nodes -x509 -days 1 -keyout plato.key -out plato.cert -subj "/CN=test"
+echo "aes_enckey_test" | base64 > plato.aes.key
+```
+
+Any arbitrary string can be used for the AES key, but it has to be 16, 24, or 32 characters in length, assuming UTF-8
+encoding.
+
+### 1.2 Modify the DAPS's `values.yaml` located at `daps/values.yaml`
+
+With the following command, we "inject" the previously created certificates and client ids into the DAPS's config:
+
+```shell
+VALUES_FILE=daps/values.yaml
+
+# Add both public keys to daps
+yq -i ".connectors[0].certificate=\"$(cat sokrates.cert)\"" "$VALUES_FILE"
+yq -i ".connectors[1].certificate=\"$(cat plato.cert)\"" "$VALUES_FILE"
+```
+
+### 1.3 Install/Launch DAPS
+
+`helm install daps daps/`
+
+## 2. Prepare Connectors
+
+Next, the certificates and private keys we created previously must be stored in each connector's vault by injecting
+a `postStart` element to the chart's configuration file:
+
+```shell
+# for sokrates
+CONFIG_FILE=sokrates-values.yaml
+
+yq -i ".vault.server.postStart |= [\"sh\",\"-c\",\"{\nsleep 5\n\ncat << EOF | /bin/vault kv put secret/daps-crt content=-\n$(cat sokrates.cert)\nEOF\n\n
+cat << EOF | /bin/vault kv put secret/daps-key content=-\n$(cat sokrates.key)\nEOF\n\n
+/bin/vault kv put secret/aes-keys content=$(cat sokrates.aes.key)\n\n}\"]" "$CONFIG_FILE"
+
+# for plato
+CONFIG_FILE=plato-values.yaml
+
+yq -i ".vault.server.postStart |= [\"sh\",\"-c\",\"{\nsleep 5\n\ncat << EOF | /bin/vault kv put secret/daps-crt content=-\n$(cat plato.cert)\nEOF\n\n
+cat << EOF | /bin/vault kv put secret/daps-key content=-\n$(cat plato.key)\nEOF\n\n
+/bin/vault kv put secret/aes-keys content=$(cat plato.aes.key)\n\n}\"]" "$CONFIG_FILE"
+```
+
+## 3 Install the connectors
+
+Use `helm` to install the Tractus-X EDC Helm charts. In this example we are using the _local_ charts, assuming you have
+Tractus-X EDC checked out in your local filesystem at `<YOUR_PATH>`.
+
+```shell
+# install sokrates
+helm install tx-sokrates <YOUR_PATH>/charts/tractusx-connector \
+            -f sokrates-values.yaml \
+            --dependency-update
+
+# install plato 
+helm install tx-plato <YOUR_PATH>/charts/tractusx-connector \
+            -f plato-values.yaml \
+            --dependency-update
+```
+
+_Note: if you prefer to use the published version of the `tractusx-connector` chart, please add the Tractus-X Helm repo
+first:_
+
+```shell
+helm repo add tractusx-edc https://eclipse-tractusx.github.io/charts/dev
+helm install tx-[sokrates|plato] tractusx-edc/tractusx-connector \
+     -f [sokrates|plato]-values.yaml \
+     --dependency-update
+```
+
+## 3.1 [Optional] Verify the correct installation
+
+There is several ways of making sure everything worked out well:
+
+- simply look at the logs of the Helm releases, e.g. with a tool
+  like [stern](https://kubernetes.io/blog/2016/10/tail-kubernetes-with-stern/) and look out for a log line similar to:
+
+  ```shell
+  stern tx-sokrates
+  ```
+
+  then look out for something similar to:
+
+  ```shell
+  tx-sokrates-controlplane-b9456f97b-s5jts tractusx-connector INFO 2023-05-31T07:24:53.020975888 tx-sokrates-controlplane ready
+  ```
+
+- wait for the Kubernetes rollout to be successful, e.g. `kubectl rollout status deployment tx-plato-controlplane`
+- use `helm test` to execute tests: `helm test tx-plato`

docs/samples/example-dataspace/daps/.helmignore

@@ -0,0 +1,23 @@
+# Patterns to ignore when building packages.
+# This supports shell glob matching, relative path matching, and
+# negation (prefixed with !). Only one pattern per line.
+.DS_Store
+# Common VCS dirs
+.git/
+.gitignore
+.bzr/
+.bzrignore
+.hg/
+.hgignore
+.svn/
+# Common backup files
+*.swp
+*.bak
+*.tmp
+*.orig
+*~
+# Various IDEs
+.project
+.idea/
+*.tmproj
+.vscode/

docs/samples/example-dataspace/daps/Chart.yaml

@@ -0,0 +1,43 @@
+#  Copyright (c) 2023 Contributors to the Eclipse Foundation
+#
+#  See the NOTICE file(s) distributed with this work for additional
+#  information regarding copyright ownership.
+#
+#  This program and the accompanying materials are made available under the
+#  terms of the Apache License, Version 2.0 which is available at
+#  https://www.apache.org/licenses/LICENSE-2.0
+#
+#  Unless required by applicable law or agreed to in writing, software
+#  distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+#  WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+#  License for the specific language governing permissions and limitations
+#  under the License.
+#
+#  SPDX-License-Identifier: Apache-2.0
+#
+
+---
+apiVersion: v2
+name: daps
+description: A Helm chart for Kubernetes
+
+# A chart can be either an 'application' or a 'library' chart.
+#
+# Application charts are a collection of templates that can be packaged into versioned archives
+# to be deployed.
+#
+# Library charts provide useful utilities or functions for the chart developer. They're included as
+# a dependency of application charts to inject those utilities and functions into the rendering
+# pipeline. Library charts do not define any templates and therefore cannot be deployed.
+type: application
+
+# This is the chart version. This version number should be incremented each time you make changes
+# to the chart and its templates, including the app version.
+# Versions are expected to follow Semantic Versioning (https://semver.org/)
+version: 0.0.1
+
+# This is the version number of the application being deployed. This version number should be
+# incremented each time you make changes to the application. Versions are not expected to
+# follow Semantic Versioning. They should reflect the version the application is using.
+# It is recommended to use it with quotes.
+appVersion: "0.0.1"

docs/samples/example-dataspace/daps/README.md

@@ -0,0 +1,39 @@
+# daps
+
+![Version: 0.0.1](https://img.shields.io/badge/Version-0.0.1-informational?style=flat-square) ![Type: application](https://img.shields.io/badge/Type-application-informational?style=flat-square) ![AppVersion: 0.0.1](https://img.shields.io/badge/AppVersion-0.0.1-informational?style=flat-square)
+
+A Helm chart for Kubernetes
+
+## Values
+
+| Key | Type | Default | Description |
+|-----|------|---------|-------------|
+| affinity | object | `{}` | [Affinity](https://kubernetes.io/docs/concepts/scheduling-eviction/assign-pod-node/#affinity-and-anti-affinity) constrains which nodes the Pod can be scheduled on based on node labels. |
+| automountServiceAccountToken | bool | `false` | Whether to [automount kubernetes API credentials](https://kubernetes.io/docs/tasks/configure-pod-container/configure-service-account/#use-the-default-service-account-to-access-the-api-server) into the pod |
+| autoscaling.enabled | bool | `false` | Enables [horizontal pod autoscaling](https://kubernetes.io/docs/tasks/run-application/horizontal-pod-autoscale/https://kubernetes.io/docs/tasks/run-application/horizontal-pod-autoscale/) |
+| autoscaling.maxReplicas | int | `100` | Maximum replicas if resource consumption exceeds resource threshholds |
+| autoscaling.minReplicas | int | `1` | Minimal replicas if resource consumption falls below resource threshholds |
+| autoscaling.targetCPUUtilizationPercentage | int | `80` | targetAverageUtilization of cpu provided to a pod |
+| autoscaling.targetMemoryUtilizationPercentage | int | `80` | targetAverageUtilization of memory provided to a pod |
+| connectors | list | `[]` |  |
+| fullnameOverride | string | `""` | Overrides the releases full name |
+| image.pullPolicy | string | `"IfNotPresent"` | [Kubernetes image pull policy](https://kubernetes.io/docs/concepts/containers/images/#image-pull-policy) to use |
+| image.repository | string | `"ghcr.io/fraunhofer-aisec/omejdn-server"` | Which omjedn container image to use |
+| image.tag | string | `"1.7.1"` | Overrides the image tag whose default is the chart appVersion |
+| imagePullSecret.dockerconfigjson | string | `""` | Image pull secret to create to [obtain the container image from private registries](https://kubernetes.io/docs/concepts/containers/images/#using-a-private-registry) Note: This value needs to adhere to the [(base64 encoded) .dockerconfigjson format](https://kubernetes.io/docs/tasks/configure-pod-container/pull-image-private-registry/#registry-secret-existing-credentials). Furthermore, if 'imagePullSecret.dockerconfigjson' is defined, it takes precedence over 'imagePullSecrets'. |
+| nameOverride | string | `""` | Overrides the charts name |
+| nodeSelector | object | `{}` | [Node-Selector](https://kubernetes.io/docs/concepts/scheduling-eviction/assign-pod-node/#nodeselector) to constrain the Pod to nodes with specific labels. |
+| podAnnotations | object | `{}` | [Annotations](https://kubernetes.io/docs/concepts/overview/working-with-objects/annotations/) added to deployed [pods](https://kubernetes.io/docs/concepts/workloads/pods/) |
+| podSecurityContext | object | `{}` |  |
+| replicaCount | int | `1` | Specifies how many replicas of a deployed pod shall be created during the deployment Note: If horizontal pod autoscaling is enabled this setting has no effect |
+| resources | object | `{}` | [Resource management](https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/) applied to the deployed pod |
+| securityContext | object | `{}` |  |
+| service.port | int | `4567` | [Service type](https://kubernetes.io/docs/concepts/services-networking/service/#defining-a-service) to expose the running application on a set of Pods as a network service. |
+| service.type | string | `"ClusterIP"` | [Service type](https://kubernetes.io/docs/concepts/services-networking/service/#publishing-services-service-types) to expose the running application on a set of Pods as a network service. |
+| serviceAccount.annotations | object | `{}` | [Annotations](https://kubernetes.io/docs/concepts/overview/working-with-objects/annotations/) to add to the service account |
+| serviceAccount.create | bool | `true` | Specifies whether a [service account](https://kubernetes.io/docs/tasks/configure-pod-container/configure-service-account/) should be created per release |
+| serviceAccount.name | string | `""` | The name of the service account to use. If not set and create is true, a name is generated using the release's fullname template |
+| tolerations | list | `[]` | [Tolerations](https://kubernetes.io/docs/concepts/scheduling-eviction/taint-and-toleration/) are applied to Pods to schedule onto nodes with matching taints. |
+
+----------------------------------------------
+Autogenerated from chart metadata using [helm-docs v1.10.0](https://github.com/norwoodj/helm-docs/releases/v1.10.0)

docs/samples/example-dataspace/daps/templates/_helpers.tpl

@@ -0,0 +1,62 @@
+{{/*
+Expand the name of the chart.
+*/}}
+{{- define "omejdn.name" -}}
+{{- default .Chart.Name .Values.nameOverride | trunc 63 | trimSuffix "-" }}
+{{- end }}
+
+{{/*
+Create a default fully qualified app name.
+We truncate at 63 chars because some Kubernetes name fields are limited to this (by the DNS naming spec).
+If release name contains chart name it will be used as a full name.
+*/}}
+{{- define "omejdn.fullname" -}}
+{{- if .Values.fullnameOverride }}
+{{- .Values.fullnameOverride | trunc 63 | trimSuffix "-" }}
+{{- else }}
+{{- $name := default .Chart.Name .Values.nameOverride }}
+{{- if contains $name .Release.Name }}
+{{- .Release.Name | trunc 63 | trimSuffix "-" }}
+{{- else }}
+{{- printf "%s-%s" .Release.Name $name | trunc 63 | trimSuffix "-" }}
+{{- end }}
+{{- end }}
+{{- end }}
+
+{{/*
+Create chart name and version as used by the chart label.
+*/}}
+{{- define "omejdn.chart" -}}
+{{- printf "%s-%s" .Chart.Name .Chart.Version | replace "+" "_" | trunc 63 | trimSuffix "-" }}
+{{- end }}
+
+{{/*
+Common labels
+*/}}
+{{- define "omejdn.labels" -}}
+helm.sh/chart: {{ include "omejdn.chart" . }}
+{{ include "omejdn.selectorLabels" . }}
+{{- if .Chart.AppVersion }}
+app.kubernetes.io/version: {{ .Chart.AppVersion | quote }}
+{{- end }}
+app.kubernetes.io/managed-by: {{ .Release.Service }}
+{{- end }}
+
+{{/*
+Selector labels
+*/}}
+{{- define "omejdn.selectorLabels" -}}
+app.kubernetes.io/name: {{ include "omejdn.name" . }}
+app.kubernetes.io/instance: {{ .Release.Name }}
+{{- end }}
+
+{{/*
+Create the name of the service account to use
+*/}}
+{{- define "omejdn.serviceAccountName" -}}
+{{- if .Values.serviceAccount.create }}
+{{- default (include "omejdn.fullname" .) .Values.serviceAccount.name }}
+{{- else }}
+{{- default "default" .Values.serviceAccount.name }}
+{{- end }}
+{{- end }}

docs/samples/example-dataspace/daps/templates/configmap.yaml

@@ -0,0 +1,92 @@
+#  Copyright (c) 2023 Contributors to the Eclipse Foundation
+#
+#  See the NOTICE file(s) distributed with this work for additional
+#  information regarding copyright ownership.
+#
+#  This program and the accompanying materials are made available under the
+#  terms of the Apache License, Version 2.0 which is available at
+#  https://www.apache.org/licenses/LICENSE-2.0
+#
+#  Unless required by applicable law or agreed to in writing, software
+#  distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+#  WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+#  License for the specific language governing permissions and limitations
+#  under the License.
+#
+#  SPDX-License-Identifier: Apache-2.0
+#
+
+---
+apiVersion: v1
+kind: ConfigMap
+metadata:
+  name: {{ include "omejdn.fullname" . }}
+  labels:
+    {{- include "omejdn.labels" . | nindent 4 }}
+data:
+  scope_mapping.yml: |-
+    ---
+    idsc:IDS_CONNECTOR_ATTRIBUTES_ALL:
+      - referringConnector
+
+  omejdn.yml: |-
+    ---
+    host: http://daps:4567/
+    path_prefix: ''
+    bind_to: 0.0.0.0
+    allow_origin: "*"
+    app_env: debug
+    openid: false
+    user_backend:
+      - yaml
+    user_backend_default: yaml
+    accept_audience: idsc:IDS_CONNECTORS_ALL
+    issuer: http://daps:4567/
+    environment: development
+    default_audience:
+      - idsc:IDS_CONNECTORS_ALL
+    access_token:
+      expiration: 3600
+      algorithm: RS256
+    id_token:
+      expiration: 3600
+      algorithm: RS256
+
+  plugins.yml: |-
+    ---
+    plugins:
+      token_user_attributes:
+
+  clients.yml: |-
+    ---
+    - client_id: data-plane-oauth2
+      client_secret: supersecret
+      name: provision oauth2
+      grant_types:
+        - client_credentials
+      token_endpoint_auth_method: client_secret_post
+      scope: openid
+{{- range $i, $val := .Values.connectors }}
+    - client_id: {{ quote $val.id }}
+      name: {{ quote $val.name }}
+      token_endpoint_auth_method: private_key_jwt
+      grant_types:
+        - client_credentials
+      scope:
+        - idsc:IDS_CONNECTOR_ATTRIBUTES_ALL
+      attributes:
+        - key: idsc
+          value: IDS_CONNECTOR_ATTRIBUTES_ALL
+        - key: securityProfile
+          value: idsc:BASE_SECURITY_PROFILE
+        {{- range $key, $value := $val.attributes }}
+        - key: {{ $key }}
+          value: {{ $value }}
+        {{- end }}
+      redirect_uri: http://localhost:4200
+{{ end -}}
+
+
+{{- range $i, $val :=  .Values.connectors }}
+  {{ $val.name }}: {{ quote $val.certificate | toString }}
+{{ end -}}