= 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
