#Concepts

#Overview

Kubernetes administrators who are familiar with persistent storage concepts can use Container Object Storage Interface (COSI) resources to manage object storage through declarative Kubernetes APIs. COSI provides a declarative mechanism for managing object storage, similar to existing Kubernetes persistent storage management approaches.

COSI uses three primary resources: BucketClass, Bucket, and BucketClaim.

#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 a Kubernetes abstraction of an actual bucket in an external object storage system.

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.