Chapter 9. Object Bucket Claim

An Object Bucket Claim can be used to request an S3 compatible bucket backend for your workloads.

You can create an Object Bucket Claim in three ways:

An object bucket claim creates a new bucket and an application account in NooBaa with permissions to the bucket, including a new access key and secret access key. The application account is allowed to access only a single bucket and can’t create new buckets by default.

9.1. Dynamic Object Bucket Claim

Similar to Persistent Volumes, you can add the details of the Object Bucket claim (OBC) to your application’s YAML, and get the object service endpoint, access key, and secret access key available in a configuration map and secret. It is easy to read this information dynamically into environment variables of your application.

Note

The Multicloud Object Gateway endpoints uses self-signed certificates only if OpenShift uses self-signed certificates. Using signed certificates in OpenShift automatically replaces the Multicloud Object Gateway endpoints certificates with signed certificates. Get the certificate currently used by Multicloud Object Gateway by accessing the endpoint via the browser. See Accessing the Multicloud Object Gateway with your applications for more information.

Procedure

  1. Add the following lines to your application YAML:

    apiVersion: objectbucket.io/v1alpha1
    kind: ObjectBucketClaim
    metadata:
      name: <obc-name>
    spec:
      generateBucketName: <obc-bucket-name>
      storageClassName: openshift-storage.noobaa.io

    These lines are the OBC itself.

    1. Replace <obc-name> with the a unique OBC name.
    2. Replace <obc-bucket-name> with a unique bucket name for your OBC.
  2. To automate the use of the OBC add more lines to the YAML file.

    For example:

    apiVersion: batch/v1
    kind: Job
    metadata:
      name: testjob
    spec:
      template:
        spec:
          restartPolicy: OnFailure
          containers:
            - image: <your application image>
              name: test
              env:
                - name: BUCKET_NAME
                  valueFrom:
                    configMapKeyRef:
                      name: <obc-name>
                      key: BUCKET_NAME
                - name: BUCKET_HOST
                  valueFrom:
                    configMapKeyRef:
                      name: <obc-name>
                      key: BUCKET_HOST
                - name: BUCKET_PORT
                  valueFrom:
                    configMapKeyRef:
                      name: <obc-name>
                      key: BUCKET_PORT
                - name: AWS_ACCESS_KEY_ID
                  valueFrom:
                    secretKeyRef:
                      name: <obc-name>
                      key: AWS_ACCESS_KEY_ID
                - name: AWS_SECRET_ACCESS_KEY
                  valueFrom:
                    secretKeyRef:
                      name: <obc-name>
                      key: AWS_SECRET_ACCESS_KEY

    The example is the mapping between the bucket claim result, which is a configuration map with data and a secret with the credentials. This specific job claims the Object Bucket from NooBaa, which creates a bucket and an account.

    1. Replace all instances of <obc-name> with your OBC name.
    2. Replace <your application image> with your application image.
  3. Apply the updated YAML file:

    # oc apply -f <yaml.file>

    Replace <yaml.file> with the name of your YAML file.

  4. To view the new configuration map, run the following:

    # oc get cm <obc-name> -o yaml

    Replace obc-name with the name of your OBC.

    You can expect the following environment variables in the output:

    • BUCKET_HOST - Endpoint to use in the application.
    • BUCKET_PORT - The port available for the application.

    • BUCKET_NAME - Requested or generated bucket name.
    • AWS_ACCESS_KEY_ID - Access key that is part of the credentials.
    • AWS_SECRET_ACCESS_KEY - Secret access key that is part of the credentials.
Important

Retrieve the AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY. The names are used so that it is compatible with the AWS S3 API. You need to specify the keys while performing S3 operations, especially when you read, write or list from the Multicloud Object Gateway (MCG) bucket. The keys are encoded in Base64. Decode the keys before using them.

# oc get secret <obc_name> -o yaml
<obc_name>
Specify the name of the object bucket claim.

9.2. Creating an Object Bucket Claim using the command line interface

