diff --git a/docs/src/SUMMARY.md b/docs/src/SUMMARY.md index 54d6d5ae87729a3fc42095cada1de572d4f99845..e98f2f693af8b4e1970b703355a2bba963d1748c 100644 --- a/docs/src/SUMMARY.md +++ b/docs/src/SUMMARY.md @@ -12,6 +12,10 @@ - [GitOps](concepts/gitops.md) - [SRE](concepts/sre.md) - [Ingress Termination](concepts/ingress-termination.md) +- [Apps](apps/README.md) + - [Blog](apps/blog.md) + - [Keycloak](apps/keycloak.md) + - [Mastodon](apps/mastodon.md) - [Infrastructure Components](components/README.md) - [calico](components/calico.md) - [cert-manager](components/cert-manager.md) diff --git a/docs/src/apps/README.md b/docs/src/apps/README.md new file mode 100644 index 0000000000000000000000000000000000000000..48167d90a93abebd7c303425d999ada9217ebd39 --- /dev/null +++ b/docs/src/apps/README.md @@ -0,0 +1,3 @@ +# Apps + +This category lists software that is used to provide Services around the Shivering-Isles infrastructure. \ No newline at end of file diff --git a/docs/src/apps/blog.md b/docs/src/apps/blog.md new file mode 100644 index 0000000000000000000000000000000000000000..9aaa7f6a2def0751efde1f74955da02615b41c56 --- /dev/null +++ b/docs/src/apps/blog.md @@ -0,0 +1,5 @@ +# Blog + +The [Shivering-Isles blog](https://shivering-isles.com) is a simple nginx image, that was infused with a built of the [jekyll-based blog content](https://git.shivering-isles.com/shivering-isles/blog). + +Besides being a static blog, it also houses the .well-known directory, that handles the [Web Key Directory](https://datatracker.ietf.org/doc/draft-koch-openpgp-webkey-service/) for the Shivering-Isles. Additionally it delegates Matrix and [Mastodon](./mastodon.md) to their respective services, allowing to use `shivering-isles.com` as domain for user identities. diff --git a/docs/src/apps/images/authentication-config.png b/docs/src/apps/images/authentication-config.png new file mode 100644 index 0000000000000000000000000000000000000000..343dd0ece12995491f0955a20ba16d684b53a0ad Binary files /dev/null and b/docs/src/apps/images/authentication-config.png differ diff --git a/docs/src/apps/keycloak.md b/docs/src/apps/keycloak.md index 6b2fb6ac055631f47bda15a2db9ddd2a1f1f8870..7b63d2bd3a7683dcbe0920de4a617aa15b1dc2bb 100644 --- a/docs/src/apps/keycloak.md +++ b/docs/src/apps/keycloak.md @@ -2,6 +2,17 @@ In the Shivering-Isles Infrastructure Keycloak is the central identity provider. It allows users to manage their sessions and provides Multi-Factor authentication for all services. -The Keycloak instance is usually referred to as "SI-Auth". The Shivering-Isles realm contains the user-base. The Keycloak system realm, called "Master," administrates the Shivering-Isles realm. +The Keycloak instance is usually referred to as ["SI-Auth"](https://auth.shivering-isles.com). The Shivering-Isles realm contains the user-base. The Keycloak system realm, called "Master," administrates the Shivering-Isles realm. While the Shivering-Isles realm is accessible over the internet, allowing easy access and authentication from everywhere in the world, the "master" realm is only accessible through the local-network administration endpoint. This reduces the risk of a take over, even if an attacker compromises credentials. + + +## Authentication configuration + +To allow Multi-Factor-Authentication (MFA) a copy of the web browser flow was adjusted to account for WebAuthn and TOTP-based MFA. + + + +The official keycloak documentation describes the basics to [set up WebAuthn as MFA flow](https://www.keycloak.org/docs/latest/server_admin/index.html#_webauthn-authenticator-setup). + +While Passwordless authentication is prepared to be rolled out, some experimentation showed that the authentication flow becomes too complex. diff --git a/docs/src/apps/mastodon.md b/docs/src/apps/mastodon.md new file mode 100644 index 0000000000000000000000000000000000000000..8dc6cf5f01e48f2e3050366eda8b04be728c0756 --- /dev/null +++ b/docs/src/apps/mastodon.md @@ -0,0 +1,3 @@ +# Mastodon + +Mastodon is the Fediverse software run in the Shivering-Isles infrastructure. It is currently running as a single-user instance. \ No newline at end of file diff --git a/docs/src/concepts/sre.md b/docs/src/concepts/sre.md index 7ce6bfe42e8cbea6619f1eed48f5fed4aa19da7a..e84fefa8517cc8004139c9f353b594eb858d08bf 100644 --- a/docs/src/concepts/sre.md +++ b/docs/src/concepts/sre.md @@ -16,4 +16,13 @@ A good start is this small video Series by Google: <iframe width="100%" height="480" src="https://www.youtube-nocookie.com/embed/?listType=playlist&list=PLIivdWyY5sqJrKl7D2u-gmis8h9K66qoj" frameborder="0" allow="autoplay; encrypted-media" allowfullscreen></iframe> -Further there is the [Google SRE book](https://sre.google/sre-book/introduction/) as recommended read. \ No newline at end of file +Further there is the [Google SRE book](https://sre.google/sre-book/introduction/) as recommended read. + +Service Level Objectives +--- + +All public facing apps should have an Service Level Objective (SLO). The most basic SLOs for web apps are the availability and latency measured throught the ingress controller. [An examples for an SLO definitions is the Shivering-Isles blog.](https://git.shivering-isles.com/shivering-isles/infrastructure-gitops/-/blob/797843c960f82a1974e2c3b632f0d45e5de9d6fe/apps/k8s01/blog/slo.yaml) + +Apps that provide more insight via metrics, can have app-specific SLOs to optimise for user impacting situations, that aren't covered by basic web metrics. [An example is the sidekiq SLO for Mastodon.](https://git.shivering-isles.com/shivering-isles/infrastructure-gitops/-/blob/797843c960f82a1974e2c3b632f0d45e5de9d6fe/apps/k8s01/mastodon/slo.yaml#L9-21) + +The actual objectives in the Shivering-Isles infrastructure are often relatively low around 95 percent. \ No newline at end of file