mpmunasinghe commented on a change in pull request #3837: Document adding a new runtime kind. URL: https://github.com/apache/incubator-openwhisk/pull/3837#discussion_r200553372
########## File path: docs/actions-new.md ########## @@ -0,0 +1,247 @@ +<!-- +# +# 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. +# +--> + +OpenWhisk supports [several languages and runtimes](actions.md#languages-and-runtimes) but +there may be other languages or runtimes that are important for your organization, for which +you want tighter integration with the platform. Adding a new language, or runtime with bespoke +packages and third party dependencies is the same from the OpenWhisk platform which is language +and runtime agnostic. + +The canonical unit of execution is a container which implements a specific interface: +1. accepts an initialization payload (the code), +2. accepts runtime payload (the input parameters) and return a result, +3. prepares the activation context, +4. flushes all `stdout` and `stderr` logs and adds a frame marker at the end of the activation. + +Any container which implements [the interface](#action-interface) may be used as an action. +It is in this way that you can add support for other languages or customized runtimes. + +The interface is enforced via a [canonical test suite](../tests/src/test/scala/actionContainers/BasicActionRunnerTests.scala) +which validates the initialization protocol, the runtime protocol, ensures the activation context is correctly prepared, +and that the logs are properly framed. Your runtime should extend this test suite, and of course include additional tests +as needed. + +The runtime support is best implemented in its own repository to permit a management +lifecycle independent of the rest of the OpenWhisk platform which only requires the following +additions: +1. introduce the runtime specification into the [runtimes manifest](../ansible/files/runtimes.json), +2. add a new `actions-<your runtime>.md` file to the [docs](.) directory, +3. add a link to your new language or runtime to the [top level index](actions.md#languages-and-runtimes), +4. add the runtime to the [Swagger file](../core/controller/src/main/resources/apiv1swagger.json), +5. add a standard test action to the [tests artifacts](../tests/dat/actions/unicode.tests). + +### The runtime manifest + +Actions when created specify the desired runtime for the function via a property called "kind". +When using the `wsk` CLI, this is specified as `--kind <runtime-kind>`. The value is a typically +a string describing the language (e.g., `nodejs`) followed by a colon and the version for the runtime +as in `nodejs:8` or `php:7.2`. + +The manifest is a map of runtime family names to an array of specific kinds. The details of the +schema are found in the [Exec Manifest](../common/scala/src/main/scala/whisk/core/entity/ExecManifest.scala). +As an example, the following entry add a new runtime family called `nodejs` with a single kind +`nodejs:6`. + +```json +{ "nodejs": [{ + "kind": "nodejs:6", + "default": true, + "image": { + "prefix": "openwhisk", + "name": "nodejs6action", + "tag": "latest" + } + }] +} +``` + +The `default` property indicates if the corresponding kind should be treated as the +default for the runtime family. The `image` structure defines the Docker image name +that is used for actions of this kind (e.g., `openwhisk/nodejs6action:latest` here). + +### The test action + +The standard test action is shown below in JavaScript. It should be adapted for the +new runtime and added to the [test artifacts directory](../tests/dat/actions/unicode.tests) +with the name `<runtime-kind>.txt` for plain text file or `<runtime-kind>.bin` for a +a binary file. The `<runtime-kind>` must match the value used for `kind` in the corresponding +runtime manifest entry. + +```js +function main(args) { + var str = args.delimiter + " ☃ " + args.delimiter; + console.log(str); + return { "winter": str }; +} +``` + +### Canonical runtime repository + +The runtime repository should follow the canonical structure used by other runtimes. + +``` +/path/to/runtime +├── build.gradle # Gradle build file to integrate with rest of build and test framework +├── core +│ └── <runtime name and version> +│ ├── Dockerfile # builds the runtime's Docker image +│ └── ... # your runtimes files which implement the action proxy +└── tests + └── src # tests suits... + └── ... # ... which extend canonical interface plus additional runtime specific tests +``` Review comment: Should we add the gradle - docker.gradle into the runtime repository structure as well. ---------------------------------------------------------------- This is an automated message from the Apache Git Service. To respond to the message, please log on GitHub and use the URL above to go to the specific comment. For queries about this service, please contact Infrastructure at: [email protected] With regards, Apache Git Services
