Product Architecture
This page describes the technical product architecture of VSHN products.
It discusses all the involved components which make up a VSHN product and outlines concepts and infrastructure which can or must be used. The main idea is to share common concepts so that VSHN products form a unity and don’t have to reinvent the wheel for basic functionality.
| This is a work in progress! |
Multi-Tenancy
VSHN products are built using multi-tenancy concepts. We define the following concepts to support multi-tenancy:
-
Organization
-
Billing Entity
-
Team
All product instances must be owned by exactly one Organization and an Organization must be assigned to a Billing Entity. A Billing Entity can be assigned to zero or more Organization. Teams are an optional feature to have fine-grained grouping of users inside an Organization, each having their own access rights.
The roots of this concept are in APPUiO Cloud. Currently, the documentation lives there. To get started with it, have a look at the following pages:
Billing
This VSHN Billing system is used to generate usage-based invoices. It must be used by all VSHN products for billing purpose, and it is bound to the Multi-Tenancy concepts.
Just like with the multi-tenancy concept, the roots are in APPUiO Cloud. See the following pages to learn more:
Configuration Management
To bring configuration to Kubernetes clusters we use Project Syn.
How we use Project Syn is documented under Project Syn at VSHN.
Documentation
Product documentation is written using AsciiDoc and Antora. For more information about our documentation system, please consult our Handbook.
Every product must provide:
- User documentation
-
to describe how to work with the product from a perspective of the user of the product. Usually lives as its own Antora project and has a unique URL, like docs.appuio.cloud or docs.appcat.ch.
- Technical documentation
-
to describe how the product works and how to develop and operate it, targeted to the VSHNeer. Usually lives under kb.vshn.ch.
- Product documentation
-
to describe the product from a business perspective. Usually lives under products.docs.vshn.ch.
Alert Routing
We use OpsGenie as the company-wide alert routing system. Each product must integrate with OpsGenie to send alerts to the support organization.
Documentation about our use of OpsGenie is currently to be found in our Wiki.
Responsibility of this system is at the Operations Work Group.
Central Metrics
Metrics should be sent to the central metrics system based on Mimir/Grafana. Grafana is available under insights.appuio.net.
There is not much documentation around yet, currently it’s being managed by Team Aldebaran.
SLA Reporting
To accommodate our requirements of having SLA reporting for our products, we provide a system for that which has to be used by all products.
The SLA data is saved in a central, Prometheus compatible database. One or more exporters are responsible to provide the actual metrics and necessary labels to generate the reports. Sloth is used to help generate the correct queries and recorders for Prometheus.
AppCat currently provides a custom tool to query the database and generate the SLA reports. It leverages queries based on Sloth to generate the SLA number over a given period of time. The reports themselves are rendered into AsciiDoc, produced with (currently) hardcoded templates, and afterwards sent to VSHN DocGen for generating a PDF file with VSHN styling.
Currently these PDFs are stored in an S3 bucket and can be provided to customers on request. For more information please consult here.
Status Page
To communicate the status of our services we use Statuspal. A product can use Statuspal if desired.
Documentation about our use of Statuspal is currently to be found in our Wiki.
Responsibility of this system is at the Operations Work Group.
External Monitoring
This is currently being figured out in VTAW-1.
Customer Portal
A product can be integrated into our customer portal.
The aim is to develop the "APPUiO Cloud Portal" (together with the Control API) into a generic "VSHN Portal" where products can hook into and provide their features. Over time this will make our current customer portal under control.vshn.net obsolete.
The roots of the "APPUiO Cloud Portal" are obviously in APPUiO Cloud. Currently, the documentation lives there. To get started with it, have a look at the following pages: