--- layout: default ---

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.

The following is a list of runtimes the Apache OpenWhisk project has officially released and made available on our Downloads page.

  • .Net - OpenWhisk runtime for .Net Core 2.2
  • Go - OpenWhisk runtime for Go
  • Java - OpenWhisk runtime for Java 8 (OpenJDK 8, JVM OpenJ9)
  • JavaScript - OpenWhisk runtime for Node.js v10, v12 and v14
  • PHP - OpenWhisk runtime for PHP 8.0, 7.4 and 7.3
  • Python - OpenWhisk runtime for Python 2.7, 3 and a 3 runtime variant for AI/ML (including packages for Tensorflow and PyTorch)
  • Ruby - OpenWhisk runtime for Ruby 2.5
  • Swift - OpenWhisk runtime for Swift 3.1.1, 4.1 and 4.2

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 programming model. If you want 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.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. A sequence can be treated as a single action in terms of it's 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 instance from 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.

{% highlight bash %} $ brew update $ brew install wsk {% endhighlight %}

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 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:

{% highlight bash %}$ wsk --help{% endhighlight %}
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 through 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:

{% highlight bash %} $ wsk property set --apihost API_HOST --auth AUTH_KEY --namespace guest {% endhighlight %}

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:

{% highlight bash %} $ export WSK_CONFIG_FILE=your-config-file {% endhighlight %}
Verify properties

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

{% highlight bash %} $ wsk property get {% endhighlight %}
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.

{% highlight bash %} $ wsk list -v {% endhighlight %}

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 from a single command using an application manifest.

Whisk deploy in the wsk CLI

The functionality of wskdeploy is also embedded as the deploy subcommand within the wsk CLI. The functionality is identical and supports all the same parameters and flags. This means that you can use the wsk deploy subcommand if you already have the CLI installed or follow the instructions below on installing the wskdeploy utility for standalone use.

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 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:

{% highlight bash %}$ wskdeploy --help{% endhighlight %}
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":

    {% highlight yaml %} {% include code/manifest-for-helloJS-2.yaml %} {% endhighlight %}
  • Save the YAML scripts as an OpenWhisk Manifest file called manifest.yaml

  • Deploy the OpenWhisk Manifest file:

    {% highlight bash %}$ wskdeploy -m manifest.yaml{% endhighlight %}
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:
    {% highlight javascript linenos %} {% include code/hello.js %} {% endhighlight %}
  2. Create an action called helloJS using hello.js:
    {% highlight bash %}$ wsk action create helloJS hello.js{% endhighlight %} 
    ok: created action helloJS
  3. Invoke an action helloJS:
    {% highlight bash %}$ wsk action invoke helloJS --result --param name World{% endhighlight %}
    {% highlight yaml %} { "greeting": "Hello World!" }{% endhighlight %}
  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:
      {% highlight yaml linenos %} {% include code/manifest-for-helloJS-1.yaml %} {% endhighlight %}
      Or

      {% highlight yaml linenos %} {% include code/manifest-for-helloJS-2.yaml %} {% endhighlight %}
    2. Run deployment with wskdeploy:
      {% highlight bash %}$ wskdeploy -m manifest.yaml{% endhighlight %}
OpenWhisk Runtime for NodeJS

