This is an automated email from the ASF dual-hosted git repository.
pdesai 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 2f6fa8d Documentation for the export feature (#862)
2f6fa8d is described below
commit 2f6fa8d39c843ae07e2a176923abf72484a9d479
Author: David Breitgand <[email protected]>
AuthorDate: Thu Apr 19 16:25:27 2018 -0400
Documentation for the export feature (#862)
* Update README.md
Short description of the export feature
* Update README.md
Added high level explanations on export feature
* Update README.md
* Create export.md
Initial description of the export feature
* Update export.md
* Update export.md
* Update export.md
* Update export.md
* Update export.md
* Update export.md
* Update export.md
* Update export.md
* Update export.md
* Update export.md
typo fixes
* Update export.md
* Update export.md
* Update export.md
* Update export.md
* Update export.md
* Update export.md
* Update export.md
* Update export.md
* Update export.md
* Update export.md
* Update export.md
* Update export.md
* Update export.md
* Update export.md
* Update export.md
* Update export.md
* Update export.md
* Update export.md
* Update export.md
* Update export.md
typos
* Update export.md
* Update export.md
* Update export.md
* Update export.md
* Update export.md
* Update export.md
* Update export.md
* Update export.md
* Update export.md
* Update export.md
* Update export.md
* Update export.md
* Update export.md
* Update export.md
* Update export.md
* Update export.md
Added advanced usage examples. Fixed typos. Style.
* Update export.md
* Update export.md
* Update export.md
* Update export.md
* Update export.md
* Update export.md
typos mostly
* Update export.md
* Update export.md
* Update export.md
typos + recursive dependencies documented. relative paths added.
---
README.md | 3 +
docs/export.md | 300 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++
2 files changed, 303 insertions(+)
diff --git a/README.md b/README.md
index f4c8102..3879fa9 100644
--- a/README.md
+++ b/README.md
@@ -23,6 +23,8 @@
`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 export --projectname managed_project_name` allows to "export" a
specified managed project into a local file system. Namely, a
`managed_project_name.yml` Manifest file will be created automatically. This
Manifest file can be used with `wskdeploy` to redeploy the managed project at a
different OpenWhisk instance. If the managed project contains dependencies on
other managed projects, then these projects will be exported automatically into
their respective manifests.
+
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.
## Here are some quick links for:
@@ -30,6 +32,7 @@ You can use this in addition to the OpenWhisk CLI. In fact,
this utility uses t
- [Downloading wskdeploy](#downloading-released-binaries) - released binaries
for Linux, Mac OS and Windows
- [Running wskdeploy](#running-wskdeploy) - run wskdeploy as a binary or Go
program
- :eight_spoked_asterisk: [Writing Package
Manifests](docs/programming_guide.md#wskdeploy-utility-by-example) - a
step-by-step guide on writing Package Manifest files for ```wskdeploy```
+- :eight_spoked_asterisk: [Exporting OpenWhisk assets](docs/export.md) - how
to use `export` feature
- [Building the project](#building-the-project) - download and build the
GoLang source code
- [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
diff --git a/docs/export.md b/docs/export.md
new file mode 100644
index 0000000..4bc5540
--- /dev/null
+++ b/docs/export.md
@@ -0,0 +1,300 @@
+# Using `wskdeploy` for exporting `OpenWhisk` assets
+
+`wskdeploy export` can be used to export `OpenWhisk` assets previously
deployed as a *managed project* via `wskdeploy sync -m manifest.yaml`.
`wskdeploy export` will create a manifest for the managed project assets and
separate manifests for each managed project that this managed project depends
upon, if such dependencies exist and have been described in `manifest.yml` when
the managed project has been initially deployed.
+The manifest(s) resulting from executing `wskdeploy export` can be later used
for deploying at a different `OpenWhisk` instance. The code of actions, which
are defined in the packages of the exported project will be saved into folders
with the names being the names of the package, the actions belong to.
+
+## Use Cases
+
+### Copy `OpenWhisk` Assets
+
+One common scenario, in which the export feature is useful, is populating a
newly installed `OpenWhisk` instance with assets from
+another `OpenWhisk` instance. One might consider a scenario, in which an
`OpenWhisk` instance is installed on premises with another `OpenWhisk` instance
residing in the cloud. Consider, for example using one `OpenWhisk` instance on
premises and another one in the cloud (e.g., the second `OpenWhisk` instance
can be [IBM Cloud Functions](https://console.bluemix.net/openwhisk/)). A fairly
common scenario is that a developer
+will need to deploy assets from the cloud `OpenWhisk` instance on the on
premises one and vice-versa.
+
+### `OpenWhisk` at the Edge
+
+In a variety of IoT and other edge computing scenarios, such as running
Virtual Network Functions (VNF) as `OpenWhisk` actions in "edge Data Centers"
+embedded with 5G-MEDIA infrastructure (as pioneered in [5G-MEDIA EU H2020
project](http://www.5gmedia.eu/)), there is a need to distribute `OpenWhisk`
assets developed centrally in the cloud (e.g., [IBM Cloud
Functions](https://console.bluemix.net/openwhisk/)) to multiple `OpenWhisk`
instances running at the edge Data Centers. Again, `wskdeploy export` is handy
as a basic tool that allows to automate this management task.
+
+## Basic Usage by Example
+
+Consider a simple manifest file
[manifest_lib1.yml](../tests/src/integration/export/manifest_lib1.yaml) for a
sample project `lib1`.
+The project contains a single `lib1_package` package that comprise three
actions (the code of the action in this simple example is the
+same for all three, but the action names are different).
+
+
+### Step 1: deploy `lib1` as a managed project
+
+```sh
+$ ./wskdeploy sync -m manifest_lib1.yaml
+```
+
+### Step 2: validate `lib1` deployment
+
+```sh
+$ ./wsk package get lib1_package
+```
+
+<details><summary>(<b>clickable</b>) You should see an output similar to
this:</summary>
+<p>
+
+```json
+ok: got package lib1_package
+{
+ "namespace": "your_namespace",
+ "name": "lib1_package",
+ "version": "0.0.2",
+ "publish": false,
+ "annotations": [
+ {
+ "key": "whisk-managed",
+ "value": {
+ "file":
"/root/go_projects/src/github.com/apache/incubator-openwhisk-wskdeploy/tests/src/integration/export/manifest_lib1.yaml",
+ "projectDeps": [],
+ "projectHash": "80eec5f8e3ee874e22bdacb76aa4cc69aad459c1",
+ "projectName": "lib1"
+ }
+ }
+ ],
+ "binding": {},
+ "actions": [
+ {
+ "name": "lib1_greeting3",
+ "version": "0.0.1",
+ "annotations": [
+ {
+ "key": "whisk-managed",
+ "value": {
+ "file":
"/root/go_projects/src/github.com/apache/incubator-openwhisk-wskdeploy/tests/src/integration/export/manifest_lib1.yaml",
+ "projectDeps": [],
+ "projectHash":
"80eec5f8e3ee874e22bdacb76aa4cc69aad459c1",
+ "projectName": "lib1"
+ }
+ },
+ {
+ "key": "exec",
+ "value": "nodejs:6"
+ }
+ ]
+ },
+ {
+ "name": "lib1_greeting2",
+ "version": "0.0.1",
+ "annotations": [
+ {
+ "key": "whisk-managed",
+ "value": {
+ "file":
"/root/go_projects/src/github.com/apache/incubator-openwhisk-wskdeploy/tests/src/integration/export/manifest_lib1.yaml",
+ "projectDeps": [],
+ "projectHash":
"80eec5f8e3ee874e22bdacb76aa4cc69aad459c1",
+ "projectName": "lib1"
+ }
+ },
+ {
+ "key": "exec",
+ "value": "nodejs:6"
+ }
+ ]
+ },
+ {
+ "name": "lib1_greeting1",
+ "version": "0.0.1",
+ "annotations": [
+ {
+ "key": "whisk-managed",
+ "value": {
+ "file":
"/root/go_projects/src/github.com/apache/incubator-openwhisk-wskdeploy/tests/src/integration/export/manifest_lib1.yaml",
+ "projectDeps": [],
+ "projectHash":
"80eec5f8e3ee874e22bdacb76aa4cc69aad459c1",
+ "projectName": "lib1"
+ }
+ },
+ {
+ "key": "exec",
+ "value": "nodejs:6"
+ }
+ ]
+ }
+ ]
+}
+```
+</p>
+</details>
+
+### Step 3: Export the newly deployed `lib1` project
+
+Exporting `lib1` project into the current directory. Please note that the
manifest name should be explicitly specified.
+
+```sh
+$ ./wskdeploy export --projectname lib1 -m my_new_lib1_manifest.yaml
+```
+
+One can also export a project into a different directory, by specifying a
manifest name containing this directory. The directory does not have to exist.
`wskdeploy` will automatically create it, if needed.
+
+<details><summary>(<b>clickable</b>) Example:</summary>
+
+```sh
+$ ./wskdeploy export --projectname lib1 -m
mydirectory/my_new_lib1_manifest.yaml
+```
+</details>
+
+### Step 4: Inspect the newly exported manifest (`my_new_lib1_manifest.yaml`)
+
+<details><summary>(<b>clickable</b>) You should see an output similar to
this:</summary>
+
+```yaml
+project:
+ name: lib1
+ namespace: ""
+ credential: ""
+ apiHost: ""
+ apigwAccessToken: ""
+ version: ""
+ packages: {}
+packages:
+ lib1_package:
+ name: lib1_package
+ version: 0.0.2
+ license: ""
+ dependencies: {}
+ namespace: your_namespace
+ credential: ""
+ apiHost: ""
+ apigwAccessToken: ""
+ actions:
+ lib1_greeting1:
+ name: lib1_greeting1
+ location: ""
+ version: 0.0.1
+ function: lib1_package/lib1_greeting1.js
+ code: ""
+ runtime: nodejs:6
+ namespace: your_namespace/lib1_package
+ credential: ""
+ exposedUrl: ""
+ web-export: ""
+ main: ""
+ limits: null
+ inputs: {}
+ outputs: {}
+ annotations:
+ exec: nodejs:6
+ lib1_greeting2:
+ name: lib1_greeting2
+ location: ""
+ version: 0.0.1
+ function: lib1_package/lib1_greeting2.js
+ code: ""
+ runtime: nodejs:6
+ namespace: your_namespace/lib1_package
+ credential: ""
+ exposedUrl: ""
+ web-export: ""
+ main: ""
+ limits: null
+ inputs: {}
+ outputs: {}
+ annotations:
+ exec: nodejs:6
+ lib1_greeting3:
+ name: lib1_greeting3
+ location: ""
+ version: 0.0.1
+ function: lib1_package/lib1_greeting3.js
+ code: ""
+ runtime: nodejs:6
+ namespace: your_namespace/lib1_package
+ credential: ""
+ exposedUrl: ""
+ web-export: ""
+ main: ""
+ limits: null
+ inputs: {}
+ outputs: {}
+ annotations:
+ exec: nodejs:6
+ triggers: {}
+ feeds: {}
+ rules: {}
+ inputs: {}
+ sequences: {}
+ apis: {}
+filepath: ""
+
+```
+</details>
+
+### Step 5: Inspect the newly exported package
+
+The code of the actions defined in the packages comprising the exported
project will be saved into the folders named after
+the respective packages. The packages' folders will be created in the same
directory into which the manifest file of the
+project is exported. Let's examine the current directory into which
`my_new_lib1_manifest.yaml` was exported in Step 3 above.
+
+```sh
+$ ls -al lib1_package
+```
+
+<details><summary>(<b>clickable</b>) You should see an output similar to
this:</summary>
+<pre>
+drwxr-xr-x 2 root root 4096 Apr 8 22:52 .
+drwxr-xr-x 26 root root 4096 Apr 8 23:38 ..
+-rw-r--r-- 1 root root 331 Apr 8 22:59 lib1_greeting1.js
+-rw-r--r-- 1 root root 331 Apr 8 22:58 lib1_greeting2.js
+-rw-r--r-- 1 root root 331 Apr 8 22:58 lib1_greeting3.js
+</pre>
+</details>
+
+## Advanced Usage
+
+The dependencies mechanism allows to express a project structure, in which one
project uses another project as a library. Also dependencies can be defined for
multiple projects. Consider a project `lib2` with the manifest
[manifest_lib2.yml](../tests/src/integration/export/manifest_lib2.yaml) and a
project `EXT_PROJECT` with the manifest
[manifest_ext.yml](../tests/src/integration/export/manifest_ext.yaml).
`EXT_PROJECT` (stands for _extending project_) uses actions from both package
`li [...]
+
+`wskdeploy export` will automatically export both `lib1` and `lib2` along with
`EXT_PROJECT`. It will not export bindings, because they will be automatically
created when re-deploying `lib1`, `lib2`, and `EXT_PROJECT` at another
OpenWhisk instance. Each exported project will have a manifest and package
folder structure similar to the explained [above](#basic-usage-by-example). The
dependency projects will be placed into `dependencies` folder beneath the
folder where the manifest of the t [...]
+
+### Exporting a Project with Dependencies
+
+#### Step 1: export `EXT_PROJECT`
+
+```sh
+$ ./wskdeploy export --projectname EXT_PROJECT -m ext_test1/ext.yaml
+```
+
+#### Step 2: Inspect the resulting directory structure
+
+```sh
+$ ls -al ./ext1
+```
+
+<details><summary>(<b>clickable</b>) You should see an output similar to
this:</summary>
+<pre>
+drwxr-xr-x 3 root root 4096 Apr 9 19:32 .
+drwxr-xr-x 29 root root 4096 Apr 9 19:33 ..
+drwxr-xr-x 4 root root 4096 Apr 9 19:32 dependencies
+-rw-r--r-- 1 root root 1260 Apr 9 19:32 ext.yaml
+</pre>
+</details>
+
+#### Step 3 Inspect the dependencies directory
+
+```sh
+$ ls -al ./ext1/dependencies
+```
+
+<details><summary>(<b>clickable</b>) You should see an output similar to
this:</summary>
+<pre>
+drwxr-xr-x 4 root root 4096 Apr 9 19:32 .
+drwxr-xr-x 3 root root 4096 Apr 9 19:32 ..
+drwxr-xr-x 2 root root 4096 Apr 9 19:32 lib1_package
+-rw-r--r-- 1 root root 1751 Apr 9 19:32 lib1.yaml
+drwxr-xr-x 2 root root 4096 Apr 9 19:32 lib2_package
+-rw-r--r-- 1 root root 1751 Apr 9 19:32 lib2.yaml
+</pre>
+</details>
+
+#### Important Notes
+
++ Recursive dependencies are not supported.
++ To redeploy a project with dependencies, a user should first deploy
dependency projects projects (`lib1` and `lib2` in our example) and only after
that, `EXT_PROJECT` can be deployed successfully.
++ `wskdeploy export` does not check for circular dependencies. In case of
circular dependencies specified by the user, `wskdeploy`'s behavior is
undefined.
++ The manifest name for exporting a top project (`EXT_PROJECT` in our case)
should be explicitly specified.
+
+
--
To stop receiving notification emails like this one, please contact
[email protected].
