Deployment Configuration Specification

This document formally describe the project configuration format.

Project configurations are written in YAML, with some restrictions:

indentation must be exactly 2 whitespace characters. No tabs are allowed.

Notation

This document uses Markdown Syntax for Object Notation to describe the JSON schema constraining project description.

`project` (top-level schema)

A project is an object representing a collection of OpenWhisk entities (actions, packages, rules, triggers and apis) and related resources. It also contains metadata, such as name and version.

Properties

name (string, optional) : the name associated to the entities described in the deployment. When set, do not change this without proper review as commands like undeploy may not work as expected.

When specified, deployed entities are fully managed.

Unmanaged entities are entities deployed using a tool other than fsh, such as wsk.

Partially managed entities are entities described in deployment files and deployed using fsh.

Compare to partially managed entities, fully managed deployments provide these additional guarantees:
- during deployment:
  - entities removed from deployment files are also undeployed
  - external (not managed by this deployment) entities are not overwritten. (Conflict detection)
- during undeployment:
  - all entities are undeployed, independently of changes in deployment files.
Internally, a fully managed entity contains the annotation called managed.
basePath (string, optional): the relative or absolute base path used to resolve relative location.
version (string, optional): project version following semver format.
dependencies (array, optional): includes external project configurations
resources (object, optional): related resources
packages (object, optional)
actions (object, optional)
triggers (object, optional)
rules (object, optional)
apis (object, optional)
environments (object, optional): project environments

Example

name: example
version: 0.1.0
basePath: .

dependencies:  # includes other project configuration
actions:   # actions in the default package
packages:  # actions in packages and package bindings
triggers:
rules:
apis:

`dependencies`

An array of dependency objects.

`dependency`

An object representing an external project configuration.

Limitation: nested dependencies are currently not supported.

Properties

location (string, required): the URL to the dependent project configuration file.

Supported format:
- git: git+<protocol>://[<user>[:<password>]@]<hostname>[:<port>][:][/]<path>#<commit-ish>, where protocol is one of ssh, http, https, or file. See here for support commit-ish formats.
- file: ./<path> or /<path>

Example

dependencies:
  - location: git+https://github.com/lionelvillard/openwhisk-deploy.git/project.yaml#master

`resources`

An object of resource objects

Properties

resource-name (resource): define a resource.

`resource`

An object representing the resource characteristics.

Properties

name (string, optional): the name of the resource. If not specified, use the associated resource-name key.
type (string, required): the resource type.
managed: (boolean, required): whether this resource is managed. A managed resource can be created, updated and deleted. Unmanaged resources are read-only; An error occurs when they do not already exist.
argument-name (any): resource-specific arguments. See resource type documentation below.

The supported types are:

IBM cloud resource types

`packages`

An object representing a list of packages. Package name must be unique among the set of package names within a namespace

Properties

package-name (binding resourceBinding | packageContent | interpolation)

`binding`

An object representing a package binding

Properties

bind (string, required): the name of the package to bind
inputs (parameters, optional): binding parameters
annotations (annotations, optional)
publish (boolean, optional, default: false): indicate whether the package is public or private

Example

packages:
  utils-binding:
    bind: /whisk.system/utils

`resourceBinding`

An object representing a resource binding

Properties

resource (string, required): the name of a resource

Example

resources:
  cloudant:
    ...

packages:
  cloudant-binding:
    resource: cloudant

`packageContent`

An object representing the content of a package.

Properties

actions (object, optional): a list of actions
inputs (parameters, optional): package parameters
annotations (annotations, optional)
publish (boolean, optional, default: false): indicate whether the package is public or private

`actions`

An object representing a list of actions.

Actions can be specified in any order, e.g. actions composing sequences can be specified after sequences. An error is raised when a cyclic dependency is detected.

Properties

action-name (action | sequence | copy | inline, optional)

where action-name must be unqualified and must be unique among the list of action names.

`action`

An object representing an action. Extends baseAction

