From 89410f66737a7b3d8680ca89a30883934d2e22a3 Mon Sep 17 00:00:00 2001 From: Paul Latzelsperger <43503240+paullatzelsperger@users.noreply.github.com> Date: Tue, 16 May 2023 13:43:05 +0200 Subject: [PATCH] docs: add documentation about the helm charts (#352) --- .../tractusx-connector-azure-vault/README.md | 36 +++++++++++++++++- .../README.md.gotmpl | 37 ++++++++++++++++++- charts/tractusx-connector-memory/Chart.yaml | 2 +- charts/tractusx-connector-memory/README.md | 32 ++++++++++++++-- .../README.md.gotmpl | 30 ++++++++++++++- charts/tractusx-connector/README.md | 29 ++++++++++++++- charts/tractusx-connector/README.md.gotmpl | 29 ++++++++++++++- 7 files changed, 181 insertions(+), 14 deletions(-) diff --git a/charts/tractusx-connector-azure-vault/README.md b/charts/tractusx-connector-azure-vault/README.md index b771639b7..f77158fd6 100644 --- a/charts/tractusx-connector-azure-vault/README.md +++ b/charts/tractusx-connector-azure-vault/README.md @@ -9,13 +9,45 @@ This chart is intended for use with an _existing_ PostgreSQL database and an _ex **Homepage:** -## TL;DR +This chart uses Azure KeyVault, which is expected to contain the following secrets on application start: + +- `daps-cert`: contains the x509 certificate of the connector. +- `daps-key`: the private key of the x509 certificate +- `aes-keys`: a 128bit, 256bit or 512bit string used to encrypt data. Must be stored in base64 format. + +These must be obtained from a DAPS instance, the process of which is out of the scope of this document. Alternatively, +self-signed certificates can be used for testing: + +```shell +openssl req -newkey rsa:2048 -new -nodes -x509 -days 3650 -keyout daps.key -out daps.cert -subj "/CN=test" +export DAPS_KEY="$(cat daps.key)" +export DAPS_CERT="$(cat daps.cert)" +``` + +## Launching the application + +The following requirements must be met before launching the application: + +- Write access to an Azure KeyVault instance is required to run this chart +- Secrets are seeded in advance +- The vault's client id, client secret, tenant id and vault name (not the url!) are known + +Please also consider using [this example configuration](https://github.com/eclipse-tractusx/tractusx-edc/blob/main/edc-tests/deployment/src/main/resources/helm/tractusx-connector-azure-vault-test.yaml) +to launch the application. +Combined, run this shell command to start the in-memory Tractus-X EDC runtime: ```shell helm repo add tractusx-edc https://eclipse-tractusx.github.io/charts/dev -helm install my-release tractusx-edc/tractusx-connector --version 0.3.3 +helm install my-release tractusx-edc/tractusx-connector-azure-vault --version 0.3.3 \ + -f /tractusx-connector-azure-vault-test.yaml \ + --set vault.azure.name=$AZURE_VAULT_NAME \ + --set vault.azure.client=$AZURE_CLIENT_ID \ + --set vault.azure.secret=$AZURE_CLIENT_SECRET \ + --set vault.azure.tenant=$AZURE_TENANT_ID ``` +Note that `DAPS_CERT` contains the x509 certificate, `DAPS_KEY` contains the private key. + ## Source Code * diff --git a/charts/tractusx-connector-azure-vault/README.md.gotmpl b/charts/tractusx-connector-azure-vault/README.md.gotmpl index 68eb2f3fe..c90617416 100644 --- a/charts/tractusx-connector-azure-vault/README.md.gotmpl +++ b/charts/tractusx-connector-azure-vault/README.md.gotmpl @@ -8,13 +8,46 @@ {{ template "chart.homepageLine" . }} -## TL;DR +This chart uses Azure KeyVault, which is expected to contain the following secrets on application start: + +- `daps-cert`: contains the x509 certificate of the connector. +- `daps-key`: the private key of the x509 certificate +- `aes-keys`: a 128bit, 256bit or 512bit string used to encrypt data. Must be stored in base64 format. + +These must be obtained from a DAPS instance, the process of which is out of the scope of this document. Alternatively, +self-signed certificates can be used for testing: + +```shell +openssl req -newkey rsa:2048 -new -nodes -x509 -days 3650 -keyout daps.key -out daps.cert -subj "/CN=test" +export DAPS_KEY="$(cat daps.key)" +export DAPS_CERT="$(cat daps.cert)" +``` + +## Launching the application + +The following requirements must be met before launching the application: + +- Write access to an Azure KeyVault instance is required to run this chart +- Secrets are seeded in advance +- The vault's client id, client secret, tenant id and vault name (not the url!) are known + +Please also consider using [this example configuration](https://github.com/eclipse-tractusx/tractusx-edc/blob/main/edc-tests/deployment/src/main/resources/helm/tractusx-connector-azure-vault-test.yaml) +to launch the application. +Combined, run this shell command to start the in-memory Tractus-X EDC runtime: ```shell helm repo add tractusx-edc https://eclipse-tractusx.github.io/charts/dev -helm install my-release tractusx-edc/tractusx-connector-azure-vault --version {{ .Version }} +helm install my-release tractusx-edc/tractusx-connector-azure-vault --version {{ .Version }} \ + -f /tractusx-connector-azure-vault-test.yaml \ + --set vault.azure.name=$AZURE_VAULT_NAME \ + --set vault.azure.client=$AZURE_CLIENT_ID \ + --set vault.azure.secret=$AZURE_CLIENT_SECRET \ + --set vault.azure.tenant=$AZURE_TENANT_ID ``` +Note that `DAPS_CERT` contains the x509 certificate, `DAPS_KEY` contains the private key. + + {{ template "chart.maintainersSection" . }} {{ template "chart.sourcesSection" . }} diff --git a/charts/tractusx-connector-memory/Chart.yaml b/charts/tractusx-connector-memory/Chart.yaml index cb0a06b72..30bf145af 100644 --- a/charts/tractusx-connector-memory/Chart.yaml +++ b/charts/tractusx-connector-memory/Chart.yaml @@ -21,7 +21,7 @@ --- apiVersion: v2 name: tractusx-connector-memory -description: A Helm chart for Tractus-X Eclipse Data Space Connector based on memory +description: A Helm chart for Tractus-X Eclipse Data Space Connector based on memory. Please only use this for development or testing purposes, never in production workloads! # 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 diff --git a/charts/tractusx-connector-memory/README.md b/charts/tractusx-connector-memory/README.md index 872827664..993964c3d 100644 --- a/charts/tractusx-connector-memory/README.md +++ b/charts/tractusx-connector-memory/README.md @@ -2,17 +2,43 @@ ![Version: 0.3.3](https://img.shields.io/badge/Version-0.3.3-informational?style=flat-square) ![Type: application](https://img.shields.io/badge/Type-application-informational?style=flat-square) ![AppVersion: 0.3.3](https://img.shields.io/badge/AppVersion-0.3.3-informational?style=flat-square) -A Helm chart for Tractus-X Eclipse Data Space Connector based on memory +A Helm chart for Tractus-X Eclipse Data Space Connector based on memory. Please only use this for development or testing purposes, never in production workloads! **Homepage:** -## TL;DR +This chart uses an in-memory secrets vault, which is required to contain the following secrets on application start: + +- `daps-cert`: contains the x509 certificate of the connector. +- `daps-key`: the private key of the x509 certificate + +These must be obtained from a DAPS instance, the process of which is out of the scope of this document. Alternatively, +self-signed certificates can be used for testing: + +```shell +openssl req -newkey rsa:2048 -new -nodes -x509 -days 3650 -keyout daps.key -out daps.cert -subj "/CN=test" +export DAPS_KEY="$(cat daps.key)" +export DAPS_CERT="$(cat daps.cert)" +``` + +## Launching the application + +The in-memory vault can be seeded directly with secrets that are passed in `:;:;...` format. +This config value can be passed to the runtime using the `vault.secrets` parameter. In addition, the runtime requires a +couple of configuration parameters, all of which can be found in the section below. Please also consider using +[this example configuration](https://github.com/eclipse-tractusx/tractusx-edc/blob/main/charts/tractusx-connector-memory/example.yaml) +to launch the application. + +Combined, run this shell command to start the in-memory Tractus-X EDC runtime: ```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 +helm install my-release tractusx-edc/tractusx-connector-memory --version 0.3.3 \ + -f /example.yaml \ + --set vault.secrets="daps-cert:$DAPS_CERT;daps-key:$DAPS_KEY" \ ``` +Note that `DAPS_CERT` contains the x509 certificate, `DAPS_KEY` contains the private key. + ## Source Code * diff --git a/charts/tractusx-connector-memory/README.md.gotmpl b/charts/tractusx-connector-memory/README.md.gotmpl index 44500d3d1..630e63377 100644 --- a/charts/tractusx-connector-memory/README.md.gotmpl +++ b/charts/tractusx-connector-memory/README.md.gotmpl @@ -8,13 +8,39 @@ {{ template "chart.homepageLine" . }} -## TL;DR +This chart uses an in-memory secrets vault, which is required to contain the following secrets on application start: + +- `daps-cert`: contains the x509 certificate of the connector. +- `daps-key`: the private key of the x509 certificate + +These must be obtained from a DAPS instance, the process of which is out of the scope of this document. Alternatively, +self-signed certificates can be used for testing: + +```shell +openssl req -newkey rsa:2048 -new -nodes -x509 -days 3650 -keyout daps.key -out daps.cert -subj "/CN=test" +export DAPS_KEY="$(cat daps.key)" +export DAPS_CERT="$(cat daps.cert)" +``` + +## Launching the application + +The in-memory vault can be seeded directly with secrets that are passed in `:;:;...` format. +This config value can be passed to the runtime using the `vault.secrets` parameter. In addition, the runtime requires a +couple of configuration parameters, all of which can be found in the section below. Please also consider using +[this example configuration](https://github.com/eclipse-tractusx/tractusx-edc/blob/main/charts/tractusx-connector-memory/example.yaml) +to launch the application. + +Combined, run this shell command to start the in-memory Tractus-X EDC runtime: ```shell helm repo add tractusx-edc https://eclipse-tractusx.github.io/charts/dev -helm install my-release tractusx-edc/tractusx-connector-memory --version {{ .Version }} +helm install my-release tractusx-edc/tractusx-connector-memory --version {{ .Version }} \ + -f /example.yaml \ + --set vault.secrets="daps-cert:$DAPS_CERT;daps-key:$DAPS_KEY" \ ``` +Note that `DAPS_CERT` contains the x509 certificate, `DAPS_KEY` contains the private key. + {{ template "chart.maintainersSection" . }} {{ template "chart.sourcesSection" . }} diff --git a/charts/tractusx-connector/README.md b/charts/tractusx-connector/README.md index dfee4ac35..85feb3436 100644 --- a/charts/tractusx-connector/README.md +++ b/charts/tractusx-connector/README.md @@ -9,11 +9,36 @@ This chart is intended for use with an _existing_ PostgreSQL database and an _ex **Homepage:** -## TL;DR +This chart uses Hashicorp Vault, which is expected to contain the following secrets on application start: + +- `daps-cert`: contains the x509 certificate of the connector. +- `daps-key`: the private key of the x509 certificate +- `aes-keys`: a 128bit, 256bit or 512bit string used to encrypt data. Must be stored in base64 format. + +These must be obtained from a DAPS instance, the process of which is out of the scope of this document. Alternatively, +self-signed certificates can be used for testing: + +```shell +openssl req -newkey rsa:2048 -new -nodes -x509 -days 3650 -keyout daps.key -out daps.cert -subj "/CN=test" +export DAPS_KEY="$(cat daps.key)" +export DAPS_CERT="$(cat daps.cert)" +``` + +## Launching the application + +The following requirements must be met before launching the application: + +- Write access to a HashiCorp Vault instance is required to run this chart +- Secrets are seeded in advance + +Please also consider using [this example configuration](https://github.com/eclipse-tractusx/tractusx-edc/blob/main/edc-tests/deployment/src/main/resources/helm/tractusx-connector-test.yaml) +to launch the application. +Combined, run this shell command to start the in-memory Tractus-X EDC runtime: ```shell helm repo add tractusx-edc https://eclipse-tractusx.github.io/charts/dev -helm install my-release tractusx-edc/tractusx-connector --version 0.3.3 +helm install my-release tractusx-edc/tractusx-connector-azure-vault --version 0.3.3 \ + -f /tractusx-connector-test.yaml ``` ## Source Code diff --git a/charts/tractusx-connector/README.md.gotmpl b/charts/tractusx-connector/README.md.gotmpl index b1671f5a2..267a294f3 100644 --- a/charts/tractusx-connector/README.md.gotmpl +++ b/charts/tractusx-connector/README.md.gotmpl @@ -8,11 +8,36 @@ {{ template "chart.homepageLine" . }} -## TL;DR +This chart uses Hashicorp Vault, which is expected to contain the following secrets on application start: + +- `daps-cert`: contains the x509 certificate of the connector. +- `daps-key`: the private key of the x509 certificate +- `aes-keys`: a 128bit, 256bit or 512bit string used to encrypt data. Must be stored in base64 format. + +These must be obtained from a DAPS instance, the process of which is out of the scope of this document. Alternatively, +self-signed certificates can be used for testing: + +```shell +openssl req -newkey rsa:2048 -new -nodes -x509 -days 3650 -keyout daps.key -out daps.cert -subj "/CN=test" +export DAPS_KEY="$(cat daps.key)" +export DAPS_CERT="$(cat daps.cert)" +``` + +## Launching the application + +The following requirements must be met before launching the application: + +- Write access to a HashiCorp Vault instance is required to run this chart +- Secrets are seeded in advance + +Please also consider using [this example configuration](https://github.com/eclipse-tractusx/tractusx-edc/blob/main/edc-tests/deployment/src/main/resources/helm/tractusx-connector-test.yaml) +to launch the application. +Combined, run this shell command to start the in-memory Tractus-X EDC runtime: ```shell helm repo add tractusx-edc https://eclipse-tractusx.github.io/charts/dev -helm install my-release tractusx-edc/tractusx-connector --version {{ .Version }} +helm install my-release tractusx-edc/tractusx-connector-azure-vault --version {{ .Version }} \ + -f /tractusx-connector-test.yaml ``` {{ template "chart.maintainersSection" . }}