Documentation

There are many resources for learning about OpenWhisk; this page attempts to organize, describe, index and link to the essential information, wherever it resides, to help users in getting started. In general, much of the best information is in the actual project repositories and we encourage you to seek detailed and in-depth information there.

OpenWhisk documentation is organized by the following roles:
  • Developers: users developing functions/actions, creating packages, feeds, and feed provider services using project APIs, clients and tooling.
  • Contributors: developers designing and coding backend architectural components and tooling that comprise the OpenWhisk platform and its project ecosystem.
  • Operators: users who deploy, configure, and host the Apache OpenWhisk Function-as-a-Service platform for development, testing and/or production.

OpenWhisk Programming Model

OpenWhisk Programming Model

The OpenWhisk programming model...

Is Event-driven

In the OpenWhisk programming model, Events drive the Serverless execution of functional code called Actions. Events can come from any Event Source or Feed service including:

  • Datastores, Message Queues, Mobile and Web Applications, Sensors, Chatbots, Scheduled tasks (via Alarms), etc.
Supports any functional programming language

The OpenWhisk platform supports Action code written for any of its ever-growing, built-in language runtimes:

  • Go - OpenWhisk runtime for Go lang
  • Java - OpenWhisk runtime for Java 8
  • JavaScript - OpenWhisk runtime for Node.js v6 and v8
  • PHP - OpenWhisk runtime for PHP 7.2 and 7.1
  • Python - OpenWhisk runtime for Python 2.7 and 3
  • Ruby - OpenWhisk runtime for Ruby 2.5
  • Swift - OpenWhisk runtime for Swift 3 and 4

If you need languages or libraries the current "out-of-the-box" runtimes do not support, you can create and customize your own executable that run "black box" Docker Actions using the Docker SDK which are run on the Docker Runtime.

Actions

This section will answer some of the essential questions about OpenWhisk Actions relative to the to the programming model. If you want to more detailed information, please read the project documentation on OpenWhisk Actions.

OpenWhisk Programming Model: Actions

What is an Action? Actions are stateless functions (code snippets) that run on the OpenWhisk platform. Actions encapsulate application logic to be executed in response to events. Actions can be invoked manually by the OpenWhisk REST API, OpenWhisk CLI, simple and user-created APIs or automated via Triggers which we will discuss later.

Does the function's language matter? No, OpenWhisk is agnostic to a function's implementation language. This means that OpenWhisk operations used to create, invoke and manage Actions are the same regardless of implementation choice. You decide what languages are best for you!

What if your preferred language/runtime is not supported by OpenWhisk? If your favorite language is not listed above, you may find the Docker action or native binary path more suitable. The OpenWhisk platform is extensible and you can add new languages or runtimes (with custom packages and third-party dependencies) following the guide described here. Please reach out to other whiskers on dev mailing list at dev@openwhisk.incubator.apache.org. once you have followed the guide on creating a new language/runtimes. Here are some examples of runtimes added by community:

Composing Sequences of Actions

Multiple actions, even implemented in different languages, may be composed together to create a longer processing pipeline called a sequence. Sequence can be treated as a single action in terms of it creation and invocation.

Learn more

Listed below are some additional topics related to developing OpenWhisk Actions:

  • Namespacing - the same Namespace and Naming rules as any OpenWhisk Entity that are part of the OpenWhisk programming model.
  • System Limits - Learn about some of the (operator configurable) System Limits that are imposed on OpenWhisk Actions.
  • Web Actions - Find out how to annotate OpenWhisk Actions to quickly enable you to build web based applications.
  • Action Processing - Find out what happens "behind the scenes" when you invoke an Action in Apache OpenWhisk.

Triggers and Rules

This section will describe how to automate OpenWhisk Actions in response to events using OpenWhisk Triggers. If you want to more detailed information, please read the project documentation on OpenWhisk Triggers and Rules.

OpenWhisk Programming Model: Actions

What is a trigger? Triggers are named channels for classes or kinds of events sent from Event Sources.

What is a Rule? Rules are used to associate one trigger with one action. After this kind of association is created, each time a trigger event is fired, the action is invoked.

What are Event Sources? These are services that generate events that often indicate changes in data or carry data themselves. Some examples of common Event Sources include:

  • Messages arriving on Message Queues
  • Changes in Databases
  • Changes in Document Stores
  • Website or Web Application interactions
  • Service APIs being invoked
  • IoT Frameworks forwarding device sensor data
  • etc.

