Creating actions

Creating actions from the CLI

1. Create an action by running the ibmcloud fn action create command.

   ibmcloud fn action create <action_name> <file> --kind <runtime>
   

   Example

   ibmcloud fn action create hello hello.js --kind nodejs:10
   

   Example output

   ok: created action hello
   

2. Verify that the action is in your actions list.

   ibmcloud fn action list
   

   Example output

   actions
   hello       private
   

Tips:

• To save on cost, you can set limits.

  • To set a limit for memory usage, include --memory <value> with your create command, where the value is in megabytes.
  • To set a timeout, include --timeout <value> with your create command, where the value is in milliseconds.

• If you packaged your code as a Docker image, include --docker <docker_hub_username>/<docker_hub_image>:<tag> with your create command instead of the local path to your app and the --kind flag. Manage your images well by not using the latest tag whenever possible. When the latest tag is used, the image with that tag is used, which might not always be the most recently created image.

  ibmcloud fn action create hello --docker <docker_hub_username>/<docker_hub_image>:<tag>
  

ibmcloud fn action create hello --docker <docker_hub_username>/<docker_hub_image>:<tag> <app_file>

Creating actions from the console

1. From the IBM Cloud Functions Create page, click Create Action.

   1. Specify a name for your action. Action names must be unique within namespaces.
   2. Specify a package for your action. Packages group actions and feeds together. You can select an existing package or create a new one.
   3. Specify a runtime for your action. Java, .Net, and Docker actions can be created from the CLI only. You can change the runtime for your action after you create it.
   4. Click Create.

2. Paste in your code. Note that code field toggles between Edit and View modes. You can test your code by clicking Invoke.

From the Actions page, you can add parameters, change the runtime, create endpoints, and more.

Creating actions from binaries

You can create and deploy an executable that runs inside the standard Docker action SDK as an action. By creating this type of action, you can develop by using Rust or even C and C++, so that you can use the right language for the task at hand while you build complex serverless applications. These types of actions can also be created as web actions.

The executable must conform to the following conventions:

• The program can accept only a single command-line argument as input. The argument is a JSON object that is encoded as a string. The object represents the input argument to the function.

• The program must return a JSON object as a JSON formatted string, sent to stdout as the final log line before the program completes.

• The program can also log to stdout and stderr.

• The program must be called exec and should be self-contained or all dependencies must be packaged with it.

To create your action from an executable, use the --native argument as shorthand for --docker openwhisk/dockerskeleton when running the create action command.

1. When you create a Docker image, an executable is created inside the container at /action/exec. Copy the /action/exec file to your local file system.
2. Create a Docker action that receives the executable as initialization data. Compress your app file and deploy it. The --native argument replaces the --docker openwhisk/dockerskeleton argument in the action create command.

Example

ibmcloud fn action create <action_name> exec.zip --native

For more information about creating actions with Docker images, see Preparing apps in Docker images.

Updating code or runtimes in actions

You can update the code in your app or to migrate to a newer version of a runtime. For example, because Node.js version 8 is in maintenance mode, you might want to switch the runtime to Node.js 10. You can update your actions from the CLI or from the console.

When you migrate to a new runtime version, you might need to change the code in your app to comply with the new runtime version. Usually, the runtime versions are compatible.

When an action is using a disabled runtime, the action can be only read or deleted; no update is possible. In this case, you can view the original action code from the console, copy it, and create a new action with the copied code.

From the CLI, you can get the action code by using the ibmcloud fn action get <action name> --save command and use the saved action file for action create by using the new runtime.

Binding parameters to actions

You can bind parameters to actions to set default parameters. Bound parameters serve as the default parameters for actions unless parameters are supplied at invocation.

Before you begin, create the action.

To bind the parameters:

1. Update an action and bind the default parameters to it.

   ibmcloud fn action update <action_name> --param <parameter_name> <parameter_value>
   

   Example

   ibmcloud fn action update MyApp --param name World
   

   Example output

   ok: updated action MyApp
   

   If you modify your non-service credential parameters, running an action update command with new parameters removes any parameters that currently exist but are not specified in the action update command. For example, if you run action update -p key1 new-value -p key2 new-value but omit any other parameters that were set, those parameters no longer exist after the action is updated. Any services that were bound to the action are also removed. If you bound a service, you must bind the services to your action again.

2. Verify that the parameters were bound to the action.

   ibmcloud fn action get MyApp parameters
   

   Example output

   ok: got action MyApp, displaying field parameters
   
   [
       {
           "key": "name",
           "value": "World"
       }
   ]
   

