Incorporating packages
IBM Cloud® Functions is deprecated. Existing Functions entities such as actions, triggers, or sequences will continue to run, but as of 28 December 2023, you can’t create new Functions entities. Existing Functions entities are supported until October 2024. Any Functions entities that still exist on that date will be deleted. For more information, see Deprecation overview.
Packages are bundled sets of related actions and feeds. Each package is designed for specific interaction with services and event providers. Some packages are installed already with IBM Cloud® Functions for you to use, but you can also install others.
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.
-
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
-
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
, andport
. These parameters must be specified for the actions and feeds to be meaningful. -
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.
-
Bind to the
/whisk.system/samples
package and set a defaultplace
parameter value.ibmcloud fn package bind /whisk.system/samples valhallaSamples --param place Valhalla
Example output
ok: created binding valhallaSamples
-
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 thevalhallaSamples
package binding. -
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 thevalhallaSamples
package binding. -
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 thevalhallaSamples
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
ormanifest.yml
file for your app and store it in the root directory. Themanifest.yaml
file specifies the overall structure of the package, including any metadata that must be included with theibmcloud fn deploy
command. To learn more aboutmanifest.yaml
files, see thewskdeploy
documentation.
To add a package:
-
Clone the package repo.
git clone https://github.com/ORG_NAME/REPOSITORY_NAME
-
Navigate to the directory that contains the
manifest.yaml
file.cd <filepath>/<package_name>
-
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
IBM Cloud Object Storage package example
To see an example of how to install a package, check out the IBM Cloud Object Storage package. IBM Cloud® Object Storage is a service that allows users to store all types of files, such as images, videos, music, and text. To interact with the files, a Cloud-based datastore of key-value pairs is stored in a bucket. So, to use the IBM Cloud Object Storage package, you must first create an IBM Cloud Object Storage service instance, and then create a bucket. The bucket is used as an environment variable that is required to install this package.
After you create the service instance and bucket, you can install the package by using the following commands:
-
Clone the package repo.
git clone https://github.com/ibm-functions/package-cloud-object-storage.git
-
Navigate to the package directory that contains the
manifest.yaml
. In this example, the Node.js runtime version of the IBM Cloud Object Storage package is used.cd package-cloud-object-storage/runtimes/nodejs
-
Deploy the package, using your bucket as an environment variable. You can give the package a custom name by using the
PACKAGE_NAME
environment variable.PACKAGE_NAME=<custom_package_name> BUCKET=<bucket_name> ibmcloud fn deploy