Why do I need to connect actions to event sources? OpenWhisk is based on an event-driven architecture where most Actions are executed as events happen. The Trigger itself is "fired" with a dictionary of key-value pairs (i.e., the parameters) coming from the Event Source and allows the configuration of optional default values thus helping assure the data is compatible with any associated Actions. Rules allow for the same Trigger to be associated with multiple Actions, as well as allow for specific automation to be enabled or disabled dynamically without destroying the Trigger definition.

Developers

The OpenWhisk project and programming model supports different kinds of developers that may wish to use different runtimes and tooling. This section contains the information and resources you need to become a Serverless application developer using the Apache OpenWhisk platform.

Pre-requisites

You will need to have access to a running instance of the OpenWhisk platform to develop against.

Running OpenWhisk locally

Developers can select to install and configure their own instancefrom among any of the options listed here: OpenWhisk Deployment Options.

For local, "light weight" development, we recommend using Kubernetes enabled within Docker (i.e., Docker for Mac or Windows, Minikube for Linux).

Using OpenWhisk on a Cloud Provider

Again, we encourage developers to leverage Cloud-based Kubernetes services to deploy OpenWhisk.

Another option would be to use Serverless provider that already hosts Apache OpenWhisk and supports its Command Line Interface (CLI) such as IBM Cloud Functions.

Using OpenWhisk

By default, local deployments of Apache Openwhisk create a guest account and endpoint for developers to use. However, if you are running on an instance of OpenWhisk administered by a Cloud provider, you will need to obtain an account and endpoint information from them.

Default Guest Account

OpenWhisk Deployments create a guest account configured with the authentication key available at:

Default API Host

Deployments of Apache Openwhisk set the default API host endpoint, used with the Command Line Interface (CLI) and the Whisk Deploy utility, to:

  • 192.168.33.13.

However, when running under a Kubernetes deployment installed using Helm, the endpoint's address and port are set in your "mycluster.yaml" deployment file. See the Deploy With Helm instructions for details.

Getting Started

As a developer, you need the right tools for the job. This section describes the various tools that you can use to work with OpenWhisk which include:

OpenWhisk CLI (wsk)

OpenWhisk offers the wsk Command Line Interface (CLI) to easily create, run, and manage OpenWhisk entities.

For detailed information on setting up and configuring the OpenWhisk CLI, go to the OpenWhisk CLI documentation page in GitHub.

Installing

You have a couple of choices on how to install the Whisk CLI depending on your target Operating System:

Using Homebrew (Linux or Mac)

To easily install the OpenWhisk CLI (wsk) you can use Homebrew for Mac or Homebrew for Linux.

$ brew update
$ brew install wsk

Then you can invoke the OpenWhisk CLI by just typing wsk from the command line.

Download and install the wsk CLI from (Linux, Mac or Windows):
  • Download the OpenWhisk CLI for your Operating System as a standalone compressed TAR Archive file (.tgz) or ZIP file (.zip) from the project Releases page in GitHub:

    where you may select to download the CLI from the "latest" release or from one of the versioned releases.

  • Uncompress the wsk executable from the tar.gz file.

  • Simplify access to the wsk executable by moving or copying the binary file to a path listed in your PATH environment variable. This will enable you to invoke the OpenWhisk CLI by just typing 'wsk' on the command line from anywhere.

    For example:

Verify Installation

You can verify your installation by invoking the Whisk CLI's help command:

$ wsk --help
Configuring

Before using the OpenWhisk CLI, you must first configure it to point to the OpenWhisk platform you want the utility to use (i.e., its API endpoint) and also provide it with your associated authentication credentials.

Setting the API Host and Authentication Key

You can configure wsk CLI to use your OpenWhisk credentials in few different ways. See the Setting up the OpenWhisk CLI page for a full set of configuration options. The instructions below walk you throguh the simplest possible configuration using only an API_HOST and AUTH_KEY CLI properties using a default guest namespace.

wsk property setup

Run the following command to set whisk API HOST and authorization key to create the configuration file:

$ wsk property set --apihost API_HOST --auth AUTH_KEY --namespace guest

The OpenWhisk CLI stores the properties set in ~/.wskprops by default. The location of this file can be altered by setting the WSK_CONFIG_FILE environment variable. For example:

