From c4f7c8df69a4bc95315e13f95d7367be08a49c82 Mon Sep 17 00:00:00 2001 From: Tobias Brunner Date: Tue, 15 Apr 2025 10:36:08 +0200 Subject: [PATCH] document models and admin --- .../portal-service-relations.drawio.svg | 469 ++++++++++++++++++ .../images/web-portal-arch-current.drawio.svg | 226 +++++++++ docs/modules/ROOT/nav.adoc | 5 +- docs/modules/ROOT/pages/web-portal-admin.adoc | 59 +++ .../ROOT/pages/web-portal-controlplanes.adoc | 30 ++ .../ROOT/pages/web-portal-planning.adoc | 64 +++ docs/modules/ROOT/pages/web-portal.adoc | 63 +-- 7 files changed, 860 insertions(+), 56 deletions(-) create mode 100644 docs/modules/ROOT/assets/images/portal-service-relations.drawio.svg create mode 100644 docs/modules/ROOT/assets/images/web-portal-arch-current.drawio.svg create mode 100644 docs/modules/ROOT/pages/web-portal-admin.adoc create mode 100644 docs/modules/ROOT/pages/web-portal-controlplanes.adoc create mode 100644 docs/modules/ROOT/pages/web-portal-planning.adoc diff --git a/docs/modules/ROOT/assets/images/portal-service-relations.drawio.svg b/docs/modules/ROOT/assets/images/portal-service-relations.drawio.svg new file mode 100644 index 0000000..ba23521 --- /dev/null +++ b/docs/modules/ROOT/assets/images/portal-service-relations.drawio.svg @@ -0,0 +1,469 @@ + + + + + + + + + + +
+
+
+ Cloud Provider "Exoscale" +
+
+
+ + + Cloud Provider "Exoscale" + + + + + + + + + + + +
+
+
+ Cloud Provider "Cloudscale" +
+
+
+ + + Cloud Provider "Cloudscale" + + + + + + + + + + + +
+
+
+ Control Plane 1 +
+
+
+ + + Control Plane 1 + + + + + + + + + + + +
+
+
+ Control Plane 2 +
+
+
+ + + Control Plane 2 + + + + + + + + + + + +
+
+
+ Control Plane N +
+
+
+ + + Control Plane N + + + + + + + + + + + + +
+
+
+ Implemented by +
+
+
+ + + Implemented by + + + + + + + + + + + +
+
+
+ Service +
+ (e.g. PostgreSQL) +
+
+
+
+ + + Service... + + + + + + + + + + + + + + + + + + + +
+
+
+ Service Definition +
+ (e.g. PostgreSQL by VSHN) +
+
+
+
+ + + Service Definition... + + + + + + + + + + + + + + + + + + + + + + + +
+
+
+ Service Offering +
+ (e.g. PostgreSQL by VSHN at Cloudscale) +
+
+
+
+ + + Service Offering... + + + + + + + + + + + + + + + +
+
+
+ Service Definition +
+ (e.g. DBaaS PostgreSQL) +
+
+
+
+ + + Service Definition... + + + + + + + + + + + + +
+
+
+ Implemented by +
+
+
+ + + Implemented by + + + + + + + + + + + +
+
+
+ Control Plane 1 +
+
+
+ + + Control Plane 1 + + + + + + + + + + + +
+
+
+ Control Plane 2 +
+
+
+ + + Control Plane 2 + + + + + + + + + + + + + + + + + + + +
+
+
+ Service Offering +
+ (e.g. PostgreSQL by VSHN at Exoscale) +
+
+
+
+ + + Service Offering... + + + + + + + + + + + + + + + + + + + +
+
+
+ Service Offering +
+ (e.g. DBaaS PostgreSQL at Exoscale) +
+
+
+
+ + + Service Offering... + + + + + + + + + + + +
+
+
+ ServiceOffering +
+ ControlPlane +
+
+ Configuration +
+
+
+
+ + + ServiceOffering... + + + + + + + + + + + +
+
+
+ ServiceOffering +
+ ControlPlane +
+
+ Configuration +
+
+
+
+ + + ServiceOffering... + + + + + + + + + + + +
+
+
+ ServiceOffering +
+ ControlPlane +
+
+ Configuration +
+
+
+
+ + + ServiceOffering... + + + + + + + + + + Text is not SVG - cannot display + + + + \ No newline at end of file diff --git a/docs/modules/ROOT/assets/images/web-portal-arch-current.drawio.svg b/docs/modules/ROOT/assets/images/web-portal-arch-current.drawio.svg new file mode 100644 index 0000000..260f505 --- /dev/null +++ b/docs/modules/ROOT/assets/images/web-portal-arch-current.drawio.svg @@ -0,0 +1,226 @@ + + + + + + + + + + + +
+
+
+ K8s API +
+
+
+ + + K8s API + + + + + + + + + + + + + + + + + + + +
+
+
+ Web Portal +
+
+
+ + + Web Portal + + + + + + + + + + + + +
+
+
+ HTTPS +
+
+
+ + + HTTPS + + + + + + + + + + + + +
+
+
+ User +
+
+
+ + + User + + + + + + + + + + + +
+
+
+ CSP 1 Zone A +
+ Control Plane +
+
+
+ + + CSP 1 Zone A... + + + + + + + + + + + +
+
+
+ CSP 2 Zone A +
+ Control Plane +
+
+
+ + + CSP 2 Zone A... + + + + + + + + + + + + +
+
+
+ K8s API +
+
+
+ + + K8s API + + + + + + + + + + + + +
+
+
+ Portal DB +
+ PostgreSQL +
+
+
+
+ + + Portal DB... + + + + + + + + + + + + +
+
+
+ VSHN Account +
+ Keycloak +
+
+
+
+ + + VSHN Account... + + + + + + + + + + Text is not SVG - cannot display + + + + \ No newline at end of file diff --git a/docs/modules/ROOT/nav.adoc b/docs/modules/ROOT/nav.adoc index ca7b4f5..447852e 100644 --- a/docs/modules/ROOT/nav.adoc +++ b/docs/modules/ROOT/nav.adoc @@ -2,6 +2,10 @@ * xref:terminology.adoc[] * xref:web-portal.adoc[] +** xref:web-portal-admin.adoc[Admin] +** xref:web-portal-controlplanes.adoc[Control-Planes] + +* xref:web-portal-planning.adoc[] ** xref:user-stories.adoc[] ** xref:organizations.adoc[] ** xref:authentication.adoc[] @@ -9,7 +13,6 @@ ** xref:service-catalog.adoc[] ** xref:service-instances.adoc[] ** xref:api.adoc[] -** xref:database-diagram.adoc[] * Cloud Providers ** xref:exoscale-osb.adoc[] \ No newline at end of file diff --git a/docs/modules/ROOT/pages/web-portal-admin.adoc b/docs/modules/ROOT/pages/web-portal-admin.adoc new file mode 100644 index 0000000..309933f --- /dev/null +++ b/docs/modules/ROOT/pages/web-portal-admin.adoc @@ -0,0 +1,59 @@ += Web Portal Admin + +The administration of the web portal happens with Django Admin. + +[TIP] +==== +* Production: https://portal.servala.com/admin[portal.servala.com^] +* Staging: https://staging.portal.servala.com/admin[staging.portal.servala.com^] +==== + +== Service Catalog and Control-Plane Models + +image::portal-service-relations.drawio.svg[] + +Service:: +The software service, top-level, categorized. + +_Examples_: PostgreSQL, Redis, GitLab. + +Admin: https://staging.portal.servala.com/admin/core/service/[staging^], https://portal.servala.com/admin/core/service/[prod^] + +Service Definition:: +A correlation between a specific managed service offering with the API definition on the control-planes. It tells the Portal which Kubernetes API implements a managed service. + +_Example_: "Forgejo by VSHN" is implemented by GVK `vshn.appcat.vshn.io/v1/VSHNForgejo` on the control-planes. + +Admin: https://staging.portal.servala.com/admin/core/servicedefinition/[staging^], https://portal.servala.com/admin/core/servicedefinition/[prod^] + +Service Offering:: +The service offering is the glue which connects a service with a service provider, the control-planes with the service definitions and plan information. It essentially tells the Portal which managed service is available on which control-plane with which specific configuration. It relates to "ControlPlane CRD" which is a correlation between "Service Offering", "Control Plane" and "Service Definition". +_Example_: "Forgejo at Hetzner Cloud" which makes the Service "Forgejo" available at Hetzner Cloud and through "ControlPlane CRDs" it defines which service definition is available in which control-plane at Hetzner Cloud. It also specifies plans with features, pricing and terms. + +Admin: https://staging.portal.servala.com/admin/core/serviceoffering/[staging^], https://portal.servala.com/admin/core/serviceoffering/[prod^] + +== Models + +In addition to the models described in <>, the following core models exist: + +Cloud Providers:: +Cloud providers where service instances can be provisioned at. + +Control Planes:: +Connections to Kubernetes API servers. Each control-plane represents a zone at a cloud provider. + +Organizations:: +The main multi-tenant object. + +Organization Memberships:: +Defines organization memberships including the roles in an organization. + +Organization Origins:: +The origin of an organization. Where the organization is coming from, influences e.g. access to control-planes or service offerings. + +Billing Entities:: +Billing contacts for Organizations - this is not further implemented yet. + +Plans:: +Plans for service offerings. + +Service Categories:: +Allows to categorize services. + +Service Instances:: +Service instances provisioned on control-planes. diff --git a/docs/modules/ROOT/pages/web-portal-controlplanes.adoc b/docs/modules/ROOT/pages/web-portal-controlplanes.adoc new file mode 100644 index 0000000..7b0328b --- /dev/null +++ b/docs/modules/ROOT/pages/web-portal-controlplanes.adoc @@ -0,0 +1,30 @@ += Web Portal Control-Planes + +Each control-plane represents a zone at a cloud provider. It's a dedicated Kubernetes API endpoint running the Servala control-plane. + +To register a control-plane, a service account with appropriate permissions is required on the Kubernetes API server. + +Example: + +[source,bash] +---- +# Create service account +kubectl -n kube-system create sa servala-portal + +# Create long-lived token for service account +kubectl -n kube-system apply -f - <