draft architecture design

docs/design/overview.md

@@ -1,3 +1,60 @@
 # Architecture
 
-Subcomponent architecture and interfaces.
+## Overview
+As laid out in the [System Architecture document](https://eoepca.readthedocs.io/projects/architecture/) the Workspace building-block comprises:
+
+* **Workspace Controller**<br>
+  Platform-level API for administration of workspaces with capabilities via an API for **Workspace Provisioning** and **Workspace Utilisation**
+
+* **Storage Controller**<br>
+  User-level API for management of storage buckets with capabilities via an API for **Bucket Provisioning**, **Bucket Management** and **Bucket Federation**
+
+* **Workspace Services**<br>
+  Comprising the **extensible set of Services** dynamically instantiated on a workspace within the scope of a project/user.
+
+* **Workspace UI**<br>
+  **Web-enabled user interface** for the capabilities offered by the Workspace and Storage Controllers.
+
+## Design
+
+A workspace involves allocating compute and storage resources tailored to a specific project or user. By leveraging Kubernetes and the multi-tenant features of the vCluster project, a balance between isolation and cost efficiency is achieved while retaining the benefits of Kubernetes. As a result, a workspace is implemented as a vCluster installation, hosting multiple "virtual" Kubernetes clusters within a single "host" Kubernetes cluster.
+
+In line with Kubernetes native concepts, a workspace is defined using a new Kubernetes Workspace CRD (Custom Resource Definition), with a corresponding Kubernetes **Workspace Controller** responsible for reconciling the desired state as specified in the Workspace CRD manifest on the cluster.
+
+The reconciliation process within the **Workspace Controller** for each workspace manifest involves the following steps
+
+- Establish a dedicated namespace for each project/user in the Host Kubernetes cluster.
+- Apply Kubernetes policies such as ResourceQuota, LimitRange, and NetworkPolicy to the namespace.
+- Deploy a vCluster with best-practice configurations within the namespace.
+- Create a new GIT repository (or a folder in an existing GIT repository, depending on the global setup) to store the desired manifests for Workspace Services to be reconciled through Flux GitOps principles.
+- Connect Flux to reconcile the GIT repository (or folder) with the vCluster.
+- Implement Kubernetes Validating Webhooks to enforce bucket creation policies, such as maximum number and size, and naming pattern conventions, within the namespace.
+
+and finally exposes
+
+- vCluster credentials for direct "virtual" Kubernetes cluster access,
+- GIT settings used for Flux,
+- The current reconciliation state.
+
+An operator can establish a workspace for a project/user imperatively via the Kubernetes API by submitting a Workspace manifest or by following a declarative (Gitops-style) approach with the Workspace manifest checked in to GIT. The Kubernetes Web UI Dashboard may be deployed on the "host" Kubernetes cluster supporting the operator process in a graphical way during **Workspace Provisioning**. For **Workspace Utilization** dedicated Grafana dashboard are established tracking workspace metrics.
+
+Note: The EOEPCA 1.x workspace API is obsolete and not included in EOEPCA+.
+
+A workspace can be accessed via the Kubernetes API and is integrated with GitOps tooling through Flux. Both common and optional components can be installed for a specific project or user. By default, the template GitRepository includes the Storage Controller, responsible for **Bucket Provisioning** and **Bucket Federation**, as well as common EOEPCA Building Blocks (BB) for resource discovery and EO data management. These **Workspace Services** can be enriched with additional tools from the EOEPCA Application Hub BB and EOEPCA MLHub BB.
+
+The **Storage Controller** is tasked with reconciling the desired state as specified in the storage manifest (for the new Kubernetes Storage CRD). It uses Terraform internally for the reconciliation process, with documentation providing specifications for common cloud providers like AWS as examples.
+
+Note: Kubernetes Validating Webhooks established in the namespace of the "host" cluster will enforce proper bucket creation policies.
+
+The reconciliation process within the Storage Controller for each storage manifest includes the following steps:
+
+- Establish a dedicated bucket or connect a federated bucket.
+- Configure bucket access and CORS policies for the bucket.
+
+and finally exposes:
+
+- Bucket credentials,
+- Access URL,
+- The current reconciliation state.
+
+TBC

docs/index.md

@@ -15,10 +15,47 @@ The documentation for the `Workspace` building block is organised as follows...
 * **API**<br>
   Details of APIs provided by the BB - including endpoints, usage descriptions and examples etc.
 
+
 ## About `Workspace`
 
-Description of the purpose of the BB.
+The `Workspace` building block provides a comprehensive solution for storing assets and offering services like cataloguing, data (cube) access, and visualization to explore stored assets. Workspaces can cater to individual users or serve as collaborative spaces for groups or projects.
+
+### Workspace Controller
+
+The Workspace Controller acts as an API for workspace administration. This includes:
+
+* **Provisioning and Lifecycle Management:** Creating, updating, and deleting workspaces.
+* **Workspace Instance Management:** Configuring and managing individual workspace instances and their associated services [BR066].
+* **REST API:** Providing a REST API for workspace administration [BR067].
+* **GitOps Approach:** Enabling workspace owners to manage their workspace offerings through a declarative GitOps approach [BR070].
+* **Extensibility:** Allowing for the extension of managed services by reusing existing building blocks [BR068, BR069].
+* **Resource Efficiency:** Designing for efficient use of platform resources [BR072].
+* **Service Management:** Enabling users to manage (enable, disable, suspend) the services provisioned within their workspace [BR071].
+
+### Storage Controller
+
+The Storage Controller provides an API for self-service management of storage buckets. Users can:
+
+* **Create and Manage Buckets:** Create and manage object storage buckets via an API associated with the workspace [BR073, BR074].
+* **Bucket Management:** Manage buckets, including listing details like bucket name, service URL, and S3 access credentials [BR075].
+* **HTTP Access:** Access buckets via direct HTTP access, supporting HTTP range requests and allowing users to upload assets [BR076, BR077].
+* **IAM Integration:** Secure S3 and HTTP access by integrating with the IAM building block [BR078].
+* **External Storage Support:** Register and integrate external S3-compatible object storage services [BR079].
+* **Unique Identification:** Uniquely identify each S3 object storage service [BR080].
+
+### Workspace Services
+
+The Workspace Services comprise an extensible set of services that can be provisioned within the workspace. These services include:
+
+* **Resource Registration/Discovery:** Enabling the registration and discovery of resources.
+* **Data & Datacube Access:** Providing access to data and data cubes.
+* **Extensibility:** Supporting arbitrary applications and tooling by reusing existing Helm charts for databases (e.g., PostGIS), JupyterHub, ML tooling (e.g., MLFlow, Tensorboard) [BR081, BR084].
+* **Public APIs:** Exposing all workspace services via their public APIs.
+* **Scoped Access:** Providing access to resources scoped according to the owning projects and users [BR082, BR083].
+
+### Workspace User Interface
 
-## Capabilities
+The Workspace User Interface provides a web-based interface for:
 
-Summary of the capabilities of the BB.
+* **Workspace Lifecycle Management:** Creating, listing, updating, and deleting workspaces.
+* **Workspace Resource Management:** Managing workspace resources, including services, storage buckets, registered resources, and DOI registrations [BR085].