Getting started with OpenWhisk Project

Level: Beginner

This is the first tutorial of a series about OpenWhisk Project. The main goal of this series is to go through:

  • the format used to describe project configurations,
  • and the commands provided by the OpenWhisk Project CLI wskp.

It assumes you are familiar with Apache OpenWhisk.

Why OpenWhisk Project?

The Serverless Framework OpenWhisk provider and tools like Apache wskdeploy allow you to install a collection of Apache OpenWhisk entities and related services via a declarative manifest file. OpenWhisk Project follows this trend and tries to go further in terms of

  • simplicity, e.g. by providing meta configuration properties such as web with full transparency,
  • reusability thanks to its module system and
  • third-party extensibility

More specifically, this tool allows you to:

  • generate project from templates,
  • deploy configurations to OpenWhisk and external services (Cloudant, Redis, etc…),
  • safely remove those configurations from OpenWhisk,
  • manage multiple deployment environments,
  • modify project configurations by automatically synchronizing them with local resources and remote resources,
  • and finally extend the configuration format through the use of plugins.

As you can see, there is a lot to cover! The goal of this tutorial is to get started with the CLI and few configuration properties. Most specifically you will learn:

  • how to install the CLI called wskp
  • how to create and deploy a project
  • how to configure node.js actions
  • how to configure sequence actions
  • and how to remove deployed project

Let’s get started.

Prerequisites

This tutorial assumes you have these tools installed on your system (Mac or Linux. Not tested on Windows):

Installing and configuring the CLI

Thinking of a collection of entities as a project is useful in a tool like the OpenWhisk Shell — in fact, an OpenWhisk Project plugin for the OpenWhisk Shell will be available soon. Meanwhile, one way to quickly play with OpenWhisk Project is through wskp.

In a terminal, run:

$ npm install openwhisk-wskp -g

This gives you the shell command wskp, a CLI wrapper around wsk or bx wsk with additional goodies such as deployment commands.

If you already have .wskprops in your home directory, skip the following steps. Otherwise keep reading.

If you prefer to use bx wsk over just wsk, you need to tell wskp by typing this:

$ wskp property set bx true

Finally, create an OpenWhisk namespace for this tutorial:

$ bx login -a api.ng.bluemix.net -o <yourorg>
$ bx iam space-create wskp
$ bx target -s wskp
$ bx wsk property get # create ~/.wskprops

Check .wskprops exists in your home directory.

Creating a project

wskp comes with a stub generator based on Yeoman. Let’s create a new project:

$ mkdir wskp-tutorial && cd wskp-tutorial && wskp yo project

In the current directory you should see the beginning of this directory structure:

|- actions          # actions in the default packages
|- <actioname>
|- packages
|- <packagename>
|- actions
|- <actionname>
openwhisk.yaml # the main project configuration file

OpenWhisk Project works better if you stick to this structure. It’s not strictly required though.

To deploy this project, just type:

$ wskp deploy openwhisk.yaml
ok.

Done! Note that nothing really happened here since openwhisk.yaml is empty. Keep reading.

Creating and deploying a nodejs action

You can again use wskp yo for creating or updating an action:

$ cd actions && mkdir echo && wskp yo action 

This time you need to provide some answers. Just select the default or first choice for all:

? Action name echo
? Action kind nodejs
? Node version default
create index.js

The stub generator only creates the files (in this particular only index.js)and does not modify the configuration file. Open openwhisk.yaml and add the following lines:

actions:
echo: # name of the action
location: ./actions/echo/index.js
inputs:
lines: ["Hello", "World"]

The location points to the source code for the echo action. By default, relative paths are, well …, relative to the enclosing resource, in this case the configuration file path.

The action kind is determined by looking at the location path extension. In that case, '.js' means nodejs:default. Default parameters are specified inside inputs.

Edit index.js :

function main(args) {
return args
}

Deploy by running wskp deploy openwhisk.yaml and invoke echo:

$ wskp action invoke echo -br
{
"msg": "Hello"
}

Configuring sequence actions

Sequence actions are configured inside the actions section. Let’s use the utils/cat action provided by whisk.system to nicely print our greeting message.

Edit openwhisk.yaml:

actions:
echo:
location: ./actions/echo/index.js
inputs:
lines: ["Hello", "World"]
  hello:
sequence: echo, /whisk.system/utils/cat

Then invoke:

$ wskp action invoke hello -br
{
"lines": [
"Hello",
"World"
],
"payload": "Hello\nWorld"
}

A few things to remember when using sequence:

  • unqualified action names (e.g. echo) are resolved using the enclosing package name. See the spec for more details.
  • the order in which actions are written has no impact on deployments. OpenWhisk Project computes which actions need to be deployed first.

Removing actions

This can easily be done with the undeploy command:

$ wskp undeploy openwhisk.yaml
$ wskp list
Entities in namespace: default
packages
actions
triggers
rules

Note that only the entities specified in the configuration are removed. Packages are removed only if no actions are still there after deploying all configured ones.

Be wary when removing actions from the configuration as undeploy won’t work as expected and will leave “zombie actions”. OpenWhisk Project supports “robust” undeploy and I will cover this feature in a subsequent tutorial.

What next?

In this tutorial I barely touched on the capabilities provided by OpenWhisk Project. Stay tuned for Part 2 which will talk about zipping…