Docs/init gateway (#343)

* 📝 update gateway heading case * 📝 rm dev section * 📝 mv gateway from readme to vitepress * Apply suggestions from code review Co-authored-by: Tobias Stadler <[email protected]> * 🔥 docs gateway rm previous version notice * 📝 docs gateway mv profiles to configuration section * 📝 gateway rm README * Apply suggestions from code review Co-authored-by: Tobias Stadler <[email protected]> * 📝 gateway mention session sync via hazelcast * 📝 gateway mention request filters * 📝 gateway feature unify indention --------- Co-authored-by: Tobias Stadler <[email protected]>
it-at-m · Jan 10, 2025 · 04e0701 · 04e0701
1 parent 43f2293
commit 04e0701
Show file tree

Hide file tree

Showing 9 changed files with 120 additions and 131 deletions.
diff --git a/.github/README.md b/.github/README.md
@@ -11,10 +11,10 @@ The RefArch is based on [Spring](https://spring.io/) and [VueJS](https://vuejs.o
 
 ## Usage
 
-The usage of the different components is described in their corresponding README.md
+Following a list of the available components. Each of them is described in their own section of the documentation.
 
-- [refarch-gateway](../refarch-gateway/README.md)
-- [refarch-integrations](../refarch-integrations/README.md)
+- refarch-gateway ([Code](../refarch-gateway), [Documentation](https://refarch.oss.muenchen.de/gateway))
+- refarch-integrations ([Code](../refarch-integrations), [Documentation](https://refarch.oss.muenchen.de/integrations))
 
 ## Contributing
 

diff --git a/docs/.vitepress/config.mts b/docs/.vitepress/config.mts
@@ -23,28 +23,19 @@ const vitepressConfig = defineConfig({
         text: "Docs",
         items: [
           { text: "Overview", link: "/overview" },
-          { text: "API gateway", link: "/gateway" },
+          { text: "API Gateway", link: "/gateway" },
           { text: "Integrations", link: "/integrations" },
-          { text: "Development", link: "/dev" },
         ],
       },
     ],
     sidebar: [
       { text: "Overview", link: "/overview" },
-      { text: "API gateway", link: "/gateway" },
+      { text: "API Gateway", link: "/gateway" },
       {
         text: "Integrations",
         link: "/integrations",
         items: [{ text: "S3", link: "/integrations/s3" }],
       },
-      {
-        text: "Development",
-        link: "/dev",
-        items: [
-          { text: "Tools", link: "/dev/tools" },
-          { text: "Stack", link: "/dev/stack" },
-        ],
-      },
     ],
     outline: {
       level: "deep",

diff --git a/docs/dev/index.md b/docs/dev/index.md
diff --git a/docs/dev/stack.md b/docs/dev/stack.md
diff --git a/docs/dev/tools.md b/docs/dev/tools.md
diff --git a/docs/gateway.md b/docs/gateway.md
@@ -1 +1,108 @@
-# API gateway
+# API Gateway
+
+RefArch gateway based on [Spring Cloud Gateway](https://spring.io/projects/spring-cloud-gateway).
+
+## Usage
+
+The gateway is released as container image `ghcr.io/it-at-m/refarch/refarch-gateway` and can be used either directly or
+via the corresponding [Helm-Chart](https://github.com/it-at-m/helm-charts/tree/main/charts/refarch-gateway).
+
+## Features
+
+Beside the default functionality of Spring Cloud Gateway (i.e. routing) following features are preconfigured/provided:
+
+- OAuth 2.0 based login
+- Route protection
+- CSRF protection with whitelist
+- Cookie to JWT mapping for session management
+- Session synchronisation between multiple instances via Hazelcast (see sections [Profiles](#profiles) and [Hazelcast](#hazelcast))
+- Health and metrics endpoints
+- Request filters (e.g. distributed tracing, error code mapper, parameter pollution, ...)
+
+### Routing
+
+Routes are configured via environment variables as listed under [Configuration](#configuration).
+
+By default, routes require authentication through OAuth 2.0 and manage the session between the client and gateway using
+cookies.
+The gateway then maps the session cookie to a JWT before routing it.
+
+Beside the default behaviour there are some special route prefixes which are handled different:
+
+- `/public/**`: All `OPTIONS` and `GET` requests are routed without security.
+- `/clients/**`: Uses JWT for authenticating incoming requests instead of session cookies.
+
+## Configuration
+
+| Var                                                      | Description                                                     | Example                                                                 |
+|----------------------------------------------------------|-----------------------------------------------------------------|-------------------------------------------------------------------------|
+| `SPRING_PROFILES_ACTIVE`                                 | See [profiles](#profiles)                                       | `local,hazelcast-local`                                                 |
+| `SPRING_CLOUD_GATEWAY_ROUTES_<index>_ID`                 | ID of a route definition.                                       | `backend`                                                               |
+| `SPRING_CLOUD_GATEWAY_ROUTES_<index>_URI`                | The URI to route to if this route matches.                      | `http://backend-service:8080/`                                          |
+| `SPRING_CLOUD_GATEWAY_ROUTES_<index>_PREDICATES_<index>` | Route predicates i.e. matcher.                                  | `Path=/api/backend-service/**`                                          |
+| `SPRING_CLOUD_GATEWAY_ROUTES_<index>_FILTERS_<index>`    | List of filters applied to the route.                           | `RewritePath=/api/backend-service/(?<urlsegments>.*), /$\{urlsegments}` |
+| `REFARCH_HAZELCAST_SERVICENAME`                          | Kubernetes service name for when using profile `hazelcast-k8s`. |                                                                         |
+| `ALLOWED_ORIGINS_PUBLIC` (optional)                      | List of URIs allowed as origin for public routes.               | `https://*.example.com,http://localhost:*`                              |
+| `ALLOWED_ORIGINS_CLIENTS` (optional)                     | List of URIs allowed as origin for clients routes.              | `https://*.example.com,http://localhost:*`                              |
+| `REFARCH_SECURITY_CSRFWHITELISTED_<index>` (optional)    | List of routes to disable CSRF protection for.                  | `/example/**`                                                           |
+
+### Security
+
+For authentication via SSO, OAuth 2.0 needs to be configured.
+See following example or the [according Spring documentation](https://docs.spring.io/spring-security/reference/servlet/oauth2/index.html).
+
+Alternatively the `no-security` profile can be used.
+
+```yaml
+spring:
+  security:
+    oauth2:
+      resourceserver:
+        jwt:
+          issuer-uri: "https://sso.example/auth/realms/example"
+      client:
+        provider:
+          sso:
+            issuer-uri: ${spring.security.oauth2.resourceserver.jwt.issuer-uri}
+        registration:
+          sso:
+            provider: sso
+            client-id: 
+            client-secret:
+            # needed for userInfo endpoint
+            scope: profile, openid
+```
+
+### Profiles
+
+| Profile           | Description                                                                                          |
+|-------------------|------------------------------------------------------------------------------------------------------|
+| `json-logging`    | Switches logging from textual to JSON output.                                                        |
+| `no-security`     | Disables all security mechanisms (e.g. authentication, authorization, CSRF) Routing works as normal. |
+| `hazelcast-local` | Configures Spring Session Hazelcast for connection via localhost (i.e. local development).           |
+| `hazelcast-k8s`   | Configures Spring Session Hazelcast for usage in Kubernetes/OpenShift cluster.                       |
+
+### Hazelcast
+
+Beside the already mentioned properties Hazelcast also has the following requirements.
+
+#### Modular java
+See https://docs.hazelcast.com/hazelcast/5.5/getting-started/install-hazelcast#using-modular-java
+
+Following Java options need to be set.
+For the gateway image this can be done with `JAVA_OPTS_APPEND`.
+```
+--add-modules java.se \
+  --add-exports java.base/jdk.internal.ref=ALL-UNNAMED \
+  --add-opens java.base/java.lang=ALL-UNNAMED \
+  --add-opens java.base/java.nio=ALL-UNNAMED \
+  --add-opens java.base/sun.nio.ch=ALL-UNNAMED \
+  --add-opens java.management/sun.management=ALL-UNNAMED \
+  --add-opens jdk.management/com.ibm.lang.management.internal=ALL-UNNAMED \
+  --add-opens jdk.management/com.sun.management.internal=ALL-UNNAMED
+```
+
+#### Kubernetes
+
+For running Hazelcast with profile `hazelcast-k8s` in Kubernetes port `5701` needs to be accessible.
+This need to be configured for the Service and Deployment.
diff --git a/docs/index.md b/docs/index.md
@@ -14,7 +14,7 @@ hero:
       text: Templates
       link: https://refarch-templates.oss.muenchen.de
     - theme: alt
-      text: API gateway
+      text: API Gateway
       link: /gateway
     - theme: alt
       text: Integrations

diff --git a/docs/overview.md b/docs/overview.md
@@ -19,23 +19,23 @@ Besides that there can be cases where modular frontends through web components,
 ```mermaid
 flowchart LR
     u([Client])
-    g[API gateway]
+    g[API Gateway]
     f[Frontend]
     b[Backend]
-    w[Web component]
+    w[Web Component]
     u --> g
     g --> f
     g --> b
     g --> w
 ```
 
-### API gateway
+### API Gateway
 
 The API gateway is a ready-to-use component and the only exposed interface for accessing the application.
 It manages all requests and routes them to the respective development components like frontend and backend.
 Besides that, it also handles cross-cutting concepts like authentication using a SSO.
 
-See [API gateway](./gateway.md) for further information.
+See [API Gateway](./gateway.md) for further information.
 
 ### Frontend
 
@@ -51,14 +51,14 @@ Like the frontend the backend is also provided as a template.
 
 The template is described [here](https://refarch-templates.oss.muenchen.de/backend).
 
-### Web component
+### Web Component
 
 The web components template enables development of modular frontend components which can be integrated into other applications.
 This concept is also known as micro frontends. By default, most applications won't require this template.
 
 The template is described [here](https://refarch-templates.oss.muenchen.de/webcomponent).
 
-## Enterprise Application integration (EAI)
+## Enterprise Application Integration (EAI)
 
 Beside the development of web applications, the RefArch also provides a template for enterprise application integration (EAI). 
 This enables integration between existing applications. By default, most applications won't require this template.

diff --git a/refarch-gateway/README.md b/refarch-gateway/README.md