{"id":19042450,"url":"https://github.com/serverless/serverless-openwhisk","last_synced_at":"2025-08-14T10:33:49.425Z","repository":{"id":47597985,"uuid":"73327784","full_name":"serverless/serverless-openwhisk","owner":"serverless","description":"Adds Apache OpenWhisk support to the Serverless Framework!","archived":true,"fork":false,"pushed_at":"2024-12-09T15:38:57.000Z","size":418,"stargazers_count":141,"open_issues_count":35,"forks_count":46,"subscribers_count":16,"default_branch":"master","last_synced_at":"2025-08-10T22:09:08.081Z","etag":null,"topics":["openwhisk","serverless","serverless-framework","serverless-functions","serverless-plugin"],"latest_commit_sha":null,"homepage":"http://openwhisk.org/","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/serverless.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2016-11-09T22:51:48.000Z","updated_at":"2025-07-04T19:10:42.000Z","dependencies_parsed_at":"2022-09-10T13:41:38.572Z","dependency_job_id":null,"html_url":"https://github.com/serverless/serverless-openwhisk","commit_stats":null,"previous_names":[],"tags_count":33,"template":false,"template_full_name":null,"purl":"pkg:github/serverless/serverless-openwhisk","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/serverless%2Fserverless-openwhisk","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/serverless%2Fserverless-openwhisk/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/serverless%2Fserverless-openwhisk/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/serverless%2Fserverless-openwhisk/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/serverless","download_url":"https://codeload.github.com/serverless/serverless-openwhisk/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/serverless%2Fserverless-openwhisk/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":270405917,"owners_count":24578152,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-14T02:00:10.309Z","response_time":75,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["openwhisk","serverless","serverless-framework","serverless-functions","serverless-plugin"],"created_at":"2024-11-08T22:37:42.165Z","updated_at":"2025-08-14T10:33:49.055Z","avatar_url":"https://github.com/serverless.png","language":"JavaScript","readme":"**📦 Archived - This repository is archived and preserved for reference only. No updates, issues, or pull requests will be accepted. If you have questions, please reach out to our support team.**\n\n---\n\n\n# Serverless Apache OpenWhisk Plugin\n[![Build Status](https://travis-ci.org/serverless/serverless-openwhisk.svg?branch=master)](https://travis-ci.org/serverless/serverless-openwhisk)\n[![codecov](https://codecov.io/gh/serverless/serverless-openwhisk/branch/master/graph/badge.svg)](https://codecov.io/gh/serverless/serverless-openwhisk)\n\nThis plugin enables support for the [Apache OpenWhisk platform](https://openwhisk.apache.org/) within the Serverless Framework.\n\n## Getting Started\n\n### Register account with Apache OpenWhisk\n\nBefore you can deploy your service to Apache OpenWhisk, you need to have an account registered with the platform.\n\n- *Want to run the platform locally?* Please read the project's [*Quick Start*](https://github.com/openwhisk/openwhisk#quick-start) guide for deploying it locally.\n- *Want to use a hosted provider?* Please [sign up](https://cloud.ibm.com/registration) for a free account with [IBM Cloud](https://cloud.ibm.com/) and then follow the instructions for getting access to [IBM Cloud Functions (Apache OpenWhisk)](https://cloud.ibm.com/openwhisk).\n\n### Set up account credentials\n\nAccount credentials for OpenWhisk can be provided through a configuration file or environment variables. This plugin requires the API endpoint, namespace and authentication credentials.\n\n**Do you want to use a configuration file for storing these values?** Please [follow the instructions](https://console.ng.bluemix.net/openwhisk/cli) for setting up the OpenWhisk command-line utility. This tool stores account credentials in the `.wskprops` file in the user's home directory. The plugin automatically extracts credentials from this file at runtime.  No further configuration is needed.\n\n**Do you want to use environment variables for credentials?** Use the following environment variables to be pass in account credentials. These values override anything extracted from the configuration file.\n\n- *OW_APIHOST* - Platform endpoint, e.g. `openwhisk.ng.bluemix.net`\n- *OW_AUTH* - Authentication key, e.g. `xxxxxx:yyyyy`\n- *OW_NAMESPACE* - Namespace, defaults to user-provided credentials\n- *OW_APIGW_ACCESS_TOKEN* - API gateway access token (optional)\n- *OW_IAM_NAMESPACE_API_KEY* - IBM Cloud IAM API key (optional \u0026 overrides `auth`).\n\n### Install Serverless Framework\n\n```shell\n$ npm install --global serverless\n```\n\n**_This framework plugin requires Node.js runtime version 6.0 or above._**\n\n### Create Service From Template\n\nUsing the `create` command, you can create an example service from the [following template](https://github.com/serverless/serverless/tree/master/lib/plugins/create/templates/openwhisk-nodejs).\n\n```shell\nserverless create --template openwhisk-nodejs --path my_service\ncd my_service\nnpm install\n```\n\nMore service examples are available in the [`serverless-examples`](https://github.com/serverless/examples) repository.\n\n**Using a self-hosted version of the platform?**\n\nEnsure you set the `ignore_certs` option in the serverless.yaml prior to deployment.\n\n```\nprovider:\n  name: openwhisk\n  ignore_certs: true\n```\n\n### Deploy Service\n\nThe sample service from the template can be deployed without modification.\n\n```shell\nserverless deploy\n```\n\nIf the deployment succeeds, the following messages will be printed to the console.\n\n```sh\n$ serverless deploy\nServerless: Packaging service...\nServerless: Compiling Functions...\nServerless: Compiling API Gateway definitions...\nServerless: Compiling Rules...\nServerless: Compiling Triggers \u0026 Feeds...\nServerless: Deploying Functions...\nServerless: Deployment successful!\n\nService Information\nplatform:\topenwhisk.ng.bluemix.net\nnamespace:\t_\nservice:\tmy_service\n\nactions:\nmy_service-dev-hello\n\ntriggers:\n**no triggers deployed***\n\nrules:\n**no rules deployed**\n\nendpoints:\n**no routes deployed**\n\nweb-actions:\n**no web actions deployed**\n```\n\n### Test Service\n\nUse the `invoke` command to test your newly deployed service.\n\n```shell\n$ serverless invoke --function hello\n{\n    \"payload\": \"Hello, World!\"\n}\n$ serverless invoke --function hello --data '{\"name\": \"OpenWhisk\"}'\n{\n    \"payload\": \"Hello, OpenWhisk!\"\n}\n```\n\n*Add the `-v` or `--verbose` flag to show more [invocation details](https://github.com/apache/incubator-openwhisk/blob/master/docs/annotations.md#annotations-specific-to-activations), e.g. activation id and duration details.*\n\n```shell\n$ serverless invoke --function hello -v\n=\u003e action (\u003cACTION_NAME\u003e) activation (\u003cID\u003e) duration: 96ms (init: 83ms, wait: 35ms)\n{\n    \"payload\": \"Hello, OpenWhisk!\"\n}\n```\n\n## Writing Functions - Node.js\n\nHere's an `index.js` file containing an example handler function.\n\n```javascript\nfunction main(params) {\n  const name = params.name || 'World';\n  return {payload:  'Hello, ' + name + '!'};\n};\n\nexports.main = main;\n```\n\nModules [should return the function handler](https://github.com/openwhisk/openwhisk/blob/master/docs/actions.md#packaging-an-action-as-a-nodejs-module) as a custom property on the global `exports` object.\n\nIn the `serverless.yaml` file, the `handler` property is used to denote the source file and module property containing the serverless function.\n\n```yaml\nfunctions:\n  my_function:\n    handler: index.main\n```\n\n### Request Properties\n\nOpenWhisk executes the handler function for each request. This function is called with a single argument, an object [containing the request properties](https://github.com/openwhisk/openwhisk/blob/master/docs/actions.md#passing-parameters-to-an-action).\n\n```javascript\nfunction main(params) {\n  const parameter = params.parameter_name;\n  ...\n};\n```\n\n### Function Return Values\n\nThe handler must return an object from the function call. Returning `undefined` or `null` will result in an error. If the handler is carrying out an [asynchronous task](https://github.com/openwhisk/openwhisk/blob/master/docs/actions.md#creating-asynchronous-actions), it can return a [`Promise`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise).\n\n```javascript\n// synchronous return\nfunction main () {\n  return { payload: \"...\" }\n}\n\n// asychronous return\nfunction main(args) {\n  return new Promise(function(resolve, reject) {\n    setTimeout(function() {\n      resolve({ done: true });\n     }, 2000);\n  })\n}\n```\n\nIf you want to return an error message, return an object with an `error` property with the message. Promise values that are rejected will be interpreted as runtime errors.\n\n```javascript\n// synchronous return\nfunction main () {\n  return { error: \"...\" }\n}\n\n// asychronous return\nfunction main(args) {\n  return new Promise(function(resolve, reject) {\n    setTimeout(function() {\n      reject(\"error message\");\n     }, 2000);\n  })\n}\n```\n\n### Using NPM Modules\n\nNPM modules must be [installed locally](https://github.com/openwhisk/openwhisk/blob/master/docs/actions.md#packaging-an-action-as-a-nodejs-module) in the `node_modules` directory before deployment. This directory will be packaged up in the deployment artefact. Any dependencies included in `node_modules` will be available through `require()` in the runtime environment.\n\nOpenWhisk provides a number of popular NPM modules in the runtime environment. Using these modules doesn't require them to be included in the deployment package. See [this list](https://github.com/openwhisk/openwhisk/blob/master/docs/reference.md#javascript-runtime-environments) for full details of which modules are available.\n\n```javascript\nconst leftPad = require(\"left-pad\")\n\nfunction pad_lines(args) {\n    const lines = args.lines || [];\n    return { padded: lines.map(l =\u003e leftPad(l, 30, \".\")) }\n};\n\nexports.handler = pad_lines;\n```\n\n## Writing Functions - PHP\n\nHere's an `index.php` file containing an example handler function.\n\n```php\n\u003c?php\nfunction main(array $args) : array\n{\n    $name = $args[\"name\"] ?? \"stranger\";\n    $greeting = \"Hello $name!\";\n    echo $greeting;\n    return [\"greeting\" =\u003e $greeting];\n}\n```\n\nIn the `serverless.yaml` file, the `handler` property is used to denote the source file and function name of the serverless function.\n\n```yaml\nfunctions:\n  my_function:\n    handler: index.main\n    runtime: php\n```\n\n### Request Properties\n\nOpenWhisk executes the handler function for each request. This function is called with a single argument, an associative array [containing the request properties](https://github.com/openwhisk/openwhisk/blob/master/docs/actions.md#passing-parameters-to-an-action).\n\n```php\nfunction main(array $args) : array\n{\n    $name = $args[\"name\"] ?? \"stranger\";\n    ...\n}\n```\n\n### Function Return Values\n\nThe handler must return  an associative array from the function call.\n\n```php\nfunc main(args: [String:Any]) -\u003e [String:Any] {\n\t...\n    return [\"foo\" =\u003e $bar];\n}\n```\n\nIf you want to return an error message, return an object with an `error` property with the message.\n\n## Writing Functions - Python\n\nHere's an `index.py` file containing an example handler function.\n\n```python\ndef endpoint(params):\n    name = params.get(\"name\", \"stranger\")\n    greeting = \"Hello \" + name + \"!\"\n    print(greeting)\n    return {\"greeting\": greeting}\n```\n\nIn the `serverless.yaml` file, the `handler` property is used to denote the source file and module property containing the serverless function.\n\n```yaml\nfunctions:\n  my_function:\n    handler: index.endpoint\n    runtime: python:3\n```\n\n### Request Properties\n\nOpenWhisk executes the handler function for each request. This function is called with a single argument, a dictionary [containing the request properties](https://github.com/openwhisk/openwhisk/blob/master/docs/actions.md#passing-parameters-to-an-action).\n\n```python\ndef endpoint(params):\n    name = params.get(\"name\", \"stranger\")\n    ...\n```\n\n### Function Return Values\n\nThe handler must return a dictionary from the function call.\n\n```python\ndef endpoint(params):\n    ...\n    return {\"foo\": \"bar\"}\n```\n\nIf you want to return an error message, return an object with an `error` property with the message.\n\n## Writing Functions - Ruby\n\nHere's an `hello.rb` file containing an example handler function.\n\n```ruby\ndef main(args)\n  name = args[\"name\"] || \"stranger\"\n  greeting = \"Hello #{name}!\"\n  puts greeting\n  { \"greeting\" =\u003e greeting }\nend\n```\n\nIn the `serverless.yaml` file, the `handler` property is used to denote the source file and function name of the serverless function.\n\n```yaml\nfunctions:\n  my_function:\n    handler: hello.main\n    runtime: ruby\n```\n\n### Request Properties\n\nOpenWhisk executes the handler function for each request. This function is called with a single argument, which is a hash [containing the request properties](https://github.com/openwhisk/openwhisk/blob/master/docs/actions.md#passing-parameters-to-an-action).\n\n```ruby\ndef main(args)\n  name = args[\"name\"] || \"stranger\"\n  ...\n```\n\n### Function Return Values\n\nThe handler must return a hash from the function call.\n\n```ruby\ndef main(args)\n  ...\n  { \"greeting\" =\u003e greeting }\nend\n```\n\nIf you want to return an error message, return an `error` property string in the return hash.\n\n## Writing Functions - Swift\n\nHere's an `index.swift` file containing an example handler function.\n\n```swift\nfunc main(args: [String:Any]) -\u003e [String:Any] {\n    if let name = args[\"name\"] as? String {\n      return [ \"greeting\" : \"Hello \\(name)!\" ]\n    } else {\n      return [ \"greeting\" : \"Hello stranger!\" ]\n    }\n}\n```\n\nIn the `serverless.yaml` file, the `handler` property is used to denote the source file and module property containing the serverless function.\n\n```yaml\nfunctions:\n  my_function:\n    handler: index.main\n    runtime: swift\n```\n\n### Request Properties\n\nOpenWhisk executes the handler function for each request. This function is called with a single argument, a dictionary [containing the request properties](https://github.com/openwhisk/openwhisk/blob/master/docs/actions.md#passing-parameters-to-an-action).\n\n```swift\nfunc main(args: [String:Any]) -\u003e [String:Any] {\n    let prop = args[\"prop\"] as? String\n}\n```\n\n### Function Return Values\n\nThe handler must return a dictionary from the function call.\n\n```swift\nfunc main(args: [String:Any]) -\u003e [String:Any] {\n\t...\n    return [\"foo\": \"bar\"]\n}\n```\n\nIf you want to return an error message, return an object with an `error` property with the message.\n\n### Codable Support\n\nSwift 4 runtimes support [Codable types](https://developer.apple.com/documentation/swift/codable) to handle the converting between JSON input parameters and response types to native Swift types.\n\n```swift\nstruct Employee: Codable {\n  let id: Int?\n  let name: String?\n}\n// codable main function\nfunc main(input: Employee, respondWith: (Employee?, Error?) -\u003e Void) -\u003e Void {\n    // For simplicity, just passing same Employee instance forward\n    respondWith(input, nil)\n}\n```\n\n### Pre-Compiled Swift Binaries\n\nOpenWhisk supports creating Swift actions from a pre-compiled binary. This reduces startup time for Swift actions by removing the need for a dynamic compilation step.\n\nIn the `serverless.yaml` file, the `handler` property can refer to the zip file containing a binary file produced by the build.\n\n```yaml\nfunctions:\n  hello:\n    handler: action.zip\n```\n\nCompiling a single Swift file to a binary can be handled using this Docker command with the OpenWhisk Swift runtime image. `main.swift` is the file containing the swift code and `action.zip` is the zip archive produced.\n\n```\ndocker run -i openwhisk/action-swift-v4.2 -compile main \u003c main.swift \u003e action.zip\n```\n\nSwift packages containing multiple source files with a package descriptor (`Package.swift` ) can be built using the following command.\n\n```\nzip - -r * | docker run -i openwhisk/action-swift-v4.2 -compile main \u003e action.zip\n```\n\n## Writing Functions - Java\n\nHere's an `src/main/java/HelloWorld.java` file containing an example handler function.\n\n```java\nimport com.google.gson.JsonObject;\n\npublic class HelloWorld {\n\n  public static JsonObject main(JsonObject args) throws Exception {\n\n    final String name = args.getAsJsonPrimitive(\"name\").getAsString();\n\n    final JsonObject response = new JsonObject();\n    response.addProperty(\"greeting\", \"Hello \" + name + \"!\");\n\n    return response;\n  }\n}\n```\n\nHere is a simple `pom.xml` file that will allow you to use Maven to build it. You will notice that `gson` is excluded from the uberjar. That is because OpenWhisk already provides this dependency.\n\n```xml\n\u003cproject\u003e\n \u003cmodelVersion\u003e4.0.0\u003c/modelVersion\u003e\n \u003cgroupId\u003ehello\u003c/groupId\u003e\n \u003cartifactId\u003ehello-world\u003c/artifactId\u003e\n \u003cversion\u003e1.0\u003c/version\u003e\n\n \u003cdependencies\u003e\n  \u003cdependency\u003e\n    \u003cgroupId\u003ecom.google.code.gson\u003c/groupId\u003e\n    \u003cartifactId\u003egson\u003c/artifactId\u003e\n    \u003cversion\u003e2.8.2\u003c/version\u003e\n  \u003c/dependency\u003e\n  \u003c/dependencies\u003e\n\n  \u003cbuild\u003e\n    \u003cplugins\u003e\n      \u003cplugin\u003e\n        \u003cgroupId\u003eorg.apache.maven.plugins\u003c/groupId\u003e\n        \u003cartifactId\u003emaven-shade-plugin\u003c/artifactId\u003e\n        \u003cversion\u003e3.1.0\u003c/version\u003e\n        \u003cexecutions\u003e\n          \u003cexecution\u003e\n            \u003cphase\u003epackage\u003c/phase\u003e\n            \u003cgoals\u003e\n              \u003cgoal\u003eshade\u003c/goal\u003e\n            \u003c/goals\u003e\n            \u003cconfiguration\u003e\n              \u003cminimizeJar\u003etrue\u003c/minimizeJar\u003e\n              \u003cartifactSet\u003e\n                \u003cexcludes\u003e\n                  \u003cexclude\u003ecom.google.code.gson:gson\u003c/exclude\u003e\n                \u003c/excludes\u003e\n              \u003c/artifactSet\u003e\n            \u003c/configuration\u003e\n          \u003c/execution\u003e\n        \u003c/executions\u003e\n      \u003c/plugin\u003e\n    \u003c/plugins\u003e\n  \u003c/build\u003e\n \u003c/project\u003e\n```\n\nIn the `serverless.yaml` file (see below), the `handler` property is the uberjar produced by calling `mvn clean package`, a colon, and then the fully qualified class name of the class with the main function. If you do not provide a class name after the jar, it will look for a class in the default package called `Main`.\n\n```yaml\nservice: my-java-service\nprovider:\n  name: openwhisk\n  runtime: java\nfunctions:\n  hello:\n    handler: target/hello-world-1.0.jar:HelloWorld\nplugins:\n  - serverless-openwhisk\n```\n\n### Request Properties\n\nOpenWhisk executes the handler function for each request. This function is called with a single argument, a `com.google.gson.JsonObject` [containing the request properties](https://github.com/openwhisk/openwhisk/blob/master/docs/actions.md#passing-parameters-to-an-action).\n\n```java\nimport com.google.gson.JsonObject;\n\npublic class MyActionClass {\n  public static JsonObject main(JsonObject args) throws Exception\n  {\n    final String name = args.getAsJsonPrimitive(\"name\").getAsString();\n    ...\n  }\n}\n```\n\n### Function Return Values\n\nThe handler must return an `com.google.gson.JsonObject` from the function call.\n\n```java\nimport com.google.gson.JsonObject;\n\npublic class MyActionClass {\n  public static JsonObject main(JsonObject args) throws Exception\n  {\n    ...\n    final JsonObject response = new JsonObject();\n    response.addProperty(\"greeting\", \"Hello \" + name + \"!\");\n\n    return response;\n  }\n}\n```\n\nIf you want to return an error message, throw an exception.\n\n## Writing Functions - Binary\n\nOpenWhisk supports executing a compiled binary for the function handler. Using a Python wrapper, the file will be invoked within the `openwhisk/dockerskeleton` Docker container.\n\nThe binary must be compiled for the correct platform architecture and only link to shared libraries installed in the `openwhisk/dockerskeleton` runtime.\n\nIn the `serverless.yaml` file, the `handler` property is used to denote the binary file to upload.\n\n```yaml\nfunctions:\n  my_function:\n    handler: bin_file\n    runtime: binary\n```\n\n### Request Properties\n\nOpenWhisk executes the binary file for each request. Event parameters are streamed to `stdio` as a JSON object string.\n\n### Function Return Values\n\nThe handler must write a JSON object string with the response parameters to `stdout` before exiting.\n\nIf you want to return an error message, return an object with an `error` property with the message.\n\n## Custom Runtime Images\n\nOpenWhisk actions can use [custom Docker images as the runtime environment](https://medium.com/openwhisk/large-applications-on-openwhisk-bcf15bff94ec). This allows extra packages, libraries or tools to be pre-installed in the runtime environment. Using a custom runtime image, with extra libraries and dependencies built-in, is useful for overcoming the [maximum deployment size](https://github.com/apache/incubator-openwhisk/blob/master/docs/reference.md#system-limits) on actions.\n\n*Images must implement the [API used by the platform](http://jamesthom.as/blog/2017/01/16/openwhisk-docker-actions/) to interact with runtime environments. Images must also be available on Docker Hub. OpenWhisk does not support private Docker registries.*\n\nOpenWhisk publishes the [existing runtime images on Docker Hub](https://hub.docker.com/r/openwhisk/). Using these images in the `FROM` directive in the `Dockerfile` is an easy way to [create new images](https://docs.docker.com/engine/reference/commandline/build/) compatible with the platform.\n\nIn the `serverless.yaml` file, the `image` property is used to denote the custom runtime image.\n\n```yaml\nfunctions:\n  my_function:\n    handler: source.js\n    runtime: nodejs\n    image: dockerhub_user/image_name\n```\n\n*Node.js, Swift, Python and Binary runtimes support using a custom image property.*\n\n## Writing Functions - Docker\n\nOpenWhisk supports creating actions from public images on Docker Hub without handler files. These images are expected to support the platform API used to instantiate and invoke serverless functions.\n\nAll necessary files for execution must be provided within the image. Local source files will not be uploaded to the runtime environment.\n\nIn the `serverless.yaml` file, the `handler` property is used to denote the image label.\n\n```yaml\nfunctions:\n  my_function:\n    handler: repo/image_name\n    runtime: docker\n```\n\n## Working With Packages\n\nOpenWhisk provides a concept called \"packages\" to manage related actions. Packages can contain multiple actions under a common identifier in a namespace. Configuration values needed by all actions in a package can be set as default properties on the package, rather than individually on each action.\n\n*Packages are identified using the following format:* `/namespaceName/packageName/actionName`.\n\n***Rules and triggers can not be created within packages.***\n\n### Implicit Packages\n\nActions can be assigned to packages by setting the function `name` with a package reference.\n\n```yaml\nfunctions:\n  foo:\n    handler: handler.foo\n    name: \"myPackage/foo\"\n  bar:\n    handler: handler.bar\n    name: \"myPackage/bar\"\n```\n\nIn this example, two new actions (`foo` \u0026 `bar`) will be created using the `myPackage` package.\n\nPackages which do not exist will be automatically created during deployments. When using the `remove` command, any packages referenced in the `serverless.yml` will be deleted.\n\n### Explicit Packages\n\nPackages can also be defined explicitly to set shared configuration parameters. Default package parameters are merged into event parameters for each invocation.\n\n```yaml\nfunctions:\n  foo:\n    handler: handler.foo\n    name: \"myPackage/foo\"\n\nresources:\n  packages:\n    myPackage:\n      name: optionalCustomName\n      parameters:\n        hello: world\n```\n\n*Explicit packages support the following properties: `name`, `parameters`, `annotations`, `services` and `shared`.*\n\n### Binding Packages\n\nOpenWhisk also supports \"binding\" external packages into your workspace. Bound packages can have default parameters set for shared actions.\n\nFor example, binding the `/whisk.system/cloudant` package into a new package allows you to set default values for the `username`, `password` and `dbname` properties. Actions from this package can then be invoked with having to pass these parameters in.\n\nDefine packages explicitly with a `binding` parameter to use this behaviour.\n\n```yaml\nresources:\n  packages:\n    mySamples:\n      binding: /whisk.system/cloudant\n      parameters:\n        username: bernie\n        password: sanders\n        dbname: vermont\n```\n\nFor more details on package binding, please see the documentation [here](https://github.com/apache/incubator-openwhisk/blob/master/docs/packages.md#creating-and-using-package-bindings).\n\n## Binding Services (IBM Cloud Functions)\n\n***This feature requires the [IBM Cloud CLI](https://console.bluemix.net/docs/cli/reference/bluemix_cli/download_cli.html#download_install) and [IBM Cloud Functions plugin](https://console.bluemix.net/openwhisk/learn/cli) to be installed.***\n\nIBM Cloud Functions supports [automatic binding of service credentials](https://console.bluemix.net/docs/openwhisk/binding_services.html#binding_services) to actions using the CLI.\n\nBound service credentials will be passed as the `__bx_creds` parameter in the invocation parameters.\n\nThis feature is also available through the `serverless.yaml` file using the `bind` property for each function.\n\n```yaml\nfunctions:\n  my_function:\n    handler: file_name.handler    \n    bind:\n      - service:\n          name: cloud-object-storage\n          instance: my-cos-storage\n```\n\nThe `service` configuration supports the following properties.\n\n- `name`: identifier for the cloud service\n- `instance`: instance name for service (*optional*)\n- `key`: key name for instance and service (*optional*)\n\n*If the `instance` or `key` properties are missing, the first available instance and key found will be used.*\n\nBinding services removes the need to manually create default parameters for service keys from platform services.\n\nMore details on binding service credentials to actions can be found in the [official documentation](https://console.bluemix.net/docs/openwhisk/binding_services.html#binding_services) and [this blog post](http://jamesthom.as/blog/2018/06/05/binding-iam-services-to-ibm-cloud-functions/).\n\nPackages defined in the `resources` section can bind services using the same configuration properties.\n\n```yaml\nresources:\n  packages:\n    myPackage:\n      bind:\n        - service:\n            name: cloud-object-storage\n            instance: my-cos-storage\n```\n\n## Runtime Configuration Properties\n\nThe following OpenWhisk configuration properties are supported for functions defined in\nthe `serverless.yaml` file.\n\n```yaml\nfunctions:\n  my_function:\n    handler: file_name.handler_func\n    name: \"custom_function_name\"\n    runtime: 'runtime_label' // defaults to nodejs:default\n    namespace: \"...\" // defaults to user-provided credentials\n    memory: 256 // 128 to 512 (MB).\n    timeout: 60 // 0.1 to 600 (seconds)\n    concurrency: 1 // 1 to 500, default is 1\n    parameters:\n      foo: bar // default parameters\n    annotations:\n      foo: bar // action annotations\n    bind:\n      - service:\n          name: cloud-object-storage\n          instance: my-cos-storage\n```\n\n## Writing Sequences\n\nOpenWhisk supports a special type of serverless function called [sequences](https://github.com/openwhisk/openwhisk/blob/master/docs/actions.md#creating-action-sequences).\n\nThese functions are defined from a list of other serverless functions. Upon invocation, the platform executes each function in series. Request parameters are passed into the first function in the list. Each subsequent function call is passed the output from the previous step as input parameters. The last function's return value is returned as the response result.\n\nHere's an example of the configuration to define a sequence function, composed of three other functions.\n\n```yaml\nfunctions:\n  my_function:\n    sequence:\n      - parse_input\n      - do_some_algorithm\n      - construct_output\n```\n\n*Sequence functions do not have a handler file defined. If you want to refer to functions not defined in the serverless project, use the fully qualified identifier e.g. /namespace/package/action_name*\n\n## Connecting HTTP Endpoints\n\nFunctions can be bound to public URL endpoints using the [API Gateway service](https://github.com/openwhisk/openwhisk/blob/master/docs/apigateway.md). HTTP requests to configured endpoints will invoke functions on-demand. Requests parameters are passed as function arguments. Function return values are serialised as the JSON response body.\n\nHTTP endpoints for functions can be configured through the `serverless.yaml` file.\n\n```yaml\nfunctions:\n  my_function:\n    handler: index.main\n    events:\n      - http: GET /api/greeting\n```\n\nHTTP event configuration also supports using explicit parameters.\n\n- `method` - HTTP method (mandatory).\n- `path` - URI path for API gateway (mandatory).\n- `resp` - controls [web action content type](https://github.com/apache/incubator-openwhisk/blob/master/docs/webactions.md#additional-features), values include: `json`, `html`, `http`, `svg`or `text` (optional, defaults to `json`).\n\n```yaml\nfunctions:\n  my_function:\n    handler: index.main\n    events:\n      - http:\n          method: GET\n          path: /api/greeting\n          resp: http\n```\n\nAPI Gateway hosts serving the API endpoints will be shown during deployment.\n\n```shell\n$ serverless deploy\n...\nendpoints:\nGET https://xxx-gws.api-gw.mybluemix.net/service_name/api/greeting --\u003e service_name-dev-my_function\n```\n\nCalling the configured API endpoints will execute the deployed functions.\n\n````shell\n$ http get https://xxx-gws.api-gw.mybluemix.net/api/greeting?user=\"James Thomas\"\nHTTP/1.1 200 OK\nContent-Type: application/json; charset=UTF-8\nDate: Mon, 19 Dec 2016 15:47:53 GMT\n\n{\n    \"message\": \"Hello James Thomas!\"\n}\n````\n\nFunctions exposed through the API Gateway service are automatically converted into Web Actions during deployment. The framework [secures Web Actions for HTTP endpoints](https://github.com/apache/incubator-openwhisk/blob/master/docs/webactions.md#securing-web-actions) using the `require-whisk-auth` annotation. If the `require-whisk-auth` annotation is manually configured, the existing annotation value is used, otherwise a random token is automatically generated.\n\n### URL Path Parameters\n\nThe API Gateway service [supports path parameters]() in user-defined HTTP paths. This allows functions to handle URL paths which include templated values, like resource identifiers.\n\nPath parameters are identified using the `{param_name}` format in the URL path. The API Gateway sends the full matched path value in the `__ow_path` field of the event parameters.\n\n```yaml\nfunctions:\n  retrieve_users:\n    handler: users.get\n    events:\n      - http:\n          method: GET\n          path: /users/{id}\n          resp: http\n```\n\nThis feature comes with the following restrictions:\n\n- *Path parameters are only supported when `resp` is configured as`http`.*\n- *Individual path parameter values are not included as separate event parameters. Users have to manually parse values from the full `__ow_path` value.*\n\n### CORS Support\n\nAPI Gateway endpoints automatically include CORS headers for all endpoints under the service base path. This property can be disabled by manually configuring the `resources.apigw.cors` property.\n\n```yaml\nresources:\n    apigw:\n        cors: false\n```\n\n### Application Authentication\n\nAPI endpoints can be protected by API keys with a secret or API keys alone.\n\nSetting the HTTP headers used to pass keys and secrets automatically enables API Gateway authentication.\n\nThis parameter configures the HTTP header containing the API key. Without the additional secret header, authentication uses an API key alone.\n\n```yaml\nresources:\n    apigw:\n        auth:\n            key: API-Key-Header\n```\n\nAdding the secret header parameter enables authentication using keys with secrets.\n\n```yaml\nresources:\n    apigw:\n        auth:\n            key: API-Key-Header\n            secret: API-Key-Secret-Header\n```\n\n*See the API Gateway [configuration panel](https://cloud.ibm.com/openwhisk/apimanagement) to manage API keys and secrets after authentication is enabled.* \n\n### Application Authentication with OAuth\n\nAPI endpoints can also be protected by an external OAuth providers. \n\nOAuth tokens must be included as the Authorization header of each API request. Token will be validated with the specified token provider. If the token is invalid, requests are rejected with response code 401.\n\nThe following OAuth providers are supported: *[IBM Cloud App ID](https://cloud.ibm.com/catalog/services/app-id), Google, Facebook and Github.*\n\n```yaml\nresources:\n  apigw:\n    oauth:\n      provider: app-id || google || facebook || github\n```\n\nIf the `app-id` provider is selected, the tenant identifier must be provided as an additional configuration token. This can be retrieved from the `tenantId` property of provisioned service credentials for the instance\n\n```yaml\nresources:\n  apigw:\n    oauth:\n      provider: app-id\n      tenant: uuid\n```\n\n*Application Authentication with keys (and secrets) and OAuth support are mutually exclusive configuration options.*\n\n### Rate Limiting\n\nAPI Gateways endpoints support rate limiting to reject excess traffic. When rate limiting is enabled,  API calls falling outside of the limit will be rejected and response code 429 will be returned.\n\n**Rate limiting is on a per-key basis and application authentication (without oauth) must be enabled.**\n\nThe  leaky bucket algorithm is used to prevent sudden bursts of invocations of APIs. If the limit is set as 10 calls per minute, users will be restricted to 1 call every 6 seconds (60/10 = 6).\n\n```yaml\nresources:\n  apigw:\n    rate_limit:\n      rate: 100\n      unit: minute || second || hour || day\n```\n\n- `rate`: number of API calls per unit of time.\n- `unit`: unit of time (*minute, second, hour, day*) used to threshold API calls with rate.\n\n### Base Path\n\nAll API Gateway endpoints defined as HTTP events in the `serverless.yml` are deployed under the default base path (`/`). This basepath can be configured explicitly using the following parameter.\n\n```yaml\nresources:\n  apigw:\n    basepath: /api\n```\n\n### API Name\n\nThe service name is used as the API identifier in the API Gateway swagger files. This can be configured explicitly using the following parameter.\n\n```yaml\nresources:\n  apigw:\n    name: my-api-name\n```\n\n## Exporting Web Actions\n\nFunctions can be turned into \"*web actions*\" which return HTTP content without use of an API Gateway. This feature is enabled by setting an annotation (`web-export`) in the configuration file.\n\n```yaml\nfunctions:\n  my_function:\n    handler: index.main\n    annotations:\n      web-export: true\n```\n\nFunctions with this annotation can be invoked through a URL template with the following parameters.\n\n```\nhttps://{APIHOST}/api/v1/web/{USER_NAMESPACE}/{PACKAGE}/{ACTION_NAME}.{TYPE}\n```\n\n- *APIHOST* - platform endpoint e.g. *openwhisk.ng.bluemix.net.*\n- *USER_NAMESPACE* - this must be an explicit namespace and cannot use the default namespace (_).\n- *PACKAGE* - action package or `default`.\n- *ACTION_NAME* - default form `${servicename}-${space}-${name}`.\n- *TYPE* - `.json`, `.html`, `.text` or `.http`.\n\nReturn values from the function are used to construct the HTTP response. The following parameters are supported.\n\n1. `headers`: a JSON object where the keys are header-names and the values are string values for those headers (default is no headers).\n2. `code`: a valid HTTP status code (default is 200 OK).\n3. `body`: a string which is either plain text or a base64 encoded string (for binary data).\n\nHere is an example of returning HTML content:\n\n```\nfunction main(args) {\n    var msg = \"you didn\u0026#39;t tell me who you are.\"\n    if (args.name) {\n        msg = `hello ${args.name}!`\n    }\n    return {body:\n       `\u003chtml\u003e\u003cbody\u003e\u003ch3\u003e\u003ccenter\u003e${msg}\u003c/center\u003e\u003c/h3\u003e\u003c/body\u003e\u003c/html\u003e`}\n}\n```\n\nHere is an example of returning binary data:\n\n```\nfunction main() {\n   let png = \u003cbase 64 encoded string\u003e\n   return {\n      headers: { \"Content-Type\": \"image/png\" },\n      body: png };\n}\n```\n\nFunctions can access request parameters using the following environment variables.\n\n1. `__ow_method` - HTTP method of the request.\n2. `__ow_headers` - HTTP request headers.\n3. `__ow_path` - Unmatched URL path of the request.\n4. `__ow_body` - Body entity from request.\n5. `__ow_query` - Query parameters from the request.\n\n**Full details on this feature are available in this [here](https://github.com/apache/incubator-openwhisk/blob/master/docs/webactions.md).**\n\n## Scheduled Invocations\n\nFunctions can be set up to fire automatically using the [alarm package](https://github.com/openwhisk/openwhisk/blob/master/docs/catalog.md#using-the-alarm-package). This allows you to invoke functions with preset parameters at specific times (*12:00 each day*) or according to a schedule (*every ten minutes*).\n\nScheduled invocation for functions can be configured through the `serverless.yaml` file.\n\nThe `schedule` event configuration is controlled by a string, based on the UNIX crontab syntax, in the format `cron(X X X X X)`. This can either be passed in as a native string or through the `rate` parameter.\n\n```yaml\nfunctions:\n  my_function:\n    handler: index.main\n    events:\n      - schedule: cron(* * * * *) // fires each minute.\n```\n\nThis above example generates a new trigger (`${service}_crawl_schedule_trigger`) and rule (`${service}_crawl_schedule_rule`) during deployment.\n\nOther `schedule` event parameters can be manually configured, e.g trigger or rule names.\n\n```yaml\nfunctions:\n  aggregate:\n    handler: statistics.handler\n    events:\n      - schedule:\n          rate: cron(0 * * * *) // call once an hour\n          trigger: triggerName\n          rule: ruleName\n          max: 10000 // max invocations, default: 1000, max: 10000\n          params: // event params for invocation\n            hello: world\n```\n\n## IBM Message Hub Events\n\nIBM Bluemix provides an \"Apache Kafka\"-as-a-Service called IBM Message Hub. Functions can be connected to fire when messages arrive on Kafka topics.\n\nIBM Message Hub instances can be provisioned through the IBM Bluemix platform. OpenWhisk on Bluemix will export Message Hub service credentials bound to a package with the following name:\n\n```\n/${BLUEMIX_ORG}_${BLUEMIX_SPACE}/Bluemix_${SERVICE_NAME}_Credentials-1\n```\n\nRather than having to manually define all the properties needed by the Message Hub trigger feed, you can reference a package to use instead. Credentials from the referenced package will be used when executing the trigger feed.\n\nDevelopers only need to add the topic to listen to for each trigger.\n\n```yaml\n# serverless.yaml\nfunctions:\n    index:\n        handler: users.main\n        events:\n            - message_hub:\n                package: /${BLUEMIX_ORG}_${BLUEMIX_SPACE}/Bluemix_${SERVICE_NAME}_Credentials-1\n                topic: my_kafka_topic\n\n```\n\nThe plugin will create a trigger called `${serviceName}_${fnName}_messagehub_${topic}` and a rule called `${serviceName}_${fnName}_messagehub_${topic}_rule` to bind the function to the message hub events.\n\nThe trigger and rule names created can be set explicitly using the `trigger` and`rule` parameters.\n\nOther functions can bind to the same trigger using the inline `trigger` event referencing this trigger name.\n\n```yaml\n# serverless.yaml\nfunctions:\n    index:\n        handler: users.main\n        events:\n            - message_hub:\n                package: /${BLUEMIX_ORG}_${BLUEMIX_SPACE}/Bluemix_${SERVICE_NAME}_Credentials-1\n                topic: my_kafka_topic\n                trigger: log_events\n                rule: connect_index_to_kafka\n     another:\n        handler: users.another\n        events:\n            - trigger: log_events\n```\n\n### Using Manual Parameters\n\nParameters for the Message Hub event source can be defined explicitly, rather than using pulling credentials from a package.\n\n```yaml\n# serverless.yaml\nfunctions:\n    index:\n        handler: users.main\n        events:\n            - message_hub:\n                topic: my_kafka_topic\n                brokers: afka01-prod01.messagehub.services.us-south.bluemix.net:9093\n                user: USERNAME\n                password: PASSWORD\n                admin_url:  https://kafka-admin-prod01.messagehub.services.us-south.bluemix.net:443\n                json: true\n                binary_key: true\n                binary_value: true\n```\n\n`topic`, `brokers`, `user`, `password` and `admin_url` are mandatory parameters.\n\n## Cloudant DB Events\n\nIBM Cloudant provides a hosted NoSQL database, based upon CouchDB, running on IBM Bluemix. Functions can be connected to events fired when the database is updated. These events use the [CouchDB changes feed](http://guide.couchdb.org/draft/notifications.html) to follow database modifications.\n\nIBM Cloudant instances can be provisioned through the IBM Bluemix platform. OpenWhisk on Bluemix will export Cloudant service credentials bound to a package with the following name:\n\n```\n/${BLUEMIX_ORG}_${BLUEMIX_SPACE}/Bluemix_${SERVICE_NAME}_Credentials-1\n```\n\nRather than having to manually define all the properties needed by the [Cloudant trigger feed](https://github.com/openwhisk/openwhisk-package-cloudant#using-the-cloudant-package), you can reference a package to use instead. Credentials from the referenced package will be used when executing the trigger feed.\n\nDevelopers only need to add the database name to follow for modifications.\n\n```yaml\n# serverless.yaml\nfunctions:\n    index:\n        handler: users.main\n        events:\n            - cloudant:\n                package: /${BLUEMIX_ORG}_${BLUEMIX_SPACE}/Bluemix_${SERVICE_NAME}_Credentials-1\n                db: my_db_name\n\n```\n\nThe plugin will create a trigger called `${serviceName}_${fnName}_cloudant_${topic}` and a rule called `${serviceName}_${fnName}_cloudant_${topic}_rule` to bind the function to the Cloudant update events.\n\nThe trigger and rule names created can be set explicitly using the `trigger` and`rule` parameters.\n\nOther functions can bind to the same trigger using the inline `trigger` event referencing this trigger name.\n\n### Using Manual Parameters\n\nParameters for the Cloudant event source can be defined explicitly, rather than using pulling credentials from a package.\n\n```yaml\n# serverless.yaml\nfunctions:\n    index:\n        handler: users.main\n        events:\n            - cloudant: // basic auth example\n                host: xxx-yyy-zzz-bluemix.cloudant.com\n                username: USERNAME\n                password: PASSWORD\n                db: db_name\n\t\t\t- cloudant: // iam auth example\n                host: xxx-yyy-zzz-bluemix.cloudant.com\n                iam_api_key: IAM_API_KEY\n                db: db_name\n```\n\n `username` and `password` or `iam_api_key` parameters can be used for authentication.\n\n### Adding Optional Parameters\n\nThe following optional feed parameters are also supported:\n\n* `max` - Maximum number of triggers to fire. Defaults to infinite.\n* `filter` - Filter function defined on a design document.\n* `query` - Optional query parameters for the filter function.\n\n```yaml\n# serverless.yaml\nfunctions:\n    index:\n        handler: users.main\n        events:\n            - cloudant:\n                ...\n                max: 10000\n                query:\n                   status: new\n                filter: mailbox/by_status\n```\n\n## Custom Event Triggers\n\nFunctions are connected to event sources in OpenWhisk [using triggers and rules](https://github.com/openwhisk/openwhisk/blob/master/docs/triggers_rules.md). Triggers create a named event stream within the system. Triggers can be fired manually or connected to external data sources, like databases or message queues.\n\nRules set up a binding between triggers and serverless functions. With an active rule, each time a trigger is fired, the function will be executed with the trigger payload.\n\nEvent binding for functions can be configured through the `serverless.yaml` file.\n\n```yaml\nfunctions:\n  my_function:\n    handler: index.main\n    events:\n      - trigger: my_trigger\n```\nThis configuration will create a trigger called `servicename-my_trigger` with an active rule binding `my_function` to this event stream.\n\n### Customising Rules\n\nRule names default to the following format `servicename-trigger-to-action`. These names be explicitly set through configuration.\n\n```yaml\nfunctions:\n  my_function:\n    handler: index.main\n    events:\n      - trigger:\n        name: \"my_trigger\"\n        rule: \"rule_name\"\n```\n\n### Customing Triggers\n\nTriggers can be defined as separate resources in the `serverless.yaml` file. This allows you to set up trigger properties like default parameters.\n\n```yaml\nfunctions:\n  my_function:\n    handler: index.main\n    events:\n      - trigger: my_trigger\n\nresources:\n  triggers:\n    my_trigger:\n      parameters:\n        hello: world            \n```\n\n### Trigger Feeds\n\nTriggers can be bound to external event sources using the `feed` property. OpenWhisk [provides a catalogue](https://github.com/openwhisk/openwhisk/blob/master/docs/catalog.md) of third-party event sources bundled as [packages](https://github.com/openwhisk/openwhisk/blob/master/docs/packages.md#creating-and-using-trigger-feeds).\n\nThis example demonstrates setting up a trigger which uses the `/whisk.system/alarms/alarm` feed. The `alarm` feed will fire a trigger according to a user-supplied cron schedule.\n\n```yaml\nresources:\n  triggers:\n    alarm_trigger:\n      parameters:\n        hello: world\n      feed: /whisk.system/alarms/alarm\n      feed_parameters:\n        cron: '*/8 * * * * *'\n```\n\n## Commands\n\nThe following serverless commands are currently implemented for the OpenWhisk provider.\n\n- `deploy` - [Deploy functions, triggers and rules for service](https://serverless.com/framework/docs/providers/openwhisk/cli-reference/deploy/).\n- `invoke`- [Invoke deployed serverless function and show result](https://serverless.com/framework/docs/providers/openwhisk/cli-reference/invoke/).\n- `invokeLocal`- [Invoke serverless functions locally and show result](https://serverless.com/framework/docs/providers/openwhisk/cli-reference/invoke#invoke-local).\n- `remove` - [Remove functions, triggers and rules for service](https://serverless.com/framework/docs/providers/openwhisk/cli-reference/remove/).\n- `logs` - [Display activation logs for deployed function](https://serverless.com/framework/docs/providers/openwhisk/cli-reference/logs/).\n- `info` - [Display details on deployed functions, triggers and rules](https://serverless.com/framework/docs/providers/openwhisk/cli-reference/info/).\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fserverless%2Fserverless-openwhisk","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fserverless%2Fserverless-openwhisk","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fserverless%2Fserverless-openwhisk/lists"}