Add documentation for storage API resources (#1213)

Rohit-0505 · web-flow · commit 6bbca962fea8 · 2025-01-09T13:29:31.000+01:00
* Add document for Storage API resources

* address review comments and refactoring
diff --git a/docs/usage/installation.md b/docs/usage/installation.md
@@ -1 +1,80 @@
-# Installing IronCore
+# Installing Ironcore
+
+## Requirements
+
+* `go` >= 1.20
+* `git`, `make`, and `kubectl`
+* [Kustomize](https://kustomize.io/)
+* Access to a Kubernetes cluster ([Minikube](https://minikube.sigs.k8s.io/docs/), [kind](https://kind.sigs.k8s.io/) or a real cluster)
+
+## Clone the Repository
+
+To bring up and install the `Ironcore` project, you first need to clone the repository.
+
+``` shell
+git clone git@github.com:ironcore-dev/ironcore.git
+cd ironcore
+```
+
+## Install cert-manager
+
+If there is no [cert-manager](https://cert-manager.io/docs/) present in the cluster it needs to be installed.
+
+``` shell
+kubectl apply -f https://github.com/cert-manager/cert-manager/releases/download/v1.16.2/cert-manager.yaml
+```
+
+## Install APIs into the Cluster
+
+Your Kubernetes API server needs to know about the APIs that come with the `Ironcore` project. To install the APIs into your cluster, run
+
+``` shell
+make install
+```
+
+**Note**: This requires the `APISERVER_IMG` (Makefile default set to `apiserver`) to be pullable from your Kubernetes
+cluster. For local development with `kind`, a make target that builds and loads the API server image and then applies
+the manifests is available via
+
+``` shell
+make kind-install
+```
+
+**Note**: In case multiple environments running, ensure that `kind get clusters` is pointing to the
+default kind cluster.
+
+## Deploy the Controller Manager
+
+The controller manager can be started via the following command.
+
+``` shell
+make kind-deploy
+```
+## Validate
+
+Make sure you have all the below pods running.
+
+``` shell
+$ kubectl get po -n ironcore-system
+NAME                                           READY   STATUS    RESTARTS       AGE
+ironcore-apiserver-85995846f9-47247            1/1     Running   0              136m
+ironcore-controller-manager-84bf4cc6d5-l224c   2/2     Running   0              136m
+ironcore-etcd-0                                1/1     Running   0              143m
+```
+
+## Apply Sample Manifests
+
+The `config/samples` folder contains samples for all APIs supported by this project. You can apply any of the samples by
+running
+
+``` shell
+kubectl apply -f config/samples/SOME_RESOURCE.yaml
+```
+
+## Cleanup
+
+To remove the APIs from your cluster, simply run.
+
+``` shell
+make uninstall
+```
diff --git a/docs/usage/storage/bucket.md b/docs/usage/storage/bucket.md
@@ -1 +1,47 @@
-# Bucket
+# Bucket
+A `Bucket` in `Ironcore` refers to a storage resource that organizes and manages data, similar to the concept of buckets in cloud storage services like Amazon S3. Buckets are containers for storing objects, such as files or data blobs, and are crucial for managing storage workloads.
+
+# Example Bucket Resource
+An example of how to define a `Bucket` resource in `Ironcore`
+
+```
+apiVersion: storage.ironcore.dev/v1alpha1
+kind: Bucket
+metadata:
+  name: bucket-sample
+spec:
+  bucketClassRef:
+    name: bucketclass-sample
+#  bucketPoolRef:
+#    name: bucketpool-sample
+```
+
+# Key Fields:
+- `bucketClassRef`(`string`): 
+  - Mandatory field
+  - `BucketClassRef` is the BucketClass of a bucket
+
+- `bucketPoolRef`(`string`):
+  - Optional field
+  -  `bucketPoolRef` indicates which BucketPool to use for the bucket, if not specified the controller itself picks the available bucketPool
+
+
+# Usage
+- **Data Storage**: Use `Buckets` to store and organize data blobs, files, or any object-based data.
+
+- **Multi-Tenant Workloads**: Leverage buckets for isolated and secure data storage in multi-tenant environments by using separate BucketClass or BucketPool references.
+
+- **Secure Access**: Buckets store a reference to the `Secret` securely in their status, and the `Secret` has the access credentials, which applications can retrieve access details from the `Secret`.
+
+# Reconciliation Process:
+- The controller detects changes and fetches bucket details.
+
+- Creation/Update ensures the backend bucket exists, metadata is synced, and credentials are updated.
+
+- The bucket will automatically sync with the backend storage system, and update the Bucket's state (e.g., `Available`, `Pending`, or `Error`) in the bucket's status.
+
+- Access details and credentials will be managed securely using Kubernetes `Secret` and the bucket status will track a reference to the `Secret`.
+
+- During deletion, resources will be cleaned up gracefully without manual intervention.
+
+- If the bucket is not ready (e.g., backend issues), reconciliation will retry
diff --git a/docs/usage/storage/bucketclass.md b/docs/usage/storage/bucketclass.md
@@ -1 +1,42 @@
-# BucketClass
+# BucketClass
+A `BucketClass` is a concept used to define and manage different types of storage buckets, typically based on resource capabilities. It is conceptually similar to Kubernetes `StorageClass`, enabling users to specify the desired properties for an Ironcore `Bucket` resource creation.
+
+# Example BucketClass Resource
+An example of how to define a `BucketClass` resource in `Ironcore`
+
+```
+apiVersion: storage.ironcore.dev/v1alpha1
+kind: BucketClass
+metadata:
+  name: bucketclass-sample
+capabilities:
+  tps: 100Mi
+  iops: 100
+```
+
+# Key Fields:
+
+- `capabilities`: Capabilities has `tps` and `iops` fields which need to be specified, it's a mandatory field,
+  - `tps`(`string`): The `tps` represents transactions per second.
+
+  - `iops`(`string`):  `iops` is the number of input/output operations a storage device can complete per second.
+
+# Usage
+
+- **BucketClass Definition**: Create a `BucketClass` to set storage properties based on resource capabilities.
+
+- **Associate with buckets**: Link a `BucketClass` to a `Bucket` using a reference in the Bucket resource.
+
+- **Dynamic configuration**: Update the `BucketClass` to modify storage properties for all its Buckets.
+
+# Reconciliation Process:
+
+- **Fetches & Validates**: Retrieves the `BucketClass` from the cluster and checks if it exists.
+
+- **Synchronizes State**: Keeps the `BucketClass` resource updated with its current state and dependencies.
+
+- **Monitors Dependencies**: Watches for changes in dependent Bucket resources and reacts accordingly.
+
+- **Handles Errors**: Requeues the reconciliation to handle errors and ensure successful completion.
+
+- **Handles Deletion**: Cleans up references, removes the finalizer, and ensures no dependent Buckets exist before deletion.
diff --git a/docs/usage/storage/bucketpool.md b/docs/usage/storage/bucketpool.md
@@ -1 +1,34 @@
-# BucketPool
+# BucketPool
+A `BucketPool` is a resource in `Ironcore` that represents a pool of storage buckets managed collectively. It defines the infrastructure's storage configuration used to provision and manage buckets, ensuring resource availability and compatibility with associated BucketClasses.
+
+# Example BucketPool Resource
+An example of how to define a `BucketPool` resource in `Ironcore`
+
+```
+apiVersion: storage.ironcore.dev/v1alpha1
+kind: BucketPool
+metadata:
+  name: bucketpool-sample
+spec:
+  providerID: ironcore://shared
+#status:
+#  state: Available
+#  availableBucketClasses:
+#    ironcore.dev/fast-class: 10Gi
+#    ironcore.dev/slow-class: 100Gi
+```
+
+# Key Fields:
+- `ProviderID`(`string`):  The `providerId` helps the controller identify and communicate with the correct storage system within the specific backened storage porvider.
+
+    for example `ironcore://shared`
+
+# Reconciliation Process:
+
+- **Bucket Type Discovery**: It constantly checks what kinds of buckets (BucketClasses) are available in the `Ironcore` Infrastructure.
+
+- **Compatibility Check**: Evaluating whether the BucketPool can create and manage each bucket type based on its capabilities.
+
+- **Status Update**: Updating the BucketPool's status to indicate the bucket types it supports, like a menu of available options.
+
+- **Event Handling**: Watches for changes in BucketClass resources and ensures the associated BucketPool is reconciled when relevant changes occur.
diff --git a/docs/usage/storage/volume.md b/docs/usage/storage/volume.md
@@ -1 +1,44 @@
-# Volume
+# Volume
+The `Ironcore` `Volume` is a storage abstraction provided by the `Ironcore Runtime Interface` `(IRI)` service, designed to integrate with external storage backend for managing persistent storage. It acts as a managed storage unit, ensuring consistency, scalability, and compatibility with Kubernetes workloads.
+By integrating Ironcore Volumes with Kubernetes, users benefit from seamless storage management, automation, and advanced features such as encryption and scalability, making it suitable for modern cloud-native and hybrid applications.
+
+# Example Volume Resource
+An example of how to define a `Volume` resource in `Ironcore`
+
+```
+apiVersion: storage.ironcore.dev/v1alpha1
+kind: Volume
+metadata:
+  name: volume-sample
+spec:
+  volumeClassRef:
+    name: volumeclass-sample
+  # volumePoolRef:
+  #   name: volumepool-sample
+  resources:
+    storage: 100Gi
+```
+
+# Key Fields:
+
+- `volumeClassRef`(`string`): `volumeClassRef` refers to the name of an Ironcore `volumeClass`( for eg: `slow`, `fast`, `super-fast` etc.) to create a volume,
+
+- `volumePoolRef` (`string`): 	`VolumePoolRef` indicates which VolumePool to use for a volume. If unset, the scheduler will figure out a suitable `VolumePoolRef`.
+
+- `resources`: `Resources` is a description of the volume's resources and capacity.
+
+# Reconciliation Process:
+
+- **Fetch Volume Resource**: Retrieve the `Volume` resource and clean up any orphaned `IRI` volumes if the resource is missing.
+
+- **Add Finalizer**: Ensure a finalizer is added to manage cleanup during deletion.
+
+- **Check IRI Volumes**: List and identify `IRI` volumes linked to the `Volume` resource.
+
+- **Create or Update Volume**:
+  - Create a new IRI volume if none exists.
+  - Update existing IRI volumes if attributes like size or encryption need adjustments.
+
+- **Sync Status**: Reflect the IRI volume's state (e.g., Pending, Available) in the Kubernetes Volume resource's status.
+
+- **Handle Deletion**: Safely delete all associated IRI volumes and remove the finalizer to complete the resource lifecycle.
diff --git a/docs/usage/storage/volumeclass.md b/docs/usage/storage/volumeclass.md
@@ -1 +1,41 @@
-# VolumeClass
+# VolumeClass
+The `VolumeClass` in `Ironcore` is a Kubernetes-like abstraction that defines a set of parameters or configurations for provisioning storage resources through the `Ironcore Runtime Interface (IRI)`. It is conceptually similar to Kubernetes `StorageClass`, enabling users to specify the desired properties for an Ironcore `Volume` resource creation.
+
+# Example VolumeClass Resource
+An example of how to define a `VolumeClass` resource in `Ironcore`
+
+```
+apiVersion: storage.ironcore.dev/v1alpha1
+kind: VolumeClass
+metadata:
+  name: volumeclass-sample
+capabilities:
+  tps: 100Mi
+  iops: 100
+```
+
+# Key Fields:
+- `capabilities`: Capabilities has tps and iops fields that need to be specified, it's a mandatory field,
+  - `tps`(`string`): The `tps` represents transactions per second.
+
+  - `iops`(`string`): `iops` is the number of input/output operations a storage device can complete per second.
+
+# Usage
+
+- **VolumeClass Definition**: Create a `VolumeClass` to set storage properties based on resource capabilities.
+
+- **Associate with Volume**: Link a `VolumeClass` to a `Volume` using a reference in the Volume resource.
+
+- **Dynamic configuration**: Update the `VolumeClass` to modify storage properties for all its Volumes.
+
+# Reconciliation Process:
+
+- **Fetches & Validates**: Retrieves the VolumeClass from the cluster and checks if it exists.
+
+- **Synchronizes State**: Keeps the VolumeClass resource updated with its current state and dependencies.
+
+- **Monitors Dependencies**: Watches for changes in dependent Volume resources and reacts accordingly.
+
+- **Handles Errors**: Requeues the reconciliation to handle errors and ensure successful completion.
+
+- **Handles Deletion**: Cleans up references, removes the finalizer, and ensures no dependent Volumes exist before deletion.
diff --git a/docs/usage/storage/volumepool.md b/docs/usage/storage/volumepool.md
@@ -1 +1,34 @@
 # VolumePool
+A `VolumePool` is a resource in `Ironcore` that represents a pool of storage volume managed collectively. It defines the infrastructure's storage configuration used to provision and manage volumes, ensuring resource availability and compatibility with associated `VolumeClasses`.
+
+# Example VolumePool Resource
+An example of how to define a `VolumePool` resource in `Ironcore`
+
+```
+apiVersion: storage.ironcore.dev/v1alpha1
+kind: VolumePool
+metadata:
+  name: volumepool-sample
+spec:
+  providerID: ironcore://shared
+#status:
+#  state: Available
+#  availableVolumeClasses:
+#    ironcore.dev/fast-class: 10Gi
+#    ironcore.dev/slow-class: 100Gi
+```
+
+# Key Fields:
+- `providerID`(`string`): The `providerId` helps the controller identify and communicate with the correct storage system within the specific backened storage porvider.
+
+    for example `ironcore://shared`
+
+# Reconciliation Process:
+
+- **Volume Type Discovery**: It constantly checks what kinds of volumes (volumeClasses) are available in the `Ironcore` Infrastructure.
+
+- **Compatibility Check**: Evaluating whether the volumePool can create and manage each volume type based on its capabilities.
+
+- **Status Update**: Updating the VolumePool's status to indicate the volume types it supports, like a menu of available options.
+
+- **Event Handling**: Watches for changes in VolumeClass resources and ensures the associated VolumePool is reconciled when relevant changes occur.
diff --git a/gen/swagger.json b/gen/swagger.json
