diff --git a/content/en/docs/installation/prereq/docker/_index.md b/content/en/docs/installation/prereq/docker/_index.md index bf569f57..8ce7230a 100644 --- a/content/en/docs/installation/prereq/docker/_index.md +++ b/content/en/docs/installation/prereq/docker/_index.md @@ -49,7 +49,7 @@ you also need also to reserve at least 8GB. > ❗ **IMPORTANT** > -> On MacOS, the default 2GB and they are definitely **not enough** to run +> On MacOS, Docker defaults to 2GB memoery and they are definitely **not enough** to run OpenServerless on your local machine. ![](/docs/installation/images/install_docker_desktop.png) diff --git a/content/en/docs/installation/quickstart/_index.md b/content/en/docs/installation/quickstart/_index.md index a6e64304..79c78ce6 100644 --- a/content/en/docs/installation/quickstart/_index.md +++ b/content/en/docs/installation/quickstart/_index.md @@ -19,7 +19,7 @@ apply the rule: "if everything fails, read the manual". Start ensuring the prerequsites are satisfied: -- [Download and install](/docs/installation/download/) ops, the +- [Download and install](/docs/installation/download/) `ops`, the OpenServerless CLI, picking version suitable for your environment. We support 64-bit versions of recent Windows, MacOS and major Linux distributions. @@ -69,8 +69,7 @@ then install OpenServerless in it. Once you have: 3. installed Docker Desktop -Make sure Docker Desktop its running before the next operation. You can -install OpenServerless and its services in Docker with just this +Make sure Docker Desktop its running before the next operation. Install OpenServerless and its services in Docker with just this command: ops setup devcluster diff --git a/content/en/docs/reference/_index.md b/content/en/docs/reference/_index.md index 5f248cb6..bd7665f6 100644 --- a/content/en/docs/reference/_index.md +++ b/content/en/docs/reference/_index.md @@ -3,18 +3,18 @@ title: Reference description: OpenServerless Developer Guide weight: 40 --- -Welcome to Nuvolaris Developer guide. +Welcome to OpenServerless Developer guide. -Nuvolaris is based on [Apache OpenWhisk](https://openwhisk.apache.org) +OpenServerless is based on [Apache OpenWhisk](https://openwhisk.apache.org) and the documentation in this section is derived for the official OpenWhisk documentation. In this sections we mostly document how to write [**actions** (functions)](#actions.adoc), the building blocks of OpenWhisk and -Nuvolaris applications. There are also a few related entities for +OpenServerless applications. There are also a few related entities for managing actions (packages, parameters etc) you also need to know. -You can write actions in a number of programming languages. Nuvolaris +You can write actions in a number of programming languages. OpenServerless supports directly [this list of programming languages](#index-runtimes.adoc). The list is expanding over the time. diff --git a/content/en/docs/reference/references/actions-actionloop/_index.md b/content/en/docs/reference/references/actions-actionloop/_index.md index a4aed592..750af0ee 100644 --- a/content/en/docs/reference/references/actions-actionloop/_index.md +++ b/content/en/docs/reference/references/actions-actionloop/_index.md @@ -3,8 +3,8 @@ title: Building your runtime --- # Developing a new Runtime with the ActionLoop proxy -The [OpenWhisk and Nuvolaris runtime specification](#actions-new.adoc) -defines the expected behavior of an OpenWhisk and Nuvolaris runtime; you +The [OpenWhisk and OpenServerless runtime specification](#actions-new.adoc) +defines the expected behavior of an OpenWhisk and OpenServerless runtime; you can choose to implement a new runtime from scratch by just following this specification. However, the fastest way to develop a new, compliant runtime is by reusing the *[ActionLoop @@ -17,7 +17,7 @@ runtime in a few hours or less. The `ActionLoop proxy` is a runtime “engine”, written in the [Go programming language](https://golang.org/), originally developed -specifically to support the [OpenWhisk and Nuvolaris Go language +specifically to support the [OpenWhisk and OpenServerless Go language runtime](https://github.com/apache/openwhisk-runtime-go). However, it was written in a generic way such that it has since been adopted to implement OpenWhisk and Nuvolaris runtimes for Swift, PHP, Python, Rust, @@ -33,11 +33,11 @@ and responsive. In fact, the ActionLoop proxy has also been adopted to improve the performance of existing runtimes like Python, Ruby, PHP, and Java where performance has improved by a factor between 2x to 20x. -### Precompilation of OpenWhisk and Nuvolaris Actions +### Precompilation of OpenWhisk and OpenServerless Actions In addition to being the basis for new runtime development, ActionLoop runtimes can also support offline “precompilation” of OpenWhisk and -Nuvolaris Action source files into a ZIP file that contains only the +OpenServerless Action source files into a ZIP file that contains only the compiled binaries which are very fast to start once deployed. More information on this approach can be found here: [Precompiling Go Sources Offline](https://github.com/apache/openwhisk-runtime-go/blob/master/docs/DEPLOY.md#precompile) @@ -171,7 +171,7 @@ Our language runtime’s `Dockerfile` has the task of preparing an environment for executing OpenWhisk and Nuvolaris Actions. Using the ActionLoop approach, we use a multistage Docker build to -1. derive our OpenWhisk and Nuvolaris language runtime from an existing +1. derive our OpenWhisk and OpenServerless language runtime from an existing Docker image that has all the target language’s tools and libraries for running functions authored in that language. @@ -424,7 +424,7 @@ launch the Java runtime. ### How the ActionLoop proxy handles action uploads -The OpenWhisk and Nuvolaris user can upload actions with the `nuv` +The OpenWhisk and OpenServerless user can upload actions with the `ops` Command Line Interface (CLI) tool as a single file. This single file can be: @@ -486,7 +486,7 @@ environment variable (you may have noticed it in the Dockerfile) that will be invoked with 3 parameters: 1. `
` is the name of the main function specified by the user on - the `nuv` command line + the `ops` command line 2. `` is the absolute directory with the sources already unzipped @@ -849,10 +849,10 @@ Congratulations! The runtime works locally! Time to test it on the public cloud. So as the last step before moving forward, let’s push the image to Docker Hub with `make push`. -### Testing on OpenWhisk and Nuvolaris +### Testing on OpenWhisk and OpenServerless -To run this test you need to configure access to OpenWhisk and Nuvolaris -with `nuv`. A simple way is to get access is to register a free account +To run this test you need to configure access to OpenWhisk and OpenServerless +with `ops`. A simple way is to get access is to register a free account in the IBM Cloud but this works also with our own deployment of OpenWhisk and Nuvolaris. diff --git a/content/en/docs/reference/references/actions-new/_index.md b/content/en/docs/reference/references/actions-new/_index.md index 5eafb039..35ade7bf 100644 --- a/content/en/docs/reference/references/actions-new/_index.md +++ b/content/en/docs/reference/references/actions-new/_index.md @@ -3,7 +3,7 @@ title: Runtimes under the hood --- # Adding Action Language Runtimes -OpenWhisk and Nuvolaris supports [several languages and +OpenWhisk and OpenServerless supports [several languages and runtimes](#index-runtimes.adoc) but there may be other languages or runtimes that are important for your organization, and for which you want tighter integration with the platform. @@ -12,7 +12,7 @@ The platform is extensible and you can add new languages or runtimes (with custom packages and third-party dependencies) This guide describes the contract a runtime must satisfy. However all -the Nuvolaris runtimes are implemented the [using the ActionLoop +the OpenServerless runtimes are implemented the [using the ActionLoop Proxy](#actions-actionloop.adoc). This proxy is implemented in Go, already satifies the semantic of a runtime ands makes very easy to build a new runtime. You just need to provide "launcher code" in your favorite @@ -92,7 +92,7 @@ with a `-`. For example, a plain text function for `nodejs:20` becomes An action consists of the user function (and its dependencies) along with a *proxy* that implements a canonical protocol to integrate with -the OpenWhisk and Nuvolaris platform. +the OpenWhisk and OpenServerless platform. The proxy is a web server with two endpoints. @@ -154,7 +154,7 @@ with a JSON object as follows: milliseconds). The initialization route is called exactly once by the OpenWhisk and -Nuvolaris platform, before executing a function. The route should report +OpenServerless platform, before executing a function. The route should report an error if called more than once. It is possible however that a single initialization will be followed by many activations (via `/run`). If an `env` property is provided, the corresponding environment variables @@ -171,7 +171,7 @@ failure. The value of the error field may be any valid JSON value. The proxy should make sure to generate meaningful log message on failure to aid the end user in understanding the failure. -**Time limit:** Every action in OpenWhisk and Nuvolaris has a defined +**Time limit:** Every action in OpenWhisk and OpenServerless has a defined time limit (e.g., 60 seconds). The initialization must complete within the allowed duration. Failure to complete initialization within the allowed time frame will destroy the container. @@ -179,13 +179,13 @@ allowed time frame will destroy the container. **Limitation:** The proxy does not currently receive any of the activation context at initialization time. There are scenarios where the context is convenient if present during initialization. This will -require a change in the OpenWhisk and Nuvolaris platform itself. Note +require a change in the OpenWhisk and OpenServerless platform itself. Note that even if the context is available during initialization, it must be reset with every new activation since the information will change with every execution. The proxy is ready to execute a function once it has successfully -completed initialization. The OpenWhisk and Nuvolaris platform will +completed initialization. The OpenWhisk and OpenServerless platform will invoke the function by posting an HTTP request to `/run` with a JSON object providing a new activation context and the input parameters for the function. There may be many activations of the same function against @@ -250,7 +250,7 @@ distinguished by the value of the `response.status` in the activation record which is `application error` if the proxy returned an `error` object, and `action developer error` otherwise. -**Time limit:** Every action in OpenWhisk and Nuvolaris has a defined +**Time limit:** Every action in OpenWhisk and OpenServerless has a defined time limit (e.g., 60 seconds). The activation must complete within the allowed duration. Failure to complete activation within the allowed time frame will destroy the container. @@ -297,12 +297,12 @@ The canonical test suite should be extended by the new runtime tests. Additional tests will be required depending on the feature set provided by the runtime. -Since the OpenWhisk and Nuvolaris platform is language and runtime +Since the OpenWhisk and OpenServerless platform is language and runtime agnostic, it is generally not necessary to add integration tests. That is the unit tests verifying the protocol are sufficient. However, it may -be necessary in some cases to modify the `nuv` CLI or other OpenWhisk -and Nuvolaris clients. In which case, appropriate tests should be added -as necessary. The OpenWhisk and Nuvolaris platform will perform a +be necessary in some cases to modify the `ops` CLI or other OpenWhisk +and OpenServerless clients. In which case, appropriate tests should be added +as necessary. The OpenWhisk and OpenServerless platform will perform a generic integration test as part of its basic system tests. This integration test will require a [test function](#the-test-action) to be available so that the test harness can create, invoke, and delete the diff --git a/content/en/docs/reference/references/advanced-cli/_index.md b/content/en/docs/reference/references/advanced-cli/_index.md index 8077a2a6..eabb99d4 100644 --- a/content/en/docs/reference/references/advanced-cli/_index.md +++ b/content/en/docs/reference/references/advanced-cli/_index.md @@ -21,7 +21,7 @@ There are two required properties to configure: deployment you want to use. 2. **Authorization key** (username and password) which grants you - access to the OpenWhisk and Nuvolaris API. + access to the OpenWhisk and OpenServerless API. The API host ia the installationj host, the one you configure in installation with `ops config apihost` @@ -37,7 +37,7 @@ environment variables. source ~/.wskprops ops -wsk property set --auth $AUTH -**Tip:** The OpenWhisk and Nuvolaris CLI stores properties in the +**Tip:** The OpenWhisk and OpenServerless CLI stores properties in the `~/.wskprops` configuration file by default. The location of this file can be altered by setting the `WSK_CONFIG_FILE` environment variable. diff --git a/content/en/docs/reference/references/naming-limits/_index.md b/content/en/docs/reference/references/naming-limits/_index.md index c2f9eacb..bdd9b5fc 100644 --- a/content/en/docs/reference/references/naming-limits/_index.md +++ b/content/en/docs/reference/references/naming-limits/_index.md @@ -4,20 +4,20 @@ title: Naming And Limits # System details The following sections provide more details about the OpenWhisk and -Nuvolaris system. +OpenServerless system. ## Entities ### Namespaces and packages -OpenWhisk and Nuvolaris actions, triggers, and rules belong in a +OpenWhisk and OpenServerless actions, triggers, and rules belong in a namespace, and optionally a package. Packages can contain actions and feeds. A package cannot contain another package, so package nesting is not allowed. Also, entities do not have to be contained in a package. -In Nuvolaris a namespace corresponds to an user. You can create users +In OpenServerless a namespace corresponds to an user. You can create users with the [admin subcommand](#cli:admin.adoc) of the CLI. The fully qualified name of an entity is @@ -105,7 +105,7 @@ More precisely, a name must match the following regular expression ### Actions -OpenWhisk and Nuvolaris has a few system limits, including how much +OpenWhisk and OpenServerless has a few system limits, including how much memory an action can use and how many action invocations are allowed per minute. diff --git a/content/en/docs/reference/references/rest_api/_index.md b/content/en/docs/reference/references/rest_api/_index.md index 5e3be20f..db50787c 100644 --- a/content/en/docs/reference/references/rest_api/_index.md +++ b/content/en/docs/reference/references/rest_api/_index.md @@ -1,11 +1,10 @@ --- title: Rest API --- -# Using REST APIs with OpenWhisk and Nuvolaris +# Using REST APIs with OpenWhisk and NuvoOpenServerlesslaris -After your OpenWhisk and Nuvolaris environment is enabled, you can use -OpenWhisk and Nuvolaris with your web apps or mobile apps with REST API -calls. +After your OpenWhisk and OpenServerlesss environment is enabled, you can use +it with your web apps or mobile apps with REST API calls. For more details about the APIs for actions, activations, packages, rules, and triggers, see the [OpenWhisk and Nuvolaris API @@ -25,7 +24,7 @@ These are the collection endpoints: https://$APIHOST/api/v1/namespaces/{namespace}/activations https://$APIHOST/api/v1/namespaces/{namespace}/limits -The `$APIHOST` is the OpenWhisk and Nuvolaris API hostname (for example, +The `$APIHOST` is the OpenWhisk and OpenServerless API hostname (for example, localhost, 172.17.0.1, and so on). For the `{namespace}`, the character `_` can be used to specify the user’s *default namespace*. @@ -88,7 +87,7 @@ allowed (that is, Access-Control-Allow-Methods is `GET, DELETE, POST, PUT, HEAD`), and Access-Control-Allow-Headers yields `Authorization, Origin, X-Requested-With, Content-Type, Accept, User-Agent`. -**Attention:** Because OpenWhisk and Nuvolaris currently supports only +**Attention:** Because OpenWhisk and OpenServerless currently supports only one key per namespace, it is not recommended to use CORS beyond simple experiments. Use [Web Actions](#webactions.adoc) to expose your actions to the public and not use the OpenWhisk and Nuvolaris authorization key @@ -96,7 +95,7 @@ for client applications that require CORS. ## Using the CLI verbose mode -The OpenWhisk and Nuvolaris CLI is an interface to the OpenWhisk and +The OpenWhisk and OpenServerless CLI is an interface to the OpenWhisk and Nuvolaris REST API. You can run the CLI in verbose mode with the flag `-v`, this will print truncated information about the HTTP request and response. To print all information use the flag `-d` for debug. @@ -106,7 +105,7 @@ they exceed 1000 bytes. Let’s try getting the namespace value for the current user. - nuv namespace list -v + ops namespace list -v REQUEST: [GET] https://$APIHOST/api/v1/namespaces @@ -133,9 +132,9 @@ Let’s try getting the namespace value for the current user. As you can see you the printed information provides the properties of the HTTP request, it performs a HTTP method `GET` on the URL `https://$APIHOST/api/v1/namespaces` using a User-Agent header -`OpenWhisk and Nuvolaris-CLI/1.0 ()` and Basic +`OpenWhisk and OpenServerless-CLI/1.0 ()` and Basic Authorization header `Basic XXXYYYY`. Notice that the authorization -value is your base64-encoded OpenWhisk and Nuvolaris authorization +value is your base64-encoded OpenWhisk and OpenServerless authorization string. The response is of content type `application/json`. ## Actions @@ -269,7 +268,7 @@ value `webhook` set. Now whenever you have an event that needs to fire this trigger it just takes an HTTP request with a method `POST` using the OpenWhisk and -Nuvolaris Authorization key. +OpenServerless Authorization key. To fire the trigger `events` with a parameter `temperature`, send the following HTTP request. diff --git a/content/en/docs/reference/references/scheduler/_index.md b/content/en/docs/reference/references/scheduler/_index.md index c0875b02..1caf096d 100644 --- a/content/en/docs/reference/references/scheduler/_index.md +++ b/content/en/docs/reference/references/scheduler/_index.md @@ -1,3 +1,65 @@ --- title: Scheduler --- +OpenServerless Operator offers the possibility to deploy a simple "scheduler" to invoke repetitive or one-shot OpenWhisk actions. For example, an action executing a SQL script to create a PostgreSQL Database or inserting reference data, or simply an action that sends notifications with an API call every day at the same time. + +# How to Activate the Scheduler + +Using the `ops` CLI, you can enable the scheduler with the following command: + +```bash +ops config enable --cron + +# if OpenServerless is not yet deployed +ops setup devcluster + +# alternatively if OpenServerless is already deployed +ops update apply + +``` + +By default, the internal scheduler executes a job every minute that starts searching for OpenWhisk actions with special annotations. + +# How to Deploy a Repetitive Action + +Let's assume we want to deploy an OpenWhisk action to be executed every 30 minutes. Suppose it's an action that simply prints something, like this: + +```python +def main(args): + print('Hello from a repeated action') + return { + 'body': 'action invoked' + } +``` + +abd save it to a file called `scheduled-action.py` + +To deploy the action and instruct OpenServerless to execute it every 30 minutes, issue the following command: + +`ops action create scheduled-action scheduled-action.py -a cron "*/30 * * * *"` + +So you can create the action in the usual way and at the end add -a cron yourCronExpression. + +# How to Deploy a One-Shot Execution Action + +Now suppose we want to execute the same action `scheduled-action.py` only once. + +To deploy an action and request a single execution automatically via the OpenServerless Scheduler, issue the following command: + + `ops action create scheduled-action scheduled-action.py -a autoexec true` + +If we now print activation logs with nuv activation poll, we will see our action execution log: + +```bash +Activation: 'scheduled' (ebd532139a464e9d9532139a46ae9d8a) +[ + "2024-03-08T07:28:02.050739962Z stdout: Hello from a scheduled action" +] +``` + +# Remarks + +The Scheduler executes the action according to the following rules: + +Actions are called in a non-blocking fashion. To verify execution and logs, use the command `ops activation list`. +Actions are invoked without any parameters. It is advised to deploy actions with self-contained parameters. diff --git a/content/en/docs/reference/runtimes/_index.md b/content/en/docs/reference/runtimes/_index.md index 7877ba1c..1714da81 100644 --- a/content/en/docs/reference/runtimes/_index.md +++ b/content/en/docs/reference/runtimes/_index.md @@ -3,7 +3,7 @@ title: Runtimes --- This document is still 🚧 **work in progress** 🚧 -The programming languages currently directly supported by Nuvolaris are: +The programming languages currently directly supported by OpenServerless are: - [🚧 Node](#actions-nodejs.adoc)