split up and add documentation

Signed-off-by: Joshua Irmer <[email protected]>
SovereignCloudStack · Jun 25, 2024 · 3e3b9f0 · 3e3b9f0
1 parent 5b538d6
commit 3e3b9f0
Show file tree

Hide file tree

Showing 2 changed files with 54 additions and 30 deletions.
diff --git a/docs/deployment-overview.md → docs/admin-authentication.md b/docs/deployment-overview.md → docs/admin-authentication.md
@@ -1,35 +1,10 @@
-# Overview
+# Admin authentication
 
-## Container view
+As the write operations of the [API server](https://github.com/SovereignCloudStack/status-page-api) are protected by [Oathkeeper](https://www.ory.sh/docs/oathkeeper) and use identities provided by [Dex](https://dexidp.io/) an Administrator is considered to be a person that can authenticate on Dex.
 
-```mermaid
-    C4Container
-    title Container diagram status page
-
-    Person(user, User, "A user who wants to know about the status.")
-    Person(admin, Admin, "An administrator who can update the status.")
-
-    Container_Boundary(status-page, "Status Page") {
-        Container(web, "Web Frontend", "JavaScript, Angular", "Provides all the status page functionality to persons via their web browser")
-        Container(dex, "Dex IdP", "", "Intermediate IdP to retrieve user data.")
-        Container(api, "API Server", "Go", "Delivers data to the Web Frontend")
-        ContainerDb(api-db, "API Database", "SQL Database", "Stores components, incidents, severities, phases, etc.")
-        Container(oathkeeper, "Oathkeeper", "AuthN, AuthZ", "Authentication proxy for write operations on the API Server.")
-
-        Rel(api, api-db, "Request data")
-        Rel(web, oathkeeper, "Request data", "Unauthenticated read, authenticated write")
-        Rel(oathkeeper, api, "Proxy and protect",)
-        Rel(web, dex, "Authentication")
-        Rel(oathkeeper, dex, "Authenticate user requests")
-    }
+On the public SCS deployment, these persons are members of the SovereignCloudStack organization.
 
-    Rel(user, web, "Reads status")
-    Rel(admin, web, "Writes status")
-    Rel(admin, dex, "Authenticate")
-
-```
-
-## Sequence view
+This sequence diagram displays a simplified flow how an administrator authenticates himself with Dex and GitHub, to authorize using the write operations.
 
 ```mermaid
 sequenceDiagram
@@ -75,5 +50,4 @@ rect rgba(64,127,0, 0.8)
     web-->>useragent: data
     useragent-->>admin: presents new data
 end
-
 ```
diff --git a/docs/overview.md b/docs/overview.md
@@ -0,0 +1,50 @@
+# Overview
+
+The status page needs some components additional to the [API server](https://github.com/SovereignCloudStack/status-page-api) to be usable by operators and customers. As the API server [does not implement any kind of authorization or authentication](https://github.com/SovereignCloudStack/standards/blob/main/Standards/scs-0402-v1-status-page-openapi-spec-decision.md#authentication-and-authorization) some components need to be deployed to protect the write operations of the API from unauthorized access.
+
+## Components
+
+These components are picked as examples and can be exchanged with any technology that is fitting the use case.
+
+The used components are [Oathkeeper](https://www.ory.sh/docs/oathkeeper) and [Dex](https://dexidp.io/) to implement AuthN[^1] and AuthZ[^2]. Oathkeeper is a proxy that handles incoming requests and authorization, while Dex is used as an identity broker, used for authentication, to be used in conjunction with Oathkeeper to secure the API server.
+
+[^1] Authentication
+[^2] Authorization
+
+Furthermore the API server needs a running database, for this [PostgreSQL is used](https://github.com/SovereignCloudStack/standards/blob/main/Standards/scs-0401-v1-status-page-reference-implementation-decision.md#database).
+
+Last but not least the the status page is completed by a web front. For this the example implementation from the [`status-page-web` repository](https://github.com/SovereignCloudStack/status-page-web).
+
+Some deployments use reverse proxies, ingress controllers or can even implement a gateway-api. These are deployment specific and can be used as the use case requires.
+
+### Component overview
+
+```mermaid
+    C4Container
+    title Component overview status page
+
+    Person(user, User, "A user who wants to know about the status.")
+    Person(admin, Admin, "An administrator who can update the status.")
+
+    Container_Boundary(status-page, "Status Page") {
+        Container(web, "Web Frontend", "JavaScript, Angular", "Provides all the status page functionality to persons via their web browser")
+        Container(dex, "Dex IdP", "", "Intermediate IdP to retrieve user data.")
+        Container(api, "API Server", "Go", "Delivers data to the Web Frontend")
+        ContainerDb(api-db, "API Database", "SQL Database", "Stores components, incidents, severities, phases, etc.")
+        Container(oathkeeper, "Oathkeeper", "AuthN, AuthZ", "Authentication proxy for write operations on the API Server.")
+
+        Rel(api, api-db, "Request data")
+        Rel(web, oathkeeper, "Request data", "Unauthenticated read, authenticated write")
+        Rel(oathkeeper, api, "Proxy and protect",)
+        Rel(web, dex, "Authentication")
+        Rel(oathkeeper, dex, "Authenticate user requests")
+    }
+
+    Rel(user, web, "Reads status")
+    Rel(admin, web, "Writes status")
+    Rel(admin, dex, "Authenticate")
+```
+
+## Deployment repository
+
+The [deployment repository](https://github.com/SovereignCloudStack/status-page-deployment) contains a [local development environment using `KinD`](./kind.md), templates for other deployments, in [example using k3s](./k3s.md) and the skeleton of the deployment for the [public SCS cluster](./scs-public.md).