Adding documentation for 0.5 release on openwhisk plugin.

New event sources for Cloudant and Message Hub. Support using plugin with local OpenWhisk deployments. Web Actions section for HTTP events without API Gw.
dudutou · Mar 11, 2017 · 9c194ec · 9c194ec
1 parent a42d7b3
commit 9c194ec
Show file tree

Hide file tree

Showing 7 changed files with 323 additions and 3 deletions.
diff --git a/docs/README.md b/docs/README.md
@@ -126,6 +126,7 @@ The Serverless Framework allows you to deploy auto-scaling, pay-per-execution, e
         <li><a href="./providers/openwhisk/guide/variables.md">Variables</a></li>
         <li><a href="./providers/openwhisk/guide/packaging.md">Packaging</a></li>
         <li><a href="./providers/openwhisk/guide/plugins.md">Plugins</a></li>
+        <li><a href="./providers/openwhisk/guide/web-actions.md">Web Actions</a></li>
         <li><a href="./providers/openwhisk/guide/workflow.md">Workflow</a></li>
         <li><a href="./providers/openwhisk/guide/serverless.yml.md">Serverless.yml</a></li>
       </ul>
@@ -164,6 +165,8 @@ The Serverless Framework allows you to deploy auto-scaling, pay-per-execution, e
     <div>
       <ul>
         <li><a href="./providers/openwhisk/events/apigateway.md">API Gateway</a></li>
+        <li><a href="./providers/openwhisk/events/cloudant.md">Cloudant DB</a></li>
+        <li><a href="./providers/openwhisk/events/messagehub.md">Message Hub</a></li>
         <li><a href="./providers/openwhisk/events/schedule.md">Schedule</a></li>
         <li><a href="./providers/openwhisk/events/triggers.md">Triggers</a></li>
       </ul>

diff --git a/docs/providers/openwhisk/cli-reference/info.md b/docs/providers/openwhisk/cli-reference/info.md
@@ -51,6 +51,5 @@ rules:
 my-hello-world-event-rule
 
 endpoints:
