Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: add walkthrough for multi-connector setup #437

Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
119 changes: 119 additions & 0 deletions docs/samples/example-dataspace/README.md
Original file line number Diff line number Diff line change
@@ -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`
23 changes: 23 additions & 0 deletions docs/samples/example-dataspace/daps/.helmignore
Original file line number Diff line number Diff line change
@@ -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/
43 changes: 43 additions & 0 deletions docs/samples/example-dataspace/daps/Chart.yaml
Original file line number Diff line number Diff line change
@@ -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"
39 changes: 39 additions & 0 deletions docs/samples/example-dataspace/daps/README.md
Original file line number Diff line number Diff line change
@@ -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)
62 changes: 62 additions & 0 deletions docs/samples/example-dataspace/daps/templates/_helpers.tpl
Original file line number Diff line number Diff line change
@@ -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 }}
92 changes: 92 additions & 0 deletions docs/samples/example-dataspace/daps/templates/configmap.yaml
Original file line number Diff line number Diff line change
@@ -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 -}}
Loading