Properties

location (string, required): the action code location. Either a folder or a file.

Relative paths are resolved by using the in-scope basePath value.

kind (enum, optional): the action kind. Determined automatically (see below)

Actual kind	Specified Kind	Default When
nodejs:6	nodejs nodejs:6 nodejs:default	file extension is `.js` file name is `package.json` folder contains `package.json`
python:2	python python:2	file extension is `.py`
python:3	python:3
java	java	file extension is `.jar`
php:7.1	php php:7.1	file extension is `.php`
swift:3.1.1	swift swift:3.1.1	file extension is `.swift`
swift:3	swift swift:3
docker	blackbox	file is `Dockefile` folder contains `Dockerfile` action has `image` property

main (string, optional): the action entry point. Only valid for Java (no default), PHP (default is main) and Python (default is main).
image (string, optional): a docker image.

Extensions

package: zip builder.
web: syntactic sugar for configurating Web actions.
combinator: syntactic sugar for the combinator package.

Examples

sequence

packages:
  utils:
    actions:
      cat:
        location: cat.js
        kind: nodejs
      mysequence:
        sequence: /whisk.system/utils/echo, /whisk.system/utils/cat

docker

actions:
  docker-action:
    image: openwhisk/dockerskeleton

`copy`

An object representing an action to copy.

Extends baseAction

Properties

copy (string, optional): the name of the action to copy. Subject to naming resolution

Copy parameters, annotations, limits and the action executable content. Can be overridden or extended with inputs, annotations, limits

The action to copy can either be locally defined (in the same manifest) or already deployed.

Example

packages:
  utils:
    actions:
      mycat:  # Copy deployed 'cat' action
        copy: /whisk.system/utils/cat
        inputs:
          lines: Hello Gentle World

      mycat2: # Copy locally defined 'mycat' action
        copy: mycat

`inline`

An object representing an action with inlined code.

Extends baseAction

Properties

code (string, required): the action textual code.
kind (baseAction enum, required): the required action kind

Example

packages:
  utils:
    actions:
      myecho:
        kind: nodejs
        code: |
          function main(params) {
            console.log(params);
            return params || {};
          }

`sequence`

An object representing a sequence action. Extends baseAction

Properties

sequence (string, required): a comma-separated list of action names.

Non-fully qualified action names are resolved as described here

Example

packages:
  utils:
    actions:
      mysequence:
        sequence: /whisk.system/utils/echo, /whisk.system/utils/cat

`baseAction`

A common set of action properties.

properties

limits (limits, optional): the action limits
inputs (parameters, optional): action parameters
annotations (annotations, optional)

Builtin annotations:
- web-export (true|false): enable/disable web action
- raw-http (true|false): enable/disable raw HTTP handling
builder (builder, optional): the action builder.

`triggers`

An object representing a list of triggers.

Properties

trigger-name (object, trigger|feed, optional)

`trigger`

An object representing a trigger.

Properties

inputs (parameters, optional): trigger parameters
annotations (annotations, optional)
publish (boolean, optional, default: false): indicate whether the package is public or private

`feed`

An object representing a feed.

Properties

feed (string, required): a feed name
inputs (parameters, optional): feed parameters
annotations (annotations, optional)
publish (boolean, optional, default: false): indicate whether the package is public or private

Example

triggers:
  # Trigger named "image-uploaded"
  # Creating trigger to fire events when data is inserted
  image-uploaded:
    feed: openwhisk-cloudant/changes
    inputs:
      dbname: ${vars.CLOUDANT_DATABASE}

`rules`

An object representing a list of rules.

Properties

rule-name (object, rule, optional)

`rule`

An object representing a rule.

Properties

trigger (string, required): the trigger name. Resolved as described here
action (string, required): the action name. Resolved as described here
status (enum active|inactive, optional): whether the rule is active or inactive. Default is active

Example

rules:
  # Rule named "echo-images"
  # Creating rule that maps database change trigger to sequence
  echo-images:
    trigger: image-uploaded
    action: write-from-cloudant-sequence

