APPUiO Control API Architecture

This page describes the APPUiO Control API. It adheres to the decision taken in APPUiO Control API and it follows the features asked in Functional Requirements Targeting the Portal.

General Principles

Kubernetes API

The Control API is built upon the Kubernetes API and adheres to it’s design principles.

API object field: .status

The status field (also called Status subresource) represents the current observed state and external information. It is read-only to the end-user.

API object field: .spec

The spec field contains the desired state for reconciliation.

Virtual vs. CRD based resources

Some resources are not persisted to etcd and are only available virtually, others are persisted to etcd and are defined and represented via CustomResourceDefinition (CRDs).

Virtual resources are accessible via an API Server Extension. These resources are similar to views in a relational database. The benefit of providing these resources instead of only using CRDs is that we can calculate access permissions dynamically for every request. The same concept is also used by OpenShift with its Project resource which represents RBAC filtered Namespaces (see kube-projects). And we can also find it in Kiosk for example.

Authentication and Authorization

Authentication against the API server is done by the APPUiO IdP. It’s always the same subject (user) which is being used throughout the whole APPUiO Cloud ecosystem.

For authorization, standard Kubernetes RBAC is being used. Kyverno policies can be used to implement enhanced policies, for example the number of resources of a specified kind a user is allowed to create.

There are several layers of authorization:

  • Kubernetes RBAC

  • Kyverno policies

  • Virtual resources with filtering

Resource Scopes

Resources on the Kubernetes API server can either be cluster scoped or namespace scoped.

Each APPUiO Control API instance is represented by one Kubernetes API server instance. This allows us to leverage the scoping concept of the Kubernetes API server to reflect the scopes in the APPUiO Cloud domain. Also, by doing it that way, standard Kubernetes RBAC rules can be used for permission handling on an organization level.

APPUiO Cloud Global resources are available on the Kubernetes global scope (no namespace) whereas organization level resources are namespace scoped.


Kubernetes cluster global resource.


Kubernetes namespaced resource.


Name Scope Type



Virtual (represents filtered Namespace resources)