Kumori PaaS Quick Start Manual

User Manual:

Open the PDF directly: View PDF .
Page Count: 36

Kumori PaaS Quick Start
Table of Contents
1. Introducing Kumori
- 1.1. The Kumori PaaS Service Model
  - 1.1.1. An example
2. Setting up tools and environment
3. Get your first service up and running in Kumori PaaS (Hello World example)
4. The Kumori PaaS Service Model in detail
5. Hello World example manifests in detail
6. Hello World v2: FE + AsciiConverter (with Load Balancing)

Kumori PaaS Quick Start

Kumori Systems v1.0.1, July 2018

Table of Contents

1. Introducing Kumori . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Ê1

1.1. The Kumori PaaS Service Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Ê1

1.1.1. An example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Ê1

2. Setting up tools and environment. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Ê2

2.1. Environment requisites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Ê2

2.2. Kumori CLI install. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Ê3

2.3. Kumori Dashboard. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Ê3

2.4. Create a workspace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Ê3

2.5. Set your workspace domain. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Ê4

2.6. Obtain your API access token . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Ê4

3. Get your first service up and running in Kumori PaaS (Hello World example) . . . . . . . . . . . . . . . . Ê6

3.1. Populate your workspace with Hello World sample service . . . . . . . . . . . . . . . . . . . . . . . . . . . Ê6

3.1.1. The helloworld component. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Ê7

3.1.2. The helloworld service. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Ê8

3.1.3. The helloworld deployment manifest . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Ê8

3.2. Build FE component . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Ê8

3.3. Register FE component. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Ê9

3.4. Register Hello World service application. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Ê9

3.5. Configure Hello World service application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Ê9

3.5.1. Configure logging system (set logzioToken parameter) . . . . . . . . . . . . . . . . . . . . . . . . . . Ê9

3.6. Deploy Hello World service. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Ê10

3.7. Update Hello World service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Ê13

3.7.1. Update and register a new version of helloworld component . . . . . . . . . . . . . . . . . . . Ê14

3.7.2. Update and register a new version of Hello World service . . . . . . . . . . . . . . . . . . . . . . . Ê14

3.7.3. Deploy a new service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Ê15

3.7.4. Change the entrypoint link to the new service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Ê16

3.7.5. Remove the old service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Ê19

4. The Kumori PaaS Service Model in detail . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Ê20

4.1. Component. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Ê20

4.1.1. Component interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Ê21

4.2. Service application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Ê22

4.3. Service. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Ê22

4.4. Manifest versioning. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Ê23

5. Hello World example manifests in detail. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Ê23

5.1. FE component . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Ê23

5.2. Service application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Ê24

5.3. Service application deployment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Ê25

6. Hello World v2: FE + AsciiConverter (with Load Balancing) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Ê26

6.1. Populate your workspace with Hello World V2 sample service . . . . . . . . . . . . . . . . . . . . . . . Ê27

6.1.1. The component helloworld_v2_fe . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Ê27

6.1.2. The component helloworld_v2_ascii. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Ê27

6.1.3. The helloworld_v2 service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Ê28

6.1.4. The helloworld deployment manifest . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Ê28

6.2. Configure logging system (set logzioToken parameter) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Ê28

6.3. Manifests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Ê28

6.3.1. FE component . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Ê28

6.3.2. AsciiConverter component . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Ê29

6.3.3. Service application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Ê30

6.3.4. Service application deployment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Ê31

6.4. Deploy Hello World v2 service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Ê31

6.5. Testing the service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Ê32

6.6. Scaling a role in a service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Ê33

This document describes the basic elements of Kumori PaaS, and guides the

developer ('you') through the implementation and deployment of two example

Node.js applications.

For sure, this is not a complete manual or a full reference guide of Kumori

PaaS. In fact, what we will show you here is only a small part of the full

potential of the platform.

1. Introducing Kumori

Kumori is a Platform as a Service (PaaS) that eases the development and deployment of an

application, and the management of its lifecycle.

Kumori runs on top of an IaaS, from where it obtains and manages resources in a transparent way

to application developer, so you don’t have to worry about infrastructure.

Kumori mission is to support the creation of elastic applications and manage their entire life cycle,

including automatic auto-scaling based on load situation, fulfilling a SLA and minimizing the

incurred cost in the underlying IAAS.

Access to Kumori PaaS is currently done via Kumori Dashboard, Kumori CLI, and the underlying

Admission REST API. The two first ways are covered, although not thoroughtly, in this guide.

1.1. The Kumori PaaS Service Model

In order for a service to be managed by Kumori PaaS, it must follow a very specific service model.

This model is defined by the following elements:

•Component: basic unit of execution. It is a runnable and self-contained piece of code that

tipically implements a certain API. A component can interact with other components through

channels, which are provided by the platform, but declared by the component developer. A

component can also have some configuration parameters and require some resources to work

(e.g. volatile or persistent volumes).

•Service application: set of components that work together to provide a final service. Each

component can carry out one or more roles. A service application declares a specific topology

connecting different role channels through defined connectors.

•Service: it is the result of deploying a service application. It is composed by a number of

running instances of each role. The number of instances may vary during service lifecycle.

1.1.1. An example

Let’s say we want to provide an ASCII art generator as a service that can be accessed through a

REST API (this example is covered in detail in section Hello World v2: FE + AsciiConverter (with

Load Balancing)). Our service application will be composed by two roles carried out by two

components:

•Asciiart Converter: converts images to a string of ASCII characters. It requires a single channel

through which it handles conversion requests.

•Front End (FE): provides a REST API to interact with Ascii Converter. This component requires