$ export WSK_CONFIG_FILE=your-config-file
Verify properties

Verify your properties were properly set by using the wsk property get command:

$ wsk property get
Test configuration

A simple "read" command will cause the CLI to authenticate to the OpenWhisk your configured API host endpoint and credentials. is incorrect.

Verify host connection

Verify your host connection and credentials using the wsk list command with the -v (verbose) flag enabled.

$ wsk list -v

You should see the full HTTP request and response headers the CLI sends/receives to/from the host along with the response codes.

Whisk Deploy (wskdeploy)

Whisk Deploy is a utility, named wskdeploy, to help deploy and manage all your OpenWhisk Packages, Actions, Triggers, Rules and APIs using a single command using an application manifest.

Installing

Download and Install the wskdeploy utility for Linux, Mac or Windows.

Download the Whisk Deploy utility
  • Download the Whisk Deploy utility for your Operating System as a standalone compressed TAR Archive file (.tgz) or ZIP file (.zip) from the project Releases page in GitHub:

    where you may select to download the utility from the "latest" release or from one of the versioned releases.

  • Uncompress the wskdeploy executable from the tar.gz file.

  • Simplify access to the wsk executable by moving or copying the binary file to a path listed in your PATH environment variable. This will enable you to invoke Whisk Deploy utility by just typing 'wskdeploy' on the command line from anywhere.

    Follow the instructions as shown for the Whisk CLI to learn how to do this for your development platform.

Verify Installation

Start by verifying the utility can display the command line help:

$ wskdeploy --help
Configure

Before you proceed with the deployment, please make sure you have setup the API_HOST and AUTH_KEY CLI properties with a default namespace as described in the Whisk CLI configuration section above.

Test configuration
  • Create and Deploy a simple OpenWhisk Manifest File

    Please refer to the Whisk Deploy Programming Guide for all manifest file grammar and syntax. This programming guide has step-by-step instructions for deploying OpenWhisk applications using wskdeploy.

    Here is a simple YAML manifest example that has an in-line function written in JavaScript that outputs "Hello World":

    packages:
        default:
            actions:
                helloJS:
                    code: |
                        function main() {
                            return {payload: 'Hello world'};
                        }
                    runtime: nodejs:10
  • Save the YAML scripts as an OpenWhisk Manifest file called manifest.yaml
  • Deploy the OpenWhisk Manifest file:

    $ wskdeploy -m manifest.yaml
Additional Resources
Medium Blogs (tagged wskdeploy)

OpenWhisk REST API

After your OpenWhisk environment is enabled, you can use OpenWhisk with your web apps or mobile apps with REST API calls. For more details about the APIs for actions, activations, packages, rules, and triggers, see the OpenWhisk API documentation.

OpenWhisk Clients

OpenWhisk provides a wrapper around the OpenWhisk APIs in multiple different languages. These can be imported and used directly in your favorite Integrated Development Environment (IDE):

Creating and Invoking Actions

In this section, we will show you how to create and invoke your first "Hello World" Action using both the OpenWhisk CLI and the Whisk Deploy utility.

All the canonical examples will be provided using JavaScript using the NodeJS runtime; however, we also provide the same examples for all other supported runtime languages (e.g., Java, Python, Swift, etc.) where possible.

Select a language

Select from the language example you would like to follow from the list below.

using NodeJS (JavaScript)

Creating and Invoking NodeJS actions

Let's look at how to write a sample hello world action in NodeJS. You can visit Creating and Invoking NodeJS actions page for further details.

Note: We will be using wsk CLI in this section. If you don't have it installed and configured, please refer to the section OpenWhisk CLI (wsk).

  1. Create a file named hello.js:
    1
    2
    3
    function main() {
        return {payload: 'Hello world'};
    }
    
  2. Create an action called helloJS using hello.js:
    $ wsk action create helloJS hello.js
    ok: created action helloJS
  3. Invoke the helloJS action as a blocking activation:
    $ wsk action invoke helloJS --blocking
    {
    "result": {
    "payload": "Hello world"
    },
    "status": "success",
    "success": true
    }
  4. Deploy using wskdeploy:

    Note: We will be using wskdeploy in this section. If you don't have the binary, please refer to the section on Whisk Deploy to download it.

    1. Create manifest.yaml with the following YAML content:
      1
      2
      3
      4
      5
      packages:
          default:
              actions:
                  helloJS:
                      function: hello.js
      
      Or

      1
      2
      3
      4
      5
      6
      7
      8
      9
      packages:
          default:
              actions:
                  helloJS:
                      code: |
                          function main() {
                              return {payload: 'Hello world'};
                          }
                      runtime: nodejs:10
      
    2. Run deployment with wskdeploy:
      $ wskdeploy -m manifest.yaml