OpenWhisk supports Node.js 14, Node.js 12, Node.js 10 runtimes where Node.js 10 being the default picked 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:
    {% highlight go linenos %} {% include code/hello.go %} {% endhighlight %}
  2. Create an action helloGo:
    {% highlight bash %}$ wsk action create helloGo hello.go{% endhighlight %}
  3. Invoke an action helloGo:
    {% highlight bash %}$ wsk action invoke helloGo --result --param name gopher{% endhighlight %}
    {% highlight yaml %} { "msg": "Hello, gopher!" } {% endhighlight %}
  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:
      {% highlight yaml linenos %} {% include code/manifest-for-helloGo.yaml %} {% endhighlight %}
    3. Run deployment with wskdeploy:
      {% highlight bash %}$ wskdeploy -m manifest.yaml{% endhighlight %}
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:
    {% highlight python linenos %} {% include code/hello.py %} {% endhighlight %}
  2. Create an action called helloPy using hello.py:
    {% highlight bash %}$ wsk action create helloPy hello.py{% endhighlight %} 
    ok: created action helloPy
  3. Invoke the helloPy action using command-line parameters:
    {% highlight bash %}$ wsk action invoke helloPy --result --param name World{% endhighlight %}
    {% highlight yaml %} { "greeting": "Hello World!" } {% endhighlight %}
  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:
      {% highlight yaml linenos %} {% include code/manifest-for-helloPy-1.yaml %} {% endhighlight %}
      Or

      {% highlight yaml linenos %} {% include code/manifest-for-helloPy-2.yaml %} {% endhighlight %}
    2. Run deployment with wskdeploy:
      {% highlight bash %}$ wskdeploy -m manifest.yaml{% endhighlight %}
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:
    {% highlight java linenos %} {% include code/Hello.java %} {% endhighlight %}

  2. Assure that you have downloaded the JAR file for the imported `com.google.gson.JsonObject` library (i.e., google-gson-2.8.5.jar from Maven) to your Java `CLASSPATH`.

  3. Compile Hello.Java into a JAR file hello.jar as follows
    {% highlight bash %} $ javac Hello.java $ jar cvf hello.jar Hello.class {% endhighlight %}
    Please note that the current default JVM for OpenWhisk is Java 8. If you are using a newer version, you must specify that release version when you compile:
    {% highlight bash %} $ javac --release 8 Hello.java {% endhighlight %}
  4. Create an action called helloJava using hello.jar specifying the Java class where the `main` entry point you wish to invoke:
    {% highlight bash %}$ wsk action create helloJava hello.jar --main Hello{% endhighlight %}
    {% highlight yaml %}ok: created action helloJava{% endhighlight %}
  5. Invoke an action helloJava:
    {% highlight bash %}$ wsk action invoke helloJava --result{% endhighlight %}
    {% highlight yaml %} { "greeting": "Hello stranger!" } {% endhighlight %}
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:
    {% highlight php linenos %} {% include code/hello.php %} {% endhighlight %}
  2. Create an action called helloPHP using hello.php:
    {% highlight bash %}$ wsk action create helloPHP hello.php{% endhighlight %}
    {% highlight bash %}ok: created action helloPHP{% endhighlight %}
  3. Invoke an action helloPHP:
    {% highlight bash %}$ wsk action invoke helloPHP --result --param name World{% endhighlight %}
    {% highlight yaml %} { "greeting": "Hello World!" } {% endhighlight %}
  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:
      {% highlight yaml linenos %} {% include code/manifest-for-helloPhp-1.yaml %} {% endhighlight %}
      Or

      {% highlight yaml linenos %} {% include code/manifest-for-helloPhp-2.yaml %} {% endhighlight %}
    2. Run deployment with wskdeploy:
      {% highlight bash %}$ wskdeploy -m manifest.yaml{% endhighlight %}
OpenWhisk Runtime for PHP