two channels. One to attend to REST petitions and the other to issue requests to the Ascii

Converter role. This component also servers the service Single Page Application (SPA).

Once deployed, Kumori PaaS will launch several instances of each role.

In this example, instances of FE role will be connected to Ascii Converter role instances through

channels and a load balancer connector (LB).

2. Setting up tools and environment

2.1. Environment requisites

•Linux OS (current LTS version of Ubuntu or equivalent)

•Docker CE

•Node.js v8

•Npm

•Git

•zip

•curl

As stated in the Docker installation guide, to use Docker as a non-root user,

you should add your user to the "docker" group with: sudo usermod -aG

docker $USER

2.2. Kumori CLI install

Kumori CLI (command-line interface) is a tool intended to boost the process of developing

elements for Kumori PaaS. It is available in npm.

$ sudo npm install -g @kumori/cli

2.3. Kumori Dashboard

Kumori Dashboard is available in https://dashboard.baco.kumori.cloud.

Be sure you already have a Kumori account, because you will need to access Dashboard in further

sections. Otherwise, sign up and get a free account here.

2.4. Create a workspace

Kumori CLI uses the concept of workspace, where all the elements related to a project are placed.

To create a new workspace, switch to an empty directory and run kumori init command:

$ mkdir workspace

$ cd workspace

$ kumori init

Ê create kumoriConfig.json

Ê create builts/README.md

Ê create components/README.md

Ê create dependencies/README.md

Ê create deployments/README.md

Ê create resources/README.md

Ê create runtimes/README.md

Ê create services/README.md

Ê create tests/README.md

kumoriConfig.json file contains the configuration used in this workspace, including the API

access token used to interact with the platform.

2.5. Set your workspace domain

In Kumori PaaS, every element is identified by a unique Uniform Resource Name (URN). This URN

is set when the element is registered in the platform and follows the pattern

eslap://<DOMAIN>/<TYPE>/<NAME>/<VERSION>. In order to avoid collisions with other

customers that would prevent you from registering parts of your project, you need to set a

domain of your own choice, which is done at workspace level (although it could be overrided

when adding particular elements):

$ kumori set domain YOUR_CHOSEN_DOMAIN



The <DOMAIN> is only used to name your elements. Hence, it can be random

or invented and you don’t have to register it anywhere beside your local

workspace. However, we strongly suggest you to use your own company

domain to avoid collisions with other company’s components.

2.6. Obtain your API access token

The API access token is used by Kumori CLI to operate with the platform. To obtain it, sign in

Kumori Dashboard using the same authorization system (Google, GitHub…) you used during sign

up. This is important, as the different systems are not linked, even if two accounts share the same

email.

Open the three-dot menu at the top right of the page, next to user name, and click on Settings.

The main view will change to the one below:

Copy the API access token.

Then, run the following Kumori CLI commands:

$ kumori stamp update -t YOUR_API_ACCESS_TOKEN baco

BACO is the current production version of Kumori PaaS and comes

preconfigured by default in the workspace.

Now, you will be able to interact with the platform from your workspace.

For security reasons, API access tokens expire after 30 days. In the future, you will be able to

issue and revoke permament tokens in Dashboard, but at the moment, you will need to repeat

this operation every month.

3. Get your first service up and running in

Kumori PaaS (Hello World example)

We are going to start with a very simple service application, composed by a single component

named FE (Front End), developed using Node.js and Express.

FE serves a static sample page in / (so you can quickly test the service in your browser) as well as

exposing a simple REST API in /api/, with two routes: /api/sayhello, which always returns

"Hello World!" message, and /api/echo/:msg, which returns the message passed as part of the

URL.

Not surprisingly, the topology of this service lacks channels and connectors for interconnecting

components.

The component is going to have a single channel that allows to access the service from the

outside, through a domain name.

3.1. Populate your workspace with Hello World sample

service

First, we need to add the Hello World sample service elements to our workspace by using the

@kumori/workspace:project-hello-world Yeoman generator. To use it, we have to provide at

least a name for the new project and we will use helloworld.

Only alphanumeric characters can be used in names. That includes numbers,

letters and underscores. So, for example, helloworld and hello_world are

allowed but hello-world is forbidden.

$ kumori project add -t @kumori/workspace:project-hello-world helloworld

This will create:

•The helloworld component under components/YOUR_CHOSEN_DOMAIN/helloworld/

workspace path.