OpenWhisk Runtime for NodeJS

OpenWhisk supports Node.js 10, Node.js 8, and Node.js 6 runtimes where Node.js 6 being default pick by wsk CLI and Whisk Deploy. If you wish to learn more about NodeJS runtime along with the libraries that are supported or "built-in" by default, please visit NodeJS Runtime GitHub Repository.

Additional Resources
Medium Blogs (tagged nodejs)
using Go

Creating And Invoking Go actions

Let's look at how to write a sample hello world action in Go. You can visit Creating and Invoking Go actions page for further details.

Note: We will be using wsk CLI in this section. If you don't have it installed and configured, please refer to the section OpenWhisk CLI (wsk).

  1. Create a file named hello.go:
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    package main
    
    import "fmt"
    
    // Main function for the action
    func Main(obj map[string]interface{}) map[string]interface{} {
    	name, ok := obj["name"].(string)
    	if !ok {
    		name = "stranger"
    	}
    	fmt.Printf("name=%s\n", name)
    	msg := make(map[string]interface{})
    	msg["msg"] = "Hello, " + name + "!"
    	return msg
    }
    
  2. Create an action helloGo:
    $ wsk action create helloGo hello.go
  3. Invoke an action helloGo:
    $ wsk action invoke helloGo -r -p name gopher
    {
    "msg": "Hello, gopher!"
    }
  4. Deploy using wskdeploy:

    Note: We will be using wskdeploy in this section. If you don't have the binary, please refer to the section on Whisk Deploy to download it.

    1. Create a directory called actions with hello.go from step 1 above.
    2. Create manifest.yaml with the following YAML content:
      1
      2
      3
      4
      5
      packages:
          default:
              actions:
                  helloGo:
                      function: hello.go
      
    3. Run deployment with wskdeploy:
      $ wskdeploy -m manifest.yaml
OpenWhisk Runtime for Go

If you wish to learn more about Go runtime along with the libraries that are supported or "built-in" by default, please visit Go Runtime GitHub Repository.

Additional Resources
using Python

Creating And Invoking Python actions

Let's look at how to write a sample hello world action in Python. You can visit Creating and Invoking Python actions page for further details.

Note: We will be using wsk CLI in this section. If you don't have it installed and configured, please refer to the section OpenWhisk CLI (wsk).

  1. Create a file named hello.py:
    1
    2
    3
    4
    5
    6
    7
    8
    def main(dict):
        if 'name' in dict:
            name = dict['name']
        else:
            name = "stranger"
        greeting = "Hello " + name + "!"
        print(greeting)
        return {"greeting": greeting}
    
  2. Create an action called helloPy using hello.py:
    $ wsk action create helloPy hello.py
    ok: created action helloPy
  3. Invoke the helloPy action using command-line parameters:
    $ wsk action invoke helloPy --blocking --param name World
    {
    "greeting": "Hello World!"
    }
  4. Deploy using wskdeploy:

    Note: We will be using wskdeploy in this section. If you don't have the binary, please refer to the section on Whisk Deploy to download it.

    1. Create manifest.yaml with the following YAML content:
      1
      2
      3
      4
      5
      packages:
          default:
              actions:
                  helloPy:
                      function: hello.py
      
      Or

      1
      2
      3
      4
      5
      6
      7
      8
      9
      10
      11
      12
      13
      14
      15
      packages:
          default:
              actions:
                  helloPy:
                      code: |
                          import sys
                          def main(dict):
                              if 'name' in dict:
                                  name = dict['name']
                              else:
                                  name = "stranger"
                              greeting = "Hello " + name + "!"
                              print(greeting)
                              return {"greeting": greeting}
                      runtime: python:2
      
    2. Run deployment with wskdeploy:
      $ wskdeploy -m manifest.yaml
OpenWhisk Runtime for Python

OpenWhisk supports Python 2 and Python 3 runtimes where Python 2 being default pick by wsk CLI and Whisk Deploy. If you wish to learn more about Python runtime along with the libraries that are supported or "built-in" by default, please visit Python Runtime GitHub Repository.