Optional: To clear the parameters that were previously bound, update the action without including any parameters.

ibmcloud fn action update <action_name> <app_file>

Packaging actions

In Cloud Functions, you can use packages to bundle together a set of related actions and feeds, and share them with others. Packages also allow parameters to be shared across all entities in the package.

A package can include actions and feeds.

• An action is a piece of code that runs on Cloud Functions. For example, the IBM Cloudant package includes actions to read and write records to an IBM Cloudant database.
• A feed is used to configure an external event source to fire trigger events. For example, the Alarm package includes a feed that can fire a trigger at a specified frequency.

1. Create a package.

   ibmcloud fn package create <package_name>
   

2. Get a summary of the package. Notice that the package is empty.

   ibmcloud fn package get --summary <package_name>
   

   Example output

   package /<namespace>/<package_name>
   

3. Create an action and include it in the package. Creating an action in a package requires that you prefix the action name with a package name. Package nesting is not allowed. A package can contain only actions and can't contain another package.

   ibmcloud fn action create <package_name>/<action_name> <app_file>
   

4. Get a summary of the package.

   ibmcloud fn package get --summary <package_name>
   

   Example output

   package /<namespace>/<package_name>
   action /<namespace>/<package_name>/<action_name>
   

Binding parameters to packages

You can set default parameters for all the entities in a package by setting package-level parameters that are inherited by all actions in the package.

Bound parameters serve as the default parameters for actions in the package unless:

• The action itself has a default parameter.
• The action has a parameter that is supplied at invocation time.

Before you begin, create a package that includes at least one action.

1. Update a package and bind the default parameter to it.

   ibmcloud fn package update <package_name> --param <parameter_name> <parameter_value>
   

   Example

   ibmcloud fn package update MyApp --param name World
   

   Example output

   ok: updated package MyApp
   

   If you modify your non-service credential parameters, running an package update command with new parameters removes any parameters that currently exist, but are not specified in the package update command. For example, if you run package update -p key1 new-value -p key2 new-value but omit any other parameters that were set, those parameters no longer exist after the package is updated. Any services that were bound to the package are also removed, so after you update other parameters you must bind services to your package again.

2. Verify that the parameters were bound to the package.

   ibmcloud fn package get MyApp parameters
   

   Example output

   ok: got package MyApp, displaying field parameters
   
   [
       {
           "key": "name",
           "value": "World"
       }
   ]
   

3. Verify that the parameters were inherited by the package.

   ibmcloud fn package get MyApp/MyAction parameters
   

   Example output

   ok: got package MyApp/MyAction, displaying field parameters
   
   [
       {
           "key": "name",
           "value": "World"
       }
   ]
   

Sharing packages of actions

After the actions and feeds that comprise a package are debugged and tested, the package can be shared with all Cloud Functions users. Sharing the package makes it possible for the users to bind the package, invoke actions in the package, and author Cloud Functions rules and sequence actions. Actions and feeds within a shared package are public. If the package is private, then all its contents are also private.

1. Run the ibmcloud fn package update command to share the package with all users.

   ibmcloud fn package update <package_name> --shared yes
   

2. Use the ibmcloud fn package get command to display the publish property of the package to verify that it is now true.

   ibmcloud fn package get <package_name> publish
   

   Example output

   ok: got package demo, displaying field publish
   true
   

3. Get a description of the package to provide others with the fully qualified name of the package so that they can bind it or invoke actions in it. The fully qualified name includes the namespace.

   ibmcloud fn package get --summary <package_name>
   

   Example output

   package /<namespace>/<package_name>
   action /<namespace>/<package_name>/<action_name>
   

Environment variables for actions

The action environment contains several environment variables that are specific to the running action. The properties are accessible in the system environment for all supported runtimes. These properties allow actions to programmatically work with assets through the REST API or set an internal alarm when the action is about to use up its allotted time budget.

def main(dict):
    import os
    __OW_ACTION_NAME = os.environ.get('__OW_ACTION_NAME')
    result = {'__OW_ACTION_NAME':__OW_ACTION_NAME}
    return result

"response": {
        "status": "success",
        "statusCode": 0,
        "success": true,
        "result": {
                "__OW_ACTION_NAME": "/<namespace>/<package_name>/<action_name>"
            }

Versioning your actions

Versioning your actions allows you to track any code modifications that you might make to your actions and to switch between different versions of the code.

ibmcloud fn rule update myRule myTrigger myAction_1.0.1