Skip to content

Commit b4ce95f

Browse files
ponachteponachte
committed
updated documentation
1 parent c6d1c57 commit b4ce95f

54 files changed

Lines changed: 1451 additions & 3603 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎aggregator-platform/README.md‎

Lines changed: 158 additions & 78 deletions
Original file line numberDiff line numberDiff line change
@@ -1,139 +1,219 @@
1-
# Aggregation Platform Helm Chart
1+
# Aggregator Platform Helm Chart
22

3-
This Helm chart deploys the **Aggregation Server**. This server allows to deploy **Aggregators** for authenticated users. A user can deploy **FnO Pipelines** inside his aggregator to aggregate UMA-protected resources.
3+
This Helm chart deploys the **Aggregator Platform**, consisting of:
4+
5+
**Aggregator Server** – manages aggregators
6+
**Ingress-UMA** – handles UMA-protected access
7+
**Token Service** – issues and manages tokens
8+
9+
The platform allows authenticated users to deploy **Aggregators**, in which they can run **FnO Services** to aggregate UMA-protected resources.
10+
11+
## Configuration
12+
13+
Below is a detailed overview of all configurable parameters.
414

515
---
616

7-
### Values
17+
### External Access
18+
19+
Defines how the platform is exposed externally. At least one external access port (HTTP or HTTPS) must be configured.
20+
21+
| Parameter | Description | Required |
22+
| - | - | - |
23+
| `external.host` | Public hostname of the platform | ✅ |
24+
| `external.httpPort` | HTTP port | ⚠️ |
25+
| `external.httpsPort` | HTTPS port | ⚠️ |
26+
| `ingressClassName` | Kubernetes ingress class name | |
27+
28+
---
29+
30+
#### TLS Configuration
31+
32+
Configure HTTPS support.
33+
34+
| Parameter | Description | Default |
35+
| - | - | - |
36+
| `tls.enabled` | Enable TLS | `false` |
37+
| `tls.mode` | TLS mode (`selfsigned` or `cert-manager`) | Required if enabled |
38+
| `tls.secretName` | Kubernetes secret for TLS certs | Required if enabled |
39+
40+
```yaml
41+
tls:
42+
enabled: true
43+
mode: selfsigned
44+
secretName: aggregator-tls
45+
```
46+
47+
***Self-Signed TLS***
848
9-
Below is a detailed description of all configurable parameters.
49+
```yaml
50+
tls:
51+
enabled: true
52+
mode: selfsigned
53+
secretName: aggregator-tls
54+
selfSigned:
55+
crt: <base64-cert>
56+
key: <base64-key>
57+
```
58+
59+
---
1060
1161
### General
1262
13-
| Parameter | Description | Default |
14-
| ---------- | ------------------------------------- | ---------------|
15-
| `host` | Host name of the aggregator platform | N/A (required) |
16-
| `loglevel` | Log level of the aggregator platform | `info` |
63+
| Parameter | Description | Default |
64+
| - | - | - |
65+
| `loglevel` | Log level of the platform | `info` |
66+
67+
---
1768

18-
### Registration Configuration
69+
### Authentication Configuration
1970

20-
Configure authorization for creating new aggregators.
71+
Controls how users can register new aggregators.
2172

2273
| Parameter | Description |
2374
| - | - |
24-
| `auth.server` | OIDC server URL |
25-
| `auth.clientId` | OIDC client ID |
26-
| `auth.clientSecret` | OIDC client secret |
27-
| `auth.allowedRegistrationTypes` | List of allowed registration types: `none`, `device_code` |
75+
| `auth.allowedRegistrationTypes` | Allowed registration flows |
76+
77+
Supported registration types:
78+
79+
- `none` – No authentication (development only)
80+
- `authorization_code` – Standard OIDC authorization code flow
81+
- `device_code` – Device Authorization Grant
82+
- `provision` – Pre-provisioned credentials
83+
84+
---
85+
86+
#### OIDC Configuration
2887