Additional Resources
Medium Blogs (tagged python)
using Java

Creating and Invoking Java actions

Let's look at how to write a sample hello world action in Java. You can visit Creating and Invoking Java actions page for further details.

Note: We will be using wsk CLI in this section. If you don't have it installed and configured, please refer to the section OpenWhisk CLI (wsk).

  1. Create a file named Hello.java:
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    package hello;
    
    import com.google.gson.JsonObject;
    
    public class Hello {
        public static JsonObject main(JsonObject args)
            String name;
    
            try {
                name = args.getAsJsonPrimitive("name").getAsString();
            } catch(Exception e) {
                name = "stranger";
            }
    
            JsonObject response = new JsonObject();
            response.addProperty("greeting", "Hello " + name + "!");
            return response;
        }
    }
    
  2. Compile Hello.Java into a JAR file hello.jar as follows
    $ javac Hello.java
    $ jar cvf hello.jar Hello.class
  3. Create an action called helloJava using hello.jar:
    $ wsk action create helloJava hello.jar --main Hello
    ok: created action helloJava
  4. Invoke an action helloJava:
    $ wsk action invoke helloJava --blocking --result
    {
    "greeting": "Hello stranger!"
    }
OpenWhisk Runtime for Java

OpenWhisk supports Java 8 runtime. If you wish to learn more about NodeJS runtime along with the libraries that are supported or "built-in" by default, please visit Java Runtime GitHub Repository.

Additional Resources
using PHP

Creating and Invoking PHP actions

Let's look at how to write a sample hello world action in PHP. You can visit Creating and Invoking PHP actions page for further details.

Note: We will be using wsk CLI in this section. If you don't have it installed and configured, please refer to the section OpenWhisk CLI (wsk).

  1. Create a file named hello.php:
    1
    2
    3
    4
    5
    6
    7
    8
    9
    <?php
    function main(array $args) : array
    {
        $name = $args["name"] ?? "stranger";
        $greeting = "Hello $name!";
        echo $greeting;
        return ["greeting" => $greeting];
    }
    ?>
    
  2. Create an action called helloPHP using hello.php:
    $ wsk action create helloPHP hello.php
    ok: created action helloPHP
  3. Invoke an action helloPHP:
    $ wsk action invoke helloPHP --blocking --result --param name World
    {
    "greeting": "Hello World!"
    }
  4. Deploy using wskdeploy:

    Note: We will be using wskdeploy in this section. If you don't have the binary, please refer to the section on Whisk Deploy to download it.

    1. Create manifest.yaml with the following YAML content:
      1
      2
      3
      4
      5
      packages:
          default:
              actions:
                  helloPHP:
                      function: hello.php
      
      Or

      1
      2
      3
      4
      5
      6
      7
      8
      9
      10
      11
      12
      13
      14
      packages:
          default:
              actions:
                  helloPHP:
                      code: |
                          <?php
                          function main(array $args) : array
                          {
                              $name = $args["name"] ?? "stranger";
                              $greeting = "Hello $name!";
                              echo $greeting;
                              return ["greeting" => $greeting];
                          }
                      runtime: php:7.1
      
    2. Run deployment with wskdeploy:
      $ wskdeploy -m manifest.yaml
OpenWhisk Runtime for PHP

OpenWhisk supports PHP 7.2 and PHP 7.1 runtimes where PHP 7.2 being default pick by wsk CLI and Whisk Deploy. If you wish to learn more about PHP runtime, please visit PHP Runtime GitHub Repository.

Additional Resources
Medium Blogs (tagged php)
using Ruby

Creating and Invoking Ruby actions

Let's look at how to write a sample hello world action in Ruby. You can visit Creating and Invoking Ruby actions page for further details.

