Object Storage

Assigning the Notifications Manager role with the console

1. Navigate to the Grant a Service Authorization page in the IAM dashboard.
2. From Source service, select Functions. Then, from Source service instance, select a Cloud Functions namespace. Note: Only IAM-enabled namespaces are supported.
3. In Target service, select Cloud Object Storage, then from Target service instance, select your IBM Cloud Object Storage instance.
4. Assign the Notifications Manager role and click Authorize.

Assigning the Notifications Manager role with the CLI

Copy the following command to assign the Notifications Manager role to your Cloud Functions namespace. Replace the source_service_instance_name variable with the name of your Cloud Functions namespace. Replace the target_service_instance name variable with the name of your IBM Cloud Object Storage instance.

ibmcloud iam authorization-policy-create functions cloud-object-storage "Notifications Manager" --source-service-instance-name <source_service_instance_name> --target-service-instance-name <target_service_instance_name>

Verify the Notifications Manager role has been set.

ibmcloud iam authorization-policies

Creating a trigger with the console

1. Navigate to the Cloud Functions Triggers page.
2. Specify an IAM-enabled namespace to contain your entities. Note: Your namespace must be in the same region as your bucket.
3. Click Create.
4. On the Connect Trigger page, click Cloud Object Storage.
5. On the New Trigger Configuration page, give your trigger a name.
6. From COS Instance, select your IBM Cloud Object Storage instance.
7. From Bucket, select your IBM Cloud Object Storage bucket.
8. Select the Object operations that activates the trigger. Both Write and Delete are selected by default.
9. (Optional) Enter an Object prefix or Object suffix or both to activate the trigger only when specific objects are updated.
10. Click Create to create the trigger.

Creating a trigger with the CLI

Target your IAM-enabled namespace. Note: Your namespace must be in the same region as your bucket.

ibmcloud fn property set --namespace <namespace_name_or_ID>

Create a trigger named cosTrigger. The --param bucket flag is required. Replace the <bucket_name> variable with the name of your bucket. (Optional) You can configure the trigger to fire only on write or delete events by specifying the --param event_types flag. If the <event_type> parameter is not specified, the trigger fires on all write, update, and delete changes to your IBM Cloud Object Storage bucket.

ibmcloud fn trigger create cosTrigger --feed /whisk.system/cos/changes --param bucket <bucket_name> --param event_types <event_type> --param prefix <prefix> --param suffix <suffix> --param endpoint <endpoint>

Verify the trigger was created by running the trigger get command.

ibmcloud fn trigger get cosTrigger

Creating an action with the console

1. Navigate to the Cloud Functions Triggers page.
2. Click the trigger that you created.
3. On the Connected Actions page, click Add.
4. On the Add Action page, select Create New.
5. Specify a name for your action.
6. Select a package for your action.
7. For the Runtime, select Node.js 10.
8. Click Create & Add.
9. On the Connected Actions page, click the action that you created.
10. On the Action page, replace the Hello World example code with the code from your cosChange.js file.
11. Click Save.

Creating an action with the CLI

Create an action called cosChange by using the cosChange.js code.

ibmcloud fn action create cosChange <filepath>/cosChange.js

Create a rule called cosRule to connect the cosChange action to the cosTrigger trigger.

ibmcloud fn rule create cosRule cosTrigger cosChange

Testing with the console

1. Make a change to an object in your IBM Cloud Object Storage bucket. For more information about adding an object to your bucket, see Add some objects to your bucket.
2. Navigate to the Cloud Functions dashboard.
3. Click Activations dashboard.
4. Review the Activations timeline pane for activations of the trigger and action that you created.

Testing with the CLI

1. Start polling for activations by running the activation poll command.

   ibmcloud fn activation poll
   

2. In your IBM Cloud Object Storage dashboard, either modify an existing bucket object or create one. To learn how to add an object to your bucket, see Add some objects to your bucket.

3. For each bucket object change, observe new activations for the cosTrigger trigger and cosChange action.

4. Stop polling by pressing ctrl c.