OpenWhisk supports PHP 8.0, PHP 7.4 and PHP 7.3 runtimes where PHP 7.4 is the 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:
    {% highlight ruby linenos %} {% include code/hello.rb %} {% endhighlight %}
  2. Create an action called hello_ruby using hello.rb:
    {% highlight bash %}$ wsk action create hello_ruby hello.rb{% endhighlight %}
    {% highlight bash %}ok: created action hello_ruby{% endhighlight %}
  3. Invoke an action hello_ruby:
    {% highlight bash %}$ wsk action invoke hello_ruby --result --param name World{% endhighlight %}
    {% highlight yaml %} { "greeting": "Hello World!" } {% endhighlight %}
  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:
      {% highlight yaml linenos %} {% include code/manifest-for-helloRuby-1.yaml %} {% endhighlight %}
      Or

      {% highlight yaml linenos %} {% include code/manifest-for-helloRuby-2.yaml %} {% endhighlight %}
    2. Run deployment with wskdeploy:
      {% highlight bash %}$ wskdeploy -m manifest.yaml{% endhighlight %}
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:
    {% highlight java linenos %} {% include code/hello.swift %} {% endhighlight %}
  2. Create an action helloSwift:
    {% highlight bash %}$ wsk action create helloSwift hello.swift{% endhighlight %}
  3. Invoke an action helloSwift:
    {% highlight bash %}$ wsk action invoke helloSwift --result --param name Carlos{% endhighlight %}
    {% highlight yaml %} { "msg": "Hello Carlos!" } {% endhighlight %}
  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:
      {% highlight yaml linenos %} {% include code/manifest-for-helloSwift.yaml %} {% endhighlight %}
    3. Run deployment with wskdeploy:
      {% highlight bash %}$ wskdeploy -m manifest.yaml{% endhighlight %}
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 README Apache OpenWhisk runtimes for Swift.

Additional Resources
Medium Blogs (tagged swift)
using .NET Core

Creating And Invoking .NET Core Actions

Let's look at how to write a sample hello world action in .NET Core. You can visit Quick .NET Core 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 C# project called Apache.OpenWhisk.Example.Dotnet:
    {% highlight bash %} $ dotnet new classlib -n Apache.OpenWhisk.Example.Dotnet -lang C# {% endhighlight %}
  2. Navigate to the Apache.OpenWhisk.Example.Dotnet directory:
    {% highlight bash %} $ cd Apache.OpenWhisk.Example.Dotnet {% endhighlight %}
  3. Install the Newtonsoft.Json NuGet package as follows:
    {% highlight bash %} $ dotnet add package Newtonsoft.Json -v 12.0.1 {% endhighlight %}
  4. Create a file called Hello.cs with the following content:
    {% highlight java linenos %} {% include code/Hello.cs %} {% endhighlight %}
  5. Publish the project as follows:
    {% highlight bash %} $ dotnet publish -c Release -o out {% endhighlight %}
  6. Publish the project as follows:
    {% highlight bash %} $ cd out $ zip -r -0 helloDotNet.zip * {% endhighlight %}
  7. Create an action helloDotNet:
    {% highlight bash %} $ wsk action create helloDotNet helloDotNet.zip --main Apache.OpenWhisk.Example.Dotnet::Apache.OpenWhisk.Example.Dotnet.Hello::Main --kind dotnet:2.2 {% endhighlight %}
  8. Invoke an action helloDotNet:
    {% highlight bash %} $ wsk action invoke helloDotNet --result --param name Shawn {% endhighlight %}
    {% highlight yaml %} { "msg": "Hello Shawn!" } {% endhighlight %}
OpenWhisk Runtime for .NET Core

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

Additional Resources
Creating and invoking .NET Core actions

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:
    {% highlight bash %}$ wsk package list /whisk.system{% endhighlight %}
  • Get a list of entities in a package:
    {% highlight bash %}$ wsk package get --summary /whisk.system/{% endhighlight %}

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:
      {% highlight bash %}$ wsk action get --summary /whisk.system/samples/greeting{% endhighlight %} 
      action /whisk.system/samples/greeting:
                    Returns a friendly greeting
                    (parameters: name, place)
    • Invoking action in a package:
      {% highlight bash %}$ wsk action invoke --result /whisk.system/samples/greeting{% endhighlight %}
      {% highlight yaml %} { "payload": "Hello, stranger from somewhere!" } {% endhighlight %}
    • Invoke the action with parameters:
      {% highlight bash %}$ wsk action invoke --result /whisk.system/samples/greeting --param name Bernie --param place Vermont{% endhighlight %}
      {% highlight yaml %} { "payload": "Hello, Bernie from Vermont!" } {% endhighlight %}
  • Creating package binding and invoking action from the binding:
    • Creating and using package bindings:
      {% highlight bash %}$ wsk package bind /whisk.system/samples valhallaSamples --param place Valhalla{% endhighlight %}
      {% highlight bash %}ok: created binding valhallaSamples{% endhighlight %}
    • Invoke an action in the package binding:
      {% highlight bash %}$ wsk action invoke --result valhallaSamples/greeting --param name Odin{% endhighlight %}
      {% highlight yaml %} { "payload": "Hello, Odin from Valhalla!" } {% endhighlight %}

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:
    {% highlight bash %}$ wsk trigger create locationUpdate{% endhighlight %}
  • Check you have created the trigger by listing the set of triggers:
    {% highlight bash %}$ wsk trigger list{% endhighlight %} 
    triggers
