Skip to content

Commit

Permalink
docs: add quick guide to the charts' README (#520)
Browse files Browse the repository at this point in the history
  • Loading branch information
paullatzelsperger authored Jun 22, 2023
1 parent 55e8d69 commit e3ef31c
Show file tree
Hide file tree
Showing 9 changed files with 148 additions and 121 deletions.
46 changes: 25 additions & 21 deletions charts/tractusx-connector-azure-vault/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,31 +9,38 @@ 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>

This chart uses Azure KeyVault, which is expected to contain the following secrets on application start:
## Setting up SSI

- `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.
### Preconditions

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:
- the Managed Identity Walled (MIW) must be running and reachable via network
- the necessary set of VerifiableCredentials for this participant must be pushed to MIW. This is typically done by the
Portal during participant onboarding
- KeyCloak must be running and reachable via network
- an account with KeyCloak must be created for this BPN and the connector must be able to obtain access tokens
- the client ID and client secret corresponding to that account must be known

```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)"
```
### Preparatory work

## Launching the application
- store your KeyCloak client secret in the Azure KeyVault. The exact procedure is as follows:
```bash
az keyvault secret set --vault-name <YOUR_VAULT_NAME> --name client-secret --value "$YOUR_CLIENT_SECRET"
```
By default, Tractus-X EDC expects to find the secret under `client-secret`.

The following requirements must be met before launching the application:
### Configure the chart

- 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
Be sure to provide the following configuration entries to your Tractus-X EDC Helm chart:
- `controlplane.ssi.miw.url`: the URL
- `controlplane.ssi.miw.authorityId`: the BPN of the issuer authority
- `controlplane.ssi.oauth.tokenurl`: the URL (of KeyCloak), where access tokens can be obtained
- `controlplane.ssi.oauth.client.id`: client ID for KeyCloak
- `controlplane.ssi.oauth.client.secretAlias`: the alias under which the client secret is stored in the vault. Defaults to `client-secret`.

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.
### Launching the application

As an easy starting point, please 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. The configuration values mentioned above (`controlplane.ssi.*`) will have to be adapted manually.
Combined, run this shell command to start the in-memory Tractus-X EDC runtime:

```shell
Expand All @@ -46,8 +53,6 @@ helm install my-release tractusx-edc/tractusx-connector-azure-vault --version 0.
--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>
Expand Down Expand Up @@ -160,7 +165,6 @@ Note that `DAPS_CERT` contains the x509 certificate, `DAPS_KEY` contains the pri
| controlplane.securityContext.runAsUser | int | `10001` | The container's process will run with the specified uid |
| controlplane.service.annotations | object | `{}` | |
| controlplane.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. |
| controlplane.ssi.endpoint.audience | string | `"http://this.audience"` | |
| controlplane.ssi.miw.authorityId | string | `""` | |
| controlplane.ssi.miw.url | string | `""` | |
| controlplane.ssi.oauth.client.id | string | `""` | |
Expand Down
47 changes: 27 additions & 20 deletions charts/tractusx-connector-azure-vault/README.md.gotmpl
Original file line number Diff line number Diff line change
Expand Up @@ -8,31 +8,40 @@

{{ template "chart.homepageLine" . }}

This chart uses Azure KeyVault, which is expected to contain the following secrets on application start:
## Setting up SSI