Note: We will be using wsk CLI in this section. If you don't have it installed and configured, please refer to the section OpenWhisk CLI (wsk).

  1. Create a file named hello.rb:
    1
    2
    3
    4
    5
    def main(params = {})
      name = params["name"] || "stranger"
      greeting = "Hello #{name}!"
      { "greeting": greeting }
    end
    
  2. Create an action called hello_ruby using hello.rb:
    $ wsk action create hello_ruby hello.rb
    ok: created action hello_ruby
  3. Invoke an action hello_ruby:
    $ wsk action invoke hello_ruby --blocking --result --param name World
    {
    "greeting": "Hello World!"
    }
  4. Deploy using wskdeploy:

    Note: We will be using wskdeploy in this section. If you don't have the binary, please refer to the section on Whisk Deploy to download it.

    1. Create manifest.yaml with the following YAML content:
      1
      2
      3
      4
      5
      packages:
          default:
              actions:
                  hello_ruby:
                      function: hello.rb
      
      Or

      1
      2
      3
      4
      5
      6
      7
      8
      9
      10
      11
      packages:
          default:
              actions:
                  hello_ruby:
                      code: |
                          def main(params = {})
                            name = params["name"] || "stranger"
                            greeting = "Hello #{name}!"
                            { "greeting": greeting }
                          end
                      runtime: ruby:2.5
      
    2. Run deployment with wskdeploy:
      $ wskdeploy -m manifest.yaml
OpenWhisk Runtime for Ruby

OpenWhisk supports Ruby 2.5 runtime. If you wish to learn more about Ruby runtime, please visit Ruby Runtime GitHub Repository.

Additional Resources

Medium Blogs (tagged ruby)
using Swift

Creating And Invoking Swift Actions

Let's look at how to write a sample hello world action in Swift. You can visit Quick Swift Action page for further details.

Note: We will be using wsk CLI in this section. If you don't have it installed and configured, please refer to the section OpenWhisk CLI (wsk).

  1. Create a file named hello.swift:
    1
    2
    3
    4
    5
    6
    7
    func main(args: [String:Any]) -> [String:Any] {
        if let name = args["name"] as? String {
            return [ "greeting" : "Hello \(name)!" ]
        } else {
            return [ "greeting" : "Hello swif4!" ]
        }
    }
    
  2. Create an action helloSwift:
    $ wsk action create helloSwift hello.swift
  3. Invoke an action helloSwift:
    $ wsk action invoke helloSwift -r -p name Carlos
    {
    "msg": "Hello Carlos!"
    }
  4. Deploy using wskdeploy:

    Note: We will be using wskdeploy in this section. If you don't have the binary, please refer to the section on Whisk Deploy to download it.

    1. Create a directory called actions with hello.swift from step 1 above.
    2. Create manifest.yaml with the following YAML content:
      1
      2
      3
      4
      5
      packages:
          default:
              actions:
                  helloSwift:
                      function: hello.swift
      
    3. Run deployment with wskdeploy:
      $ wskdeploy -m manifest.yaml
OpenWhisk Runtime for Swift

If you wish to learn more about Swift runtime along with the libraries that are supported or "built-in" by default, please visit the project REAMDE Apache OpenWhisk runtimes for Swift.

Additional Resources
Medium Blogs (tagged swift)

Managing Actions with OpenWhisk Packages

What is a package? In OpenWhisk, you can use packages to bundle together a set of related actions, and share them with others. OpenWhisk comes with a list of packages You can get more details on OpenWhisk packages here.

Does OpenWhisk comes with any pre-installed packages? OpenWhisk comes with a list of pre-installed public packages which can be used by anyone. OpenWhisk has created a dedicated shared namespace /whisk.system for all the public packages.

Which all packages are available under /whisk.system? You can get a list of packages available in shared namespace by using wsk CLI:

  • Get a list of packages:
    $ wsk package list /whisk.system
  • Get a list of entities in a package:
    $ wsk package get --summary /whisk.system/<package-name>

How do I invoke an action from a public package? There are two way to invoke an action from a package, (1) Invoking an action directly from a package (2) Creating a package binding and then invoking an action in the binding.

  • Invoking an action from a public package:
    • Get a description of the /whisk.system/samples/greeting action:
      $ wsk action get --summary /whisk.system/samples/greeting
      action /whisk.system/samples/greeting:
                          Returns a friendly greeting
                          (parameters: name, place)
    • Invoking action in a package:
      $ wsk action invoke --result /whisk.system/samples/greeting
      {
      "payload": "Hello, stranger from somewhere!"
      }
    • Invoke the action with parameters:
      $ wsk action invoke --result /whisk.system/samples/greeting --param name Bernie --param place Vermont
      {
      "payload": "Hello, Bernie from Vermont!"
      }
  • Creating package binding and invoking action from the binding:
    • Creating and using package bindings:
      $ wsk package bind /whisk.system/samples valhallaSamples --param place Valhalla
      ok: created binding valhallaSamples
    • Invoke an action in the package binding:
      $ wsk action invoke --result valhallaSamples/greeting --param name Odin
      {
      "payload": "Hello, Odin from Valhalla!"
      }