-https://xyz1234-gws.api-gw.mybluemix.net
-/hello-world GET -> hello-world
+GET https://xxx-gws.api-gw.mybluemix.net/api/path --> hello-world-dev-helloWorld
 ```
diff --git a/docs/providers/openwhisk/events/cloudant.md b/docs/providers/openwhisk/events/cloudant.md
@@ -0,0 +1,111 @@
+<!--
+title: Serverless Framework - Apache OpenWhisk Events - Cloudant DB
+menuText: Cloudant
+menuOrder: 4
+description: Follow database modification events from IBM Cloudant with Apache OpenWhisk via the Serverless Framework
+layout: Doc
+-->
+
+<!-- DOCS-SITE-LINK:START automatically generated  -->
+### [Read this on the main serverless docs site](https://www.serverless.com/framework/docs/providers/openwhisk/events/cloudant)
+<!-- DOCS-SITE-LINK:END -->
+
+# Cloudant
+
+This event allows you to connect functions to [IBM Cloudant](https://cloudant.com/), a NoSQL database-as-a-service based upon [Apache CouchDB](http://couchdb.apache.org/). Functions are invoked for each database modification that occurs. 
+
+This event utilise the trigger feed provided by the [Cloudant package](https://github.com/openwhisk/openwhisk-package-cloudant).
+
+## Setup
+
+[IBM Cloudant](https://cloudant.com/) instances can be provisioned through the [IBM Bluemix](https://console.ng.bluemix.net) platform. OpenWhisk on Bluemix will export Cloudant service credentials bound to a package with the following name:
+
+```
+/${BLUEMIX_ORG}_${BLUEMIX_SPACE}/Bluemix_${SERVICE_NAME}_Credentials-1
+```
+
+## Configuration 
+
+Users need to pass the database credentials and the database name to listen to changes on when defining the event.
+
+### Using Package Credentials
+
+Rather than having to manually define all authentication properties needed by the Cloudant trigger feed, you can reference a package which provides these properties as default parameters.
+
+Developers only need to add the database to listen to for each event.
+
+```yaml
+# serverless.yaml
+functions:
+    index:
+        handler: users.main
+        events:
+            - cloudant: 
+                package: /${BLUEMIX_ORG}_${BLUEMIX_SPACE}/Bluemix_${SERVICE_NAME}_Credentials-1
+                db: db_name
+
+```
+
+The configuration will create a trigger called `${serviceName}_${fnName}_cloudant_${db}` and a rule called `${serviceName}_${fnName}_cloudant_${db}_rule` to bind the function to the database update events.
+
+The trigger and rule names created can be set explicitly using the `trigger` and `rule` parameters.
+
+### Using Manual Parameters
+
+Authentication credentials for the Cloudant event source can be defined explicitly, rather than using pulling credentials from a package.
+
+```yaml
+# serverless.yaml
+functions:
+    index:
+        handler: users.main
+        events:
+            - cloudant: 
+                host: xxx-yyy-zzz-bluemix.cloudant.com
+                username: USERNAME
+                password: PASSWORD
+                db: db_name               
+```
+
+### Binding Multiple Functions
+
+Other functions can bind to the same database event being fired using the inline `trigger` event and referencing this trigger name.
+
+```yaml
+# serverless.yaml
+functions:
+    index:
+        handler: users.main
+        events:
+            - cloudant: 
+                package: /${BLUEMIX_ORG}_${BLUEMIX_SPACE}/Bluemix_${SERVICE_NAME}_Credentials-1
+                db: my_db
+                trigger: db_events
+                rule: connect_index_to_db 
+     another:
+        handler: users.another
+        events:
+            - trigger: db_events 
+```
+
+## Event Details
+
+Functions are invoked with the JSON object returned by the [CouchDB changes feed](http://guide.couchdb.org/draft/notifications.html) for each database modification. The contents of the generated events have the following parameters:
+
+- `id`: The document ID.
+- `seq`: The sequence identifier that is generated by Cloudant.
+- `changes`: An array of objects, each of which has a `rev` field that contains the revision ID of the document.
+
+The JSON representation of the trigger event is as follows:
+
+```json
+{
+    "id": "6ca436c44074c4c2aa6a40c9a188b348",
+    "seq": "2-g1AAAAL9aJyV-GJCaEuqx4-BktQkYp_dmIfC",
+    "changes": [
+        {
+            "rev": "2-da3f80848a480379486fb4a2ad98fa16"
+        }
+    ]
+}
+```
diff --git a/docs/providers/openwhisk/events/messagehub.md b/docs/providers/openwhisk/events/messagehub.md
@@ -0,0 +1,118 @@
+<!--
+title: Serverless Framework - Apache OpenWhisk Events - IBM Message Hub
+menuText: Message Hub
+menuOrder: 4
+description: Follow Apache Kafka queue messages from IBM's Message Hub service with Apache OpenWhisk via the Serverless Framework
+layout: Doc
+-->
+
+<!-- DOCS-SITE-LINK:START automatically generated  -->
+### [Read this on the main serverless docs site](https://www.serverless.com/framework/docs/providers/openwhisk/events/messagehub)
+<!-- DOCS-SITE-LINK:END -->
+
+# Message Hub
+
+This event allows you to connect functions to [IBM Message Hub](https://developer.ibm.com/messaging/message-hub/), a scalable message bus in the cloud, based upon [Apache Kafka](https://kafka.apache.org/). Functions are invoked with messages that are added to a Kafka topic.
+
+This event utilise the trigger feed provided by the [Message Hub package](https://github.com/openwhisk/openwhisk-package-kafka).
+
+## Setup
+
+[IBM Message Hub](https://developer.ibm.com/messaging/message-hub/) instances can be provisioned through the [IBM Bluemix](https://console.ng.bluemix.net) platform. OpenWhisk on Bluemix will export Message Hub service credentials bound to a package with the following name:
+
+```
+/${BLUEMIX_ORG}_${BLUEMIX_SPACE}/Bluemix_${SERVICE_NAME}_Credentials-1
+```
+
+## Configuration 
+
+Users need to pass the message hub credentials and the kafka topic to listen for messages on when defining the event.
+
+### Using Package Credentials
+
+Rather than having to manually define all authentication properties needed by the Message Hub trigger feed, you can reference a package which provides these properties as default parameters.
+
+Developers only need to add the kafka topic to listen for messages on with each event.
+
+```yaml
+# serverless.yaml
+functions:
+    index:
+        handler: users.main
+        events:
+            - messagehub: 
+                package: /${BLUEMIX_ORG}_${BLUEMIX_SPACE}/Bluemix_${SERVICE_NAME}_Credentials-1
+                topic: my_kafka_topic
+
+```
+
+*Optional parameters `json`, `binary_key`, `binary_value` are also supported.*
+
+The configuration will create a trigger called `${serviceName}_${fnName}_messagehub_${db}` and a rule called `${serviceName}_${fnName}_messagehub_${db}_rule` to bind the function to the database update events.
+
+The trigger and rule names created can be set explicitly using the `trigger` and `rule` parameters.
+
+### Using Manual Parameters
+
+Authentication credentials for the Message Hub event source can be defined explicitly, rather than using pulling credentials from a package.
+
+```yaml
+# serverless.yaml
+functions:
+    index:
+        handler: users.main
+        events:
+            - message_hub: 
+                topic: my_kafka_topic
+                brokers: afka01-prod01.messagehub.services.us-south.bluemix.net:9093
+                user: USERNAME
+                password: PASSWORD
+                admin_url:  https://kafka-admin-prod01.messagehub.services.us-south.bluemix.net:443
+                json: true
+                binary_key: true
+                binary_value: true         
+```
+
+`topic`, `brokers`, `user`, `password` and `admin_url` are mandatory parameters.
+
+### Binding Multiple Functions
+
+Other functions can bind to the same database event being fired using the inline `trigger` event and referencing this trigger name.
+
+```yaml
+# serverless.yaml
+functions:
+    index:
+        handler: users.main
+        events:
+            - message_hub: 
+                package: /${BLUEMIX_ORG}_${BLUEMIX_SPACE}/Bluemix_${SERVICE_NAME}_Credentials-1
+                topic: my_kafka_topic
+                trigger: log_events
+                rule: connect_index_to_kafka 
+     another:
+        handler: users.another
+        events:
+            - trigger: log_events 
+```
+
+## Event Details
+
+The payload of that trigger event will contain a `messages` field which is an array of messages that have been posted since the last time your trigger fired. 
+
+The JSON representation of a sample event is as follows:
+
+```json
+{
+    "messages": [
+        {
+            "partition": 0,
+            "key": "U29tZSBrZXk=",
+            "offset": 421760,
+            "topic": "mytopic",
+            "value": "Some value"
+        }
+    ]
+}
+```
+For more details on the exact semantics of the message properties, please see the [trigger feed documentation](https://github.com/openwhisk/openwhisk-package-kafka).
diff --git a/docs/providers/openwhisk/guide/credentials.md b/docs/providers/openwhisk/guide/credentials.md
@@ -70,6 +70,17 @@ cd openwhisk/tools/vagrant
 
 This platform will now be running inside a virtual machine at the following IP address: `192.168.33.13`
 
+**Please note:** *If you are using a self-hosted platform, the `ignore_certs` property in `serverless.yaml` needs to be `true`. This allows the client to be used against local deployments of OpenWhisk with a self-signed certificate.* 
+
+```yaml
+service: testing
+provider:
+  name: openwhisk
+  ignore_certs: true
+functions:
+  ...
+```
+
 ### Access Account Credentials
 
 The default environment has a guest account configured with the authentication key available here: https://github.com/openwhisk/openwhisk/blob/master/ansible/files/auth.guest

diff --git a/docs/providers/openwhisk/guide/serverless.yml.md b/docs/providers/openwhisk/guide/serverless.yml.md
@@ -28,6 +28,7 @@ provider:
   timeout: 10 # The default is 60  
   overwrite: true # Can we overwrite deployed functions? default is true
   namespace: 'custom' # use custom namespace, defaults to '_'
+  ignore_certs: true # ignore ssl verification issues - used for local deploys
 
 functions:
   usersCreate: # A Function
@@ -41,6 +42,8 @@ functions:
     runtime: nodejs:6
     overwrite: false # Can we overwrite deployed function? 
     namespace: 'custom' # use custom namespace, defaults to '_'
+    annotations:
+        parameter_name: value
     events: # The Events that trigger this Function
     # This creates an API Gateway HTTP endpoint which can be used to trigger this function.  Learn more in "events/apigateway"
       - http: METHOD /path/to/url
@@ -61,5 +64,4 @@ resources:
       feed: /whisk.system/alarms/alarm
       feed_parameters: 
         cron: '*/8 * * * * *'
-
 ```
