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/20 20:46:29 UTC
[incubator-openwhisk-wskdeploy] branch master updated: Programming
Guide part4, plus reworked README with index (#526)
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 538d4b1 Programming Guide part4, plus reworked README with index (#526)
538d4b1 is described below
commit 538d4b1277b4e8b33168449db9bad78a3d70503e
Author: Matt Rutkowski <mr...@us.ibm.com>
AuthorDate: Wed Sep 20 15:46:27 2017 -0500
Programming Guide part4, plus reworked README with index (#526)
* Update and organize README topics; link to programming guide.
* Update and organize README topics; link to programming guide.
* Update and organize README topics; link to programming guide.
* Update and organize README topics; link to programming guide.
* Update and organize README topics; link to programming guide.
* Update and organize README topics; link to programming guide.
* Update and organize README topics; link to programming guide.
* Update and organize README topics; link to programming guide.
* Update and organize README topics; link to programming guide.
* Update and organize README topics; link to programming guide.
* Update and organize README topics; link to programming guide.
* Update and organize README topics; link to programming guide.
* Update and organize README topics; link to programming guide.
* Update and organize README topics; link to programming guide.
* Update and organize README topics; link to programming guide.
* Update and organize README topics; link to programming guide.
* Update and organize README topics; link to programming guide.
* Update and organize README topics; link to programming guide.
* Update and organize README topics; link to programming guide.
* Update and organize README topics; link to programming guide.
* Update and organize README topics; link to programming guide.
* Update and organize README topics; link to programming guide.
* Update and organize README topics; link to programming guide.
* Update and organize README topics; link to programming guide.
* Update and organize README topics; link to programming guide.
---
README.md | 151 +++++++++++++++++++-------------
docs/examples/manifest_hello_world.yaml | 13 ++-
docs/examples/src/hello.js | 6 ++
docs/programming_guide.md | 72 +++++++++++----
tests/dat/actions/hello.js | 18 +---
5 files changed, 159 insertions(+), 101 deletions(-)
diff --git a/README.md b/README.md
index 14d0129..38c7f47 100644
--- a/README.md
+++ b/README.md
@@ -3,67 +3,52 @@
[](http://www.apache.org/licenses/LICENSE-2.0)
[](https://travis-ci.org/apache/incubator-openwhisk-wskdeploy)
-DISCLAIMER - wskdeploy is an experimental tool.
------------------------------------------------
+`wskdeploy` is a utility to help you describe and deploy any part of the OpenWhisk programming model using a Manifest file written in YAML. Use it to deploy all your OpenWhisk [Packages](https://github.com/apache/incubator-openwhisk/blob/master/docs/packages.md), [Actions](https://github.com/apache/incubator-openwhisk/blob/master/docs/actions.md), [Triggers, and Rules](https://github.com/apache/incubator-openwhisk/blob/master/docs/triggers_rules.md) using a single command!
-`wskdeploy` is a utility to help you create and deploy OpenWhisk packages and their entities using a Manifest file wrttien in YAML. Deploy all your Actions, Triggers, Rules and rules using a single command! You can use this in addition to the OpenWhisk CLI. In fact, this utility uses the OpenWhisk "Go" CLI to create its HTTP REST calls for deploying and undeploying your packages.
+You can use this in addition to the OpenWhisk CLI. In fact, this utility uses the [OpenWhisk "Go" Client](https://github.com/apache/incubator-openwhisk-client-go) to create its HTTP REST calls for deploying and undeploying your packages.
-# How to run
-`wskdeploy` is written in Go. You can invoke it as a Go program, or run its binary file `wskdeploy` directly after building.
+# Here are some quick links for:
-The following examples show you how to invoke wskdeploy's command line help using both methods, as well as deploy the `triggerrule` test case:
+- [Building the project](#building-the-project) - download and build the GoLang source code
+- [Running wskdeploy](#running-wskdeploy) - run wskdeploy as a binary or Go program
+- [Downloading released binaries](#downloading-released-binaries) - for Linux, Mac OS and Windows
+- [Writing Package manifests](docs/programming_guide.md) - step-by-step guide on writing Package Manifest and deployment files for ```wskdeploy```
+- [Contributing to the project](#contributing-to-the-project) - join us!
+- [Debugging wskdeploy](docs/wskdeploy_debugging.md) - helpful tips for debugging the code and your manifest files
+- [Troubleshooting](#troubleshooting) - known issues (e.g., Git)
-### Go program
+<!-- ----------------------------------------------------------------------------- -->
+## Building the project
-invoking command line help:
-```
-$ go run main.go --help
-```
-
-deploying the ```triggerrule``` test case:
-```
-$ go run main.go -m tests/usecases/triggerrule/manifest.yml -d tests/usecases/triggerrule/deployment.yml
-```
-
-### Binary file
-
-invoking command line help:
-```
-$ ./wskdeploy --help
-```
-
-deploying the ```triggerrule``` test case:
-```
-$ ./wskdeploy -m tests/usecases/triggerrule/manifest.yml -d tests/usecases/triggerrule/deployment.yml
-```
+### GoLang setup
-# Where to download the binary wskdeploy
+The wskdeploy utility is a GoLang program so you will first need to [Download and install GoLang](https://golang.org/doc/install) onto your local machine.
-`wskdeploy` is available on the release page of openwhisk-wskdeploy project: [click here to download](https://github.com/apache/incubator-openwhisk-wskdeploy/releases).
-We currently have binaries available for Linux, Mac OS and windows under amd64 architecture. You can find the binary, which fits your local environment.
+Make sure your `$GOPATH` is defined correctly in your environment. For detailed setup of your GoLang development environment, please read [How to Write Go Code](https://golang.org/doc/code.html).
-# How to build on local host
-There is another approach to get the binary `wskdeploy`, which is to build it from the source code with Go tool.
+### Get the source code from GitHub
-Make sure `$GOPATH` is defined. If not, setup your [Go development environment](https://golang.org/doc/code.html).
-
-Then download `wskdeploy` and dependencies by typing:
+Once your environment is setup, download `wskdeploy` and its dependencies:
```sh
$ cd $GOPATH
$ go get github.com/apache/incubator-openwhisk-wskdeploy # see known issues below if you get an error
```
-And finally build `wskdeploy`
+### Build the binary
+Use the Go utility to build the ```wskdeploy``` binary as follows:
```sh
$ cd src/github.com/apache/incubator-openwhisk-wskdeploy/
$ go build -o wskdeploy
```
-If you would like to build the binary for a specific operating system, you may add the arguments GOOS and GOARCH into the
-Go build command. You have to set GOARCH to amd64 or 386. GOOS can be set to "linux" "darwin" or "windows".
+### building for other Operating Systems (GOOS) and Architectures (GOARCH)
+
+If you would like to build the binary for a specific operating system, you may add the arguments GOOS and GOARCH into the Go build command. You may set
+- ```GOOS``` to "linux", "darwin" or "windows"
+- ```GOARCH``` to "amd64" or "386"
For example, run the following command to build the binary for 64-bit Linux:
@@ -71,6 +56,8 @@ For example, run the following command to build the binary for 64-bit Linux:
$ GOOS=linux GOARCH=amd64 go build -o wskdeploy
```
+### build using GoDep tool
+
If you want to build with the godep tool, please execute the following commands.
```sh
@@ -79,17 +66,53 @@ $ godep get # Download and install packages with specified d
$ godep go build -o wskdeploy # build the wskdeploy tool.
```
-You can verify your build by running:
+<!-- ----------------------------------------------------------------------------- -->
+
+## Running ```wskdeploy```
+
+After building the wskdeploy binary, you can run it as follows:
+#### Running the Binary file
+
+Start by verifying the utility can display the command line help:
```sh
-./wskdeploy --help
+$ ./wskdeploy --help
```
-# Contributing
+then try deploying an OpenWhisk Manifest and Deployment file:
+```sh
+$ ./wskdeploy -m tests/usecases/triggerrule/manifest.yml -d tests/usecases/triggerrule/deployment.yml
+```
-Start by creating a fork of `incubator-openwhisk-wskdeploy` and then change the git `origin` to point to your forked repository, as follows:
+#### Running as a Go program
+
+Since ```wskdeploy``` is a GoLang program, you may choose to run it using the Go utility:
+```sh
+$ go run main.go --help
+```
+and deploying using the Go utility would look like:
+```sh
+$ go run main.go -m tests/usecases/triggerrule/manifest.yml -d tests/usecases/triggerrule/deployment.yml
```
+<!-- ----------------------------------------------------------------------------- -->
+
+## Downloading released binaries
+
+Binaries of `wskdeploy` are available for download on the project's GitHub release page:
+- [https://github.com/apache/incubator-openwhisk-wskdeploy/releases](https://github.com/apache/incubator-openwhisk-wskdeploy/releases).
+
+For each release, we typically provide binaries built for Linux, Mac OS (Darwin) and Windows on the AMD64 architecture. However, we provide instructions on how to build your own binaries as well from source code with the Go tool. See [Building the project](#building-the-project).
+
+_If you are a Developer or Contributor, **we recommend building from the latest source code** from the project's master branch._
+
+<!-- ----------------------------------------------------------------------------- -->
+
+## Contributing to the project
+
+Start by creating a fork of `incubator-openwhisk-wskdeploy` and then change the git `origin` to point to your forked repository, as follows:
+
+```sh
$ cd $GOPATH/src/github.com/apache/incubator-openwhisk-wskdeploy
$ git remote rename origin upstream
$ git remote add origin https://github.com/<your fork>/incubator-openwhisk-wskdeploy
@@ -99,8 +122,10 @@ $ git branch --set-upstream-to origin/master # track master from origin now
You can now use `git push` to push changes to your repository and submit pull requests.
-# How to Cross Compile Binary with Gradle/Docker
+### How to Cross Compile Binary with Gradle/Docker
+
If you don't want to bother with go installation, build, git clone etc, and you can do it with Gradle/Docker.
+
After compiling, a suitable wskdeploy binary that works for your OS platform will be available under /bin directory.
1. First you need a docker daemon running locally on your machine.
@@ -125,24 +150,15 @@ If you would like to build the binaries available for all the operating systems
$ ./gradlew distDocker -PcrossCompileCLI=true
```
-Then, you will find the binaries and their compressed packages generated under the folder bin/<os>/<cpu arc>/ for each
-operating system and CPU architecture pair. We supports both amd64 and 386 for Linux, Mac and Windows operating systems.
-
-# Debugging
+Then, you will find the binaries and their compressed packages generated under the folder ```bin/<os>/<arch>/``` for each supported Operating System and CPU Architecture pair.
-### Enable additional trace in Go client
+<!-- ----------------------------------------------------------------------------- -->
-Wskdeploy uses the OpenWhisk Go Client to format and invoke OpenWhisk's APIs which has additional debug tracing available.
-
-To enable this trace, set the following environment variable in Bash:
-```
-# set to any value > 0
-WSK_CLI_DEBUG=1
-```
+## Troubleshooting
-# Known issues
+### Known issues
-### Git commands using HTTPS, not SSH
+#### Git commands using HTTPS, not SSH
The "go get" command uses HTTPS with GitHub and when you attempt to "commit" code you might be prompted with your GitHub credentials. If you wish to use your SSH credentials, you may need to issue the following command to set the appropriate URL for your "origin" fork:
@@ -150,7 +166,19 @@ The "go get" command uses HTTPS with GitHub and when you attempt to "commit" cod
git remote set-url origin git@github.com:<username>/incubator-openwhisk-wskdeploy.git
```
-### Git clone RPC failed: HTTP 301
+<or> you can manually change the remote (origin) url within your .git/config file:
+```
+[remote "origin"]
+ url = git@github.com:<username>/incubator-openwhisk-wskdeploy
+```
+
+while there, you can verify that your upstream repository is set correctly:
+```
+[remote "upstream"]
+ url = git@github.com:apache/incubator-openwhisk-wskdeploy
+```
+
+#### Git clone RPC failed: HTTP 301
This sometimes occurs using "go get" the wskdeploy code (which indirectly invokes "git clone"). You might get this error when downloading `incubator-openwhisk-wskdeploy`:
@@ -158,11 +186,8 @@ This sometimes occurs using "go get" the wskdeploy code (which indirectly invoke
error: RPC failed; HTTP 301 curl 22 The requested URL returned error: 301
fatal: The remote end hung up unexpectedly
-This is caused by newer `git` not forwarding request anymore. One solution is to allow forwarding for `gopkg.in`
+This is caused by newer `git` versions not forwarding requests anymore. One solution is to allow forwarding for `gopkg.in`
```
$ git config --global http.https://gopkg.in.followRedirects true
```
-
-DISCLAIMER - wskdeploy is an experimental tool.
------------------------------------------------
diff --git a/docs/examples/manifest_hello_world.yaml b/docs/examples/manifest_hello_world.yaml
index 80f60f0..34944fa 100644
--- a/docs/examples/manifest_hello_world.yaml
+++ b/docs/examples/manifest_hello_world.yaml
@@ -1,9 +1,8 @@
# Example 1: Basic Hello World using NodeJS (JavaScript)
package:
- hello_world_package:
- # name: hello_world_package
- version: 1.0
- license: Apache-2.0
- actions:
- hello_world:
- function: src/hello.js
+ name: hello_world_package
+ version: 1.0
+ license: Apache-2.0
+ actions:
+ hello_world:
+ function: src/hello.js
diff --git a/docs/examples/src/hello.js b/docs/examples/src/hello.js
index 55d282f..69da099 100644
--- a/docs/examples/src/hello.js
+++ b/docs/examples/src/hello.js
@@ -1,3 +1,9 @@
+// Licensed to the Apache Software Foundation (ASF) under one or more contributor
+// license agreements; and to You under the Apache License, Version 2.0.
+
+/*
+ * Hello, world
+ */
function main(params) {
msg = "Hello, " + params.name + " from " + params.place;
return { payload: msg };
diff --git a/docs/programming_guide.md b/docs/programming_guide.md
index b447f7e..8c7a3af 100644
--- a/docs/programming_guide.md
+++ b/docs/programming_guide.md
@@ -6,35 +6,77 @@ This guide will walk you through how to describe OpenWhisk applications using th
### 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)
-# Debugging your package
-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:
-```
+```yaml
package:
- helloworld:
- version: 1.0
- license: Apache-2.0
- actions:
- hello:
- version: 1.0
- function: src/hello/hello.js
+ name: hello_world_package
+ version: 1.0
+ license: Apache-2.0
+ actions:
+ hello_world:
+ function: src/hello.js
```
where "hello.js" contains the following JavaScript code:
-```
+```javascript
function main(params) {
msg = "Hello, " + params.name + " from " + params.place;
return { payload: msg };
}
```
-## Creating a valid Package
+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)
+
+## 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:
+
+```sh
+$ ./wskdeploy -m docs/examples/manifest_hello_world.yaml
+```
+
+if you want to simply verify your manifest is able to read and parse your manifest file, you can add the ```-i``` or ```--allow-interactive``` flag:
-The "hello world" example, however, does not represent the minimum valid Manifest file which would need to include only the required parts of the Package desciptor.
+```sh
+$ ./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.
-Please see [wskdeploy_packages.md](wskdeploy_packages.md) for an exploration of the **Packages** schema.
+```
+ ____ ___ _ _ _ _ _
+ /\ \ / _ \ _ __ ___ _ __ | | | | |__ (_)___| | __
+ /\ /__\ \ | | | | '_ \ / _ \ '_ \| | | | '_ \| / __| |/ /
+ / \____ \ / | |_| | |_) | __/ | | | |/\| | | | | \__ \ <
+ \ \ / \/ \___/| .__/ \___|_| |_|__/\__|_| |_|_|___/_|\_\
+ \___\/ |_|
+Package:
+ name: hello_world_package
+ bindings:
+
+ * action: hello_world
+ bindings:
+ annotations:
+
+ Triggers:
+ Rules:
+
+Do you really want to deploy this? (y/N):
+
+```
+
+## 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/tests/dat/actions/hello.js b/tests/dat/actions/hello.js
index 25fdafb..125cbdb 100644
--- a/tests/dat/actions/hello.js
+++ b/tests/dat/actions/hello.js
@@ -1,19 +1,5 @@
-/*
- * Licensed to the Apache Software Foundation (ASF) under one or more
- * contributor license agreements. See the NOTICE file distributed with
- * this work for additional information regarding copyright ownership.
- * The ASF licenses this file to You under the Apache License, Version 2.0
- * (the "License"); you may not use this file except in compliance with
- * the License. You may obtain a copy of the License at
- *
- * http://www.apache.org/licenses/LICENSE-2.0
- *
- * Unless required by applicable law or agreed to in writing, software
- * distributed under the License is distributed on an "AS IS" BASIS,
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- * See the License for the specific language governing permissions and
- * limitations under the License.
- */
+// Licensed to the Apache Software Foundation (ASF) under one or more contributor
+// license agreements; and to You under the Apache License, Version 2.0.
/*
* Return a simple greeting message for the whole world.
--
To stop receiving notification emails like this one, please contact
['"commits@openwhisk.apache.org" <co...@openwhisk.apache.org>'].