servala/servala-portal
3
0
Fork 0
Code Issues 21 Pull requests 5 Projects 2 Releases Packages 2 Activity Actions

move over documentation from old place
All checks were successful
Build and Deploy Antora Docs / build (push) Successful in 38s
Details
Build and Deploy Antora Docs / deploy (push) Successful in 5s
Details

Browse source
This commit is contained in:
Tobias Brunner 2025-03-11 15:37:13 +01:00
parent 16e8c2729b
commit d61465b6ea
No known key found for this signature in database
11 changed files with 1184 additions and 2 deletions
Download patch file Download diff file Expand all files Collapse all files

62
docs/modules/ROOT/pages/service-instances.adoc Normal file
View file

@ -0,0 +1,62 @@
= Service Instances
Working with service instances happens by directly talking to the xref:control-planes.adoc[control plane APIs].
The actions of ordering, listing, viewing, updating and deleting are directly executed on the control plane API.
No state of any service instance is stored in the database of the portal, the source of truth is in the possession of the control plane.
All actions are executed in the context of the organization and control plane tuple.
This dictates what is available and possible.
Examples of Kubernetes service resources, see https://docs.appcat.ch/[docs.appcat.ch^].
== Organization Namespace
Every organization has a dedicated Kubernetes namespace on the control plane.
This namespace is managed by the portal and created on first use (see https://docs.appuio.cloud/user/how-to/manage-projects-and-namespaces.html#_creating_namespaces[APPUiO docs on creating namespaces]).
Service instance resources live in the organizations namespace.
== Dynamic Service Spec Form
Service parametrization is subject to the capability of the API (XRD) exposed by the control plane.
The form is dynamically generated by the OpenAPI spec.
Certain standard fields of this spec are intercepted and either hidden, shown read-only or filled with default values.
These mainly concerns the Crossplane core fields:
* `spec.compositionRef`
* `spec.compositionSelector`
* `spec.compositionRevisionRef`
* `spec.compositionRevisionSelector`
* `spec.resourceRefs`
* `spec.writeConnectionSecretToRef`
We can also specify rules how to make field names look nicer (For example: `logLevel` (original) becomes `Log Level`).
And we might also want to intercept other fields (configurable).
== Create / Update / Delete
By choosing a service from the available plans (organization and control plane context), the service is parametrized and then created directly in the chosen control plane in the organizations namespace.
The control plane does its validation and admission tasks, any errors, warnings or other information returned by the control plane is surfaced to the user via the portal.
For updating a service instance, the form is pre-filled with the current values.
Deletion happens by deleting the resource in the control plane.
The portal makes sure to handle potentially available deletion protection, available on certain services (For example https://docs.appcat.ch/vshn-managed/postgresql/delete.html[PostgreSQL by VSHN^]).
== Listing and Viewing
Listing of service instances and viewing their details is done by directly querying the control plane API.
The list view shows all service instances on all control planes of the organization and depending on the access the user has.
In the detail view of a service instance, all important details are displayed, also from the `.status` sub-resource.
This view also allows access to the connection credentials which contain the details how to access the service instance.
== Other Service Features
Services might have additional features which will be incorporated into the portal for ease of use.
A non-exhaustive list:
* Listing of available backups
* Restoring from backup
* Metrics and alerts