When creating an Object Bucket Claim (OBC) using the command-line interface, you get a configuration map and a Secret that together contain all the information your application needs to use the object storage service.

Prerequisites

  • Download the Multicloud Object Gateway (MCG) command-line interface.

    # subscription-manager repos --enable=rh-odf-4-for-rhel-8-x86_64-rpms
    # yum install mcg
    Note

    Specify the appropriate architecture for enabling the repositories using the subscription manager.

    • For IBM Power, use the following command:
    # subscription-manager repos --enable=rh-odf-4-for-rhel-8-ppc64le-rpms
    • For IBM Z, use the following command:
    # subscription-manager repos --enable=rh-odf-4-for-rhel-8-s390x-rpms

Procedure

  1. Use the command-line interface to generate the details of a new bucket and credentials.

    Run the following command:

    # noobaa obc create <obc-name> -n openshift-storage

    Replace <obc-name> with a unique OBC name, for example, myappobc.

    Additionally, you can use the --app-namespace option to specify the namespace where the OBC configuration map and secret will be created, for example, myapp-namespace.

    For example:

    INFO[0001] ✅ Created: ObjectBucketClaim "test21obc"

    The MCG command-line-interface has created the necessary configuration and has informed OpenShift about the new OBC.

  2. Run the following command to view the OBC:

    # oc get obc -n openshift-storage

    For example:

    NAME        STORAGE-CLASS                 PHASE   AGE
    test21obc   openshift-storage.noobaa.io   Bound   38s
  3. Run the following command to view the YAML file for the new OBC:

    # oc get obc test21obc -o yaml -n openshift-storage

    For example:

    apiVersion: objectbucket.io/v1alpha1
    kind: ObjectBucketClaim
    metadata:
      creationTimestamp: "2019-10-24T13:30:07Z"
      finalizers:
      - objectbucket.io/finalizer
      generation: 2
      labels:
        app: noobaa
        bucket-provisioner: openshift-storage.noobaa.io-obc
        noobaa-domain: openshift-storage.noobaa.io
      name: test21obc
      namespace: openshift-storage
      resourceVersion: "40756"
      selfLink: /apis/objectbucket.io/v1alpha1/namespaces/openshift-storage/objectbucketclaims/test21obc
      uid: 64f04cba-f662-11e9-bc3c-0295250841af
    spec:
      ObjectBucketName: obc-openshift-storage-test21obc
      bucketName: test21obc-933348a6-e267-4f82-82f1-e59bf4fe3bb4
      generateBucketName: test21obc
      storageClassName: openshift-storage.noobaa.io
    status:
      phase: Bound
  4. Inside of your openshift-storage namespace, you can find the configuration map and the secret to use this OBC. The CM and the secret have the same name as the OBC.

    Run the following command to view the secret:

    # oc get -n openshift-storage secret test21obc -o yaml

    For example:

    apiVersion: v1
    data:
      AWS_ACCESS_KEY_ID: c0M0R2xVanF3ODR3bHBkVW94cmY=
      AWS_SECRET_ACCESS_KEY: Wi9kcFluSWxHRzlWaFlzNk1hc0xma2JXcjM1MVhqa051SlBleXpmOQ==
    kind: Secret
    metadata:
      creationTimestamp: "2019-10-24T13:30:07Z"
      finalizers:
      - objectbucket.io/finalizer
      labels:
        app: noobaa
        bucket-provisioner: openshift-storage.noobaa.io-obc
        noobaa-domain: openshift-storage.noobaa.io
      name: test21obc
      namespace: openshift-storage
      ownerReferences:
      - apiVersion: objectbucket.io/v1alpha1
        blockOwnerDeletion: true
        controller: true
        kind: ObjectBucketClaim
        name: test21obc
        uid: 64f04cba-f662-11e9-bc3c-0295250841af
      resourceVersion: "40751"
      selfLink: /api/v1/namespaces/openshift-storage/secrets/test21obc
      uid: 65117c1c-f662-11e9-9094-0a5305de57bb
    type: Opaque

    The secret gives you the S3 access credentials.

  5. Run the following command to view the configuration map:

    # oc get -n openshift-storage cm test21obc -o yaml

    For example:

    apiVersion: v1
    data:
      BUCKET_HOST: 10.0.171.35
      BUCKET_NAME: test21obc-933348a6-e267-4f82-82f1-e59bf4fe3bb4
      BUCKET_PORT: "31242"
      BUCKET_REGION: ""
      BUCKET_SUBREGION: ""
    kind: ConfigMap
    metadata:
      creationTimestamp: "2019-10-24T13:30:07Z"
      finalizers:
      - objectbucket.io/finalizer
      labels:
        app: noobaa
        bucket-provisioner: openshift-storage.noobaa.io-obc
        noobaa-domain: openshift-storage.noobaa.io
      name: test21obc
      namespace: openshift-storage
      ownerReferences:
      - apiVersion: objectbucket.io/v1alpha1
        blockOwnerDeletion: true
        controller: true
        kind: ObjectBucketClaim
        name: test21obc
        uid: 64f04cba-f662-11e9-bc3c-0295250841af
      resourceVersion: "40752"
      selfLink: /api/v1/namespaces/openshift-storage/configmaps/test21obc
      uid: 651c6501-f662-11e9-9094-0a5305de57bb

    The configuration map contains the S3 endpoint information for your application.

