Incorporating packages

Overview for packages

Pre-installed packages are automatically registered within Cloud Functions in the /whisk.system namespace. You can use them without completing any installation steps.

Installable packages are packages that are available for you to install, edit, and use based on your needs. Installable packages do not reside within the Cloud Functions system. Instead, installable packages are externally housed in individual GitHub repositories.

You can install these packages or your own directly into your namespace, and can give a package a custom name. Because the package is installed into your own namespace, you can modify the actions and feeds in the package as needed.

Browsing pre-installed packages

Several packages are registered with Cloud Functions already for you. You can get a list of packages in a namespace, list the entities in a package, and get a description of the individual entities in a package.

1. Get a list of packages in the /whisk.system namespace.

   ibmcloud fn package list /whisk.system
   

   Package list output:

   packages
   /whisk.system/cloudant         shared
   /whisk.system/websocket        shared
   /whisk.system/utils            shared
   /whisk.system/samples          shared
   /whisk.system/cos              shared
   /whisk.system/messaging        shared
   /whisk.system/alarms           shared
   

2. Get a list of entities in a package.

   ibmcloud fn package get --summary <package_name>
   

   Example

   ibmcloud fn package get --summary /whisk.system/cloudant
   

   Example output

   package /whisk.system/cloudant: Cloudant database service
       (parameters: *apihost, *bluemixServiceName, dbname, host, iamApiKey, iamUrl, overwrite, password, username)
   action /whisk.system/cloudant/delete-attachment: Delete document attachment from database
       (parameters: attachmentname, dbname, docid, docrev, params)
   action /whisk.system/cloudant/update-attachment: Update document attachment in database
       (parameters: attachment, attachmentname, contenttype, dbname, docid, docrev, params)
   action /whisk.system/cloudant/read-attachment: Read document attachment from database
       (parameters: attachmentname, dbname, docid, params)
   action /whisk.system/cloudant/create-attachment: Create document attachment in database
       (parameters: attachment, attachmentname, contenttype, dbname, docid, docrev, params)
   action /whisk.system/cloudant/read-changes-feed: Read Cloudant database changes feed (non-continuous)
       (parameters: dbname, params)
   ...
   ...
   feed   /whisk.system/cloudant/changes: Database change feed
       (parameters: dbname, filter, iamApiKey, iamUrl, query_params)
   

   This output shows that the IBM Cloudant package includes several actions and a feed.

   The IBM Cloudant package also defines the parameters username, password, host, and port. These parameters must be specified for the actions and feeds to be meaningful.

3. Get a description of an action or feed to see the parameters that are required.

   Example

   ibmcloud fn action get --summary /whisk.system/cloudant/read
   

   Example output

   action /whisk.system/cloudant/read: Read document from database
       (parameters: *apihost, *bluemixServiceName, dbname, *id, params)
   

   This output shows that the IBM Cloudant read action requires three parameters, including the database and document ID to retrieve.

Binding parameters to pre-installed packages

Although you can use the entities in a package directly, you might find yourself passing the same parameters to the action every time. You can simplify the process by binding to a package and specifying default parameters, which are inherited by the actions in the package.

For example, in the /whisk.system/cloudant package, you can set default username, password, and dbname values in a package binding and these values are automatically passed to any actions in the package.

In the following example, you bind to the /whisk.system/samples package.

1. Bind to the /whisk.system/samples package and set a default place parameter value.

   ibmcloud fn package bind /whisk.system/samples valhallaSamples --param place Valhalla
   

   Example output

   ok: created binding valhallaSamples
   

2. Get a description of the package binding.

   ibmcloud fn package get --summary valhallaSamples
   

   Example output

   package /<namespace_ID>/valhallaSamples
   action /<namespace_ID>/valhallaSamples/greeting: Returns a friendly greeting
   action /<namespace_ID>/valhallaSamples/wordCount: Count words in a string
   action /<namespace_ID>/valhallaSamples/helloWorld: Demonstrates logging facilities
   action /<namespace_ID>/valhallaSamples/curl: Curl a host url
   

   Notice that all the actions in the /whisk.system/samples package are available in the valhallaSamples package binding.

3. Invoke an action in the package binding.

   ibmcloud fn action invoke --blocking --result valhallaSamples/greeting --param name Odin
   

   Example output

   {
       "payload": "Hello, Odin from Valhalla!"
   }
   

   Notice from the result that the action inherits the place parameter that you set when you created the valhallaSamples package binding.

4. Invoke an action and overwrite the default parameter value.

   ibmcloud fn action invoke --blocking --result valhallaSamples/greeting --param name Odin --param place Asgard
   

   Example output

   {
       "payload": "Hello, Odin from Asgard!"
   }
   

   Notice that the place parameter value that is specified with the action invocation overwrites the default value set in the valhallaSamples package binding.

Adding your own packages

You can create a package of local code or a clone of any GitHub repository.

Before you begin

• Install the Cloud Functions plug-in for the IBM Cloud CLI.
• Create a manifest.yaml or manifest.yml file for your app and store it in the root directory. The manifest.yaml file specifies the overall structure of the package, including any metadata that must be included with the ibmcloud fn deploy command. To learn more about manifest.yaml files, see the wskdeploy documentation.

To add a package:

1. Clone the package repo.

   git clone https://github.com/ORG_NAME/REPOSITORY_NAME
   

2. Navigate to the directory that contains the manifest.yaml file.

   cd <filepath>/<package_name>
   

3. Deploy the package.

   ibmcloud fn deploy -m manifest.yaml
   

   Some packages require certain environment variables to enable the package to function properly. If so, include the environment variables with the deploy command. For example, you can choose a name for the package and specify it with the PACKAGE_NAME variable.

   PACKAGE_NAME=CUSTOM_PACKAGE_NAME VARIABLE_NAME=VARIABLE_VALUE ibmcloud fn deploy -m manifest.yaml