- `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.
### Preconditions

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:
- the Managed Identity Walled (MIW) must be running and reachable via network
- the necessary set of VerifiableCredentials for this participant must be pushed to MIW. This is typically done by the
Portal during participant onboarding
- KeyCloak must be running and reachable via network
- an account with KeyCloak must be created for this BPN and the connector must be able to obtain access tokens
- the client ID and client secret corresponding to that account must be known

```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)"
```
### Preparatory work

- store your KeyCloak client secret in the Azure KeyVault. The exact procedure is as follows:
```bash
az keyvault secret set --vault-name <YOUR_VAULT_NAME> --name client-secret --value "$YOUR_CLIENT_SECRET"
```
By default, Tractus-X EDC expects to find the secret under `client-secret`.

## Launching the application

The following requirements must be met before launching the application:
### Configure the chart

- 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
Be sure to provide the following configuration entries to your Tractus-X EDC Helm chart:
- `controlplane.ssi.miw.url`: the URL
- `controlplane.ssi.miw.authorityId`: the BPN of the issuer authority
- `controlplane.ssi.oauth.tokenurl`: the URL (of KeyCloak), where access tokens can be obtained
- `controlplane.ssi.oauth.client.id`: client ID for KeyCloak
- `controlplane.ssi.oauth.client.secretAlias`: the alias under which the client secret is stored in the vault. Defaults to `client-secret`.

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.

### Launching the application

As an easy starting point, please 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. The configuration values mentioned above (`controlplane.ssi.*`) will have to be adapted manually.
Combined, run this shell command to start the in-memory Tractus-X EDC runtime:

```shell
Expand All @@ -45,8 +54,6 @@ helm install my-release tractusx-edc/tractusx-connector-azure-vault --version {{
--set vault.azure.tenant=$AZURE_TENANT_ID
```

Note that `DAPS_CERT` contains the x509 certificate, `DAPS_KEY` contains the private key.


{{ template "chart.maintainersSection" . }}

Expand Down
2 changes: 0 additions & 2 deletions charts/tractusx-connector-azure-vault/values.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -139,8 +139,6 @@ controlplane:
client:
id: ""
secretAlias: "client-secret"
endpoint:
audience: "http://this.audience"
service:
# -- [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.
type: ClusterIP
Expand Down
44 changes: 24 additions & 20 deletions charts/tractusx-connector-memory/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,39 +6,44 @@ A Helm chart for Tractus-X Eclipse Data Space Connector based on memory. Please

**Homepage:** <https://github.com/eclipse-tractusx/tractusx-edc/tree/main/charts/tractusx-connector-memory>

This chart uses an in-memory secrets vault, which is required to contain the following secrets on application start:
## Setting up SSI

- `daps-cert`: contains the x509 certificate of the connector.
- `daps-key`: the private key of the x509 certificate
### Preconditions

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:
- the Managed Identity Walled (MIW) must be running and reachable via network
- the necessary set of VerifiableCredentials for this participant must be pushed to MIW. This is typically done by the
Portal during participant onboarding
- KeyCloak must be running and reachable via network
- an account with KeyCloak must be created for this BPN and the connector must be able to obtain access tokens
- the client ID and client secret corresponding to that account must be known

```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)"
```
### Preparatory work

- store your KeyCloak client secret in the HashiCorp vault. The exact procedure will depend on your deployment of HashiCorp Vault and
is out of scope of this document. But by default, Tractus-X EDC expects to find the secret under `secret/client-secret`.

## Launching the application
### Configure the chart

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/edc-tests/deployment/src/main/resources/helm/tractusx-connector-memory-test.yaml)
to launch the application.
Be sure to provide the following configuration entries to your Tractus-X EDC Helm chart:
- `runtime.ssi.miw.url`: the URL
- `runtime.ssi.miw.authorityId`: the BPN of the issuer authority
- `runtime.ssi.oauth.tokenurl`: the URL (of KeyCloak), where access tokens can be obtained
- `runtime.ssi.oauth.client.id`: client ID for KeyCloak
- `runtime.ssi.oauth.client.secretAlias`: the alias under which the client secret is stored in the vault. Defaults to `client-secret`.

### Launching the application

As an easy starting point, please 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. The configuration values mentioned above (`controlplane.ssi.*`) will have to be adapted manually.
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.5.0-rc1 \
-f <path-to>/tractusx-connector-memory-test.yaml \
--set vault.secrets="daps-cert:$DAPS_CERT;daps-key:$DAPS_KEY" \
--set vault.secrets="client-secret:$YOUR_CLIENT_SECRET"
```

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>
Expand Down Expand Up @@ -157,7 +162,6 @@ Note that `DAPS_CERT` contains the x509 certificate, `DAPS_KEY` contains the pri
| runtime.securityContext.runAsUser | int | `10001` | The container's process will run with the specified uid |
| runtime.service.annotations | object | `{}` | |
| runtime.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. |
| runtime.ssi.endpoint.audience | string | `"http://this.audience"` | |
| runtime.ssi.miw.authorityId | string | `""` | |
| runtime.ssi.miw.url | string | `""` | |
| runtime.ssi.oauth.client.id | string | `""` | |
Expand Down
45 changes: 26 additions & 19 deletions charts/tractusx-connector-memory/README.md.gotmpl
Original file line number Diff line number Diff line change
Expand Up @@ -8,39 +8,46 @@

{{ template "chart.homepageLine" . }}

This chart uses an in-memory secrets vault, which is required to contain the following secrets on application start:
## Setting up SSI

- `daps-cert`: contains the x509 certificate of the connector.
- `daps-key`: the private key of the x509 certificate
### Preconditions

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:
- the Managed Identity Walled (MIW) must be running and reachable via network
- the necessary set of VerifiableCredentials for this participant must be pushed to MIW. This is typically done by the
Portal during participant onboarding
- KeyCloak must be running and reachable via network
- an account with KeyCloak must be created for this BPN and the connector must be able to obtain access tokens
- the client ID and client secret corresponding to that account must be known

### Preparatory work

- store your KeyCloak client secret in the HashiCorp vault. The exact procedure will depend on your deployment of HashiCorp Vault and
is out of scope of this document. But by default, Tractus-X EDC expects to find the secret under `secret/client-secret`.

```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
### Configure the chart

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/edc-tests/deployment/src/main/resources/helm/tractusx-connector-memory-test.yaml)
to launch the application.
Be sure to provide the following configuration entries to your Tractus-X EDC Helm chart:
- `runtime.ssi.miw.url`: the URL
- `runtime.ssi.miw.authorityId`: the BPN of the issuer authority
- `runtime.ssi.oauth.tokenurl`: the URL (of KeyCloak), where access tokens can be obtained
- `runtime.ssi.oauth.client.id`: client ID for KeyCloak
- `runtime.ssi.oauth.client.secretAlias`: the alias under which the client secret is stored in the vault. Defaults to `client-secret`.


### Launching the application

As an easy starting point, please 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. The configuration values mentioned above (`controlplane.ssi.*`) will have to be adapted manually.
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 }} \
-f <path-to>/tractusx-connector-memory-test.yaml \
--set vault.secrets="daps-cert:$DAPS_CERT;daps-key:$DAPS_KEY" \
--set vault.secrets="client-secret:$YOUR_CLIENT_SECRET"
```

Note that `DAPS_CERT` contains the x509 certificate, `DAPS_KEY` contains the private key.

{{ template "chart.maintainersSection" . }}

{{ template "chart.sourcesSection" . }}
Expand Down
2 changes: 0 additions & 2 deletions charts/tractusx-connector-memory/values.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -138,8 +138,6 @@ runtime:
client:
id: ""
secretAlias: "client-secret"
endpoint:
audience: "http://this.audience"

service:
# -- [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.
Expand Down
Loading

0 comments on commit e3ef31c

Please sign in to comment.