/someNamespace/locationUpdate                            private
  • Fire the trigger by specifying its name and parameters:
    {% highlight bash %}$ wsk trigger fire locationUpdate --param name Bob --param place NYC{% endhighlight %} 
    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.
    {% highlight javascript linenos %} {% include code/hello-with-params.js %} {% endhighlight %}
    {% highlight bash %}$ wsk action create hello hello.js{% endhighlight %}
    {% highlight bash %}$ wsk action invoke --result hello --param name Bernie --param place Vermont{% endhighlight %}
    {% highlight yaml %} { "payload": "Hello, Bernie from Vermont" } {% endhighlight %}
Associate the Trigger and Action using a Rule
  • Create the rule (i.e., an association):
    {% highlight bash %}$ wsk rule create myRule locationUpdate hello{% endhighlight %} 
    ok: created rule myRule
Invoke the Action by Firing the Trigger
  • Fire the locationUpdate trigger:
    {% highlight bash %}$ wsk trigger fire locationUpdate --param name Bob --param place NYC{% endhighlight %} 
    ok: triggered /_/locationUpdate with id abcd...
  • Verify that the action was invoked by checking the activations list:
    {% highlight bash %}$ wsk activation list --limit 2{% endhighlight %} 
    activations
1234.... hello
abcd.... locationUpdate
  • Retrieving the trigger activation record:
    {% highlight bash %}$ wsk activation result 1234....{% endhighlight %}
    {% highlight yaml %}{ "payload": "Hello, Bob from NYC" } {% endhighlight %}
    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:

{% highlight bash %}$ wsk package list /whisk.system{% endhighlight %} 
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:

  • openwhisk-package-alarm is an Apache OpenWhisk alarm package that can be used to create periodic, time-based alarms.
  • openwhisk-package-cloudant enables you to work with a Cloudant database.
  • openwhisk-package-kafka allows you to communicate with Kafka or Message Hub instances for publishing and consuming messages using native high performance Kafka API.
  • openwhisk-package-rss allows users to subscribe to RSS/ATOM feeds and receive events when a new feed item is available.
  • openwhisk-package-deploy offers a convenient way for you to describe and deploy any part of the OpenWhisk programming model using a Manifest file written in YAML.
  • openwhisk-package-jira includes actions that interact with JIRA software software development tool used for issue tracking, and project management functions.
  • openwhisk-package-template is a template for Openwhisk Packages, it can be used to build, test and integrate new packages.

Sample OpenWhisk Applications

GitHub Slack Bot

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

Serverless Message Archiver To Object Storage (MATOS) Sample Application

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:

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

openwhisk-slackinvite:

openwhisk-slackinvite implements invitations for Apache OpenWhisk Slack Community.

Tutorial and Workshop

OpenWhisk Tutorial

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

OpenWhisk Workshop

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

Development Tools

The OpenWhisk Debugger

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).

Platform

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

openwhisk

openwhisk-cli

openwhisk-apigateway

openwhisk-catalog

Runtimes

