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/15 20:29:02 UTC
[incubator-openwhisk-wskdeploy] branch master updated: Update guide,
add debugging and configuring markdown. (#489)
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 d3d0ab4 Update guide, add debugging and configuring markdown. (#489)
d3d0ab4 is described below
commit d3d0ab434f1a36913d2b15bfd7d7af8d2a3cdae7
Author: Matt Rutkowski <mr...@us.ibm.com>
AuthorDate: Fri Sep 15 15:29:00 2017 -0500
Update guide, add debugging and configuring markdown. (#489)
* Update guide, add debugging and configuring markdown.
* Update guide, add debugging and configuring markdown.
* Update guide, add debugging and configuring markdown.
* Update guide, add debugging and configuring markdown.
* Update guide, add debugging and configuring markdown.
* Rename manifest and deployment files to indicate contents.
* fix some types
* Update .MD files to separate out Package schema doc.
* Fix a few typos and add YAML error example.
---
docs/programming_guide.md | 44 ++++++++++++----------
docs/wskdeploy_configuring.md | 43 +++++++++++++++++++++
docs/wskdeploy_debugging.md | 39 +++++++++++++++++++
...{programming_guide.md => wskdeploy_packages.md} | 10 +----
parsers/yamlparser.go | 2 +-
parsers/yamlparser_test.go | 28 +++++++-------
...eployment_data_action_with_inputs_outputs.yaml} | 0
...ploy1.yaml => deployment_data_application.yaml} | 0
...ml => deployment_data_application_package.yaml} | 0
tests/dat/manifest_bad_yaml.yaml | 14 +++++++
...yaml => manifest_validate_package_grammar.yaml} | 2 +-
...fest_validate_trigger_action_rule_grammar.yaml} | 1 +
utils/util_test.go | 2 +-
13 files changed, 140 insertions(+), 45 deletions(-)
diff --git a/docs/programming_guide.md b/docs/programming_guide.md
index 7003130..41c827f 100644
--- a/docs/programming_guide.md
+++ b/docs/programming_guide.md
@@ -1,35 +1,39 @@
-# Whisk Deploy Tool by Example
+# ```wskdeploy``` utility by example
_A step-by-step guide for deploying Apache OpenWhisk applications using Package Manifest files._
-This guide, by example, will walk you through how to describe OpenWhisk applications using the OpenWhisk Packaging specification and deply them through the wskdeploy utility to any OpenWhisk Serverless provider.
+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) and deploy them through the Whisk Deploy utility.
-It assumes that you have setup and can run the ```wskdeploy``` as described in the [project README](https://github.com/apache/incubator-openwhisk-wskdeploy#). If so, then the utility will use the OpenWhisk APIHOST and AUTH variable values in your .wskprops file to attempt deployment.
+### Setting up your Host and Credentials
+In order to deply 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)
-## Creating an OpenWhisk Package
+# 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) document.
-### Start with a Package Manifest (YAML) file
-The wskdeploy utility maninly uses a single file, that uses a YAML syntax, called a "Package Manifest", to describe all the OpenWhisk components that make up your OpenWhisk Package including Actions, Triggers, Rules, etc.
+# 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:
-The minimal manifest file would include only a package declaration, a version number and a license for the package:
```
-package:
- name: helloworld
+helloworld:
version: 1.0
license: Apache-2.0
+ actions:
+ hello:
+ version: 1.0
+ function: src/hello/hello.js
```
-Save this into a file called "manifest.yaml" in a directory of your choice.
+where "hello.js" contains the following JavaScript code:
+```
+function main(params) {
+ console.log('hello', params.payload+'!');
+ return { payload: msg };
+}
+```
-### Executing the wskdeploy utility
+## Creating a valid Package
-Simply execute the wskdeploy binary against the directory you saved your "manifest.yaml" file in by pointing it to the package location using the ```-p``` 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.
-```
-$ wskdeploy -p <my_directory>
-```
-wskdeploy will automatically look for any file named "manifest.yaml" or "manifest.yml" in the directory it is pointed; however, the manifest file can be called anything as long as it has a .yaml or .yml extension and passed on the command line using the ```-m``` flag.
+Please see [wskdeploy_packages.md](wskdeploy_packages.md) for an exploration of the **Packages** schema.
-For example, if you called your manifest "my_pkg_manifest.yml" you could simply provide the manifest file name as follows:
-```
-$ wskdeploy -p <my_directory> -m my_pkg_manifest.yaml
-```
diff --git a/docs/wskdeploy_configuring.md b/docs/wskdeploy_configuring.md
new file mode 100644
index 0000000..ec13f62
--- /dev/null
+++ b/docs/wskdeploy_configuring.md
@@ -0,0 +1,43 @@
+# Configuring ```wskdeploy```
+
+At minimum, the wskdeploy utility needs valid OpenWhisk APIHOST and AUTH variable to attempt deployment. In this case the default target namespace is assumed; otherwise, NAMESPACE also needs to be provided.
+
+## Precedence order
+
+Wskdeploy attempts to find these values in the following order:
+
+1. **Command line**
+
+Values supplied on the command line using the ```apihost```, ```auth``` and ```namespace``` flags will override values supplied elsewhere (below).
+
+for example the following flags can be used:
+
+```
+$ wskdeploy --apihost <host> --auth <auth> --namespace <namespace>
+```
+
+Command line values are considered higher in precedence since they indicate an intentional user action to override values that may have been supplied in files.
+
+2. **Deployment file**
+
+Values supplied in a Deployment YAML file will override values found elsewhere (below).
+
+3. **Manifest file**
+
+Values supplied in a Manifest YAML file will override values found elsewhere (below).
+
+4. **.wskprops**
+
+Values set using the Whisk Command Line Interface (CLI) are stored in a ```.wskprops```, typically in your $HOME directory, will override values found elsewhere (below).
+
+It assumes that you have setup and can run the wskdeploy as described in the project README. If so, then the utility will use the OpenWhisk APIHOST and AUTH variable values in your .wskprops file to attempt deployment.
+
+5. **Interactice mode**
+
+If interactive mode is enabled (i.e., using the ```-i``` or ```--allow-interactive``` flags) then wskdeploy will prompt for any missing (required) values.
+
+for example:
+
+```
+$ wskdeploy -i -m manifest.yaml
+```
diff --git a/docs/wskdeploy_debugging.md b/docs/wskdeploy_debugging.md
new file mode 100644
index 0000000..767de72
--- /dev/null
+++ b/docs/wskdeploy_debugging.md
@@ -0,0 +1,39 @@
+# Debugging ```wskdeploy```
+
+The Whisk Deploy utility provides several ways to help you in debugging your OpenWhisk application or package during parsing, deployment or undeployment.
+
+## Enabling Verbose mode
+
+The first thing you should do is turn on _"verbose mode"_ using the flag ```-v``` or ```--verbose```. This will assure that all Informational messages within the code will be displayed.
+
+```
+$ wskdeploy -v -m manifest.yaml
+```
+
+## Enable additional trace in Go Client
+
+Wskdeploy uses the OpenWhisk GoLang 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
+```
+
+## Pay attention to Named error messages
+
+Wskpdeloy uses named errors that describe the type of any error found along with additional values that correspond with an error.
+
+For example, if you have an error in your Manifest's YAML, you may see an error such as:
+```
+[50]: Invalid input of Yaml file =====> incubator-openwhisk-wskdeploy/parsers/manifest_parser.go
+[98]: Failed to parse the yaml file manifest_bad_yaml.yaml
+ =====> yaml: line 13: could not find expected ':'
+```
+
+The named error **NewInputYamlFormatError** provides direct indication of both where in the utilities GoLang code the error was reported, but also details provided from the YAML parser regarding where the Manifest file may contain a grammar error.
+
+
+All current named errors supported by the utility can be found in the latest ```wskdeployerror.go``` source file:
+[wskdeployerror.go](https://github.com/apache/incubator-openwhisk-wskdeploy/blob/master/utils/wskdeployerror.go)
diff --git a/docs/programming_guide.md b/docs/wskdeploy_packages.md
similarity index 54%
copy from docs/programming_guide.md
copy to docs/wskdeploy_packages.md
index 7003130..e042d8c 100644
--- a/docs/programming_guide.md
+++ b/docs/wskdeploy_packages.md
@@ -1,14 +1,9 @@
-# Whisk Deploy Tool by Example
-_A step-by-step guide for deploying Apache OpenWhisk applications using Package Manifest files._
-
-This guide, by example, will walk you through how to describe OpenWhisk applications using the OpenWhisk Packaging specification and deply them through the wskdeploy utility to any OpenWhisk Serverless provider.
-
-It assumes that you have setup and can run the ```wskdeploy``` as described in the [project README](https://github.com/apache/incubator-openwhisk-wskdeploy#). If so, then the utility will use the OpenWhisk APIHOST and AUTH variable values in your .wskprops file to attempt deployment.
+# Working with packages
## Creating an OpenWhisk Package
### Start with a Package Manifest (YAML) file
-The wskdeploy utility maninly uses a single file, that uses a YAML syntax, called a "Package Manifest", to describe all the OpenWhisk components that make up your OpenWhisk Package including Actions, Triggers, Rules, etc.
+The wskdeploy utility mainly uses a single file, that uses a YAML syntax, called a "Package Manifest", to describe all the OpenWhisk components that make up your OpenWhisk Package including Actions, Triggers, Rules, etc.
The minimal manifest file would include only a package declaration, a version number and a license for the package:
```
@@ -21,7 +16,6 @@ package:
Save this into a file called "manifest.yaml" in a directory of your choice.
### Executing the wskdeploy utility
-
Simply execute the wskdeploy binary against the directory you saved your "manifest.yaml" file in by pointing it to the package location using the ```-p``` flag.
```
diff --git a/parsers/yamlparser.go b/parsers/yamlparser.go
index 27ed9ff..2005801 100644
--- a/parsers/yamlparser.go
+++ b/parsers/yamlparser.go
@@ -139,7 +139,7 @@ type Package struct {
Version string `yaml:"version"` //used in manifest.yaml
License string `yaml:"license"` //used in manifest.yaml
Repositories []Repository `yaml:"repositories,omitempty"`
- Dependencies map[string]Dependency `yaml: dependencies` // used in manifest.yaml
+ Dependencies map[string]Dependency `yaml: dependencies` //used in manifest.yaml
Function string `yaml:"function"` //used in deployment.yaml
//mapping to wsk.SentPackageNoPublish.Namespace
Namespace string `yaml:"namespace"` //used in both manifest.yaml and deployment.yaml
diff --git a/parsers/yamlparser_test.go b/parsers/yamlparser_test.go
index f97532a..e18ee36 100644
--- a/parsers/yamlparser_test.go
+++ b/parsers/yamlparser_test.go
@@ -25,14 +25,14 @@ import (
"testing"
)
-var manifestfile1 = "../tests/dat/manifest1.yaml"
-var manifestfile2 = "../tests/dat/manifest2.yaml"
+var manifestfile_val_pkg = "../tests/dat/manifest_validate_package_grammar.yaml"
+var manifestfile_val_tar = "../tests/dat/manifest_validate_trigger_action_rule_grammar.yaml"
var manifestfile3 = "../tests/dat/manifest3.yaml"
var manifestfile4 = "../tests/dat/manifest4.yaml"
var manifestfile5 = "../tests/dat/manifest5.yaml"
var manifestfile6 = "../tests/dat/manifest6.yaml"
-var testfile1 = "../tests/dat/deploy1.yaml"
-var testfile2 = "../tests/dat/deploy2.yaml"
+var deploymentfile_data_app = "../tests/dat/deployment_data_application.yaml"
+var deploymentfile_data_app_pkg = "../tests/dat/deployment_data_application_package.yaml"
var testfile3 = "../tests/dat/deploy3.yaml"
var testfile4 = "../tests/dat/deploy4.yaml"
@@ -192,7 +192,7 @@ func TestParseManifestYAML_param(t *testing.T) {
func TestParseDeploymentYAML_Application(t *testing.T) {
//var deployment utils.DeploymentYAML
mm := NewYAMLParser()
- deployment, _ := mm.ParseDeployment(testfile1)
+ deployment, _ := mm.ParseDeployment(deploymentfile_data_app)
//get and verify application name
assert.Equal(t, "wskdeploy-samples", deployment.Application.Name, "Get application name failed.")
@@ -204,7 +204,7 @@ func TestParseDeploymentYAML_Application(t *testing.T) {
func TestParseDeploymentYAML_Package(t *testing.T) {
//var deployment utils.DeploymentYAML
mm := NewYAMLParser()
- deployment, _ := mm.ParseDeployment(testfile2)
+ deployment, _ := mm.ParseDeployment(deploymentfile_data_app_pkg)
assert.Equal(t, 1, len(deployment.Application.Packages), "Get package list failed.")
for pkg_name := range deployment.Application.Packages {
@@ -224,7 +224,7 @@ func TestParseDeploymentYAML_Package(t *testing.T) {
func TestParseDeploymentYAML_Action(t *testing.T) {
mm := NewYAMLParser()
- deployment, _ := mm.ParseDeployment(testfile2)
+ deployment, _ := mm.ParseDeployment(deploymentfile_data_app_pkg)
for pkg_name := range deployment.Application.Packages {
@@ -251,8 +251,8 @@ func TestParseDeploymentYAML_Action(t *testing.T) {
func TestComposeWskPackage(t *testing.T) {
mm := NewYAMLParser()
- deployment, _ := mm.ParseDeployment(testfile2)
- manifest, _ := mm.ParseManifest(manifestfile1)
+ deployment, _ := mm.ParseDeployment(deploymentfile_data_app_pkg)
+ manifest, _ := mm.ParseManifest(manifestfile_val_pkg)
pkglist := deployment.Application.GetPackageList()
for _, pkg := range pkglist {
@@ -312,7 +312,7 @@ func TestComposeWskRule(t *testing.T) {
func TestGetActionList(t *testing.T) {
mm := NewYAMLParser()
- manifest, _ := mm.ParseManifest(manifestfile2)
+ manifest, _ := mm.ParseManifest(manifestfile_val_tar)
pkg := manifest.Package
actions := pkg.GetActionList()
assert.Equal(t,3, len(actions), "Get action list failed.")
@@ -320,7 +320,7 @@ func TestGetActionList(t *testing.T) {
func TestGetTriggerList(t *testing.T) {
mm := NewYAMLParser()
- manifest, _ := mm.ParseManifest(manifestfile2)
+ manifest, _ := mm.ParseManifest(manifestfile_val_tar)
pkg := manifest.Package
triggers := pkg.GetTriggerList()
assert.Equal(t,2, len(triggers), "Get trigger list failed.")
@@ -328,7 +328,7 @@ func TestGetTriggerList(t *testing.T) {
func TestGetRuleList(t *testing.T) {
mm := NewYAMLParser()
- manifest, _ := mm.ParseManifest(manifestfile2)
+ manifest, _ := mm.ParseManifest(manifestfile_val_tar)
pkg := manifest.Package
rules := pkg.GetRuleList()
assert.Equal(t,3, len(rules), "Get trigger list failed.")
@@ -336,7 +336,7 @@ func TestGetRuleList(t *testing.T) {
func TestGetFeedList(t *testing.T) {
mm := NewYAMLParser()
- manifest, _ := mm.ParseManifest(manifestfile2)
+ manifest, _ := mm.ParseManifest(manifestfile_val_tar)
pkg := manifest.Package
feeds := pkg.GetFeedList()
assert.Equal(t,4, len(feeds), "Get feed list failed.")
@@ -344,7 +344,7 @@ func TestGetFeedList(t *testing.T) {
func TestGetApisList(t *testing.T) {
mm := NewYAMLParser()
- manifest, _ := mm.ParseManifest(manifestfile2)
+ manifest, _ := mm.ParseManifest(manifestfile_val_tar)
pkg := manifest.Package
apis := pkg.GetApis()
assert.Equal(t,5, len(apis), "Get api list failed.")
diff --git a/tests/dat/deployment.yaml b/tests/dat/deployment_data_action_with_inputs_outputs.yaml
similarity index 100%
rename from tests/dat/deployment.yaml
rename to tests/dat/deployment_data_action_with_inputs_outputs.yaml
diff --git a/tests/dat/deploy1.yaml b/tests/dat/deployment_data_application.yaml
similarity index 100%
rename from tests/dat/deploy1.yaml
rename to tests/dat/deployment_data_application.yaml
diff --git a/tests/dat/deploy2.yaml b/tests/dat/deployment_data_application_package.yaml
similarity index 100%
rename from tests/dat/deploy2.yaml
rename to tests/dat/deployment_data_application_package.yaml
diff --git a/tests/dat/manifest_bad_yaml.yaml b/tests/dat/manifest_bad_yaml.yaml
new file mode 100644
index 0000000..9a8d689
--- /dev/null
+++ b/tests/dat/manifest_bad_yaml.yaml
@@ -0,0 +1,14 @@
+package:
+ name: BadYAML
+ actions:
+ # helloworld action in NodeJS
+ helloNodejs:
+ function: actions/hello.js
+ inputs:
+ name:
+ type: string
+ description: name of a person
+ place:
+ type: string
+ /// bad description
+ description: location of a person
diff --git a/tests/dat/manifest1.yaml b/tests/dat/manifest_validate_package_grammar.yaml
similarity index 52%
rename from tests/dat/manifest1.yaml
rename to tests/dat/manifest_validate_package_grammar.yaml
index 3673c61..8d28a44 100644
--- a/tests/dat/manifest1.yaml
+++ b/tests/dat/manifest_validate_package_grammar.yaml
@@ -1,5 +1,5 @@
+# This test file is used to test the basic Package grammar
package:
name: helloworld
version: 1.0
license: Apache-2.0
-
diff --git a/tests/dat/manifest2.yaml b/tests/dat/manifest_validate_trigger_action_rule_grammar.yaml
similarity index 90%
rename from tests/dat/manifest2.yaml
rename to tests/dat/manifest_validate_trigger_action_rule_grammar.yaml
index 8e37b6b..046b751 100644
--- a/tests/dat/manifest2.yaml
+++ b/tests/dat/manifest_validate_trigger_action_rule_grammar.yaml
@@ -1,3 +1,4 @@
+# This test file is used to test the basic Trigger-Action-Rule grammar
package:
name: manifest2
version: 1.0
diff --git a/utils/util_test.go b/utils/util_test.go
index 7a00659..daa4ecd 100644
--- a/utils/util_test.go
+++ b/utils/util_test.go
@@ -28,7 +28,7 @@ import (
)
var contentReader = new(ContentReader)
-var testfile = "../tests/dat/deployment.yaml"
+var testfile = "../tests/dat/deployment_data_action_with_inputs_outputs.yaml"
func TestLocalReader_ReadLocal(t *testing.T) {
b, _ := contentReader.ReadLocal(testfile)
--
To stop receiving notification emails like this one, please contact
['"commits@openwhisk.apache.org" <co...@openwhisk.apache.org>'].