PLEASE NOTE: This document applies to an unreleased version of Rook. It is strongly recommended that you only use official releases of Rook, as unreleased versions are subject to changes and incompatibilities that will not be supported in the official releases.
If you are using an official release version of Rook, you should refer to the documentation for your specific version.Documentation for other releases can be found by using the version selector in the bottom left of any doc page.
Ceph Object Bucket Claim
Rook supports the creation of new buckets and access to existing buckets via two custom resources:
Object Bucket Claim (OBC)is custom resource which requests a bucket (new or existing) and is described by a Custom Resource Definition (CRD) shown below.
Object Bucket (OB)is a custom resource automatically generated when a bucket is provisioned. It is a global resource, typically not visible to non-admin users, and contains information specific to the bucket. It is described by an OB CRD, also shown below.
An OBC references a storage class which is created by an administrator. The storage class defines whether the bucket requested is a new bucket or an existing bucket. It also defines the bucket retention policy.
Users request a new or existing bucket by creating an OBC which is shown below. The ceph provisioner detects the OBC and creates a new bucket or grants access to an existing bucket, depending the the storage class referenced in the OBC. It also generates a Secret which provides credentials to access the bucket, and a ConfigMap which contains the bucket’s endpoint. Application pods consume the information in the Secret and ConfigMap to access the bucket. Please note that to make provisioner watch the cluster namespace only you need to set
true in the operator manifest, otherwise it watches all namespaces.
OBC Custom Resource
apiVersion: objectbucket.io/v1alpha1 kind: ObjectBucketClaim metadata: name: ceph-bucket  namespace: rook-ceph  spec: bucketName:  generateBucketName: photo-booth  storageClassName: rook-ceph-bucket  additionalConfig:  maxObjects: "1000" maxSize: "2G"
ObjectBucketClaim. This name becomes the name of the Secret and ConfigMap.
namespace(optional) of the
ObjectBucketClaim, which is also the namespace of the ConfigMap and Secret.
bucketNamename of the
bucket. Not recommended for new buckets since names must be unique within an entire object store.
generateBucketNamevalue becomes the prefix for a randomly generated name, if supplied then
bucketNamemust be empty. If both
generateBucketNameare supplied then
BucketNamehas precedence and
GenerateBucketNameis ignored. If both
generateBucketNameare blank or omitted then the storage class is expected to contain the name of an existing bucket. It’s an error if all three bucket related names are blank or omitted.
storageClassNamewhich defines the StorageClass which contains the names of the bucket provisioner, the object-store and specifies the bucket retention policy.
additionalConfigis an optional list of key-value pairs used to define attributes specific to the bucket being provisioned by this OBC. This information is typically tuned to a particular bucket provisioner and may limit application portability. Options supported:
maxObjects: The maximum number of objects in the bucket
maxSize: The maximum size of the bucket, please note minimum recommended value is 4K.
OBC Custom Resource after Bucket Provisioning
apiVersion: objectbucket.io/v1alpha1 kind: ObjectBucketClaim metadata: creationTimestamp: "2019-10-18T09:54:01Z" generation: 2 name: ceph-bucket namespace: default  resourceVersion: "559491" spec: ObjectBucketName: obc-default-ceph-bucket  additionalConfig: null bucketName: photo-booth-c1178d61-1517-431f-8408-ec4c9fa50bee  storageClassName: rook-ceph-bucket  status: phase: Bound 
namespacewhere OBC got created.
ObjectBucketNamegenerated OB name created using name space and OBC name.
- the generated (in this case), unique
bucket namefor the new bucket.
- name of the storage class from OBC got created.
- phases of bucket creation:
- Pending: the operator is processing the request.
- Bound: the operator finished processing the request and linked the OBC and OB
- Released: the OB has been deleted, leaving the OBC unclaimed but unavailable.
- Failed: not currently set.
apiVersion: v1 kind: Pod metadata: name: app-pod namespace: dev-user spec: containers: - name: mycontainer image: redis envFrom:  - configMapRef: name: ceph-bucket  - secretRef: name: ceph-bucket 
env:if mapping of the defined key names to the env var names used by the app is needed.
- makes available to the pod as env variables:
- makes available to the pod as env variables:
apiVersion: storage.k8s.io/v1 kind: StorageClass metadata: name: rook-ceph-bucket labels: aws-s3/object  provisioner: rook-ceph.ceph.rook.io/bucket  parameters:  objectStoreName: my-store objectStoreNamespace: rook-ceph region: us-west-1 bucketName: ceph-bucket  reclaimPolicy: Delete 
label(optional) here associates this
StorageClassto a specific provisioner.
provisionerresponsible for handling
bucketNameis required for access to existing buckets but is omitted when provisioning new buckets. Unlike greenfield provisioning, the brownfield bucket name appears in the
StorageClass, not the
- rook-ceph provisioner decides how to treat the
OBCis deleted for the bucket. See explanation as specified in Kubernetes
- Delete = physically delete the bucket.
- Retain = do not physically delete the bucket.