5. You can see the details of an activation by running the activation get command.

   ibmcloud fn activation get ACTIVATION_ID
   

6. If you are unable to observe new activations, verify that the parameter values are correct by running the trigger get command.

   ibmcloud fn trigger get cosTrigger
   

You can see an example activation in the Data structure of an Object Storage trigger activation section.

IBM Cloud Object Storage trigger entities

The IBM Cloud Object Storage trigger contains the /whisk.system/cos package and supports the following parameters.

IBM Cloud Object Storage trigger parameters

The /whisk.system/cos/changes feed supports the following parameters.

Data structure of an IBM Cloud Object Storage trigger activation

The content of the generated events has the following parameters:

The following sample is an example JSON response of a trigger activation. You can get details of an activation by running ibmcloud fn activation get <activation_id>.

{
    "namespace": "<namespace_ID>",
    "name": "cosTrigger",
    "version": "0.0.1",
    "subject": "ServiceId-65348247-951f-4f22-b2ef-7782597c3ab1",
    "activationId": "78fg525e45964bcdae525e45966bcd6f",
    "start": 1567608038827,
    "end": 0,
    "duration": 0,
    "statusCode": 0,
    "response": {
        "status": "success",
        "statusCode": 0,
        "success": true,
        "result": {
            "bucket": "bucket_name",
            "endpoint": "s3.private.us-east.cloud-object-storage.appdomain.cloud",
            "key": "sample.txt",
            "notification": {
                "bucket_name": "bucket_name",
                "content_type": "application/octet-stream",
                "event_type": "Object:Write",
                "format": "2.0",
                "object_etag": "a2b2d66938b1f023dec6394f12b782b5",
                "object_length": "5",
                "object_name": "sample.txt",
                "request_id": "216c7ddb-218c-4fb7-84d2-293f286b62e6",
                "request_time": "2019-09-04T14:40:35.294Z"
            }
        }
    },
    "logs": [
        "{\"statusCode\":0,\"success\":true,\"activationId\":\"1a80c8449e7d49fb80c8449e7d99fb2a\",\"rule\":\"e8b676ee-1726-4541-8f16-f87902bb3ab31/cosRule\",\"action\":\"e8b676ee-1726-4541-8f16-f87902bb3ab31/cosChange\"}"
    ],
    "annotations": [],
    "publish": false
}

Details and limits for Object Storage triggers

Triggers created with /whisk.system/cos package have the following limitations.

• Trigger ordering is not guaranteed. Trigger firing sequence may not match bucket update sequence.
• The trigger only fires on successful bucket events.
• Automatic trigger disablement - permissions change, COS bucket authentication changes, namespace authentication.
• Namespaces that contain the /whisk.system/cos package cannot be deleted until the package is deleted.
• After the trigger is created, the Notifications Manager role cannot be removed from your Cloud Functions namespace. Removing the role disables the trigger.
• For batch requests, each object change is handled individually and the trigger is fired for each successful change event.
• All characters are permitted in an object key except for ASCII control character NUL.
• Naming limitations for Cloud Functions triggers can be found on the System details and limits page.

Installing with the console

1. In the Cloud Functions console, go to the Create page.
2. Select the namespace in which you want to install the IBM Cloud Object Storage package.
3. Click Install Packages.
4. Click the IBM Cloud Object Storage Package group, then click the IBM Cloud Object Storage Package.
5. In the Available Runtimes section, select either Node.JS or Python. Then, click Install.
6. After the package is installed, you are redirected to the Actions page and can search for your new package, which is named cloud-object-storage.

Installing with the CLI

1. Clone the IBM Cloud Object Storage package repo.

   git clone https://github.com/ibm-functions/package-cloud-object-storage.git
   

2. Navigate to either the runtimes/nodejs or runtimes/python< directory to select a runtime for the actions in the package.

   cd package-cloud-object-storage/runtimes/<nodejs_or_python>
   

3. Deploy the package.

   ibmcloud fn deploy
   