29-
- `none`: Create an unauthorized aggregator (development)
30-
- `device code`: Enable authorization using the Device Authorization Grant
88+
Used for OIDC-based flows (`authorization_code`, `device_code`).
89+
90+
| Parameter | Description |
91+
| - | - |
92+
| `auth.oidc.server` | OIDC provider URL |
93+
| `auth.oidc.clientId` | OIDC client ID |
94+
| `auth.oidc.clientSecret` | OIDC client secret |
95+
| `auth.solidOidc` | Enable Solid-OIDC behavior | `true` |
96+
97+
---
98+
99+
#### Provision Configuration
100+
101+
Required when using `provision`.
102+
103+
| Parameter | Description |
104+
| - | - |
105+
| `auth.provision.clientId` | Client ID |
106+
| `auth.provision.clientSecret` | Client secret |
107+
| `auth.provision.webId` | WebID of the provisioned agent |
108+
| `auth.provision.authServer` | Authorization server |
109+
110+
---
31111

32112
### Specification Configuration
33113

34-
Configure how the platform will implement the spec endpoints
114+
Controls the exposed API paths and available transformations.
35115

36116
| Parameter | Description | Default |
37117
| - | - | - |
38-
| `spec.service_collection` | URL path for service collection | `/services` |
39-
| `spec.transformation_catalog` | URL path for transformation catalog | `/transformations` |
118+
| `spec.service_collection` | Service collection endpoint | `/services` |
119+
| `spec.transformation_catalog` | Transformation catalog endpoint | `/transformations` |
120+
| `spec.registration` | Registration endpoint | `/registration` |
40121
| `transformations` | List of available transformations | `[]` |
41122

42-
***Trnsformation example***
43123

44-
- The FnO Description should be given without `@base`
45-
- `inputMapping` links parameters to ENV variables
46-
- `outputMapping` links outputs to services
124+
125+
***Transformation example***
126+
127+
- The FnO Description **must not include** `@base`
128+
- `image` specifies the container image to use for this transformation
129+
- `id` is the FnO Function ID (without the base URI)
130+
- `inputMapping` maps parameters to environment variables
131+
- `outputMapping` maps outputs to container endpoints
47132

48133
```yaml
49134
transformations:
50-
- name: sparqlQuery
135+
- name: incremental-kvasir
51136
spec:
52-
id: SparqlQuery # The ID of the FnO Function
53-
image: incremunica # The implementation to use
54-
# The FnO Description
55-
fno: |
137+
id: IncrementalKvasir
138+
image: incremunica-kvasir
139+
fno: |
56140
@prefix fno: <https://w3id.org/function/ontology#> .
57141
@prefix xsd: <http://www.w3.org/2001/XMLSchema#> .
58142
@prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#> .
59143
60-
<SparqlQuery>
144+
<IncrementalKvasir>
61145
a fno:Function ;
62-
fno:expects ( <Sources> <Query> ) ;
63-
fno:returns ( <Result> ) .
146+
fno:expects ( <Query> <Sources> <Schema> <Context> ) ;
147+
fno:returns ( <QueryResult> ) .
64148
149+
<Query>
150+
a fno:Parameter ;
151+
fno:type xsd:string ;
152+
fno:predicate <query> ;
153+
fno:required "true"^^xsd:boolean .
154+
65155
<Sources>
66156
a fno:Parameter ;
157+
fno:type xsd:string ;
67158
fno:predicate <sources> ;
159+
fno:required "true"^^xsd:boolean .
160+
161+
<Schema>
162+
a fno:Parameter ;
68163
fno:type xsd:string ;
164+
fno:predicate <schema> ;
69165
fno:required "true"^^xsd:boolean .
70166
71-
<Query>
167+
<Context>
72168
a fno:Parameter ;
73-
fno:predicate <query> ;
74169
fno:type xsd:string ;
170+
fno:predicate <context> ;
75171
fno:required "true"^^xsd:boolean .
76-
77-
<Result>
172+
173+
<QueryResult>
78174
a fno:Output ;
79175
fno:predicate <result> .
80176
inputMapping:
177+
query: QUERY
81178
sources: SOURCES
179+
schema: SCHEMA
180+
context: CONTEXT
82181
outputMapping:
83182
result:
84-
port: 8080
183+
port: 3000
85184
path: /
86185
```
87186