diff --git a/docs/providers/openwhisk/guide/web-actions.md b/docs/providers/openwhisk/guide/web-actions.md
@@ -0,0 +1,76 @@
+<!--
+title: Serverless Framework - Apache OpenWhisk Guide - Web Actions
+menuText: Web Actions
+menuOrder: 6
+description: Configuring Apache OpenWhisk Web Actions in the Serverless Framework
+layout: Doc
+-->
+
+<!-- DOCS-SITE-LINK:START automatically generated  -->
+### [Read this on the main serverless docs site](https://www.serverless.com/framework/docs/providers/openwhisk/guide/web-actions)
+<!-- DOCS-SITE-LINK:END -->
+
+# Web Actions
+
+Functions can be turned into ["*web actions*"](https://github.com/openwhisk/openwhisk/blob/master/docs/actions.md) which return HTTP content without use of an API Gateway. This feature is enabled by setting an annotation (`web-export`) in the configuration file.
+
+```
+functions:
+  my_function:
+    handler: index.main
+    annotations:
+      web-export: true
+```
+
+Functions with this annotation can be invoked through a URL template with the following parameters.
+
+```
+https://{APIHOST}/api/v1/experimental/web/{USER_NAMESPACE}/{PACKAGE}/{ACTION_NAME}.{TYPE}
+
+```
+
+- *APIHOST* - platform endpoint e.g. *openwhisk.ng.bluemix.net.*
+- *USER_NAMESPACE* - this must be an explicit namespace and cannot use the default namespace (_).
+- *PACKAGE* - action package or `default`.
+- *ACTION_NAME* - default form `${servicename}-${space}-${name}`.
+- *TYPE* - `.json`, `.html`, `.text` or `.http`.
+
+Return values from the function are used to construct the HTTP response. The following parameters are supported.
+
+1. `headers`: a JSON object where the keys are header-names and the values are string values for those headers (default is no headers).
+2. `code`: a valid HTTP status code (default is 200 OK).
+3. `body`: a string which is either plain text or a base64 encoded string (for binary data).
+
+Here is an example of returning HTML content:
+
+```javascript
+function main(args) {
+    var msg = "you didn&#39;t tell me who you are."
+    if (args.name) {
+        msg = `hello ${args.name}!`
+    }
+    return {body:
+       `<html><body><h3><center>${msg}</center></h3></body></html>`}
+}
+```
+
+Here is an example of returning binary data:
+
+```javascript
+function main() {
+   let png = <base 64 encoded string>
+   return { 
+      headers: { "Content-Type": "image/png" },
+      body: png };
+}
+```
+
+Functions can access request parameters using the following environment variables.
+
+1. `**__ow_meta_verb:**` the HTTP method of the request.
+2. `**__ow_meta_headers:**` the request headers.
+3. `**__ow_meta_path:**` the unmatched path of the request.
+
+Full details on this new feature are available in this [blog post](https://medium.com/openwhisk/serverless-http-handlers-with-openwhisk-90a986cc7cdd#.2x09176m8).
+
+**\*IMPORTANT: [Web Actions](https://github.com/openwhisk/openwhisk/blob/master/docs/actions.md) is currently experimental and may be subject to breaking changes.***