`apis`

An object representing a list of apis.

Properties

apiname (object, api, optional):

`api`

An object representing an api. The format loosely follows the OpenAPI format.

Properties

basePath (string, required): the API base path. LIMITATION: currently it must be the same as the api name
paths (apiPaths, optional): the list of relative paths

Plugin extensions:

swagger: describes routes in Swagger.

Example

apis:
  /hello:
    basePath: /hello
    paths:
      /world:
        get: hello

`apiPaths`

An object representing a list of relative api paths.

Properties

relpath (object, apiPath, optional):

`apiPath`

An object representing a path.

Properties

get (string, optional): the action name of the GET operation
put (string, optional): the action name of the PUT operation
post (string, optional): the action name of the POST operation
delete (string, optional): the action name of the DELETE operation
options (string, optional): the action name of the OPTIONS operation
head (string, optional): the action name of the HEAD operation
patch (string, optional): the action name of the PATCH operation

`parameters`

An object representing a list of parameters

Properties

key (string | interpolation, optional)

Example

Action parameters:

packages:
  utils:
    actions:
      cat:
        location: cat.js
        inputs:
          mykey: myvalue

`annotations`

An object representing a list of annotations.

Properties

{key} (string | interpolation, optional)

`limits`

An object representing action limits

Properties

memory (integer, optional, default: 256): the maximum memory limit in MB for the action
logsize (integer, optional, default:10): the maximum log size limit in MB for the action
timeout (integer, optional, default:60000): the timeout limit in milliseconds after which the action is terminated

Properties

plugin (string, required): the name of the plugin

`builder`

An object representing the action builder.

Extensible: see builder contribution point.

Properties

name (string, required): the name of the builder plugin.
paramname (any): the plugin input parameters

Example

actions:
  zipaction:
    builder:
      name: package
      excludes:
        - *.ts

`interpolation`

A string of the form ${ expr } where expr is interpreted as a Javascript expression returning a JSON value. This expression is evaluated in a sandbox initialized to this object:

vars: an object containing resolved variable values in addition to built-in variables.

The built-in variables are:

envname: name of the current environment

`environments`

An object representing a list of environments.

Properties

name (object, environment, optional): the named environment. Use envname in interpolations to get the current environment name.

`environment`

An object representing a set of policies attached to the environment.

Properties

writable (boolean, optional): dictate which deployment mode to use when deploying projects.

Entity name resolution

Non-fully qualified entity names are resolved as follows:

partially qualified names (packageName/actionName) are resolved using the enclosing namespace
unqualified names (actionName) are resolved using the enclosing package name (if any) and namespace.

Files

format.md

Latest commit

History

format.md

File metadata and controls

Deployment Configuration Specification

Notation

project (top-level schema)

Properties

Example

dependencies

dependency

Properties

Example

resources

Properties

resource

Properties

packages

Properties

binding

Properties

Example

resourceBinding

Properties

Example

packageContent

Properties

actions

Properties

action

Properties

Extensions

Examples

sequence

docker

copy

Properties

Example

inline

Properties

Example

sequence

Properties

Example

baseAction

properties

triggers

Properties

trigger

Properties

feed

Properties

Example

rules

Properties

rule

Properties

Example

apis

Properties

api

Properties

Example

apiPaths

Properties

apiPath

Properties

parameters

Properties

Example

annotations

Properties

limits

Properties

Properties

builder

Properties

Example

`project` (top-level schema)

`dependencies`

`dependency`

`resources`

`resource`

`packages`

`binding`

`resourceBinding`

`packageContent`

`actions`

`action`

`copy`

`inline`

`sequence`

`baseAction`

`triggers`

`trigger`

`feed`

`rules`

`rule`

`apis`

`api`

`apiPaths`

`apiPath`

`parameters`

`annotations`

`limits`

`builder`

`interpolation`

`environments`

`environment`