diff --git a/README.md b/README.md index 9c4e8b9b1..392a737e3 100644 --- a/README.md +++ b/README.md @@ -154,29 +154,57 @@ After compiling, a suitable wskdeploy binary that works for your OS platform wil 1. Verify your installed Gradle version is `5.5.1` (or higher) - - If you use Windows OS, type ```gradlew.bat -version ```. - - For Unix/Linux/Mac, please type ```./gradlew -version```. + - On Windows OS, type ```gradlew.bat -version ```. + - On Unix/Linux/Mac, please type ```./gradlew -version```. > **Note** Gradle v6 is not yet supported. -1. For Windows type ```gradlew.bat distDocker```. For Linux/Unix/Mac, please type ```./gradlew distDocker```. These -commands will start the wskdeploy cross compile for your specific OS platform inside a Docker container. +1. Cross-compile binaries for all supported Operating Systems and Architectures: -1. After build success, you should find a correct binary under current /bin dir of you openwhisk-deploy clone dir. + - On Windows, type ```gradlew.bat goBuild``` + - On Linux/Unix/Mac, please type ```./gradlew goBuild```. -If you would like to build the binaries available for all the operating systems and architectures, run the following command: +1. Upon a successful build, all binaries can be found within the `./build` directory of your project: -```sh -$ ./gradlew distDocker -PcrossCompileWSKDEPLOY=true -``` + ```sh + $ ls build + darwin-amd64 linux-amd64 linux-arm64 linux-s390x windows-amd64 + linux-386 linux-arm linux-ppc64le windows-386 + ``` -Then, you will find the binaries and their compressed packages generated under the folder ```bin///``` for each supported Operating System and CPU Architecture pair. +#### Compiling for a single OS/ARCH + +1. View gradle build tasks for supported Operating Systems and Architectures: + + ```sh + ./gradlew tasks + ``` -### Building for Internationalization + you will see build tasks for supported OS/ARCH combinations: + + ```sh + Gogradle tasks + -------------- + buildDarwinAmd64 - Custom go task. + buildLinux386 - Custom go task. + buildLinuxAmd64 - Custom go task. + buildLinuxArm - Custom go task. + buildLinuxArm64 - Custom go task. + buildLinuxPpc64le - Custom go task. + buildLinuxS390x - Custom go task. + buildWindows386 - Custom go task. + buildWindowsAmd64 - Custom go task. + ``` + + > Note: The `buildWindows386` option is only supported on Golang versions less than 1.15. + +#### Building for Internationalization Please follow this process for building any changes to translatable strings: - [How to generate the file i18n_resources.go for internationalization](https://github.com/apache/openwhisk-wskdeploy/blob/master/wski18n/README.md) +--- + ### Running as a Go program Since ```wskdeploy``` is a GoLang program, you may choose to run it using the Go utility. After building the wskdeploy binary, you can run it as follows: diff --git a/build.gradle b/build.gradle index 49d68d6eb..af63a7c89 100644 --- a/build.gradle +++ b/build.gradle @@ -38,7 +38,7 @@ golang { } // The `gogradle` plugin was designed to work with `govendor` and `godeps` tools -// We must disable its tasks that attempt to "fetch" dpendendencies +// We must disable its tasks that attempt to "fetch" dependencies // into a "/vendor" directory and use them to build the project (which will fail) installDependencies.enabled = false resolveBuildDependencies.enabled = false diff --git a/parsers/manifest_parser_test.go b/parsers/manifest_parser_test.go index c09f0db30..18db3bd6e 100644 --- a/parsers/manifest_parser_test.go +++ b/parsers/manifest_parser_test.go @@ -1924,9 +1924,9 @@ func TestParseYAML_param(t *testing.T) { assert.Equal(t, false, param.Value, "Get param value failed.") case "inline0": assert.Equal(t, 456.423, param.Value, "Get param value failed.") - case "inlin10": + case "inline10": assert.Equal(t, nil, param.Value, "Get param value failed.") - case "inlin11": + case "inline11": assert.Equal(t, true, param.Value, "Get param value failed.") case "expand1": assert.Equal(t, nil, param.Value, "Get param value failed.") diff --git a/specification/html/spec_actions.md b/specification/html/spec_actions.md index 6995348fc..14b7f72d8 100644 --- a/specification/html/spec_actions.md +++ b/specification/html/spec_actions.md @@ -20,6 +20,7 @@ ## Actions #### Subsections + - [Fields](#fields) - [Requirements](#requirements) - [Notes](#notes) @@ -32,6 +33,7 @@ The Action entity schema contains the necessary information to deploy an OpenWhisk function and define its deployment configurations, inputs and outputs. ### Fields + | Key Name | Required | Value Type | Default | Description | |:---|:---|:---|:---|:---| | version | no | [version](spec_parameter_types.md#openwhisk-types) | N/A | The optional user-controlled version for the Action. | @@ -78,6 +80,7 @@ The following annotations have special meanings for Actions: - When the `code` key-value is specified, the `runtime` **SHALL** be a required field. #### Annotation requirements + - The annotation `require-whisk-auth` **SHALL** only be valid for web actions (i.e., if the `web` key or `web-export` annotation is set to `true`). - If the value of the `require-whisk-auth` annotation is an `integer` its value **MUST** be a positive integer less than or equal to the `MAX_INT` value of `9007199254740991`. - When the `web` or `web-export` key is present and set to `true` the web action's **MUST** also be marked `final`. This happens automatically when the `web` or `web-export` keys are present and set to `true`. @@ -175,12 +178,12 @@ See the file [runtimes.json](https://github.com/apache/openwhisk/blob/master/ans the main [apache/openwhisk](https://github.com/apache/openwhisk) repository for the latest supported runtimes nad versions. #### Notes + - **WARNING**: _For OpenWhisk project builds, the Docker image used is tagged `nightly` in Docker Hub (e.g, for GitHub pull requests). Production uses of OpenWhisk code may use different images and tagged (released) image versions._ - If no value for `runtime` is supplied, the value `language:default` will be assumed. - OpenWhisk runtimes may also include additional built-in packages (or libraries) that have been determined be useful for Actions surveyed and tested by the OpenWhisk platform. - ### Recognized File extensions Although it is best practice to provide a runtime value when declaring an Action, it is not required. In those cases, that a runtime is not provided, the package tooling will attempt to derive the correct runtime based upon the the file extension for the Action's function (source code file). The diff --git a/specification/html/spec_apis.md b/specification/html/spec_apis.md index df59fa759..7802a09c6 100644 --- a/specification/html/spec_apis.md +++ b/specification/html/spec_apis.md @@ -22,6 +22,7 @@ The API entity schema is used to define an OpenWhisk API within a manifest. ### Fields + diff --git a/specification/html/spec_entity_naming_and_namespacing.md b/specification/html/spec_entity_naming_and_namespacing.md index 1e37fc7ed..809e37003 100644 --- a/specification/html/spec_entity_naming_and_namespacing.md +++ b/specification/html/spec_entity_naming_and_namespacing.md @@ -26,7 +26,7 @@ packages, belongs in a *namespace.* The fully qualified name of any entity has the format: -``` +```sh /[/]/ ``` @@ -34,7 +34,7 @@ The namespace is typically provided at bind-time by the user deploying the packa #### Requirements -- The “/whisk.system“ namespace is reserved for entities that are distributed with the OpenWhisk system. +- The “/whisk.system“ namespace is reserved for entities that are distributed with the OpenWhisk system. ### Entity Names @@ -42,17 +42,19 @@ The names of all entities, including actions, triggers, rules, packages, and namespaces, are a sequence of characters that follow the following format: -- The first character SHALL be an alphanumeric character, a digit, or an underscore. -- The subsequent characters MAY be alphanumeric, digits, spaces, or any of the following: -``` -_, @, ., - -``` +- The first character SHALL be an alphanumeric character, a digit, or an underscore. +- The subsequent characters MAY be alphanumeric, digits, spaces, or any of the following: + + ```sh + _, @, ., - + ``` + - The last character SHALL NOT be a space. - The maximum name length of any entity name is 256 characters (i.e., ENTITY_NAME_MAX_LENGTH = 256). Valid entity names are described with the following regular expression (Java metacharacter syntax): -``` +```sh "\A([\w]|[\w][\w@ .-]{0,${ENTITY_NAME_MAX_LENGTH - 2}}[\w@.-])\z" ``` diff --git a/specification/html/spec_intro.md b/specification/html/spec_intro.md index ac6b8e55d..984352bff 100644 --- a/specification/html/spec_intro.md +++ b/specification/html/spec_intro.md @@ -31,15 +31,15 @@ Development Kits (SDKs). The code for the Actions, along with any support services implementing *Feeds*, are packaged according to this specification to be compatible with the OpenWhisk catalog and its tooling. It also serves as a means for architects and developers to model OpenWhisk package Actions as part of full, event-driven services and applications providing the necessary information for artifact and data type validation along with package management operations. -### Compatibility +## Compatibility This specification is intended to be compatible with the following specifications: -- *OpenWhisk API which is defined as an OpenAPI document: * - - +- *OpenWhisk API which is defined as an OpenAPI document:* + - -- *OpenAPI Specification when defining REST APIs and parameters:* - - +- *OpenAPI Specification when defining REST APIs and parameters:* + - -

