You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@openwhisk.apache.org by ja...@apache.org on 2019/04/23 10:41:57 UTC
[incubator-openwhisk] branch master updated: Updating Node.js and
Docker docs. (#4451)
This is an automated email from the ASF dual-hosted git repository.
jamesthomas pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/incubator-openwhisk.git
The following commit(s) were added to refs/heads/master by this push:
new 5a40820 Updating Node.js and Docker docs. (#4451)
5a40820 is described below
commit 5a408201a1afac72785d96d10ecbf3e114783c5e
Author: James Thomas <jt...@gmail.com>
AuthorDate: Tue Apr 23 11:41:43 2019 +0100
Updating Node.js and Docker docs. (#4451)
* Updating Node.js and Docker docs.
Adding common use-case instructions based on community feedback.
* Fixing scancode issues
---
docs/actions-docker.md | 435 +++++++++++++++++++++++++++++++++----------------
docs/actions-nodejs.md | 317 ++++++++++++++++++++++++-----------
2 files changed, 515 insertions(+), 237 deletions(-)
diff --git a/docs/actions-docker.md b/docs/actions-docker.md
index 84ce543..5d53a1c 100644
--- a/docs/actions-docker.md
+++ b/docs/actions-docker.md
@@ -19,149 +19,298 @@
## Creating and invoking Docker actions
-With OpenWhisk Docker actions, you can write your actions in any language, bundle larger
-or complex dependencies, and tailor the runtime environment to suite your needs.
-
-- As a prerequisite, you must have a Docker Hub account.
- To set up a free Docker ID and account, go to [Docker Hub](https://hub.docker.com).
-- The easiest way to get started with a Docker action is to use the OpenWhisk Docker skeleton.
- - You can install the skeleton with the `wsk sdk install docker` CLI command.
- - This is a a Docker image based on [python:3.6.1-alpine](https://hub.docker.com/r/library/python).
- - The skeleton requires an entry point located at `/action/exec` inside the container.
- This may be an executable script or binary compatible with this distribution.
- - The executable receives the input arguments via a single command-line argument string
- which can be deserialized as a `JSON` object.
- It must return a result via `stdout` as a single-line string of serialized `JSON`.
- - You may include any compilation steps or dependencies by modifying the `Dockerfile`
- included in the `dockerSkeleton`.
-
-The instructions that follow show you how to use the OpenWhisk Docker skeleton.
-
-1. Install the Docker skeleton.
-
- ```
- wsk sdk install docker
- ```
- ```
- The Docker skeleton is now installed at the current directory.
- ```
-
- ```
- $ ls dockerSkeleton/
- ```
- ```
- Dockerfile README.md buildAndPush.sh example.c
- ```
-
- The skeleton is a Docker container template where you can inject your code in the form of custom binaries.
-
-2. Create the executable. The Docker skeleton includes a C program that you can use as an example.
-
- ```
- cat dockerSkeleton/example.c
- ```
- ```c
- #include <stdio.h>
- int main(int argc, char *argv[]) {
- printf("This is an example log message from an arbitrary C program!\n");
- printf("{ \"msg\": \"Hello from arbitrary C program!\", \"args\": %s }",
- (argc == 1) ? "undefined" : argv[1]);
- }
- ```
-
- You can modify this file as needed, or, add additional code and dependencies to the Docker image.
- In case of the latter, you may need to tweak the `Dockerfile` as necessary to build your executable.
- The binary must be located inside the container at `/action/exec`.
-
- The executable receives a single argument from the command line. It is a string serialization of the JSON
- object representing the arguments to the action. The program may log to `stdout` or `stderr`.
- By convention, the last line of output _must_ be a stringified JSON object which represents the result of
- the action.
-
-3. Build the Docker image and upload it using a supplied script.
- You must first run `docker login` to authenticate, and then run the script with a chosen image name.
-
- ```
- docker login -u janesmith -p janes_password
- ```
- ```
- cd dockerSkeleton
- ```
- ```
- ./buildAndPush.sh janesmith/blackboxdemo
- ```
-
- Notice that part of the example.c file is compiled as part of the Docker image build process,
- so you do not need C compiled on your machine.
- In fact, unless you are compiling the binary on a compatible host machine, it may not run inside
- the container since formats will not match.
-
- Your Docker container may now be used as an OpenWhisk action.
-
- ```
- wsk action create example --docker janesmith/blackboxdemo
- ```
-
- Notice the use of `--docker` when creating an action. Currently all Docker images are assumed
- to be hosted on Docker Hub.
-
- *Note:* It is considered best-practice for production images to be versioned via docker image tags. The absence of a tag will be treated the same as using a "latest" tag, which will result in a pull from the registry when creating new containers. Pulling an image may fail due to a network interruption or Docker Hub outage. For tagged images however, the system will gracefully recover from a failed pull by using the image that is already locally available, making it much more resilient [...]
-
- The "latest" tag should therefore only be used for rapid prototyping where guaranteeing the latest code state is more important than runtime stability at scale.
-
- Please also note that "latest" doesn't mean newest tag, but rather "latest" is an alias for any image built without an explicit tag.
-
-## Invoking a Docker action
-
-Docker actions are invoked as [any other OpenWhisk action](actions.md#the-basics).
-
- ```
- wsk action invoke --result example --param payload Rey
- ```
- ```json
- {
- "args": {
- "payload": "Rey"
- },
- "msg": "Hello from arbitrary C program!"
- }
- ```
-
-## Updating a Docker action
-
-To update the Docker action, run buildAndPush.sh again _and_ update your action.
-This will upload the latest image to Docker Hub and force the system to create a new container based on the image.
-If you do not update the action, then the image is pulled when there are no warm containers available for your action.
-A warm container will continue using a previous version of your Docker image,
-and any new invocations of the action will continue to use that image unless you run `wsk action update`.
-This will indicate to the system that for new invocations it should execute a docker pull to get your new Docker image.
-
- ```
- ./buildAndPush.sh janesmith/blackboxdemo
- ```
- ```
- wsk action update example --docker janesmith/blackboxdemo
- ```
-
-**Note:** As noted above, only images with the tag "latest" or no tag will guarantee to be pulled again, even after updating the action. Any other tag might fall back to use the old image for stability reasons.
-
-To force an updated image after an action update, consider using versioned tags on the image.
+Apache OpenWhisk supports using custom Docker images as the action runtime. Custom runtimes images can either have the action source files built-in or injected dynamically by the platform during initialisation.
+
+Building custom runtime images is a common solution to the issue of having external application dependencies too large to deploy, due to the action size limit (48MB), e.g. machine learning libraries.
+
+### Usage
+
+The [Apache OpenWhisk CLI](https://github.com/apache/incubator-openwhisk-cli) has a `--docker` configuration parameter to set a custom runtime for an action.
+
+```
+wsk action create <ACTION_NAME> --docker <IMAGE> source.js
+```
+
+*`<IMAGE>` must be an image name for a public Docker image on [Docker Hub](https://hub.docker.com/search?q=&type=image).*
+
+The `--docker` flag can also be used without providing additional source or archive files for an action.
+
+```
+wsk action create <ACTION_NAME> --docker <IMAGE>
+```
+
+In this scenario, action source code will not be injected into the runtime during cold-start initialisation. The runtime container must handle the platform invocation requests directly.
+
+### Restrictions
+
+- Custom runtime images must implement the [Action interface](https://github.com/apache/incubator-openwhisk/blob/master/docs/actions-new.md#runtime-general-requirements). This is the [protocol used by the platform](https://github.com/apache/incubator-openwhisk/blob/master/docs/actions-new.md#action-interface) to pass invocation requests to the runtime containers. Containers are expected to expose a HTTP server (running on port 8080) with `/init` and `/run` endpoints.
+- Custom runtime images must be available on [Docker Hub](https://hub.docker.com/search?q=&type=image). Docker Hub is the only container registry currently supported. This means all custom runtime images will need to be publicly available.
+- Custom runtime images will be pulled from Docker Hub into the local platform registry upon the first invocation. This can lead to longer cold-start times on the first invocation with a new or updated image. Once images have been pulled down, they are cached locally.
+
+### Image Refresh Behaviour
+
+Custom runtimes images should be versioned using explicit [image tags](https://docs.docker.com/engine/reference/commandline/tag/) where possible.
+
+When an image identifier has the `latest` tag (or has no explicit tag), creating new runtime containers from a custom image will always result in an image refresh check against the registry. Pulling an image may fail due to a network interruption or Docker Hub outage. Explicitly tagged images allow the system to gracefully recover by using locally cached images, making it much more resilient against external issues.
+
+The "latest" tag should only be used for rapid prototyping, where guaranteeing the latest code state is more important than runtime stability at scale.
+
+### Existing Runtime Images
+
+Apache OpenWhisk publishes all the [existing runtime images](https://hub.docker.com/u/openwhisk) on Docker Hub. This makes it simple to extend an existing runtimes with additional libraries or native dependencies. Public runtimes images can be used as base images in new runtime images.
+
+Here are some of the more common runtime images...
+
+- `openwhisk/action-nodejs-v10` - [Node.js 10](https://hub.docker.com/r/openwhisk/action-nodejs-v10) ([Source](https://github.com/apache/incubator-openwhisk-runtime-nodejs/blob/master/core/nodejs10Action/Dockerfile))
+- `openwhisk/python3action` - [Python 3](https://hub.docker.com/r/openwhisk/python3action) ([Source](https://github.com/apache/incubator-openwhisk-runtime-python/blob/master/core/pythonAction/Dockerfile))
+- `openwhisk/java8action` - [Java 8](https://hub.docker.com/r/openwhisk/java8action) ([Source](https://github.com/apache/incubator-openwhisk-runtime-java/blob/master/core/java8/Dockerfile))
+- `openwhisk/action-swift-v4.2` - [Swift 4.2](https://hub.docker.com/r/openwhisk/action-swift-v4.2) ([Source](https://github.com/apache/incubator-openwhisk-runtime-swift/blob/master/core/swift42Action/Dockerfile))
+- `openwhisk/action-php-v7.3` - [PHP 7.3](https://hub.docker.com/r/openwhisk/action-php-v7.3) ([Source](https://github.com/apache/incubator-openwhisk-runtime-php/blob/master/core/php7.3Action/Dockerfile))
+- `openwhisk/action-ruby-v2.5` - [Ruby 2.5](https://hub.docker.com/r/openwhisk/action-ruby-v2.5) ([Source](https://github.com/apache/incubator-openwhisk-runtime-ruby/blob/master/core/ruby2.5Action/Dockerfile))
+
+## Extending Existing Runtimes
+
+If you want to use extra libraries in an action that can't be deployed (due to the action size limit), building a custom runtime with a project image runtime base image is an easy way to handle this.
+
+By using an existing language runtime image as the base image, the container will already be set up to handle platform invocation requests for that language. This means the image build file only needs to contain commands to install those extra libraries or dependencies
+
+Here are examples for Node.js and Python using this approach to provide large libraries in the runtime.
+
+### Node.js
+
+[Tensorflow.js](https://www.tensorflow.org/js/) is a JavaScript implementation of [TensorFlow](https://www.tensorflow.org/), the open-source Machine Learning library from Google. This project also comes with a [Node.js backend driver](https://github.com/tensorflow/tfjs-node) to run the project on CPU or GPU devices in the Node.js runtime.
+
+Both the core library and CPU backend driver for Node.js (`tfjs` and `tfjs-node`) can be installed as normal NPM packages. Unfortunately, it is not possible to deploy these libraries in a zip file to the Node.js runtime in Apache OpenWhisk due to the size of the library and its dependencies. The `tfjs-node` library has a native dependency which is over 170MB.
+
+Instead, we can build a custom runtime which extends the project's Node.js runtime image and runs `npm install` during the container build process. These libraries will then be pre-installed into the runtime and can be excluded from the deployment archive.
+
+- Create a `Dockerfile` with the following contents:
+
+```
+FROM openwhisk/action-nodejs-v10:latest
+
+RUN npm install @tensorflow/tfjs-node
+```
+
+- Build the Docker image.
+
+```
+docker build -t action-nodejs-v10:tf-js .
+```
+
+- Tag the Docker image with your Docker Hub username.
+
+```
+docker tag action-nodejs-v10:tf-js <USER_NAME>/action-nodejs-v10:tf-js
+```
+
+- Push the Docker image to Docker Hub.
+
+```
+docker push <USER_NAME>/action-nodejs-v10:tf-js
+```
+
+- Create a new Apache OpenWhisk action with the following source code:
+
+```javascript
+const tf = require('@tensorflow/tfjs-node')
+
+const main = () => {
+ return { tf: tf.version }
+}
+```
+
+```
+wsk action create tfjs --docker <USER_NAME>/action-nodejs-v10:tf-js action.js
+```
+
+- Invoking the action should return the TensorFlow.js libraries versions available in the runtime.
+
+```
+wsk action invoke tfjs --result
+```
+
+```
+{
+ "tf": {
+ "tfjs": "1.0.4",
+ "tfjs-converter": "1.0.4",
+ "tfjs-core": "1.0.4",
+ "tfjs-data": "1.0.4",
+ "tfjs-layers": "1.0.4",
+ "tfjs-node": "1.0.3"
+ }
+}
+```
+
+### Python
+
+Python is a popular language for machine learning and data science due to availability of libraries like [numpy](http://www.numpy.org/).
+
+Python libraries can be [imported into the Python runtime](https://github.com/apache/incubator-openwhisk/blob/master/docs/actions-python.md#packaging-python-actions-with-a-virtual-environment-in-zip-files) in Apache OpenWhisk by including a `virtualenv` folder in the deployment archive. This approach does not work when the deployment archive would be larger than the action size limit (48MB).
+
+Instead, we can build a custom runtime which extends the project's Python runtime image and runs `pip install` during the container build process. These libraries will then be pre-installed into the runtime and can be excluded from the deployment archive.
+
+- Create a `Dockerfile` with the following contents:
+
+```
+FROM openwhisk/python3action:latest
+
+RUN apk add --update py-pip
+RUN pip install numpy
+```
+
+- Build the Docker image.
+
+```
+docker build -t python3action:ml-libs .
+```
+
+- Tag the Docker image with your Docker Hub username.
+
+```
+docker tag python3action:ml-libs <USER_NAME>/python3action:ml-libs
+```
+
+- Push the Docker image to Docker Hub.
+
+```
+docker push <USER_NAME>/python3action:ml-libs
+```
+
+- Create a new Apache OpenWhisk action with the following source code:
+
+```python
+import numpy
+
+def main(params):
+ return {
+ "numpy": numpy.__version__
+ }
+```
+
+```
+wsk action create ml-libs --docker <USER_NAME>/python3action:ml-libs action.py
+```
+
+- Invoking the action should return the TensorFlow.js library versions available in the runtime.
+
+```
+wsk action invoke ml-libs --result
+```
+
+```
+{
+ "numpy": "1.16.2"
+}
+```
## Creating native actions
-Docker actions accept initialization data via a (zip) file, similar to other actions kinds.
-For example, the tutorial above created a binary executable inside the container located at `/action/exec`.
-If you copy this file to your local file system and zip it into `exec.zip` then you can use the following
-commands to create a docker action which receives the executable as initialization data.
-
- ```bash
- wsk action create example exec.zip --native
- ```
- which is equivalent to the following command.
- ```bash
- wsk action create example exec.zip --docker openwhisk/dockerskeleton
- ```
-
-Using `--native`, you can see that any executable may be run as an OpenWhisk action.
-This includes `bash` scripts, or cross compiled binaries. For the latter, the constraint
-is that the binary must be compatible with the `openwhisk/dockerskeleton` image.
+Docker support can also be used to run any executable file (from static binaries to shell scripts) on the platform. Executable files need to use the `openwhisk/dockerskeleton` [runtime image](https://github.com/apache/incubator-openwhisk-runtime-docker). Native actions can be created using the `--native` CLI flag, rather than explicitly specifying `dockerskeleton` as the runtime image name.
+
+### Usage
+
+```
+wsk action create my-action --native source.sh
+wsk action create my-action --native archive.zip
+```
+
+Executables can either be text or binary files. Text-based executable files (e.g. shell scripts) are passed directly as the action source files. Binary files (e.g. C programs) must be named `exec` and packaged into a zip archive.
+
+Native action source files must be executable within the `openwhisk/dockerskeleton` [runtime image](https://github.com/apache/incubator-openwhisk-runtime-docker). This means being compiled for the correct platform architecture, linking to the correct dynamic libraries and using pre-installed external dependencies.
+
+When an invocation request is received by the runtime container, the native action file will be executed until the process exits. Action invocation parameters will be passed as a JSON string to `stdin`.
+
+When the process ends, the last line of text output to `stdout` will be parsed as the action result. This must contain a text string with a JSON object. All other text lines written to `stdout` will be treated as logging output and returned into the response logs for the activation.
+
+### Example (Shell Script)
+
+- Create a shell script called `script.sh` with the following contents.
+
+```
+#!/bin/bash
+read ARGS
+NAME=`echo "$ARGS" | jq -r '."name"'`
+DATE=`date`
+echo "{ \"message\": \"Hello $NAME! It is $DATE.\" }"
+```
+
+- Create an action from this shell script.
+
+```
+ wsk action create bash script.sh --native
+```
+
+- Invoke the action with the `name` parameter.
+
+```
+wsk action invoke bash --result --param name James
+```
+
+```
+{
+ "message": "Hello James! It is Thu Apr 18 15:24:23 UTC 2019."
+}
+```
+
+### Example (Static C Binary)
+
+- Create a C source file called `main.c` with the following contents:
+
+```c
+#include <stdio.h>
+int main(int argc, char *argv[]) {
+ printf("This is an example log message from an arbitrary C program!\n");
+ printf("{ \"msg\": \"Hello from arbitrary C program!\", \"args\": %s }",
+ (argc == 1) ? "undefined" : argv[1]);
+}
+```
+
+- Create a shell script (`build.sh`) with the following contents:
+
+```
+#!/bin/bash
+apk add gcc libc-dev
+
+gcc main.c -o exec
+```
+
+- Make the build script executable.
+
+```
+chmod 755 build.sh
+```
+
+- Compile the C binary using the `dockerskeleton` image and the build script.
+
+```
+docker run -it -v $PWD:/action/ -w /action/ openwhisk/dockerskeleton ./build.sh
+```
+
+- Add the binary to a zip file.
+
+```
+zip -r action.zip exec
+```
+
+- Create an action from the zip file containing the binary.
+
+```
+ wsk action create c-binary action.zip --native
+```
+
+- Invoke the action with the `name` parameter.
+
+```
+wsk action invoke c-binary --result --param name James
+```
+
+```
+{
+ "args": {
+ "name": "James"
+ },
+ "msg": "Hello from arbitrary C program!"
+}
+```
diff --git a/docs/actions-nodejs.md b/docs/actions-nodejs.md
index ff6434e..9c76149 100644
--- a/docs/actions-nodejs.md
+++ b/docs/actions-nodejs.md
@@ -104,7 +104,7 @@ Datetime Activation ID Kind Start Duration
"end": 1552762005048,
...
}
- ```
+ ```
Comparing the `start` and `end` time stamps in the activation record, you can see that this activation took slightly over two seconds to complete.
@@ -166,11 +166,17 @@ This example invokes a Yahoo Weather service to get the current conditions at a
This example also passed a parameter to the action by using the `--param` flag and a value that can be changed each time the action is invoked. Find out more about parameters in the [Working with parameters](./parameters.md) section.
-## Packaging an action as a Node.js module
+## Packaging actions as Node.js modules with NPM libraries
+
+Instead of writing all your action code in a single JavaScript source file, actions can be deployed from a zip file containing a [Node.js module](https://nodejs.org/docs/latest-v10.x/api/modules.html#modules_modules).
+
+Archive zip files are extracted into the runtime environment and dynamically imported using `require()` during initialisation. **Actions packaged as a zip file MUST contain a valid `package.json` with a `main` field used to denote the [module index file](https://nodejs.org/docs/latest-v10.x/api/modules.html#modules_folders_as_modules) to return.**
-As an alternative to writing all your action code in a single JavaScript source file, you can write an action as a `npm` package. Consider as an example a directory with the following files:
+Including a `node_modules` folder in the zip file means external NPM libraries can be used on the platform.
-First, `package.json`:
+### Simple Example
+
+- Create the following `package.json` file:
```json
{
@@ -182,7 +188,7 @@ First, `package.json`:
}
```
-Then, `index.js`:
+- Create the following `index.js` file:
```javascript
function myAction(args) {
@@ -194,132 +200,261 @@ function myAction(args) {
exports.main = myAction;
```
-Note that the action is exposed through `exports.main`; the action handler itself can have any name, as long as it conforms to the usual signature of accepting an object and returning an object (or a `Promise` of an object). Per Node.js convention, you must either name this file `index.js` or specify the file name you prefer as the `main` property in package.json.
+Functions are exported from a module by setting properties on the `exports` object. The `--main` property on the action can be used to configure the module function invoked by the platform (this defaults to `main`).
-To create an OpenWhisk action from this package:
+- Install module dependencies using NPM.
-1. Install first all dependencies locally
+```
+npm install
+```
- ```
- $ npm install
- ```
+- Create a `.zip` archive containing all files (including all dependencies).
-2. Create a `.zip` archive containing all files (including all dependencies):
+```
+zip -r action.zip *
+```
- ```
- $ zip -r action.zip *
- ```
+> Please note: Using the Windows Explorer action for creating the zip file will result in an incorrect structure. OpenWhisk zip actions must have `package.json` at the root of the zip, while Windows Explorer will put it inside a nested folder. The safest option is to use the command line `zip` command as shown above.
- > Please note: Using the Windows Explorer action for creating the zip file will result in an incorrect structure. OpenWhisk zip actions must have `package.json` at the root of the zip, while Windows Explorer will put it inside a nested folder. The safest option is to use the command line `zip` command as shown above.
+- Create the action from the zip file.
-3. Create the action:
+```
+wsk action create packageAction --kind nodejs:10 action.zip
+```
- ```
- wsk action create packageAction --kind nodejs:10 action.zip
- ```
+When creating an action from a `.zip` archive with the CLI tool, you must explicitly provide a value for the `--kind` flag by using `nodejs:10`, `nodejs:8` or `nodejs:6`.
+
+- Invoke the action as normal.
+
+```
+wsk action invoke --result packageAction --param lines "[\"and now\", \"for something completely\", \"different\" ]"
+```
+```json
+{
+ "padded": [
+ ".......................and now",
+ "......for something completely",
+ ".....................different"
+ ]
+}
+```
- When creating an action from a `.zip` archive with the CLI tool, you must explicitly provide a value for the `--kind` flag by using `nodejs:10`, `nodejs:8` or `nodejs:6`.
+### Handling NPM Libraries with Native Dependencies
-4. You can invoke the action like any other:
+Node.js libraries can import native dependencies needed by the modules. These native dependencies are compiled upon installation to ensure they work in the local runtime. Native dependencies for NPM libraries must be compiled for the correct platform architecture to work in Apache OpenWhisk.
- ```
- wsk action invoke --result packageAction --param lines "[\"and now\", \"for something completely\", \"different\" ]"
- ```
- ```json
- {
- "padded": [
- ".......................and now",
- "......for something completely",
- ".....................different"
- ]
- }
- ```
+There are two approaches to using libraries with native dependencies...
-Finally, note that while most `npm` packages install JavaScript sources on `npm install`, some also install and compile binary artifacts. The archive file upload currently does not support binary dependencies but rather only JavaScript dependencies. Action invocations may fail if the archive includes binary dependencies.
+1. Run `npm install` inside a Docker container from the platform images.
+2. Building custom runtime image with libraries pre-installed.
-### Package an action as a single bundle
+**The first approach is easiest but can only be used when a zip file containing all source files and libraries is less than the action size limit (48MB).**
-It is convenient to only include the minimal code into a single `.js` file that includes dependencies. This approach allows for faster deployments, and in some circumstances where packaging the action as a zip might be too large because it includes unnecessary files.
+#### Running `npm install` inside runtime container
-You can use a JavaScript module bundler such as [webpack](https://webpack.js.org/concepts/). When webpack processes your code, it recursively builds a dependency graph that includes every module that your action needs.
+ - Run the following command to bind the local directory into the runtime container and run `npm install`.
-Here is a quick example using webpack:
+```
+docker run -it -v $PWD:/nodejsAction openwhisk/action-nodejs-v10 "npm install"
+```
+ This will leave a `node_modules` folder with native dependencies compiled for correct runtime.
-Taking the previous example `package.json` add `webpack` as a development dependency and add some npm script commands.
-```json
-{
- "name": "my-action",
- "main": "dist/bundle.js",
- "scripts": {
- "build": "webpack --config webpack.config.js",
- "deploy": "wsk action update my-action dist/bundle.js --kind nodejs:8"
- },
- "dependencies": {
- "left-pad": "1.1.3"
+ - Zip up the action source files including `node_modules` directory.
+
+```
+zip -r action.zip *
+```
+
+- Create new action with action archive.
+
+```
+ibmcloud wsk action create my-action --kind nodejs:10 action.zip
+```
+
+#### Building custom runtime image
+
+- Create a `Dockerfile` with the `npm install` command run during build.
+
+```
+FROM openwhisk/action-nodejs-v10
+
+RUN npm install <LIB_WITH_NATIVE_DEPS>
+```
+
+- Build and push the image to Docker Hub.
+
+```
+$ docker build -t <USERNAME>/custom-runtime .
+$ docker push <USERNAME>/custom-runtime
+```
+
+- Create new action using custom runtime image.
+
+```
+ibmcloud wsk action create my-action --docker <USERNAME>/custom-runtime action.zip
+```
+
+**Make sure the `node_modules` included in the `action.zip` does not include the same libraries folders.**
+
+## Using JavaScript Bundlers to package action source files
+
+Using a JavaScript module bundler can transform application source files (with external dependencies) into a single compressed JavaScript file. This can lead to faster deployments, lower cold-starts and allow you to deploy large applications where individual sources files in a zip archive are larger than the action size limit.
+
+Here are the instructions for how to use three popular module bundlers with the Node.js runtime. The "left pad" action example will be used as the source file for bundling along with the external library.
+
+### Using rollup.js ([https://rollupjs.org](https://rollupjs.org))
+
+- Re-write the `index.js` to use ES6 Modules, rather than CommonJS module format.
+
+```javascript
+import leftPad from 'left-pad';
+
+function myAction(args) {
+ const lines = args.lines || [];
+ return { padded: lines.map(l => leftPad(l, 30, ".")) }
+}
+
+export const main = myAction
+```
+
+*Make sure you export the function using the `const main = ...` pattern. Using `export {myAction as main}` does not work due to tree-shaking. See this [blog post](https://boneskull.com/rollup-for-javascript-actions-on-openwhisk/) for full details on why this is necessary.*
+
+- Create the Rollup.js configuration file in `rollup.config.js` with the following contents.
+
+```javascript
+import commonjs from 'rollup-plugin-commonjs';
+import resolve from 'rollup-plugin-node-resolve';
+
+export default {
+ input: 'index.js',
+ output: {
+ file: 'bundle.js',
+ format: 'cjs'
},
- "devDependencies": {
- "webpack": "^3.8.1"
- }
+ plugins: [
+ resolve(),
+ commonjs()
+ ]
+};
+```
+
+- Install the Rollup.js library and plugins using NPM.
+
+```
+npm install rollup rollup-plugin-commonjs rollup-plugin-node-resolve --save-dev
+```
+
+- Run the Rollup.js tool using the configuration file.
+
+```
+npx rollup --config
+```
+
+- Create an action using the bundle source file.
+
+```
+wsk action create my-action bundle.js --kind nodejs:10
+```
+
+- Invoke the action as normal. Results should be the same as the example above.
+
+```
+wsk action invoke my-action --result --param lines "[\"and now\", \"for something completely\", \"different\" ]"
+```
+
+### Using webpack ([https://webpack.js.org/](https://webpack.js.org/))
+
+- Change `index.js` to export the `main` function using as a global reference.
+
+```javascript
+const leftPad = require('left-pad');
+
+function myAction(args) {
+ const lines = args.lines || [];
+ return { padded: lines.map(l => leftPad(l, 30, ".")) }
}
+
+global.main = myAction
```
-Create the webpack configuration file `webpack.config.js`.
+This allows the bundle source to "break out" of the closures Webpack uses when defining the modules.
+
+- Create the Webpack configuration file in `webpack.config.js` with the following contents.
+
```javascript
-var path = require('path');
module.exports = {
entry: './index.js',
+ target: 'node',
output: {
- path: path.resolve(__dirname, 'dist'),
filename: 'bundle.js'
- },
- target: 'node'
+ }
};
```
-Set the variable `global.main` to the main function of the action.
-From the previous example:
+- Install the Webpack library and CLI using NPM.
+
+```
+npm install webpack-cli --save-dev
+```
+
+- Run the Webpack tool using the configuration file.
+
+```
+npx webpack --config webpack.config.js
+```
+
+- Create an action using the bundle source file.
+
+```
+wsk action create my-action dist/bundle.js --kind nodejs:10
+```
+
+- Invoke the action as normal. Results should be the same as the example above.
+
+```
+wsk action invoke my-action --result --param lines "[\"and now\", \"for something completely\", \"different\" ]"
+```
+
+### Using parcel ([https://parceljs.org/](https://parceljs.org/))
+
+- Change `index.js` to export the `main` function using as a global reference.
+
```javascript
+const leftPad = require('left-pad');
+
function myAction(args) {
- const leftPad = require("left-pad")
- const lines = args.lines || [];
- return { padded: lines.map(l => leftPad(l, 30, ".")) }
+ const lines = args.lines || [];
+ return { padded: lines.map(l => leftPad(l, 30, ".")) }
}
-global.main = myAction;
-```
-If your function name is `main`, use this syntax instead:
-```javascript
-global.main = main;
+global.main = myAction
```
-To build and deploy an OpenWhisk Action using `npm` and `webpack`:
+This allows the bundle source to "break out" of the closures Parcel uses when defining the modules.
-1. First, install dependencies locally:
+- Install the Parcel library using NPM.
- ```
- npm install
- ```
+```
+npm install parcel-bundler --save-dev
+```
-2. Build the webpack bundle:
+- Run the Parcel tool using the configuration file.
- ```
- npm run build
- ```
+```
+ npx parcel index.js
+```
- The file `dist/bundle.js` is created, and is used to deploy as the Action source code.
+- Create an action using the bundle source file.
-3. Create the Action using the `npm` script or the CLI.
- Using `npm` script:
- ```
- npm run deploy
- ```
+```
+wsk action create my-action dist/index.js --kind nodejs:10
+```
- Using the CLI:
- ```
- wsk action update my-action dist/bundle.js
- ```
+- Invoke the action as normal. Results should be the same as the example above.
-Finally, the bundle file that is built by `webpack` doesn't support binary dependencies but rather JavaScript dependencies. So Action invocations will fail if the bundle depends on binary dependencies, because this is not included with the file `bundle.js`.
+```
+wsk action invoke my-action --result --param lines "[\"and now\", \"for something completely\", \"different\" ]"
+```
## Reference
@@ -397,9 +532,3 @@ The Node.js version 10.13.0 environment is used if the `--kind` flag is explicit
The following packages are pre-installed in the Node.js version 10 environment:
- [openwhisk v3.18.0](https://www.npmjs.com/package/openwhisk) - JavaScript client library for the OpenWhisk platform. Provides a wrapper around the OpenWhisk APIs.
-
-### Packaging npm packages with your actions
-For any `npm` packages that are not pre-installed in the Node.js environment, you can bundle them as dependencies when you create or update your action.
-
-For more information, see [Packaging an action as a Node.js module](./actions.md#packaging-an-action-as-a-nodejs-module) or [Packaging an action as a single bundle](./actions.md#packaging-an-action-as-a-single-bundle).
-