openwhisk-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From houshen...@apache.org
Subject [incubator-openwhisk-wskdeploy] branch master updated: Update guide, add debugging and configuring markdown. (#489)
Date Fri, 15 Sep 2017 20:29:02 GMT
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 <mrutkows@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" <commits@openwhisk.apache.org>'].

Mime
View raw message