4. Verify that the cloud-object-storage package is added to your package list.

   ibmcloud fn package list
   

Setting an IAM access policy with the console

1. Navigate to the Service IDs tab in the IAM console.
2. Click the service ID that corresponds to your Cloud Functions namespace.
3. On the Manage page, click Access policies.
4. Click Assign access.
5. Click Assign access to resources.
6. From Services, select Cloud Object Storage.
7. From Service instance, select your IBM Cloud Object Storage instance.
8. To limit access to a specific bucket, enter bucket for Resource type and enter your bucket-name for Resource ID.
9. Review the IAM roles and select the appropriate role to assign to your namespace.
10. After you have selected a role, click Save.

Setting an IAM access policy with the CLI

Copy the following command and replace the variables.

ibmcloud iam service-policy-create <service-id-name> --roles <role> --service-name cloud-object-storage</br> --service-instance <resource-instance-id> --region global</br> --resource-type bucket --resource <bucket-name>

• Replace service-id-name with the name of your Cloud Functions namespace.
• Replace role with the IAM role you want to assign to your Cloud Functions namespace.
• (Optional) Include the --resource-type bucket and --resource <bucket-name> flags to limit access to a specific bucket. If you do not include these flags, access is granted at the service level.
• Replace <bucket-name>. with the name of your bucket.

You still need to pass the bucket name and endpoint during action invocation. You can avoid having to pass these values each time by binding them to the cloud-object-storage package or to a specific action in the package. To do this, see Setting default parameters for a package or an action.

Creating service credentials for accessing your IBM Cloud Object Storage instance

If you plan to use the client-get-signed-url action, you must create service credentials. You can then bind service credentials to the cloud-object-storagepackage.

Binding your IBM Cloud Object Storage service credentials to the package or actions.

To use the client-get-signed-url action in the cloud-object-storage package, you must bind your IBM Cloud Object Storage service credentials to the action.

• To bind service credentials to all actions in the package, use the service bind command in the CLI.
• To bind service credentials to individual actions, complete the following steps in the console.

Binding service credentials in the console

1. From the Actions page, click cloud-object-storage package.
2. Next, click the client-get-signed-url action, then click Parameters.
3. Click Add to enter a new parameter. Note that parameters must be entered as key and value pairs.
4. For Parameter Name, enter the key __bx_creds.
5. For Default Value, paste in the service credentials JSON object from the IBM Cloud Object Storage service instance that you created earlier.
6. Repeat the steps for each action that you want to use.

Binding service credentials in the CLI

Bind the credentials from the IBM Cloud Object Storage instance you created to the package. You can include the --keyname flag to bind specific service credentials. For more information about binding services, see Service commands.

ibmcloud fn service bind cloud-object-storage cloud-object-storage --keyname <service_key>

Verify that the package is configured with your IBM Cloud Object Storage service instance credentials.

ibmcloud fn package get <namespace_ID>cloud-object-storage parameters

You still need to pass the bucket and endpoint values during action invocation. Or, you can bind these parameters to the package or an action. To do this, see Setting default parameters for a package or action.

Updating parameters for all actions in a package

ibmcloud fn package update cloud-object-storage 
--param bucket <bucket-name> 
--param endpoint <bucket-endpoint>

Updating parameters to a specific action

ibmcloud fn action update cloud-object-storage/object-write 
--param bucket <bucket-name> 
--param endpoint <bucket_endpoint>

You can also bind parameters to actions by using Parameters in the console. To add parameters in the console, navigate to the Actions page and click one of your actions. Then, click Parameters > Add Parameter. You must add parameters in <key> and <value> pairs.

After you have updated the package or action to include the bucket and endpoint parameters, you must rebind the service with service bind command.

Package parameters for Object Storage

The following package parameters are expected to be bound to the package, and are automatically available for all actions. It is also possible to specify these parameters when you invoke one of the actions.

Action parameters for Object Storage

The following action parameters are specified when you invoke the individual actions. Not all these parameters are supported by every action. Refer to the Available entities table to see which parameters are supported by which action.