Where do I get more information on packages? Please read OpenWhisk Packages for further details.

Automating Actions from Event Sources

In this section, we will show how to automate Actions in response to events coming from Event Sources. Specifically, we will show how to create, fire and associate a basic Trigger with input parameters to an Action using a Rule.

Create and fire Trigger
  • Create a trigger to send user location updates:
    $ wsk trigger create locationUpdate
  • Check you have created the trigger by listing the set of triggers:
    $ wsk trigger list
    triggers
    /someNamespace/locationUpdate                            private
  • Fire the trigger by specifying its name and parameters:
    $ wsk trigger fire locationUpdate --param name Bob --param place NYC
    ok: triggered locationUpdate

    Firing a trigger like this currently does not do anything. We need to associate this trigger with an action. This kind of association is called a rule.

Verify you have an Action created
  • Please make sure you have the hello action created. If not, you can follow instruction in the section above with the following hello.js.
    1
    2
    3
    function main(params) {
        return {payload: 'Hello, ' + params.name + ' from ' + params.place};
    }
    
    $ wsk action create hello hello.js
    $ wsk action invoke --result hello --param name Bernie --param place Vermont
    {
    "payload": "Hello, Bernie from Vermont"
    }
Associate the Trigger and Action using a Rule
  • Create the rule (i.e., an association):
    $ wsk rule create myRule locationUpdate hello
    ok: created rule myRule
Invoke the Action by Firing the Trigger
  • Fire the locationUpdate trigger:
    $ wsk trigger fire locationUpdate --param name Bob --param place NYC
    ok: triggered /_/locationUpdate with id abcd...
  • Verify that the action was invoked by checking the activations list:
    $ wsk activation list --limit 2
    activations
    1234.... hello
    abcd.... locationUpdate
    
  • Retrieving the trigger activation record:
    $ wsk activation result 1234....
    {
    "payload": "Hello, Bob from NYC"
    }
    You can see that the hello action received the event payload and returned the expected string.

Using OpenWhisk Enabled Services

OpenWhisk offers a catalog of packages which gives you can easy way to enhance your application with useful capabilities, and to access external services in the ecosystem. Examples of external services which are OpenWhisk-enabled include Slack, GitHub, Alarms, etc.

The catalog is available as packages under /whisk.system namespace. Using the following command, you can get a list of packages under /whisk.system:

$ wsk package list /whisk.system
packages
/whisk.system/alarms                                shared
/whisk.system/system                                shared
/whisk.system/utils                                 shared
/whisk.system/samples                               shared
/whisk.system/slack                                 shared
/whisk.system/github                                shared
...

Each of the packages under OpenWhisk Catalog is hosted in a GitHub repo. Please refer to these package repositories for further details:

Sample OpenWhisk Applications

GitHub Slack Bot

incubator-openwhisk-GitHubSlackBot demonstrates integration of GitHub Pull Request management with Slack and using Alarms.

Serverless Message Archiver To Object Storage (MATOS) Sample Application

incubator-openwhisk-sample-matos demonstrates an implementation of a simple pipeline that reads messages from a Message Hub topic and archives them in batches into an Object Storage folder.

Slackbot for OpenWhisk:

incubator-openwhisk-sample-slackbot a proof-of-concept Slackbot to invoke OpenWhisk actions.

openwhisk-slackinvite:

incubator-openwhisk-slackinvite implements invitations for Apache OpenWhisk Slack Community.

Tutorial and Workshop

OpenWhisk Tutorial

incubator-openwhisk-tutorial contains an interactive tutorials for the OpenWhisk CLI.

OpenWhisk Workshop

incubator-openwhisk-workshop provides a series of exercises to help you understand how to use OpenWhisk to build serverless applications.

Development Tools

The OpenWhisk Debugger

incubator-openwhisk-debugger supports debugging OpenWhisk actions. The debugger will arrange things so that the actions you wish to debug will be offloaded from the main OpenWhisk servers and instead run locally on your laptop. You can then, from within the debugger, inspect and modify values.

Contributors