Normative References

-

 

+
- - + +
-

Tag

- 		-

Description

- 		TagDescription
-

RFC2119

+

RFC2119

S. Bradner, Key words for use in RFCs to Indicate Requirement Levels, http://www.ietf.org/rfc/rfc2119.txt, IETF RFC 2119, March 1997.

@@ -44,7 +39,7 @@
-

YAML-1.2

+

YAML-1.2

YAML, Version 1.2, 3rd Edition, Patched at 2009-10-01, Oren Ben-Kiki, Clark Evans, Ingy dšt Net http://www.yaml.org/spec/1.2/spec.html

@@ -52,7 +47,7 @@
-

YAML-TS-1.1

+

YAML-TS-1.1

Timestamp Language-Independent Type for YAML Version 1.1, Working Draft 2005-01-18, http://yaml.org/type/timestamp.html

@@ -60,7 +55,7 @@
-

Maven-Version

+

Maven-Version

The version type is defined with the Apache Maven project's policy draft:

@@ -69,7 +64,7 @@
-

OpenAPI-2.0

+

OpenAPI-2.0

The OpenAPI (f.k.a. 'Swagger') specification for defining REST APIs as JSON.

@@ -78,7 +73,7 @@
-

Linux-SPDX

+

Linux-SPDX

Linux Foundation, SPDX License list