9.3. Creating an Object Bucket Claim using the OpenShift Web Console

You can create an Object Bucket Claim (OBC) using the OpenShift Web Console.

Prerequisites

  • Administrative access to the OpenShift Web Console.
  • In order for your applications to communicate with the OBC, you need to use the configmap and secret. For more information about this, see Section 9.1, “Dynamic Object Bucket Claim”.

Procedure

  1. Log into the OpenShift Web Console.
  2. On the left navigation bar, click StorageObject Bucket ClaimsCreate Object Bucket Claim.

    1. Enter a name for your object bucket claim and select the appropriate storage class based on your deployment, internal or external, from the dropdown menu:

      Internal mode

      The following storage classes, which were created after deployment, are available for use:

      • ocs-storagecluster-ceph-rgw uses the Ceph Object Gateway (RGW)
      • openshift-storage.noobaa.io uses the Multicloud Object Gateway (MCG)
      External mode

      The following storage classes, which were created after deployment, are available for use:

      • ocs-external-storagecluster-ceph-rgw uses the RGW
      • openshift-storage.noobaa.io uses the MCG

        Note

        The RGW OBC storage class is only available with fresh installations of OpenShift Data Foundation version 4.5. It does not apply to clusters upgraded from previous OpenShift Data Foundation releases.

    2. Click Create.

      Once you create the OBC, you are redirected to its detail page.

9.4. Attaching an Object Bucket Claim to a deployment

Once created, Object Bucket Claims (OBCs) can be attached to specific deployments.

Prerequisites

  • Administrative access to the OpenShift Web Console.

Procedure

  1. On the left navigation bar, click StorageObject Bucket Claims.
  2. Click the Action menu (⋮) next to the OBC you created.

    1. From the drop-down menu, select Attach to Deployment.
    2. Select the desired deployment from the Deployment Name list, then click Attach.

9.5. Viewing object buckets using the OpenShift Web Console

You can view the details of object buckets created for Object Bucket Claims (OBCs) using the OpenShift Web Console.

Prerequisites

  • Administrative access to the OpenShift Web Console.

Procedure

  1. Log into the OpenShift Web Console.
  2. On the left navigation bar, click StorageObject Buckets.

    Optonal: You can also navigate to the details page of a specific OBC, and click the Resource link to view the object buckets for that OBC.

  3. Select the object bucket of which you want to see the details. Once selected you are navigated to the Object Bucket Details page.

9.6. Deleting Object Bucket Claims

Prerequisites

  • Administrative access to the OpenShift Web Console.

Procedure

  1. On the left navigation bar, click StorageObject Bucket Claims.
  2. Click the Action menu (⋮) next to the Object Bucket Claim (OBC) you want to delete.

    1. Select Delete Object Bucket Claim.
    2. Click Delete.