The Apache OpenWhisk project welcomes any and all developers to become a Contributor to any part of our project. Contributions can range from fixing documentation and adding testcases, to fixing bugs, proposing and implementing new features and reviewing others' Pull Requests (PRs).

The following Wiki pages describe the "How Tos" of becoming an official Contributor:

Project Structure

OpenWhisk is comprised of multiple repositories that can be found in Apache GitHub (using a name query by repository):

For convenience, here is a listing of current Apache OpenWhisk project repositories (by category).

Note: OpenWhisk repositories follow a naming convention where all repo starts with incubator, for example, openwhisk-cli GitHub repository is named incubator-openwhisk-cli.

Platform

Primary source code repositories including platform code, run books, tests and more.

openwhisk

openwhisk-cli

openwhisk-apigateway

openwhisk-catalog

Packages

Several common service integrations are made available as packages. By default they are registered in the OpenWHisk catalog, under the /whisk.system/ namespace, and include:

openwhisk-package-alarms

openwhisk-package-cloudant

openwhisk-package-kafka

openwhisk-package-deploy

openwhisk-package-pushnotifications

openwhisk-package-rss

openwhisk-package-jira

openwhisk-package-template

Clients and SDK

Here are the clients to access to OpenWhisk API:

openwhisk-client-go

openwhisk-client-js

openwhisk-client-swift

openwhisk-client-python

Others

Few other misc. but crucial repositories.

openwhisk-release

openwhisk-website

openwhisk-external-resources

Contributor resources

This section lists a number of resources for OpenWhisk Contributors:

Contributing new Action Language Runtimes

OpenWhisk supports several languages via its Action Runtimes, but there may be other languages or runtimes that you may want to contribute to the project.

Read this guide on how to get started: Adding Action Language Runtimes

Operators

This section has information that is primarily focused on deploying, configuring and administrating an Apache OpenWhisk Serverless platform.

OpenWhisk Architecture

The diagram below depicts the high-level architecture of OpenWhisk. From Nginx to Kafka to Docker, multiple technologies are powering Apache OpenWhisk which shows its committment to be a true Open Source Serverless Cloud Platform.

OpenWhisk Architecture

You can read about more about the OpenWhisk platform components along with its internal flow of processing here:

Deployment Options

OpenWhisk offers different deployment options for installing and configuring the OpenWhisk platform components. However, Kubernetes is the recommended option as it is supported on most major platforms and includes great options for local developers to get running quickly, as well as supports operators needing to manage large scale production deployments.

Kubernetes

OpenWhisk can be deployed using Helm charts on any Kubernetes provisioned locally or from a public cloud provider.

Please refer to: Deploy OpenWhisk to a Kubernetes Cluster for detailed deployment instructions which includes specific customizations including Docker Desktop (Mac, Windows), Minikube, Google, IBM Cloud, IBM Cloud Private, etc.).

Alternative options

Here are some alternate choices for deploying the OpenWhisk platform:

Docker Compose

If you like using Docker directly, another easy local alternative is to get Docker installed on Mac, Windows or Linux and use Docker Compose. Please note that this option does not give you a production deployment but gives you enough of the pieces to start writing functions and seeing them executing.

$ git clone https://github.com/apache/incubator-openwhisk-devtools.git
$ cd incubator-openwhisk-devtools/docker-compose
$ make quick-start

For more detailed instructions, see the OpenWhisk with Docker Compose project.

Ansible

Deploying OpenWhisk using Ansible is a more imperative, script-based deployment option such as in a CI/CD (Travis) pipeline. The OpenWhisk playbooks are structured such that it allows cleaning, deploying, or re-deploying a single component as well as the entire OpenWhisk stack.

Vagrant

A Vagrant machine is also available to run OpenWhisk on Mac, Windows PC or GNU/Linux. Downloading and install VirtualBox and Vagrant for your operating system and architecture. You can follow the steps under Vagrant Setup to run your first OpenWhisk action using Vagrant.

Mesos

Deploy OpenWhisk to a Mesos Cluster is under active development.

OpenShift

OpenWhisk Deployment on OpenShift is under active development.

Administrative Operations

This section contains a list of resources which can be utilized to administer the running OpenWhisk instance.

Operator Resources

Other Resources

  • Events - list of past OpenWhisk events
  • Awesome OpenWhisk - list of OpenWhisk resources and tips including articles, books, videos, presentations, podcasts, etc.

Frequently Asked Questions