You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@openwhisk.apache.org by ho...@apache.org on 2017/09/22 16:40:15 UTC
[incubator-openwhisk-wskdeploy] branch master updated: Guide part5
(#538)
This is an automated email from the ASF dual-hosted git repository.
houshengbo pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/incubator-openwhisk-wskdeploy.git
The following commit(s) were added to refs/heads/master by this push:
new 30b3db7 Guide part5 (#538)
30b3db7 is described below
commit 30b3db7fcfe9ef644d56884d4628b09e95e00c3f
Author: Matt Rutkowski <mr...@us.ibm.com>
AuthorDate: Fri Sep 22 11:40:13 2017 -0500
Guide part5 (#538)
* Start building out examples using helloworld variants.
* Start building out examples using helloworld variants.
* Start building out examples using helloworld variants.
* Start building out examples using helloworld variants.
* Start building out examples using helloworld variants.
* Start building out examples using helloworld variants.
* Start building out examples using helloworld variants.
* Start building out examples using helloworld variants.
* Start building out examples using helloworld variants.
* Start building out examples using helloworld variants.
* Start building out examples using helloworld variants.
* Start building out examples using helloworld variants.
* Start building out examples using helloworld variants.
* Start building out examples using helloworld variants.
* Start building out examples using helloworld variants.
* Start building out examples using helloworld variants.
* Start building out examples using helloworld variants.
* Start building out examples using helloworld variants.
* Start building out examples using helloworld variants.
* Start building out examples using helloworld variants.
* Start building out examples using helloworld variants.
* Start building out examples using helloworld variants.
* Start building out examples using helloworld variants.
* Start building out examples using helloworld variants.
* Start building out examples using helloworld variants.
---
docs/examples/deployment_hello_world_2.yaml | 9 ++
docs/examples/manifest_hello_world_2.yaml | 13 +++
docs/examples/manifest_hello_world_3.yaml | 20 ++++
docs/examples/manifest_package_minimal.yaml | 5 +
docs/examples/src/hello.js | 2 +-
docs/programming_guide.md | 37 +++----
specification/html/spec_normative_refs.md | 149 ++++++++++++++++++++++++++++
specification/html/spec_types_yaml.md | 139 ++++++++++++++++++++++++++
8 files changed, 355 insertions(+), 19 deletions(-)
diff --git a/docs/examples/deployment_hello_world_2.yaml b/docs/examples/deployment_hello_world_2.yaml
new file mode 100644
index 0000000..7e9acdc
--- /dev/null
+++ b/docs/examples/deployment_hello_world_2.yaml
@@ -0,0 +1,9 @@
+application:
+ name: foo
+ packages:
+ hello_world_package:
+ actions:
+ ello_world:
+ inputs:
+ name: Amy
+ place: Paris
diff --git a/docs/examples/manifest_hello_world_2.yaml b/docs/examples/manifest_hello_world_2.yaml
new file mode 100644
index 0000000..f178ad4
--- /dev/null
+++ b/docs/examples/manifest_hello_world_2.yaml
@@ -0,0 +1,13 @@
+# Example 2: “Hello world” with explicit input and output parameter declarations
+package:
+ name: hello_world_package
+ version: 1.0
+ license: Apache-2.0
+ actions:
+ hello_world_2:
+ function: src/hello.js
+ inputs:
+ name: string
+ place: string
+ outputs:
+ greeting: string
diff --git a/docs/examples/manifest_hello_world_3.yaml b/docs/examples/manifest_hello_world_3.yaml
new file mode 100644
index 0000000..1e7d9d5
--- /dev/null
+++ b/docs/examples/manifest_hello_world_3.yaml
@@ -0,0 +1,20 @@
+# Example 3: inputs and output parameters with explicit types and descriptions
+package:
+ name: hello_world_package
+ version: 1.0
+ license: Apache-2.0
+ actions:
+ hello_world_3:
+ function: src/hello/hello.js
+ runtime: nodejs@6
+ inputs:
+ name:
+ type: string
+ description: name of person
+ place:
+ type: string
+ description: location of person
+ outputs:
+ greeting:
+ type: string
+ description: greeting string
diff --git a/docs/examples/manifest_package_minimal.yaml b/docs/examples/manifest_package_minimal.yaml
new file mode 100644
index 0000000..5286e5c
--- /dev/null
+++ b/docs/examples/manifest_package_minimal.yaml
@@ -0,0 +1,5 @@
+# Example 1: Minimum valid Package manifest file
+package:
+ name: hello_world_package
+ version: 1.0
+ license: Apache-2.0
diff --git a/docs/examples/src/hello.js b/docs/examples/src/hello.js
index 69da099..ffeaf23 100644
--- a/docs/examples/src/hello.js
+++ b/docs/examples/src/hello.js
@@ -6,5 +6,5 @@
*/
function main(params) {
msg = "Hello, " + params.name + " from " + params.place;
- return { payload: msg };
+ return { greeting: msg };
}
diff --git a/docs/programming_guide.md b/docs/programming_guide.md
index 8c7a3af..3a6b75d 100644
--- a/docs/programming_guide.md
+++ b/docs/programming_guide.md
@@ -1,12 +1,19 @@
# ```wskdeploy``` utility by example
_A step-by-step guide for deploying Apache OpenWhisk applications using Package Manifest files._
-This guide will walk you through how to describe OpenWhisk applications using the [OpenWhisk Packaging Specification](https://github.com/apache/incubator-openwhisk-wskdeploy/tree/master/specification#openwhisk-packaging-specification) and deploy them through the Whisk Deploy utility. Please use the specification as the ultimate reference for all Manifest file grammar and syntax.
+This guide will walk you through how to describe OpenWhisk applications and packages using the [OpenWhisk Packaging Specification](https://github.com/apache/incubator-openwhisk-wskdeploy/tree/master/specification#openwhisk-packaging-specification) and deploy them through the Whisk Deploy (```wskdeploy```) utility. Please use the specification as the ultimate reference for all Manifest file grammar and syntax.
+## Getting started
### Setting up your Host and Credentials
In order to deploy your OpenWhisk package, at minimum, the ```wskdeploy``` utility needs valid OpenWhisk APIHOST and AUTH variable to attempt deployment. Please read the [Configuring wskdeploy](wskdeploy_configuring.md#configuring-wskdeploy)
-# Creating a "hello world" application
+### Debugging your Package Manifests
+
+In addition to the normal output the ```wskdeploy``` utility provides, you may enable additional information that may further assist you in debugging. Please read the [Debugging Whisk Deploy](wskdeploy_debugging.md#debugging-wskdeploy) document.
+
+---
+
+## Creating a "hello world" application
As with most language introductions, here we show a minimal "hello world" application as encoded in an OpenWhisk Package Manifest YAML file:
@@ -24,13 +31,17 @@ where "hello.js" contains the following JavaScript code:
```javascript
function main(params) {
msg = "Hello, " + params.name + " from " + params.place;
- return { payload: msg };
+ return { greeting: msg };
}
```
-The source code for this example can be found here [https://github.com/apache/incubator-openwhisk-wskdeploy/blob/master/docs/examples/manifest_hello_world.yaml](https://github.com/apache/incubator-openwhisk-wskdeploy/blob/master/docs/examples/manifest_hello_world.yaml)
+#### Source code
+The source code for the manifest and JavaScript files can be found here:
+- [manifest_hello_world.yaml](https://github.com/apache/incubator-openwhisk-wskdeploy/blob/master/docs/examples/manifest_hello_world.yaml)
+- [hello.js](https://github.com/apache/incubator-openwhisk-wskdeploy/blob/master/docs/examples/src/hello.js)
+
-## Deploying "hello world"
+### Deploying "hello world"
You can actually deploy the "hello world" manifest from the incubator-openwhisk-wskdeploy project directory if you have downloaded it from GitHub:
@@ -47,13 +58,6 @@ $ ./wskdeploy -i -m docs/examples/manifest_hello_world.yaml
and the utility will stop, show you all the OpenWhisk package components it will deply and ask you if you want to deploy them or not.
```
- ____ ___ _ _ _ _ _
- /\ \ / _ \ _ __ ___ _ __ | | | | |__ (_)___| | __
- /\ /__\ \ | | | | '_ \ / _ \ '_ \| | | | '_ \| / __| |/ /
- / \____ \ / | |_| | |_) | __/ | | | |/\| | | | | \__ \ <
- \ \ / \/ \___/| .__/ \___|_| |_|__/\__|_| |_|_|___/_|\_\
- \___\/ |_|
-
Package:
name: hello_world_package
bindings:
@@ -66,17 +70,14 @@ Package:
Rules:
Do you really want to deploy this? (y/N):
-
```
-## Examining the "hello world" Manifest
+### Examining the "hello world" Manifest
The "hello world" example represents the minimum valid Manifest file which includes only the required parts of the Package and Action desciptors.
+<!--
If you want to explore all possible Package and Action declarations (i.e., their schema) you can read:
- [Exploring Packages](wskdeploy_packages.md) - step-by-step guide on the **Package** schema.
- [Exploring Actions](wskdeploy_actions.md) - step-by-step guide on the **Action** schema.
-
-# Debugging your Package Manifests
-
-In addition to the normal output the wskdeploy utility provides, you may enable additional information that may further assist you in debugging. Please read the [Debugging Whisk Deploy](wskdeploy_debugging.md#debugging-wskdeploy) document.
+-->
diff --git a/specification/html/spec_normative_refs.md b/specification/html/spec_normative_refs.md
new file mode 100644
index 0000000..248fc4b
--- /dev/null
+++ b/specification/html/spec_normative_refs.md
@@ -0,0 +1,149 @@
+
+<!--
+********************************
+ Normative Reference
+********************************
+-->
+<h2>Normative References</h2>
+<p> </p>
+<table width="100%">
+ <tr>
+ <th>
+ <p>Tag</p>
+ </th>
+ <th>
+ <p>Description</p>
+ </th>
+ </tr>
+ <tr>
+ <td>
+ <p><a>RFC2119</a></p>
+ </td>
+ <td>
+ <p>S. Bradner, <i>Key words for use in RFCs to Indicate Requirement Levels</i>, <a href="http://www.ietf.org/rfc/rfc2119.txt">http://www.ietf.org/rfc/rfc2119.txt</a>, IETF RFC 2119, March 1997.</p>
+ </td>
+ </tr>
+ <tr>
+ <td>
+ <p><a>YAML-1.2</a></p>
+ </td>
+ <td>
+ <p>YAML, Version 1.2, 3rd Edition, Patched at 2009-10-01, Oren Ben-Kiki, Clark Evans, Ingy dšt Net <a href="http://www.yaml.org/spec/1.2/spec.html">http://www.yaml.org/spec/1.2/spec.html</a></p>
+ </td>
+ </tr>
+ <tr>
+ <td>
+ <p><a>YAML-TS-1.1</a></p>
+ </td>
+ <td>
+ <p>Timestamp Language-Independent Type for YAML Version 1.1, Working Draft 2005-01-18, <a href="http://yaml.org/type/timestamp.html">http://yaml.org/type/timestamp.html</a></p>
+ </td>
+ </tr>
+ <tr>
+ <td>
+ <p><a>Maven-Version</a></p>
+ </td>
+ <td>
+ <p>The version type is defined with the <a href="https://maven.apache.org/index.html">Apache Maven project's</a> policy draft:</p>
+ <p><a href="https://cwiki.apache.org/confluence/display/MAVEN/Version+number+policy">https://cwiki.apache.org/confluence/display/MAVEN/Version+number+policy</a></p>
+ </td>
+ </tr>
+ <tr>
+ <td>
+ <p><a>OpenAPI-2.0</a></p>
+ </td>
+ <td>
+ <p>The OpenAPI (f.k.a. 'Swagger') specification for defining REST APIs as JSON.</p>
+ <p><a href="https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md">https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md</a></p>
+ </td>
+ </tr>
+ <tr>
+ <td>
+ <p><a>Linux-SPDX</a></p>
+ </td>
+ <td>
+ <p>Linux Foundation, SPDX License list</p>
+ <p><a href="https://spdx.org/licenses/">https://spdx.org/licenses/</a></p>
+ </td>
+ </tr>
+ <tr>
+ <td>
+ <p><a>NPM-SPDX-Syntax</a></p>
+ </td>
+ <td>
+ <p>Node Package Manager (NPM) SPDX License Expression Syntax</p>
+ <p><a href="https://www.npmjs.com/package/spdx">https://www.npmjs.com/package/spdx</a></p>
+ </td>
+ </tr>
+</table>
+
+<!--
+********************************
+ Non-normative Reference
+********************************
+-->
+
+<h2>Non-normative References</h2>
+<p> </p>
+<table width="100%">
+ <tr>
+ <th>
+ <p>Tag</p>
+ </th>
+ <th>
+ <p>Description</p>
+ </th>
+ </tr>
+ <tr>
+ <td>
+ <p><a>OpenWhisk-API</a></p>
+ </td>
+ <td>
+ <p>OpenWhisk REST API which is defined as an OpenAPI document.</p>
+ <p><a href="https://raw.githubusercontent.com/openwhisk/openwhisk/master/core/controller/src/main/resources/whiskswagger.json">https://raw.githubusercontent.com/openwhisk/openwhisk/master/core/controller/src/main/resources/whiskswagger.json</a></p>
+ </td>
+ </tr>
+ <tr>
+ <td>
+ <p><a>GNU-units</a></p>
+ </td>
+ <td>
+ <p>Size-type units are based upon a subset of those defined by GNU at <a href="http://www.gnu.org/software/parted/manual/html_node/unit.html">http://www.gnu.org/software/parted/manual/html_node/unit.html</a></p>
+ </td>
+ </tr>
+ <tr>
+ <td>
+ <p><a>RFC 6838</a></p>
+ </td>
+ <td>
+ <p>Mime Type definitions in compliance with <a href="http://tools.ietf.org/html/rfc6838">RFC 6838</a>.</p>
+ </td>
+ </tr>
+ <tr>
+ <td>
+ <p><a>RFC 7231</a></p>
+ </td>
+ <td>
+ <p>HTTP 1.1. status codes are described in compliance with <a href="http://tools.ietf.org/html/rfc7231#section-6">RFC 7231</a>.</p>
+ </td>
+ </tr>
+ <tr>
+ <td>
+ <p><a>IANA-Status-Codes</a></p>
+ </td>
+ <td>
+ <p>HTTP Status codes as defined in the <a href="http://www.iana.org/assignments/http-status-codes/http-status-codes.xhtml">IANA Status Code Registry</a>.</p>
+ </td>
+ </tr>
+ <tr>
+ <td>
+ <p>JSON Schema Specification</p>
+ </td>
+ <td>
+ <p>The built-in parameter type 'json' references this specification.</p>
+ <p>http://json-schema.org/</p>
+ </td>
+ </tr>
+</table>
+
+</html>
diff --git a/specification/html/spec_types_yaml.md b/specification/html/spec_types_yaml.md
new file mode 100644
index 0000000..9cb7fd8
--- /dev/null
+++ b/specification/html/spec_types_yaml.md
@@ -0,0 +1,139 @@
+<h2>YAML Types</H2>
+
+<p>Many of the types we use in this profile are <i>built-in</i> types from the <a
+href="http://www.yaml.org/spec/1.2/spec.html">YAML 1.2 specification</a>
+(i.e., those identified by the 'tag:yaml.org,2002' version tag). </p>
+
+<p>The following table declares the valid YAML type URIs and
+aliases that SHALL be used when defining parameters or properties within an
+OpenWhisk package manifest:<a> </a></p>
+
+<table width="100%">
+ <th>
+ <th>
+ <p>Type Name</p>
+ </th>
+ <th>
+ <p>Type URI</p>
+ </th>
+ <th>
+ <p>Notes</p>
+ </th>
+ </tr>
+ <tr>
+ <td>
+ <p><a>string</a></p>
+ </td>
+ <td>
+ <p>tag:yaml.org,2002:str (default)</p>
+ </td>
+ <td>
+ <p>Default type if no type provided</p>
+ </td>
+ </tr>
+ <tr>
+ <td>
+ <p><a>integer</a></p>
+ </td>
+ <td>
+ <p>tag:yaml.org,2002:int</p>
+ </td>
+ <td>
+ <p>Signed. Includes large integers (i.e., long type)</p>
+ </td>
+ </tr>
+ <tr>
+ <td>
+ <p><a>float</a></p>
+ </td>
+ <td>
+ <p>tag:yaml.org,2002:float</p>
+ </td>
+ <td>
+ <p>Signed. Includes large floating point values (i.e., double type)</p>
+ </td>
+ </tr>
+ <tr>
+ <td>
+ <p><a>boolean</a></p>
+ </td>
+ <td>
+ <p>tag:yaml.org,2002:bool</p>
+ </td>
+ <td>
+ <p>This specification uses lowercase 'true' and lowercase 'false'</p>
+ </td>
+ </tr>
+ <tr>
+ <td>
+ <p><a>timestamp</a></p>
+ </td>
+ <td>
+ <p>tag:yaml.org,2002:timestamp (see <a href="spec_normative_refs.md">YAML-TS-1.1</a>)</p>
+ </td>
+ <td>
+ <p>ISO 8601 compatible.</p>
+ </td>
+ </tr>
+ <tr>
+ <td>
+ <p><a>null</a></p>
+ </td>
+ <td>
+ <p>tag:yaml.org,2002:null</p>
+ </td>
+ <td>
+ <p>Different meaning than an empty string, map, list, etc.</p>
+ </td>
+ </tr>
+ <tr>
+ <td>
+ <p>version</p>
+ </td>
+ <td>
+ <p>tag:maven.apache.org:version (see <a href="spec_normative_refs.md">Maven version</a>)</p>
+ </td>
+ <td>
+ <p>Typically found in modern tooling (i.e., 'package@version' or 'package:version' format).</p>
+ </td>
+ </tr>
+ <tr>
+ <td>
+ <p><a>string256</a></p>
+ </td>
+ <td>
+ <p>long length strings (e.g., descriptions)</p>
+ </td>
+ <td>
+ <p>A string type limited to 256 characters.</p>
+ </td>
+ </tr>
+ <tr>
+ <td>
+ <p><a>string64</a></p>
+ </td>
+ <td>
+ <p>medium length strings (e.g., abstracts, hover text)</p>
+ </td>
+ <td>
+ <p>A string type limited to 64 characters.</p>
+ </td>
+ </tr>
+ <tr>
+ <td>
+ <p><a>string16</a></p>
+ </td>
+ <td>
+ <p>short length strings (e.g., small form-factor list displays)</p>
+ </td>
+ <td>
+ <p>A string type limited to 16 characters.</p>
+ </td>
+ </tr>
+</table>
+
+<h4>Requirements</h4>
+<ul>
+<li>The 'string' type SHALL be the default type when not specified on a parameter or property declaration.</li>
+<li>All 'boolean' values SHALL be lowercased (i.e., 'true' or 'false').</li>
+</ul>
--
To stop receiving notification emails like this one, please contact
['"commits@openwhisk.apache.org" <co...@openwhisk.apache.org>'].