From bdbbfe0588e333b58d7636907bbe8082d72d825b Mon Sep 17 00:00:00 2001
From: Tobias Brunner <tobias.brunner@vshn.ch>
Date: Mon, 10 Mar 2025 16:28:22 +0100
Subject: [PATCH] document terminology

---
 docs/modules/ROOT/nav.adoc               |  1 +
 docs/modules/ROOT/pages/terminology.adoc | 30 ++++++++++++++++++++++++
 2 files changed, 31 insertions(+)
 create mode 100644 docs/modules/ROOT/pages/terminology.adoc

diff --git a/docs/modules/ROOT/nav.adoc b/docs/modules/ROOT/nav.adoc
index 5d67faa..fc6dcf2 100644
--- a/docs/modules/ROOT/nav.adoc
+++ b/docs/modules/ROOT/nav.adoc
@@ -1 +1,2 @@
 * xref:index.adoc[Home]
+* xref:terminology.adoc[]
\ No newline at end of file
diff --git a/docs/modules/ROOT/pages/terminology.adoc b/docs/modules/ROOT/pages/terminology.adoc
new file mode 100644
index 0000000..c249ec5
--- /dev/null
+++ b/docs/modules/ROOT/pages/terminology.adoc
@@ -0,0 +1,30 @@
+= Terminology
+
+Web Portal (Portal)::
+This is the aggregated view and entry point for the user.
+It provides the mechanisms for the multi-tenant, multi-service-provider self-service portal.
+
+Control Plane (CP)::
+This runs Crossplane and the AppCat Control Plane (Kubernetes API) which manages all the service instances on worker clusters.
+Each zone of a Service Provider runs at least one CP.
+
+Worker Cluster::
+Clusters running the actual workload, managed by the Control Plane.
+Each zone of a CSP runs at least one Worker Cluster.
+Services are directly exposed to the end-user.
+
+Service::
+A generic service like "PostgreSQL" or "Keycloak".
+This doesn't include pricing or any other aspect of a managed service.
+
+Plan::
+A bundle of a service, a price, an SLA and other parameters to form an offering.
+It can be instantiated (ordered) and parametrized according to the specification in the offering.
+
+Crossplane specific terms::
+* Compositions - A template to define how to create resources.
+* Composite Resource Definition (`XRD`) - A custom API specification.
+* Composite Resource (`XR`) - Created by using the custom API defined in a Composite Resource Definition. XRs use the Composition template to create new managed resources.
+* Claims (`XRC`) - Like a Composite Resource, but with namespace scoping.
+* Managed Resource (`MR`) - Represents an external service in a Provider.
+* Providers enable Crossplane to provision infrastructure on an external service. Providers create new Kubernetes APIs and map them to external APIs.
\ No newline at end of file