OpenWhisk supports several languages via Docker runtime containers.

openwhisk-runtime-nodejs

openwhisk-runtime-docker

openwhisk-runtime-python

openwhisk-runtime-go

openwhisk-runtime-swift

openwhisk-runtime-php

openwhisk-runtime-java

openwhisk-runtime-ruby

Deployments

OpenWhisk can be deployed and configured on variety of platforms.

openwhisk-deploy-kube

openwhisk-devtools/docker-compose

openwhisk/ansible

openwhisk/vagrant-setup

Tooling

OpenWhisk provides variety of tools around deployment and development.

openwhisk-wskdeploy

openwhisk-devtools

openwhisk-debugger

openwhisk-playground

openwhisk-vscode

openwhisk-xcode

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

Samples

Few example applications to demonstrate OpenWhisk features and functionalities:

openwhisk-sample-slackbot

openwhisk-slackinvite

openwhisk-GitHubSlackBot

openwhisk-sample-matos

openwhisk-tutorial

openwhisk-workshop

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:

What Can I Contribute?

Usually, contributors come because they want to fix or improve some part of the project. This can include the code itself in any of the project repositories under our project, project documentation, test cases, literally anything!

Here are some specific ideas to get you thinking ...

  • Fix open issues: both bugs and feature issues in GitHub.
  • Improve Documentation: READMEs, Website Developer or Operator docs (Examples, How Tos), Medium blog articles, etc.
  • Testcases (any repo.): e.g., functional code coverage, performance, config. variants, parallelize test buckets, etc.
  • Add Operational Plug-ins: e.g., metrics, logging, artifact storage impls., etc.)
  • Add/Improve Language Runtimes: See Contributing new Action Language Runtimes below. e.g., new languages, additional framework variants), etc.
  • Improve tooling: Enhance CLI features, extend APIs for new use cases, etc.
  • Feature ideas, Use cases, Design proposals: Support new scenarios, deployments (platforms), schedulers, etc. Submit ideas via our developer email list and use our Confluence Wiki to develop your ideas.

Contributing Language Runtimes

OpenWhisk supports several languages via its Action Runtimes, but there may be other languages you would like supported or even language variants with different frameworks for languages we support today. OpenWhisk is all about making it easy for ANY developer, using any functional language they are comfortable with, to develop Actions for our platform!

You can create a new runtime in two ways:

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 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:

Quick Start

The easiest way to start using OpenWhisk is to install the "Standalone" OpenWhisk stack. This is a full-featured OpenWhisk stack running as a Java process for convenience. Serverless functions run within Docker containers. You will need Docker, Java and Node.js available on your machine.

To get started:

{% highlight bash %} $ git clone https://github.com/apache/openwhisk.git $ cd openwhisk $ ./gradlew core:standalone:bootRun {% endhighlight %}

  • When the OpenWhisk stack is up, it will open your browser to a functions Playground, typically served from http://localhost:3232. The Playground allows you create and run functions directly from your browser.
  • To make use of all OpenWhisk features, you will need the OpenWhisk command line tool called wsk which you can download from https://s.apache.org/openwhisk-cli-download. Please refer to the CLI configuration for additional details. Typically you configure the CLI for Standalone OpenWhisk as follows:

{% highlight bash %} wsk property set \ --apihost 'http://localhost:3233' \ --auth '23bc46b1-71f6-4ed5-8c54-816aa4f8c502:123zO3xZCLrMN6v2BKK1dXYFpXlPkccOFqm12CdAsMgRU4VrNZ9lyGVCGuMDGIwP' {% endhighlight %}

  • Standalone OpenWhisk can be configured to deploy additional capabilities when that is desirable. Additional resources are available here.

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.

{% highlight bash %} $ git clone https://github.com/apache/openwhisk-devtools.git $ cd openwhisk-devtools/docker-compose $ make quick-start {% endhighlight %}

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.

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

{% include partial/faq.html %}