docs: add documentation about the helm charts (#352)

eclipse-tractusx · May 16, 2023 · 89410f6 · 89410f6
1 parent 58c746e
commit 89410f6
Show file tree

Hide file tree

Showing 7 changed files with 181 additions and 14 deletions.
diff --git 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:** <https://github.com/eclipse-tractusx/tractusx-edc/tree/main/charts/tractusx-connector>
 
-## 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 <path-to>/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
 
 * <https://github.com/eclipse-tractusx/tractusx-edc/tree/main/charts/tractusx-connector>

diff --git 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 <path-to>/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
@@ -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
@@ -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:** <https://github.com/eclipse-tractusx/tractusx-edc/tree/main/charts/tractusx-connector-memory>
 
-## 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 `<key>:<value>;<key2>:<value2>;...` 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 <path-to>/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
 
 * <https://github.com/eclipse-tractusx/tractusx-edc/tree/main/charts/tractusx-connector-memory>

diff --git 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 `<key>:<value>;<key2>:<value2>;...` 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 <path-to>/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
@@ -9,11 +9,36 @@ This chart is intended for use with an _existing_ PostgreSQL database and an _ex
 
 **Homepage:** <https://github.com/eclipse-tractusx/tractusx-edc/tree/main/charts/tractusx-connector>
 
-## 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 <path-to>/tractusx-connector-test.yaml
 ```
 
 ## Source Code

diff --git 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 <path-to>/tractusx-connector-test.yaml
 ```
 
 {{ template "chart.maintainersSection" . }}