How to Create Rook Ceph Object Buckets for Developers

This guide will walk you through the steps to create an Object Bucket Claim (OBC), validate the bucket's functionality, and integrate the newly created bucket into your application.

note

This guide is intended to be completed by a developer.

Step 1: Creating an Object Bucket Claim (OBC)

The initial step involves creating an OBC. Once the OBC is in place, Rook's bucket provisioner will automatically generate a new bucket for you. It is important to note that the OBC specifies the storage class previously defined by your administrator. Upon bucket provisioning, a custom resource, known as an Object Bucket (OB), is created. This OB is a global resource, usually hidden from non-admin users, and holds specific details about the bucket.

The following is a sample YAML configuration to create an OBC:

apiVersion: objectbucket.io/v1alpha1
kind: ObjectBucketClaim
metadata:
  name: ceph-bucket
  namespace: app-namespace
spec:
  # If 'bucketName' is set, ensure it is unique across the object store.
  # If 'generateBucketName' is set, 'bucketName' should be empty.
  generateBucketName: photo-booth # Becomes the prefix for a randomly generated bucket name
  storageClassName: rook-ceph-bucket # Specifies the StorageClass that contains the bucket provisioner's name
  additionalConfig:
    maxObjects: "1000"
    maxSize: "2G"

Step 2: Operator-Generated Artifacts for Bucket Access

After the OBC is successfully created, Rook's operator will handle the rest. It creates the bucket and generates essential artifacts, including a secret and a ConfigMap, to facilitate bucket access. Both the secret and ConfigMap bear the same name as the OBC and are created within the same namespace.

• The secret contains the credentials required for application pods to interact with the bucket.
• The ConfigMap holds information regarding the bucket endpoint and is utilized by the pod.

Step 3: Testing Bucket Functionality with an S3 Client

To verify that your application can interact with the S3 bucket, you can deploy a sample pod that uses the aws-cli image to upload and download a file to and from the bucket. Below is an example pod manifest:

apiVersion: v1
kind: Pod
metadata:
  name: s3-test-pod
  namespace: app-namespace
spec:
  containers:
    - name: s3-client
      image: registry1.dso.mil/ironbank/opensource/amazon/aws-cli:latest
      command:
      - "/bin/sh"
      - "-c"
      - |
        echo "Hello Rook" > /tmp/rookObj
        aws s3 cp /tmp/rookObj s3://<your-bucket-name>/rookObj
        aws s3 cp s3://<your-bucket-name>/rookObj /tmp/downloadedObj
      env:
        - name: AWS_ACCESS_KEY_ID
          value: <your-access-key-id>
        - name: AWS_SECRET_ACCESS_KEY
          value: <your-secret-access-key>

Step 4: Application Configuration for Bucket Access

When deploying applications that need to interact with the newly created bucket, your YAML file should reference both the ConfigMap and Secret. This ensures that the appropriate environment variables are automatically set in your application.

The following is a sample YAML configuration to accomplish this:

apiVersion: v1
kind: Pod
metadata:
  name: app-pod
  namespace: app-namespace
spec:
  containers:
  - name: mycontainer
    image: redis
    envFrom:
    - configMapRef:
        name: ceph-bucket # Environment variables: BUCKET_HOST, BUCKET_PORT, BUCKET_NAME
    - secretRef:
        name: ceph-bucket # Environment variables: AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY

By following these steps, you should be well-equipped to provision and utilize S3 buckets via Rook-Ceph in your applications.