@@ -87,7 +82,7 @@
-

NPM-SPDX-Syntax

+

NPM-SPDX-Syntax

Node Package Manager (NPM) SPDX License Expression Syntax

@@ -103,19 +98,15 @@ -->

Non-normative References

-

 

+ - - + +
-

Tag

- 		-

Description

- 		TagDescription
-

OpenWhisk-API

+

OpenWhisk-API

OpenWhisk REST API which is defined as an OpenAPI document.

@@ -124,7 +115,7 @@
-

GNU-units

+

GNU-units

Size-type units are based upon a subset of those defined by GNU at http://www.gnu.org/software/parted/manual/html_node/unit.html

@@ -132,7 +123,7 @@
-

RFC 6838

+

RFC 6838

Mime Type definitions in compliance with RFC 6838.

@@ -140,7 +131,7 @@
-

RFC 7231

+

RFC 7231

HTTP 1.1. status codes are described in compliance with RFC 7231.

@@ -148,7 +139,7 @@
-

IANA-Status-Codes

+

IANA-Status-Codes

HTTP Status codes as defined in the IANA Status Code Registry.

@@ -159,8 +150,8 @@

JSON Schema Specification

 -

The built-in parameter type 'json' references this specification.

-

http://json-schema.org/

+

The built-in parameter type 'json' references this specification: + http://json-schema.org/
diff --git a/specification/html/spec_package_processing.md b/specification/html/spec_package_processing.md index 29a501fb0..5234c56c1 100644 --- a/specification/html/spec_package_processing.md +++ b/specification/html/spec_package_processing.md @@ -22,12 +22,12 @@ This document defines two file artifacts that are used to deploy Packages to a target OpenWhisk platform; these include: -- ***Package Manifest file***: Contains the Package definition along +- ***Package Manifest file***: Contains the Package definition along with any included Action, Trigger or Rule definitions that comprise the package. This file includes the schema of input and output data to each entity for validation purposes. -- ***Deployment file*** (optional): Contains the values and bindings used +- ***Deployment file*** (optional): Contains the values and bindings used configure a Package to a target OpenWhisk platform provider’s environment and supply input parameter values for Packages, Actions and Triggers. This can include Namespace bindings, security and @@ -35,10 +35,9 @@ Packages to a target OpenWhisk platform; these include: #### Notes -- _Deployment files are optional_. Deployment can be fully accomplished +- _Deployment files are optional_. Deployment can be fully accomplished with simply a Manifest File. - ### Conceptual Package creation and publishing The following diagram illustrates how a developer would create OpenWhisk diff --git a/specification/html/spec_parameter_types.md b/specification/html/spec_parameter_types.md index ff725deb0..25b3d0289 100644 --- a/specification/html/spec_parameter_types.md +++ b/specification/html/spec_parameter_types.md @@ -17,7 +17,7 @@ # --> -# Parameter Types +## Parameter Types - [YAML Types](#yaml-types) - [OpenWhisk Types](#openwhisk-types) @@ -25,7 +25,7 @@ --- -#### YAML Types +### YAML Types Many of the types we use in this profile are *built-in* types from the [YAML 1.2 specification](http://www.yaml.org/spec/1.2/spec.html) (i.e., those identified by the “tag:yaml.org,2002” version tag). @@ -40,7 +40,7 @@ The following table declares the valid YAML type URIs and aliases that SHALL be | timestamp | tag:yaml.org,2002:timestamp | ISO 8601 compatible timestamp. See [YAML-TS-1.1](spec_normative_refs.md) | | null | tag:yaml.org,2002:null | Different meaning than an empty string, map, list, etc. | -#### Requirements +### Requirements - The ‘string’ type SHALL be the default type when not specified on a parameter or property declaration. - All ‘boolean’ values SHALL be lowercased (i.e., ‘true’ or ‘false’). diff --git a/specification/html/spec_parameters.md b/specification/html/spec_parameters.md index fc9436987..0efffca47 100644 --- a/specification/html/spec_parameters.md +++ b/specification/html/spec_parameters.md @@ -23,12 +23,14 @@ - [Dollar Notation ($)](#dollar-notation--schema-for-values) ## Parameter schema + The Parameter schema is used to define input and/or output data to be used by OpenWhisk entities for the purposes of validation. ### Fields + | Key Name | Required | Value Type | Default | Description | |:---|:---|:---|:---|:---| -| type | no | _<any>_ | string | Optional valid type name or the parameter’s value for alidation purposes. By default, the type is string. | +| [type](./spec_parameter_types.md) | no | _<any>_ | string | Optional valid type name or the parameter’s value for validation purposes. By default, the type is string. | | description | no | string256 | N/A | Optional description of the Parameter. | | value | no | _<any>_ | N/A | The optional user supplied value for the parameter.
Note: this is not the default value, but an explicit declaration which allows simple usage of the Manifest file without a Deployment file. | | required | no | boolean | true | Optional indicator to declare the parameter as required (i.e., true) or optional (i.e., false). | @@ -39,26 +41,72 @@ The Parameter schema is used to define input and/or output data to be used by Op ### Requirements -The 'schema' key's value MUST be compatible with the value provided on both the 'type' and 'value' keys; otherwise, it is considered an error. +The `schema` key's value MUST be compatible with the value provided on both the 'type' and 'value' keys; otherwise, it is considered an error. ### Notes -The 'type' key acknowledges some popular schema (e.g., JSON) to use when validating the value of the parameter. In the future additional (schema) types may be added for convenience. +The `type` key acknowledges some popular schema (e.g., JSON) to use when validating the value of the parameter. In the future additional (schema) types may be added for convenience. -### Grammar +### Examples + +#### Single-line declaration *(type inferred)* -#### Single-line ```yaml +... + inputs: + inline1: '{ "key": true }' + inline2: Just a string + inline3: null + inline4: true + inline5: 42 + inline6: -531 + inline7: 432.432E-43 + inline8: '[ true, null, "boo", { "key": 0 }]' + inline9: !!bool false + inline0: !!float 456.423 + inline10: # JSON null + inline11: True # JSON true + inline12: ["v1", "v2"] # Array + inline13: # Array + - "value1" + - "value2" ``` -Where is inferred to be a YAML type as shown in the YAML Types section above (e.g., string, integer, float, boolean, etc.). +Where `` is inferred to be a YAML type as shown in the YAML Types section above (e.g., string, integer, float, boolean, etc.). If you wish the parser to validate against a different schema, then the multi-line grammar MUST be used where the value would be supplied on the keyname 'value' and the type (e.g., 'json') and/or schema (e.g., OpenAPI) can be supplied. -#### Multi-line +#### Multi-line declaration *(explicitly typed)* + ```yaml +... + inputs: + multiline1: + value: "hello" + type: string + description: "greeting" + multiline2: + value: '{ "key": true }' + type: string + description: "map as string" + multiline3: + value: null + type: string + description: "null string" + multiline4: + value: 42 + type: integer + multiline: + value: 456.423 + type: float ``` +More examples of multiline, including advanced types like JSON, can be found here: + +- [docs/examples/manifest_hello_world_advanced_parms.yaml](docs/examples/manifest_hello_world_advanced_parms.yaml) +- [tests/dat/manifest_validate_multiline_params.yaml](tests/dat/manifest_validate_multiline_params.yaml) +- [tests/dat/manifest_validate_json_params.yaml](tests/dat/manifest_validate_json_params.yaml) + ### Status values | Status Value | Description | @@ -101,23 +149,31 @@ annotations: > - Several, non-normative "annotations" keynames and allowed values (principally for User Interface (UI) design and tooling information) may be defined in this specification or optional usage. +--- ## Dollar Notation ($) schema for values In a Manifest or Deployment file, a parameter value may be set from the local execution environment by using the dollar ($) notation to denote names of local environment variables which supply the value to be inserted at execution time. ### Syntax + ```yaml : $ ``` -### Example +### Examples + ```yaml ... inputs: userName: $DEFAULT_USERNAME ``` +More examples of dollar notation, including use within JSON data, can be found here: + +- [docs/examples/manifest_hello_world_env_var_parms.yaml](docs/examples/manifest_hello_world_env_var_parms.yaml) +- [tests/dat/manifest_validate_json_params.yaml](tests/dat/manifest_validate_json_params.yaml) + ### Requirements - Processors or tooling that encounter ($) Dollar notation and are unable to locate the value in the execution environment SHOULD resolve the value to be the default value for the type (e.g., an empty string ("") for type 'string'). @@ -127,7 +183,6 @@ In a Manifest or Deployment file, a parameter value may be set from the local ex - Processors or tooling that encounter ($) Dollar notation for values should attempt to locate the corresponding named variables set into the local execution environment (e.g., where the tool was invoked) and assign its value to the named input parameter for the OpenWhisk entity. - This specification does not currently consider using this notation for other than simple data types (i.e., we support this mechanism for values such as `strings`, `integers`, `floats`, etc.) at this time. - diff --git a/specification/html/spec_rule.md b/specification/html/spec_rule.md index 0b6b80ded..1fa2137fd 100644 --- a/specification/html/spec_rule.md +++ b/specification/html/spec_rule.md @@ -22,6 +22,7 @@ The Rule entity schema contains the information necessary to associates one trigger with one action, with every firing of the trigger causing the corresponding action to be invoked with the trigger event as input. For more information, see the document "[Creating Triggers and Rules](https://github.com/apache/openwhisk/blob/master/docs/triggers_rules.md)". #### Subsections + - [Fields](#fields) - [Requirements](#requirements) - [Notes](#notes) @@ -29,6 +30,7 @@ The Rule entity schema contains the information necessary to associates one trig - [Example](#example) ### Fields + diff --git a/specification/html/spec_schema.md b/specification/html/spec_schema.md index d7eb41862..e8c311027 100644 --- a/specification/html/spec_schema.md +++ b/specification/html/spec_schema.md @@ -17,7 +17,7 @@ # --> -# Schema +## Schema This section defines all the essential schema used to describe OpenWhisk packages and programming model entities within a manifest. diff --git a/specification/html/spec_sequences.md b/specification/html/spec_sequences.md index 0529d89fc..6fe9a0630 100644 --- a/specification/html/spec_sequences.md +++ b/specification/html/spec_sequences.md @@ -22,6 +22,7 @@ Actions can be composed into sequences to, in effect, form a new Action. The Sequence entity allows for a simple, convenient way to describe them in the Package Manifest. ### Fields +
@@ -77,6 +78,7 @@ sequences: ``` ### Example + ```yaml sequences: newbot: diff --git a/specification/html/spec_shared_entity_schema.md b/specification/html/spec_shared_entity_schema.md index 34798a853..ff413e54f 100644 --- a/specification/html/spec_shared_entity_schema.md +++ b/specification/html/spec_shared_entity_schema.md @@ -90,6 +90,7 @@ The Entity Schema contains fields that are common (shared) to all OpenWhisk enti ### Grammar + ```yaml description: displayName: @@ -97,7 +98,8 @@ annotations: > ``` ### Requirements -- Non-required fields MAY be stored as ÒannotationsÓ within the OpenWhisk framework after they have been used for processing. + +- Non-required fields MAY be stored as `annotations` within the OpenWhisk framework after they have been used for processing. - Description string values SHALL be limited to 256 characters. - DisplayName string values SHALL be limited to 16 characters. - Annotations MAY be ignored by target consumers of the Manifest file as they are considered data non-essential to the deployment of management of OpenWhisk entities themselves. @@ -105,6 +107,7 @@ annotations: > - For any OpenWhisk Entity, the maximum size of all Annotations SHALL be 256 characters. ### Notes + - Several, non-normative Annotation keynames and allowed values for (principally for User Interface (UI) design) may be defined below for optional usage.