#Concepts

#Overview

This document introduces Kubernetes administrators familiar with persistent storage concepts to the core resources and principles of the Container Object Storage Interface (COSI). COSI provides a declarative mechanism for managing object storage (such as AWS S3, MinIO, and Ceph RGW), similar to existing Kubernetes persistent storage management approaches.

We will cover the three primary resources in COSI—BucketClass, Bucket, and BucketClaim—drawing analogies with Kubernetes storage resources to clarify their relationships and functionalities.

#Core Resources

COSI defines three essential resources:

#1. BucketClass

Scope: Cluster-scoped Analogous Kubernetes Concept: Similar to StorageClass

BucketClass is created by cluster administrators to define specific types or service levels of buckets, including region location, redundancy policies, and performance tiers.

Key functions:

• Specifies bucket deletion policies (e.g., whether to delete the underlying bucket upon BucketClaim deletion)
• Specifies the COSI driver (driverName)
• Defines vendor-specific parameters

YAML Example:

apiVersion: objectstorage.k8s.io/v1alpha1
kind: BucketClass
metadata:
  name: ceph-cosi-driver-class
deletionPolicy: Delete
driverName: ceph.objectstorage.k8s.io
parameters:
  objectStoreUserSecretName: rook-ceph-object-user-object-store-user-for-cosi
  objectStoreUserSecretNamespace: rook-ceph

#2. Bucket

Scope: Cluster-scoped Analogous Kubernetes Concept: Similar to PersistentVolume (PV)

Bucket represents an abstraction of an actual bucket present in an external object storage system (such as AWS S3, MinIO, Ceph RGW) within Kubernetes.

Lifecycle management:

• Dynamic creation: Automatically created by the COSI controller upon receiving a BucketClaim request.

#3. BucketClaim

Scope: Namespace-scoped Analogous Kubernetes Concept: Similar to PersistentVolumeClaim (PVC)

BucketClaim resources are created by application developers within their namespaces to request object storage buckets.

Workflow:

1. User creates a BucketClaim specifying a BucketClass.
2. The COSI controller detects the request and dynamically creates the bucket in the object storage backend based on the BucketClass definition.
3. A corresponding Bucket resource is created and bound to the BucketClaim.
4. A Secret containing bucket access credentials is generated and automatically mounted into Pods requesting the bucket.

YAML Example:

apiVersion: objectstorage.k8s.io/v1alpha1
kind: BucketClaim
metadata:
  name: my-app-bucket-claim
  namespace: my-app-ns
spec:
  bucketClassName: ceph-standard-replicated
  protocol:
    s3: {} # Defaults populated by the driver

#Resource Interaction Workflow

The following process demonstrates the dynamic creation flow of COSI resources in practice:

1. Cluster administrator creates and maintains BucketClass.
2. Namespace user creates a BucketClaim referencing the BucketClass.
3. COSI controller observes the BucketClaim, dynamically creates the bucket based on the BucketClass definition.
4. The controller generates a corresponding Bucket resource within Kubernetes.
5. BucketClaim and Bucket are bound together.
6. A Secret containing storage credentials is created for Pod use.
7. Pods mount the Secret and access the object storage.

#Summary

By leveraging standardized APIs provided by COSI, Kubernetes administrators can declaratively and portably manage object storage resources, greatly enhancing integration efficiency between applications and object storage within Kubernetes clusters.