•The helloworld service application under services/YOUR_CHOSEN_DOMAIN/helloworld/`

workspace path.

•The helloworld deployment manifest under deployments/helloworld workspace path.

3.1.1. The helloworld component

The source code of this example is extensively commented and we encourage

you to review it for implementation details.

A component is nothing more than a class that inherits from Component (more on this later) and

implements the necessary methods used by the Kumori runtime (in this example, the one

corresponding to Node.js) to manage its lifecycle.

Internally, the helloworld component contains several files:

package.json

The usual in a project for Node.js. It is worth noting that it includes dependencies to two

Kumori modules:

•component: class that our component must extend.

•http-message: equivalent to the Node.js http module, but that listens on a Kumori channel

instead of IP+port.

Currently, those dependencies are git repositories but will be registered soon as npm modules

and, most probably, also included in the platform runtime environments used to run the

components.

Apart from that, it includes some custom NPM scripts, being dist, superclean and devinit

mandatory.

taskfile.js

Contains Taskr configuration and targets. Taskr is a task automation tool, much like Gulp or

Grunt, but with some nice features. In our templates, we provide targets for installing

dependencies, building and generating distributable versions of the components, the ones that

Kumori CLI uses under the hood.

Manifest.json

It is the descriptor of the component. We will explain its content later on in section Hello

World example manifests in detail. For the moment, just mentioning that it defines component

channels and parameters.

lib/restapi.coffee

REST API implementation. It uses an average Express server but employs Kumori’s custom

httpMessage module instead of using Node.js http module.

lib/index.coffee

FE component implementation. Its methods constructor, run, shutdown y configure are invoked

by Kumori PaaS, managing instance lifecycle. In its constructor the RestAPI object is created,

which is started in run method.

static/

Contains the files used for serving the static sample page, i.e. a bunch of HTML, JS, image and

font files.

3.1.2. The helloworld service

A service application makes use of components, assigns them roles, defines connectors, defines

service channels and declares a specific topology connecting role channels with other role

channels or service channels through defined connectors. This is declared in Manifest.json

descriptor file.

3.1.3. The helloworld deployment manifest

A deployment represents the act of running a service application, which creates a service. The

new service configuration is provided in the deployment manifest Manifest.json. This file and

contains:

•The parameters values (if any).

•The resources assigned (if any).

•The roles arrangement (RAM, CPU, instance boundaries, …).

Note that the file itself does not runs anything. Just contains the configuration needed in the

deployment process. The deployment itself will be performen later in section Deploy Hello World

service.

See section The Kumori PaaS Service Model in detail for more information.

3.2. Build FE component

Running a service applications implies running several instances of each involved components. To

run a component we need first to build it which means creating a zip file containing everything

the platform will need to run it. What should be included in that file depends mostly on the

language used to develop the component. In this example, FE is a NodeJS component and to build

it we need first to install its dependencies. Whatever the building process does, it ends creating a

distrutable file containing everything the platform will need to run a component instance.

We do not recomment to run npm install directly, since we may have some dependencies on

the operating system libraries (e.g when compiling some module, using node-gyp in this case) that

may cause troubles later.

Therefore, we suggest to use Kumori CLI, which internally runs some scripts defined in

package.json that essentially execute npm install in the same runtime environment (i.e. same

Docker image) needed to run that component instances in the platform. The specific runtime is

defined in component manifest, but more on that later in section Hello World example manifests

in detail.

To build the component, run the following Kumori CLI command:

$ kumori component build helloworld

This operation makes use of Docker. In case you haven’t added your user to

docker group, you will need to run the above command with sudo.

3.3. Register FE component

Now it’s time to register our previosly built component in Kumori PaaS.

To do so, run the following Kumori CLI command:

$ kumori component register helloworld

This requires that you have configured a valid API access token. If that’s not the

case, please revisit section Obtain your API access token.

3.4. Register Hello World service application

Once the component is registered, the service application must be registered too.

To register it in Kumori PaaS, run the following Kumori CLI command:

$ kumori service register helloworld

3.5. Configure Hello World service application

As explained in section Populate your workspace with Hello World sample service, during the

population step a deployment manifest is created in deployments/helloworld.

You can create as many deployment configurations as you want, even for the

same service application. Just execute kumori deployment add to add more

deployment manifests to your workspace.

The Manifest.json file, that we will explain later on in section Hello World example manifests in

detail, contains all service application deployment configuration. In this example, we can configure

the logging system.

3.5.1. Configure logging system (set logzioToken parameter)

The following is not mandatory but we encourage you to do it, especially if you

introduce modifications in the code.

The FE component can use a logging system. This is especially useful when running software on a

managed environment, i.e. when running your service applications in Kumori PaaS. There are

many solutions available, we have just chosen the simplest one to our knowledge.

Go to https://logz.io/freetrial/ and create an account.

You will be immediately logged in, you don’t even need to click on any confirmation email.

Then, go to https://app.logz.io/#/dashboard/settings/general and copy account token.

Finally, edit deployments/helloworld/Manifest.json and set logzioToken value.

You will be able to check logs in https://app.logz.io/#/dashboard/kibana once you have deployed

the service.

3.6. Deploy Hello World service

It’s time to deploy! Once again, you can do it using Kumori CLI:

$ kumori deployment deploy helloworld

As a result, you will get some information about the new service, including its unique name (URN).

---------------------------------------------------------

Elements already registered in baco:

* eslap://kumori.systems/services/helloworld/0_0_1 SKIPPED

* eslap://kumori.systems/components/helloworld/0_0_1 SKIPPED

---------------------------------------------------------

Service deployed:

Nickname: helloworld

URN: slap://kumori.systems/deployments/20180702_150513/ed8a7c2e

Role: helloworld-fe

---------------------------------------------------------



As expected, the output points out that the component and service have been

alredy registered because we registered them earlier. As we will see later in

section Hello World v2: FE + AsciiConverter (with Load Balancing), we can build

the components, register everything and deploy a service application in a single

step. However, for this very first example, we think is far more educational to

show all those actions step by step.

Keep the URN since you will need it later.

At this point, you have deployed your service, but it is not accesible from outside. Go to Kumori

Dashboard - Overview, and press Add Entrypoint button.

Do not select any domain, so a random domain is generated, and press Deploy button.

After a while, this will deploy an HTTP inbound service.

Then, click on the blue Info button of the newly created HTTP inbound service.

This shows that service in detail, including the assigned random domain. Under Connections, on

the dropdown menu next to frontend (that’s a service channel), select helloworld ~ service.

You will not be able link the Inbound service until at least one instance of the

helloworld-fe role is created. If the drop down menu is empty, wait a few

minutes.

Press Apply Changes button .

This links the HTTP inbound service with the Hello World service through their service channels.

Finally, go the provided website URL and have fun.

If you have been extremely quick doing the above steps and see an error

message telling you that the requested service is not deployed, just wait a bit

and press Try Again button.

Apart from the static page available in /, check /api/sayhello and

/api/echo/:msg routes from your browser or command-line curl.

Hooray! You have deployed your first service in Kumori PaaS. Now, let’s see what we have done

and give some insights. Now let’s see how we can update it.

3.7. Update Hello World service

In Kumori Platform, registered elements (like a component or a service) are immutable and cannot

be changed. This ensures that an URN will allways point to the same element. If we need to

update an element it must be registered with a different URN. The most strightforward way of

doing that is increasing the version part of the original element URN (see section Manifest

versioning).

In this section we show how a new version of our helloworld service can be created, registred and

deployed. This new version will return Hello world updated! instead of Hello world! when

the /api/sayhello API call is invoked. We also show how the inbound we created before (see

section Deploy Hello World service) can be linked to the new version of the service to keep the

same domain.

3.7.1. Update and register a new version of helloworld component

First, we update the helloworld component.

Edit the file components/YOUR_CHOSEN_DOMAIN/helloworld/lib/restapi.js and change the

the /api/sayhello handler to return Hello world updated!

_createExpressApp() {

Ê ...

Ê app.use('/api/sayhello', (req, res, next) => {

Ê res.status(200).send('Hello world updated!');

Ê });

Ê ...

}

Edit the file components/YOUR_CHOSEN_DOMAIN/helloworld/Manifest.json and change the

component name version to 0_0_2:

{

Ê "spec": "http://eslap.cloud/manifest/component/1_0_0",

Ê "name": "eslap://YOUR_CHOSEN_DOMAIN/components/helloworld/0_0_2",

Ê ...

}

Once updated, we build and register the new version as we did with the previous version in

sections Build FE component and Register FE component. Both versions can coexist because they

have a different URN.

$ kumori component build helloworld

...

$ kumori component register helloworld

...

3.7.2. Update and register a new version of Hello World service

The next step is to register a new version of the service application using the updated component

instead of the old one. We do that by assigning the new version of FE component to the service

helloworld-fe role.

Edit the file services/YOUR_CHOSEN_DOMAIN/helloworld/Manifest.json and change the

service name and component version to 0_0_2:

{

Ê "spec": "http://eslap.cloud/manifest/service/1_0_0",

Ê "name": "eslap://YOUR_CHOSEN_DOMAIN/services/helloworld/0_0_2",

Ê ...

Ê "roles": [{

Ê "name": "helloworld-fe",

Ê "component": "eslap://YOUR_CHOSEN_DOMAIN/components/helloworld/0_0_2"

Ê }],

Ê ...

}

The new service application is registered as we did previously in section Register Hello World

service application.

$ kumori service register helloworld

3.7.3. Deploy a new service

The next step is to deploy a new instance of helloworld service application but, this time, using

the new version 0_0_2. There are two ways of doing this:

•Update the current deployment manifest we created previously in section Configure Hello

World service application to point to the new version of the service application.

•Create a new deployment manifest, keeping the old one as it is.

For this example we will modify the existing deployment manifest.

Adding a new deployment is as easy as using the kumori deployment add

command.

Edit the file deployments/helloworld/Manifest.json and change the version of the service

application name in servicename key:

{

Ê "spec": "http://eslap.cloud/manifest/deployment/1_0_0",

Ê "servicename": "eslap://YOUR_CHOSEN_DOMAIN/services/helloworld/0_0_2",

Ê ...

}

And that’s it!! Now, we can deploy the new version of the service as we did in section Deploy

Hello World service.

$ kumori deployment deploy helloworld

As a result, a new service appears in the dashborad overview page.

3.7.4. Change the entrypoint link to the new service

After the previous step, we will have a new service deployed but the entrypoint we created in

section Deploy Hello World service will still point to the previous service. If you take a look again

to the overview page, notice that the link is still assigned to the

eslap://YOUR_CHOSEN_DOMAIN/services/helloworld/0_0_1 service. Again, we can take two

different paths:

•Create a new entrypoint and link it to the new service.

•Unlink the existing entrypoint from the old service and link it to the new one.

We will take the second approach to keep the same domain.

Unlinking an entrypoint is easy. We only have to select the old helloworld service by clicking on

its blue Info button in the overview section. We will get the detailed page of that service.

Then, we click the cross icon in the domain assigned to service in the Connections section

(note that you will see your random

domain instead of problem-throw).

And apply changes .

If we go back to the overview page, we will see now that none of the existing services have the

entrypoint assigned.

Click not the Info button of the

eslap://YOUR_CHOSEN_DOMAIN/services/helloworld/0_0_2 service and select the inbound

service in the service channel drop down list of the Connections section.

And apply changes .

If you go back again to the overview page, the entrypoint is now assigned to the new service,

Check the link with the /api/sayhello and you will get Hello world updated!.

3.7.5. Remove the old service

Once we checked that everything is working, we can remove the old service. We can do that

either from the Kumori CLI or through the dashboard itself by clicking clicking on its blue Info

button of the eslap://YOUR_CHOSEN_DOMAIN/services/helloworld/0_0_1 and, then,

the Undeploy button . We will use CLI in this example:

$ kumori deployment undeploy slap://kumori.systems/deployments/20180702_150513/ed8a7c2e

4. The Kumori PaaS Service Model in detail

As we have briefly seen, manifests are used to describe and declare elements in Kumori PaaS. A

manifest includes element type (component, service application, service deployment) and its

characteristics (name, configuration parameters, channels, connectors, etc.).

A more detailed description of the elements of the Kumori PaaS Service Model and their

associated manifests is provided hereunder.

4.1. Component

A component is a standalone piece of software that can be scaled independently. Although a

component can be arbitrarily complex, it is recommended to encapsulate simple and specific

functionality, as microservice-based architectures suggest.

Components communicate among them through channels and must implement the Component

interface (described in section Component interface) in order to be managed by Kumori PaaS.

There are implementations of this interface for Node.js and Java.

Registering a component in Kumori PaaS requires of:

•The component binaries (or the code in case of interpreted languages) and their dependencies

(node_modules for Node.js components).

•A component manifest declaring its characteristics, including:

◦Name of the component. The name is a URN that must follow the format

eslap://YOUR_CHOSEN_DOMAIN/component/COMPONENT_NAME/VERSION. E.g.

eslap://kumori.systems/component/helloworld/0_0_1.

◦Name of the component runtime. It must be one of the runtimes registered in the

platform. E.g. eslap://eslap.cloud/runtime/native/2_0_0.

◦Channels needed to provide its functionality to other components.

◦Required channels to make use of other components functionality.

◦Name and type of the configuration parameters.

◦Name and type of resources it needs (e.g. volatile or persistent volumes).

Channels are objects provided by Kumori PaaS to component instances based on what is stated in

their manifest. The semantics of the channels depend on their type:

•Send: allows sending messages and assigning them a topic (sendChannel.send(message)).

•Receive: allows receiving messages and subscribe to topics

(receiveChannel.on('message', (message) ⇒ {…})).

•Request: allows issuing a request that expects an asynchronous response using promises

(requestChannel.sendRequest(message).then((response) ⇒ {…})).

•Reply: allows handling requests and replying them asynchronously

(replyChannel.handleRequest = (request) ⇒ {…; return promise;}).

•Duplex: allows to send messages specifying the recipient and receive messages sent by

others. It is like a combination of Send and Receive channels for point to point communication.

Currently, the channels protocol is ilustrative metadata and is not processed

by the platform. However, this field might be used in the future and we

recommend to put realistic values, specially for production ready services.

4.1.1. Component interface

As we said, components must implement the Component interface, which is provided as a class

that component code should extend. The Component interface is decribed below.

class Component

Ê constructor: (

Ê @runtime, ①

Ê @role, ②

Ê @iid, ③

Ê @incnum, ④

Ê @localData, ⑤

Ê @resources, ⑥

Ê @parameters, ⑦

Ê @dependencies, ⑧

Ê @offerings ⑨

Ê ) ->

Ê run: () -> ⑩

Ê shutdown: () -> ⑪

Ê reconfig: (parameters) -> ⑫

module.exports = Component

①Object providing toolkit API of the runtime agent that runs the component

②Name of the role carried out by the component.

③Identifier (string) assigned to the instance of the component. Typically there will be several

instances of the component at a given time (variable over time depending on the load and

performance).

④Incarnation number. If an instance "dies" unexpectedly (e.g. due to a bug), the platform will

restart it and increase this value.

⑤Path where the instance can store data. It is volatile, and data persistence is not ensured on

instance restart or relocation. All instances have this resource by default.

⑥Dictionary of assigned Kumori resources to the instance. For example, a persistent volume.

⑦Dictionary containing the values for the parameters declared in the component’s manifest.

Those values are set during the service deployment process.

⑧Dictionary of the channels required by the component, through which it can issue requests to

other roles or services. Keys are channel names, values are channel objects.

⑨Dictionary of the channels offered by the component, through which it can answer requests

from other roles or services.

⑩Method invoked by Kumori PaaS to start instance execution.

⑪Method invoked by Kumori PaaS to warn instance about its inminent shutdown. Instance

should take necessary actions in this situation, persisting its state if needed. If the instance

doesn’t gracefully shutdown, it will be killed.

⑫Method invoked by Kumori PaaS to modify instance configuration.

4.2. Service application

A service application is a set of components interconnected to provide a certain functionality.

Each component carries out a role and its channels are paired using connectors.

A service application also declares its own channels that can be used to link it to other services. A

service channel must necessarily be paired with a channel of one of the roles that compose the

service application.

A service application is defined in a manifest, the service manifest, which declares:

•The service application name. The name is a URN that must follow the format

eslap://YOUR_CHOSEN_DOMAIN/service/SERVICE_NAME/VERSION. E.g.

eslap://kumori.systems/service/helloworld/0_0_1.

•The roles that compose the service and which components will carry them out.

•The service parameters, their type and how their values will be propagated to role

parameters.

•The resources required for the service, their type and how they are distributed among the

roles.

•The connectors that will pair the role channels. There are three possible types of connectors:

◦Publish/Subscribe: allows to pair Send and Receive channels.

◦Load Balancer: allows to pair Request and Reply channels.

◦Full: allows to pair Duplex channels.

A service registration will fail if its required components have not been also registered before.

4.3. Service

A service is the result of deploying a service application with a certain configuration. The

deployment process involves creating instances of each role component and configuring them

appropriately. Kumori PaaS can host multiple services of a single service application at the same

time, each with its own configuration and component instances. The execution of deployment

process starts with a deployment manifest that must contain, among other things:

•The name (URN) of the service application to be deployed.

•The value for each configuration parameter declared in the service application manifest.

•The resource elements (e.g. volumes) to be assigned to the service.

•The initial system resource allocation (e.g. CPU and RAM units) per role.

Once deployed, the number of instances assigned to each role in a service will vary over time

depending on their workload fluctuation. When an instance sends a message through one of its

channels, it will reach one or more instances of the paired channels, depending on the type of

connector used:

•Publish/Subscribe: reaches all target instances. If the message includes a topic, only instances

subscribed to that topic will receive the message.

•Load Balancer: the request will only be handled by one of the instances.

•Full: the recipient is determined by the instance sending the message.

Since the components are standalone pieces of software, they can be scaled independently.

Because Kumori PaaS knows the topology of services and manages communication channels, it is

able to understand the interdependencies between roles in a service and take them into account

to anticipate possible variations in the environment (e.g. load).

4.4. Manifest versioning

Once an element has been registered in Kumori PaaS (e.g. the component

eslap://kumori.systems/component/helloworld/0_0_1), it cannot be modified.

Any modification requires registering again the element with an incremented version in its

manifest (e.g. eslap://kumori.systems/component/helloworld/0_0_2).

If the element is referenced in another manifest, you will need to update the

later (and increment its version) as well.

5. Hello World example manifests in detail

There are three manifests in Hello World example: one for the FE component, another for the

service application, and a final one for the specific deployment of the service application that we

have get into Kumori PaaS.

5.1. FE component

{

Ê "spec": "http://eslap.cloud/manifest/component/1_0_0",

Ê "name": "eslap://kumori.systems/components/helloworld/0_0_1", ①

Ê "runtime": "eslap://eslap.cloud/runtime/native/2_0_0", ②

Ê "code": "helloworld-code-blob", ③

Ê "configuration": {

Ê "resources": [ ], ④

Ê "parameters": [{ ⑤

Ê "name": "logzioToken",

Ê "type": "eslap://eslap.cloud/parameter/string/1_0_0"

Ê }]

Ê },

Ê "channels": { ⑥

Ê "requires": [],

Ê "provides": [{

Ê "name": "entrypoint",

Ê "type": "eslap://eslap.cloud/channel/reply/1_0_0",

Ê "protocol": "eslap://eslap.cloud/protocol/message/http/1_0_0"

Ê }]

Ê },

Ê "profile": {

Ê "threadability": "*"

Ê }

}

①Name of the component.

②Name of the component runtime. In this case, the corresponding to Node.js (native runtime of

Kumori PaaS).

③Name of the bundle that contains all the stuff (e.g. code) belonging to this component.

④Resources it needs (e.g. volatile or persistent volumes). Not used in this example.

⑤Component parameters. In the component instantiation process (Component class

constructor), it will be given a value for the logzioToken parameter, of string type. These

values are set in the deployment manifest, and are propagated to all instances of this

component.

⑥Component channels. In this case, it provides a single Reply channel named entrypoint. This

channel is not used for communicating to other components (since there are none), and is

linked (service manifest) to the service channel.

5.2. Service application

{

Ê "spec": "http://eslap.cloud/manifest/service/1_0_0",

Ê "name": "eslap://kumori.systems/services/helloworld/0_0_1", ①

Ê "configuration": {

Ê "resources": [],

Ê "parameters": [{ ②

Ê "name": "helloworld-fe",

Ê "type": "eslap://eslap.cloud/parameter/json/1_0_0"

Ê }]

Ê },

Ê "roles": [{ ③

Ê "name": "helloworld-fe",

Ê "component": "eslap://kumori.systems/components/helloworld/0_0_1"

Ê }],

Ê "channels": { ④

Ê "provides": [{

Ê "name": "service",

Ê "type": "eslap://eslap.cloud/channel/reply/1_0_0",

Ê "protocol": "eslap://eslap.cloud/protocol/message/http/1_0_0"

Ê }],

Ê "requires": []

Ê },

Ê "connectors": [{ ⑤

Ê "type": "eslap://eslap.cloud/connector/loadbalancer/1_0_0",

Ê "depended": [{

Ê "endpoint": "service"

Ê }],

Ê "provided": [{

Ê "role": "helloworld-fe",

Ê "endpoint": "entrypoint"

Ê }]

}

①Name of the service application.

②Spreading of the parameter values from the ones set in the deployment manifest to the

parameters declared in the component.

③List of roles that compose the service application. A component can carry out one or more

roles in the service, and instances will be created for each of them. In this example, the

component eslap://kumori.systems/components/helloworld/0_0_1 is assigned a single

role named "helloworld-fe".

④Service channels. In this case it provides a single Reply channel named service, which allows

access from the outside to the REST API that provides the service.

⑤Connectors. We use a LB connector to link the service service channel to the entrypoint

channel of the FE component. LB connectors pair Request channels with Reply channels, with

one exception: when they connect a service Reply channel to a component Reply channel (in

this case, LB performs forwarding functions).

5.3. Service application deployment

{

Ê "spec": "http://eslap.cloud/manifest/deployment/1_0_0",

Ê "servicename": "eslap://kumori.systems/services/helloworld/0_0_1", ①

Ê "name": "helloworld", ②

Ê "configuration": {

Ê "resources": {},

Ê "parameters": { ③

Ê "helloworld-fe": {

Ê "logzioToken":"xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Ê }

Ê },

Ê "roles": {

Ê "helloworld-fe": {

Ê "resources": { ④

Ê "__instances": 1,

Ê "__maxinstances": 3,

Ê "__cpu": 1,

Ê "__memory": 1,

Ê "__ioperf": 1,

Ê "__iopsintensive": false,

Ê "__bandwidth": 10,

Ê "__resilience": 1

Ê }

}

①URN of the service application to be deployed.

②Short name for the service. You will see this name in Kumori Dashboard, for example.

③Initial values for the component parameters. The various possibilities of the spreading

mechanism from the values set in the deployment to the parameters declared in the

components are beyond the scope of this guide.

In this case, we use a very simple mechanism: in the deployment manifest we have a json for

each of the components, the values of this json are mapped one-to-one with the role

parameters.

④For each role, we set the initial number of instances, the maximum number of instances

(Kumori PaaS won’t scale the role beyond this amount), resource allocation units, and

resilience.

6. Hello World v2: FE + AsciiConverter (with

Load Balancing)

The second example is a service application to convert images to an ASCII character matrix. This

service can be accessed through a Single Page Application (SPA) web page.

As in the previous example, we have a FE component that implements the REST API using

Express. The image conversion falls upon a second component: AsciiConverter.

The communication between both components is of Request-Reply type, so both are connected

through an LB connector (FE using Request channel, AsciiConverter using Reply channel).



If the replyer component holds a state, it will not be shared across all its

instances. If there is more than one instance during the life cycle of the service,

then a request might be handled by an instance that does not have access to

the state shard required to solve it.

6.1. Populate your workspace with Hello World V2

sample service

For this second example, we are going to use the @kumori/workspace:project-hello-world-

v2 template, that provides the fully implemented FE and Asciiart Converter components and the

service manifest describing the service topology. We are going to name the project as

helloworld_v2:

$ kumori project add -t @kumori/workspace:project-hello-world-v2 helloworld_v2

This will create the following elements:

•A component under components/YOUR_CHOSEN_DOMAIN/helloworld_v2_fe/ workspace

path.

•A component under components/YOUR_CHOSEN_DOMAIN/helloworld_v2_ascii/ workspace

path.

•A service under services/YOUR_CHOSEN_DOMAIN/helloworld_v2/ workspace path.

•A deployment manifest under deployments/helloworld_v2/ workspace path.

6.1.1. The component helloworld_v2_fe

The source code of this example is extensively commented and we encourage

you to review it for implementation details.

The implementation of the FE component is very similar to that of the first example. However, in

this case the RestAPI delegates the processing of the request to the AsciiConverter component

via the asciiclient Request channel.

The method RestAPI._processRequest() shows how to send a message through a _Request_

channel and receive the reply asynchronously through a promise.

6.1.2. The component helloworld_v2_ascii

The source code of this example is extensively commented and we encourage

you to review it for implementation details.

AsciiConverter converts images to ASCII.

Through the asciiapi Reply channel, it receives requests from the FE component.

The method AsciiConverter._handleRequest() shows how to process messages received by

a _Reply_ channel.

6.1.3. The helloworld_v2 service

This time declares two roles:

•helloworld_v2_ascii: converts images to ascii.

•helloworld_v2_fe: serves de SPA and redirects REST calls to helloworld_v2_ascii.

The topology is also extended with a new connector linking asciiclient channel from

helloworld_v2_fe to asciiapi channel from helloworld_v2_ascii.

6.1.4. The helloworld deployment manifest

This time the deployment configuration is used to configure both components logger. See section

Manifests for detailed information about this example manifests.

6.2. Configure logging system (set logzioToken

parameter)

The following is not mandatory (our examples work), but we encourage you to

do it, especially if you introduce modifications in the code.

As in the first example, set the logzioToken value in deployments/helloworld-

v2/Manifest.json.

You will be able to check logs in https://app.logz.io/#/dashboard/kibana once you have deployed

the service.

6.3. Manifests

We have four manifests: one for each of the components (FE and AsciiConverter), another for the

service application, and a final one for the service application deployment.

6.3.1. FE component

{

Ê "spec": "http://eslap.cloud/manifest/component/1_0_0",

Ê "name": "eslap://kumori.systems/components/helloworld_v2_fe/0_0_1",

Ê "runtime": "eslap://eslap.cloud/runtime/native/2_0_0",

Ê "code": "helloworld_v2_fe-code-blob",

Ê "configuration": {

Ê "resources": [ ],

Ê "parameters": [{

Ê "name": "logzioToken",

Ê "type": "eslap://eslap.cloud/parameter/string/1_0_0"

Ê }]

Ê },

Ê "channels": {

Ê "requires": [{ ①

Ê "name": "asciiclient",

Ê "type": "eslap://eslap.cloud/channel/request/1_0_0",

Ê "protocol": "TBD"

Ê }],

Ê "provides": [{

Ê "name": "entrypoint",

Ê "type": "eslap://eslap.cloud/channel/reply/1_0_0",

Ê "protocol": "eslap://eslap.cloud/protocol/message/http/1_0_0"

Ê }]

Ê },

Ê "profile": {

Ê "threadability": "*"

Ê }

}

①The FE component manifest is basically the same as in the first example, to which we have

added a Request channel. It appears in the channels/requires section as it is a dependency

of the FE component on another component.

6.3.2. AsciiConverter component

{

Ê "spec": "http://eslap.cloud/manifest/component/1_0_0",

Ê "name": "eslap://kumori.systems/components/helloworld_v2_ascii/0_0_1",

Ê "runtime": "eslap://eslap.cloud/runtime/native/2_0_0",

Ê "code": "helloworld_v2_ascii-code-blob",

Ê "configuration": {

Ê "resources": [ ],

Ê "parameters": [{

Ê "name": "logzioToken",

Ê "type": "eslap://eslap.cloud/parameter/string/1_0_0"

Ê }]

Ê },

Ê "channels": {

Ê "provides": [{ ①

Ê "name": "asciiapi",

Ê "type": "eslap://eslap.cloud/channel/reply/1_0_0",

Ê "protocol": "TBD"

Ê }],

Ê "requires": []

Ê },

Ê "profile": {

Ê "threadability": "*"

Ê }

}

①The AsciiConverter component provides (channels/provides) a Reply channel.

6.3.3. Service application

{

Ê "spec": "http://eslap.cloud/manifest/service/1_0_0",

Ê "name": "eslap://kumori.systems/services/helloworld_v2/0_0_1",

Ê "configuration": {

Ê "resources": [],

Ê "parameters": [{

Ê "name": "helloworld_v2-fe",

Ê "type": "eslap://eslap.cloud/parameter/json/1_0_0"

Ê },

Ê {

Ê "name": "helloworld_v2-ascii", ①

Ê "type": "eslap://eslap.cloud/parameter/json/1_0_0"

Ê }]

Ê },

Ê "roles": [{ ②

Ê "name": "helloworld_v2-fe",

Ê "component": "eslap://kumori.systems/components/helloworld_v2_fe/0_0_1"

Ê },{

Ê "name": "helloworld_v2-ascii",

Ê "component": "eslap://kumori.systems/components/helloworld_v2_ascii/0_0_1"

Ê }],

Ê "channels": { ③

Ê "provides": [{

Ê "name": "service",

Ê "type": "eslap://eslap.cloud/channel/reply/1_0_0",

Ê "protocol": "eslap://eslap.cloud/protocol/message/http/1_0_0"

Ê }],

Ê "requires": []

Ê },

Ê "connectors": [{

Ê "type": "eslap://eslap.cloud/connector/loadbalancer/1_0_0",

Ê "depended": [{

Ê "endpoint": "service"

Ê }],

Ê "provided": [{

Ê "role": "helloworld_v2-fe",

Ê "endpoint": "entrypoint"

Ê }]

Ê },{

Ê "type": "eslap://eslap.cloud/connector/loadbalancer/1_0_0", ④

Ê "depended": [{

Ê "role": "helloworld_v2-fe",

Ê "endpoint": "asciiclient"

Ê }],

Ê "provided": [{

Ê "role": "helloworld_v2-ascii",

Ê "endpoint": "asciiapi"

Ê }]

}

①AsciiConverter role also needs to receive the logzioToken parameter.

②We have added a new role, associated with the AsciiConverter component.

③The service channels section has not changed: the service still has a single entrypoint.

④Includes a new LB connector to link the FE Request channel to the AsciiConverter Reply

channel.

6.3.4. Service application deployment

{

Ê "spec": "http://eslap.cloud/manifest/deployment/1_0_0",

Ê "servicename": "eslap://kumori.systems/services/helloworld_v2/0_0_1",

Ê "name": "helloworld_v2",

Ê "configuration": {

Ê "resources": {},

Ê "parameters": {

Ê "helloworld_v2-fe": {

Ê "logzioToken":"xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Ê },

Ê "helloworld_v2-ascii": { ①

Ê "logzioToken":"xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Ê }

Ê },

Ê "roles": {

Ê "helloworld_v2-fe": {

Ê "resources": {

Ê "__instances": 1,

Ê "__maxinstances": 3,

Ê "__cpu": 1,

Ê "__memory": 1,

Ê "__ioperf": 1,

Ê "__iopsintensive": false,

Ê "__bandwidth": 10,

Ê "__resilience": 1

Ê },

Ê "helloworld_v2-ascii": { ②

Ê "resources": {

Ê "__instances": 1,

Ê "__maxinstances": 3,

Ê "__cpu": 1,

Ê "__memory": 1,

Ê "__ioperf": 1,

Ê "__iopsintensive": false,

Ê "__bandwidth": 10,

Ê "__resilience": 1

Ê }

}

①AsciiConverter role also needs to receive the logzioToken parameter.

②We have added a new section of initial resource allocation for the new AsciiConverter role.

6.4. Deploy Hello World v2 service

It’s time to deploy! Once again, you can do it using Kumori CLI. However, this time we use the

following special flags:

•--build-components: builds the required components as long as they have not been

previously build or registered.

•--generate-inbounds: creates and links an inbound entrypoint service to each service

channel. For each new inbound, a random subdomain under deployedin.cloud is also

created.

$ kumori deployment deploy --build-components --generate-inbounds helloworld_v2



As you may have noticed, we have skipped the build, registration and

entrypoint creation steps. As we have previously said, --build-components

and --generate-inbounds flags are used to automatically build the

components and create the entrypoints. The kumori deployment deploy

command also registers any element required but not previously registered in

the platform, as long as it exists in the current workspace and have been

already built.

As a result, this time the deployment process will respond with two new services:

•An instance of helloworld-v2 service. It will include a URN key with the new deployment

name. Note down this URN since we will use it later in section Scaling a role in a service.

•An instance of an inbound service. The information provided for this service will include a

link key with the randomly generated URL. This is the URL you will use later in section

Testing the service to test your service.

6.5. Testing the service

We can test the deployed service application by accessing the generated random domain. That

will serve a Single Page Application to convert images to ascii:

Select an image and see the resulting ASCII version. Note that the service shows which instance

attended your request.

6.6. Scaling a role in a service

We can manually scale any role using the Kumori CLI. As an example, we scale the frontend:

$ kumori deployment scale <DEPLOYMENT_URN> helloworld_v2-fe 2

you can also manually scale a role from the service detailed view in the

dashboard. Click the icon of your service in the main page (Overview).

Try to convert several images and check if the replyer instance id changes.

Kumori PaaS Quick Start Manual

Navigation menu

Versions of this User Manual:

Views

Navigation