From c238f3e6c33e13d4cfdcd41945e6a7e75415326a Mon Sep 17 00:00:00 2001 From: "Dr. Christoph \"Schorsch\" Jung" Date: Tue, 3 Dec 2024 14:40:02 +0100 Subject: [PATCH] docs: refactore deployment information into admin guide. --- README.md | 1 + docs/README.md | 162 +------------------------------------ docs/admin/README.md | 188 +++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 192 insertions(+), 159 deletions(-) create mode 100644 docs/admin/README.md diff --git a/README.md b/README.md index 2c0c320..eee97ff 100644 --- a/README.md +++ b/README.md @@ -30,6 +30,7 @@ KA-EDC is a product of the [Tractus-X Knowledge Agents Kit](https://eclipse-trac * See the [User Documentation](docs/README.md) * See the [Architecture](docs/architecture/Arc42.md) * See the [OpenAPI definition](https://github.com/eclipse-tractusx/knowledge-agents/blob/main/docs/api/openAPI.yaml) +* See the [Administration Guide](docs/admin/README.md) * See the [Authors](AUTHORS.md) * See the [Changelog](CHANGELOG.md) * See the [Code of Conduct](CODE_OF_CONDUCT.md) diff --git a/docs/README.md b/docs/README.md index fea83c5..1db778e 100644 --- a/docs/README.md +++ b/docs/README.md @@ -49,165 +49,9 @@ using different extensions for - Persistence of the Control-Plane-State - Persistence of Secrets (Vault) -## Connector Setup - -The two supported setups are. - -- Setup 1: PostgreSQL & Azure Vault - - [Control Plane](https://github.com/eclipse-tractusx/edc-controlplane/edc-controlplane-postgresql-azure-vault/README.md) - - [Agent Plane](../agent-plane/agentplane-azure-vault/README.md) - - [Data Plane](https://github.com/eclipse-tractusx/edc-dataplane/edc-dataplane-azure-vault/README.md) - - [JWT Auth Extension](../common/jwt-auth/README.md) -- Setup 2: PostgreSQL & HashiCorp Vault - - [Control Plane](https://github.com/eclipse-tractusx/edc-controlplane/README.md) - - [Agent Plane](../agent-plane/agentplane-hashicorp/README.md) - - [Data Plane](https://github.com/eclipse-tractusx/edc-dataplane/edc-dataplane-hashicorp-vault/README.md) - - [JWT Auth Extension](../common/jwt-auth/README.md) - -## Helm Deployment - -To install a KA-enabled EDC (Setup 1 - Postgresql & Hashicorp Vault), add the following lines to the dependency section of your Charts.yaml - -```yaml -dependencies: - - - name: tractusx-connector - repository: https://eclipse-tractusx.github.io/charts/dev - version: 0.7.0 - alias: my-connector - - name: agent-plane - repository: https://eclipse-tractusx.github.io/charts/dev - version: 1.14.24-SNAPSHOT - alias: my-agent -``` - -To install a KA-enabled EDC (Setup 2 - Postgresql & Azure Vault), add the following lines to the dependency section of your Charts.yaml - -```yaml -dependencies: - - - name: tractusx-connector - repository: https://eclipse-tractusx.github.io/charts/dev - version: 0.7.0 - alias: my-connector - - name: agent-plane-azure-vault - repository: https://eclipse-tractusx.github.io/charts/dev - version: 1.14.24-SNAPSHOT - alias: my-agent -``` - -The configuration in your values.yaml follows the [Tractux-X EDC Helm Chart](https://github.com/eclipse-tractusx/tractusx-edc/blob/main/charts/tractusx-connector/README.md). -A few sections can be copied over 1-1 to the agent-plane which we demonstrate in the following. -The agent-plane chart is documented [here](charts/agent-plane/README.md). -The agent-plane-azure-vault chart is documented [here](charts/agent-plane-azure-vault/README.md). - -```yaml -my-connector: - fullnameOverride: my-connector - # -- Dataspace Settings - participant: &dataspacesettings - id: BPNL0000000DUMMY - # -- Self-Sovereign Identity Settings - iatp: &ssisettings - id: *customerDid - trustedIssuers: - - *operatingDid - sts: - dim: - url: *dimUrl - oauth: - token_url: *customerOauth - client: - id: *customerOauthClient - secret_alias: *customerOauthSecret - postgresql: &dbsettings - jdbcUrl: *customerDbUrl - auth: - database: *customerDbName - username: *customerDbUser - password: *customerDbPass - vault: &vaultsettings - azure: *azureVault - hashicorp: *hashicorpVault - controlplane: &consumerControlPlane - endpoints: - management: - authKey: *customerApiKey - bdrs: - server: - url: *bdrsUrl - ingresses: - - enabled: true - hostname: my-connector-cp.domain - endpoints: - - protocol - - management - - api - tls: - enabled: true - certManager: - clusterIssuer: *clusterIssuer - env: - EDC_DATAPLANE_SELECTOR_AGENTPLANE_URL: http:/my-agent-agentplane:8083/api/signaling/v1/dataflows - EDC_DATAPLANE_SELECTOR_AGENTPLANE_SOURCETYPES: cx-common:Protocol?w3c:http:SPARQL,cx-common:Protocol?w3c:http:SKILL - EDC_DATAPLANE_SELECTOR_AGENTPLANE_TRANSFERTYPES: HttpData-PULL - EDC_DATAPLANE_SELECTOR_AGENTPLANE_DESTINATIONTYPES: HttpProxy - EDC_DATAPLANE_SELECTOR_AGENTPLANE_PROPERTIES: '{ "publicApiUrl": "https://my-agent.domain/api/public/" }' - EDC_IAM_TRUSTED-ISSUER_0-ISSUER_ID: *operatorDid - dataplane: - token: &tokensettings - env: - EDC_IAM_TRUSTED-ISSUER_0-ISSUER_ID: *operatorDid - -my-agent: - fullnameOverride: my-agent - participant: *dataspacesettings - iatp: *ssisettings - postgresql: *dbsettings - vault: *vaultsettings - connector: my-connector - controlplane: *consumerControlPlane - token: *tokensettings - auth: {} - ingresses: - - enabled: true - hostname: my-agent.domain - endpoints: - - public - - default - tls: - enabled: true - certManager: - clusterIssuer: *clusterIssuer - configs: - # -- An example of an empty graph in ttl syntax - dataspace.ttl: | - ################################################################# - # Catena-X Agent Bootstrap Graph in TTL/RDF/OWL FORMAT - ################################################################# - @prefix : . - @prefix cx-common: . - @prefix owl: . - @prefix rdf: . - @prefix xml: . - @prefix json: . - @prefix xsd: . - @prefix rdfs: . - @prefix bpnl: . - @prefix bpns: . - @base . - - bpnl:BPNL000000000OEM cx-common:id "BPNL000000000OEM"^^xsd:string; - cx-common:hasConnector . - agent: - synchronization: 360000 - connectors: - BPNL000000000OEM: https://partner-connector-cp.partner-domain - BPNL0000000DUMMY: https://my-connector-cp.domain - services: - # -- A regular expression which outgoing service URLs must match (unless overwritten by a specific asset property) - allow: '(https|(edcs?))://.*' -``` +## Deployment + +see the [Administration Guide](admin/README.md) ## Recommended Documentation diff --git a/docs/admin/README.md b/docs/admin/README.md new file mode 100644 index 0000000..743cb05 --- /dev/null +++ b/docs/admin/README.md @@ -0,0 +1,188 @@ + + +# Tractus-X Knowledge Agents EDC Extensions (KA-EDC) Administration Guide + +## Deployment + +Deployment can be done +* via [JAR libraries](https://github.com/orgs/eclipse-tractusx/packages?repo_name=knowledge-agents-edc&ecosystem=maven) copied into your Java runtime +* via [Docker images](https://hub.docker.com/r/tractusx) +* via [Helm Charts (Stable Versions)](https://eclipse-tractusx.github.io/charts/stable) or [Helm Charts (Dev Versions)](https://eclipse-tractusx.github.io/charts/stable) + +## Connector Setup + +The two supported setups are. + +- Setup 1: PostgreSQL & Azure Vault + - [Control Plane](https://github.com/eclipse-tractusx/edc-controlplane/edc-controlplane-postgresql-azure-vault/README.md) + - [Agent Plane](../../agent-plane/agentplane-azure-vault/README.md) + - [Data Plane](https://github.com/eclipse-tractusx/edc-dataplane/edc-dataplane-azure-vault/README.md) + - [JWT Auth Extension](../../common/jwt-auth/README.md) +- Setup 2: PostgreSQL & HashiCorp Vault + - [Control Plane](https://github.com/eclipse-tractusx/edc-controlplane/README.md) + - [Agent Plane](../../agent-plane/agentplane-hashicorp/README.md) + - [Data Plane](https://github.com/eclipse-tractusx/edc-dataplane/edc-dataplane-hashicorp-vault/README.md) + - [JWT Auth Extension](../../common/jwt-auth/README.md) + +## Helm Deployment + +To install a KA-enabled EDC (Setup 1 - Postgresql & Hashicorp Vault), add the following lines to the dependency section of your Charts.yaml + +```yaml +dependencies: + + - name: tractusx-connector + repository: https://eclipse-tractusx.github.io/charts/dev + version: 0.7.0 + alias: my-connector + - name: agent-plane + repository: https://eclipse-tractusx.github.io/charts/dev + version: 1.14.24-SNAPSHOT + alias: my-agent +``` + +To install a KA-enabled EDC (Setup 2 - Postgresql & Azure Vault), add the following lines to the dependency section of your Charts.yaml + +```yaml +dependencies: + + - name: tractusx-connector + repository: https://eclipse-tractusx.github.io/charts/dev + version: 0.7.0 + alias: my-connector + - name: agent-plane-azure-vault + repository: https://eclipse-tractusx.github.io/charts/dev + version: 1.14.24-SNAPSHOT + alias: my-agent +``` + +The configuration in your values.yaml follows the [Tractux-X EDC Helm Chart](https://github.com/eclipse-tractusx/tractusx-edc/blob/main/charts/tractusx-connector/README.md). +A few sections can be copied over 1-1 to the agent-plane which we demonstrate in the following. +The agent-plane chart is documented [here](charts/agent-plane/README.md). +The agent-plane-azure-vault chart is documented [here](charts/agent-plane-azure-vault/README.md). + +```yaml +my-connector: + fullnameOverride: my-connector + # -- Dataspace Settings + participant: &dataspacesettings + id: BPNL0000000DUMMY + # -- Self-Sovereign Identity Settings + iatp: &ssisettings + id: *customerDid + trustedIssuers: + - *operatingDid + sts: + dim: + url: *dimUrl + oauth: + token_url: *customerOauth + client: + id: *customerOauthClient + secret_alias: *customerOauthSecret + postgresql: &dbsettings + jdbcUrl: *customerDbUrl + auth: + database: *customerDbName + username: *customerDbUser + password: *customerDbPass + vault: &vaultsettings + azure: *azureVault + hashicorp: *hashicorpVault + controlplane: &consumerControlPlane + endpoints: + management: + authKey: *customerApiKey + bdrs: + server: + url: *bdrsUrl + ingresses: + - enabled: true + hostname: my-connector-cp.domain + endpoints: + - protocol + - management + - api + tls: + enabled: true + certManager: + clusterIssuer: *clusterIssuer + env: + EDC_DATAPLANE_SELECTOR_AGENTPLANE_URL: http:/my-agent-agentplane:8083/api/signaling/v1/dataflows + EDC_DATAPLANE_SELECTOR_AGENTPLANE_SOURCETYPES: cx-common:Protocol?w3c:http:SPARQL,cx-common:Protocol?w3c:http:SKILL + EDC_DATAPLANE_SELECTOR_AGENTPLANE_TRANSFERTYPES: HttpData-PULL + EDC_DATAPLANE_SELECTOR_AGENTPLANE_DESTINATIONTYPES: HttpProxy + EDC_DATAPLANE_SELECTOR_AGENTPLANE_PROPERTIES: '{ "publicApiUrl": "https://my-agent.domain/api/public/" }' + EDC_IAM_TRUSTED-ISSUER_0-ISSUER_ID: *operatorDid + dataplane: + token: &tokensettings + env: + EDC_IAM_TRUSTED-ISSUER_0-ISSUER_ID: *operatorDid + +my-agent: + fullnameOverride: my-agent + participant: *dataspacesettings + iatp: *ssisettings + postgresql: *dbsettings + vault: *vaultsettings + connector: my-connector + controlplane: *consumerControlPlane + token: *tokensettings + auth: {} + ingresses: + - enabled: true + hostname: my-agent.domain + endpoints: + - public + - default + tls: + enabled: true + certManager: + clusterIssuer: *clusterIssuer + configs: + # -- An example of an empty graph in ttl syntax + dataspace.ttl: | + ################################################################# + # Catena-X Agent Bootstrap Graph in TTL/RDF/OWL FORMAT + ################################################################# + @prefix : . + @prefix cx-common: . + @prefix owl: . + @prefix rdf: . + @prefix xml: . + @prefix json: . + @prefix xsd: . + @prefix rdfs: . + @prefix bpnl: . + @prefix bpns: . + @base . + + bpnl:BPNL000000000OEM cx-common:id "BPNL000000000OEM"^^xsd:string; + cx-common:hasConnector . + agent: + synchronization: 360000 + connectors: + BPNL000000000OEM: https://partner-connector-cp.partner-domain + BPNL0000000DUMMY: https://my-connector-cp.domain + services: + # -- A regular expression which outgoing service URLs must match (unless overwritten by a specific asset property) + allow: '(https|(edcs?))://.*' +``` +