88-
### TLS Configuration
89-
90-
TLS can be **disabled**, use **self-signed certs**, or use **cert-manager** for production
91-
187+
### Aggregator Server Configuration
92188
| Parameter | Description | Default |
93189
| - | - | - |
94-
| `tls.enabled` | Enable TLS | `false` |
95-
| `tls.secretName` | Name of the secret containing TLS cert/key | `aggregator-tls` |
96-
| `tls.mode` | TLS mode (`selfsigned` or `cert-manager`) | N/A (required if enabled) |
97-
98-
**Self-signed TLS Example**
99-
```yaml
100-
tls:
101-
enabled: true
102-
mode: selfsigned
103-
selfSigned:
104-
crt: tls.crt # TLS certificate
105-
key: tls.key # TLS private key
106-
```
107-
**Cert-manager TLS Example**
108-
```yaml
109-
tls:
110-
enabled: true
111-
mode: cert-manager
112-
certManager:
113-
issuerName: letsencrypt-prod
114-
issuerKind: ClusterIssuer # "Issuer" or "ClusterIssuer"
115-
issuerGroup: cert-manager.io
116-
duration: 2160h # Optional certificate validity
117-
renewBefore: 720h # Optional renew-before duration
118-
```
119-
120-
### Server Configuration
121-
| Parameter | Description | Default |
122-
| -| -| - |
123-
| `server.replicaCount` | Number of Aggregator Server replicas | `1` |
124-
| `server.image.repository` | Docker image repository | `aggregator-server` |
125-
| `server.image.tag` | Docker image tag | `latest` |
126-
| `server.image.pullPolicy` | Image pull policy | `Never` |
127-
| `server.readinessProbe` | Readiness probe settings | See `values.yaml` |
190+
| `server.replicaCount` | Number of replicas | `1` |
191+
| `server.image.repository` | Docker image | `aggregator-server` |
192+
| `server.image.tag` | Image tag | `latest` |
193+
| `server.image.pullPolicy` | Pull policy | `Never` |
194+
| `server.readinessProbe` | Readiness probe config | See `values.yaml` |
128195

129196
### Ingress-UMA Configuration
130197
| Parameter | Description | Default |
131198
| - | - | - |
132-
| `ingressUma.replicaCount` | Number of Ingress-UMA replicas | `1` |
133-
| `ingressUma.image.repository` | Docker image repository | `ingress-uma` |
134-
| `ingressUma.image.tag` | Docker image tag | `latest` |
199+
| `ingressUma.replicaCount` | Number of replicas | `1` |
200+
| `ingressUma.image.repository` | Docker image | `ingress-uma` |
201+
| `ingressUma.image.tag` | Image tag | `latest` |
202+
| `ingressUma.image.pullPolicy` | Pull policy | `Never` |
135203
| `ingressUma.disableAuth` | Disable UMA authentication | `false` |
136-
| `ingressUma.readinessProbe` | Readiness probe settings | See `values.yaml` |
204+
| `ingressUma.readinessProbe` | Readiness probe config | See `values.yaml` |
205+
| `ingressUma.terminationGracePeriodSeconds` | Shutdown grace period | `50` |
206+
207+
### Token Service Configuration
208+
| Parameter | Description | Default |
209+
| - | - | - |
210+
| `tokenService.replicaCount` | Number of replicas | `1` |
211+
| `tokenService.image.repository` | Docker image | `token-service` |
212+
| `tokenService.image.tag` | Image tag | `latest` |
213+
| `tokenService.image.pullPolicy` | Pull policy | `Never` |
214+
| `tokenService.readinessProbe` | Readiness probe config | See `values.yaml` |
215+
| `tokenService.terminationGracePeriodSeconds` | Shutdown grace period | `60` |
216+
137217

138218

139219

0 commit comments

Comments
 (0)