quebic

Quebic - FaaS Framework

Quebic is a framework for writing serverless functions to run on Kubernetes. Currently it supports for Python, Java and NodeJS programming models to write functions.

• Wiki
• Demo
• Example Project
• Event-driven Microservices with Quebic

Contents

• Getting Started
• Function Runtimes
• Function Container
• Routing
• Asynchronous invocation from API Gateway
• Logs
• Configurations
• Example Project
• Consultants
• Releases

Getting Started

Prerequisites : Kubernetes

• Setup Kubernetes

Getting Binaries

• Download binaries from here. Save and extract it into preferred location.

• Install golang into your environment.
• Get govendor tool.
• Run govendor fetch. This will download all the required dependencies for quebic.
• Run for build quebic cli go install quebic-faas/quebic-faas-cli
• Congrats !!! Now you can find your binaries from $GOPATH/bin dir.

Run quebic-manager

• Jump into quebic binaries location. Then run this quebic manager start
• This commond deploy and start the quebic-manager inside k8 cluster.

Connect cli with manager

• Run quebic manager connect
• This commond config quebic-cli to connect with quebic-manager

Fetch quebic-manager logs

• Run quebic manager logs

Check status of quebic-manager

• Run quebic manager status

Function Runtimes

Python Runtime

• Write your logic inside the handler.

def handler(payload, context, callback):
    
    def __callback(r):
        callback(None, 'success', 201)

    def __error_callback(err):
        callback(None, 'failed', 403)

    context.messenger()
      .publish(
         'test.Receiver', 
         {'id': payload}, 
         __callback, 
         __error_callback
      )

• Context have these methods.

context.base_event # return event details comes into this function
context.messenger() # return messenger instance
context.logger() # return logger instance

• CallBack provides way to reply.

callback(); # reply 200 status code with empty data
callback(null, "success")  # reply 200 status code with data
callback(null, "success", 201)  # reply 201 status code with data
callback(error) # reply 500 status code with with error-data
callback(error, null, 401) # reply 401 status code with with error-data 

• Messenger provides way to publish events.

context.messenger().publish(
    "users.UserValidate", # event id 
    user, # payload
    callback, # success callback(result)
    error_callback, # err callback(err) 
    1000 * 8 # timeout (ms)
)

• Logger provides way to attach logs for particular request context. We will discuss more about this logger in later section.

context.logger().info("log info")
context.logger().error("log error")
context.logger().warn("log warn")

• Deployment .yml spec file by describing how you want to deploy your functions into quebic.
• Package your whole nodejs project dir into .tar file. Then set your .tar file location into source field in deployment spec.
• If your handler is just a single python file. Then just set your .py file location into source field. No need to package it. Then handler field will be like this index.handler. here handler is the function
• runtime will be python_2.7 or python_3.6

 function:
   name: hello-function # function name 
   source: /functions/hello-function.tar # tar package location
   handler: index.handler # request handler 
   runtime: python_2.7 # function runtime
   replicas: 2 # replicas count
   events: # function going to listen these events
     - users.UserValidate
   ...

Java Runtime

• RequestHandler is an interface which comes with quebic-runtime-java library. You can add your logic inside it's handle() method.
• The Request Type and Response Type can be any Primitive data type or Object.

public class HelloFunction implements RequestHandler<Request, Response>{
 
 public void handle(Request request, CallBack<Response> callback, Context context) {
	 callback.success(new Response(1, "reply success"));
 }
 
}

• Context have these methods.

BaseEvent baseEvent(); // return event details comes into this function
Messenger messenger(); // return messenger instance
Logger logger(); // return logger instance

• CallBack provides way to reply.

callback.success(); //reply 200 status code with empty data
callback.success("reply success"); //reply 200 status code with data
callback.success(201, "reply success"); //reply 201 status code with data

callBack.failure("Error occurred"); //reply 500 status code with err-data
callBack.failure(401, "Error occurred"); //reply 401 status code with error-data

• Messenger provides way to publish events.
• void publish(String eventID, Object eventPayload, MessageHandler successHandler,ErrorHandler errorHandler,int timeout)throws MessengerException;

context.messenger().publish("users.UserValidate", user, s->{
  user.setId(UUID.randomUUID().toString());
  callBack.success(201, user);
}, e->{
  callBack.failure(e.statuscode(), e.error());
}, 1000 * 8);

• Logger provides way to attach logs for particular request context. We will discuss more about this logger in later section.

context.logger().info("log info");
context.logger().error("log error");
context.logger().warn("log warn");

• Create new maven project.
• Add this dependency and repository into .pom file.

<dependency>
   <groupId>com.quebic.faas.runtime</groupId>
   <artifactId>quebic-faas-runtime-java</artifactId>
   <version>0.0.1-SNAPSHOT</version>
</dependency>

<repositories>
   <repository>
    <id>quebic-runtime-java-mvn-repo</id>
    <url>https://raw.github.com/quebic-source/quebic-runtime-java/mvn-repo/</url>
    <snapshots>
     <enabled>true</enabled>
     <updatePolicy>always</updatePolicy>
    </snapshots>
   </repository>
</repositories>

• Run mvn clean package

• Deployment .yml spec file by describing how you want to deploy your functions into quebic. This is code snippet for deployment spec

function:
 name: hello-function # function name 
 source: /functions/hello-function.jar # jar artifact location
 handler: com.quebicfaas.examples.HelloFunction # request handler java class
 runtime: java # function runtime
 events: # function going to listen these events
   - users.UserCreate
   - users.UserUpdate

route:
 requestMethod: POST
 url: /users
 requestMapping:
   - eventAttribute: eID
     requestAttribute: id
   ...

NodeJS Runtime

• Write your logic inside the handler.

exports.validationHandler = function(payload, context, callback){
    
    if(validateUser(payload)){
        
        callback(null, true, 200);

    }else{

        callback(new Error('Not a valid e-mail address'), null, 400);

    }

}

• CallBack provides way to reply.

callback(); //reply 200 status code with empty data
callback(null, "success");  //reply 200 status code with data
callback(null, "success", 201);  //reply 201 status code with data
callback(error); //reply 500 status code with with error-data
callback(error, null, 401); //reply 401 status code with with error-data 

• Deployment .yml spec file by describing how you want to deploy your functions into quebic.
• Package your whole nodejs project dir into .tar file. Then set your .tar file location into source field in deployment spec.
• If the handler file app.js then handler file needs to set like this app.helloHandler
• If you are working on single javascript file. Then just set your .js file location into source field. No need to package.

 function:
   name: hello-function # function name 
   source: /functions/hello-function.tar # tar package location
   handler: app.helloHandler # request handler 
   runtime: nodejs # function runtime
   replicas: 2 # replicas count
   events: # function going to listen these events
     - users.UserValidate
   ...

Manage your functions with quebic cli

• quebic function create --file [deployment spec file]

• quebic function update --file [deployment spec file]

• quebic function deploy --name [function name] --version [version]

• quebic function scale --name [function name] --replicas [count]

• quebic function delete --name [function name]

• quebic function ls

• quebic function inspect --name [function name]

• quebic function test --name [function name] --payload '{"message":"hello"}'

Function Container

• You can decide spin up mechanism of your function container.
• By default container is started after create function spec. But you can config it to start by a request
• You can decide idle timeout of the container.

function:
  life:
    awake: request
    idleState:
      timeout: 15
      timeunit: minutes # or seconds or hours

Routing

• You can create routing endpoint to fire events from apigateway.

• Routing .yml spec is used to describe how it behave when invoke it.

name: users_route # route name just for identify
requestMethod: POST 
url: /users
async: true # enable asynchronous invocation
successResponseStatus: 201 # default response http status code
event: users.UserCreate # event going to send
requestMapping:
  - eventAttribute: eID # attribute name which function going to access in event's payload
    requestAttribute: id # attribute name which come in http request
  - eventAttribute: eName
    requestAttribute: name
headerMapping:
  - eventAttribute: auth # attribute name which function going to access in event's payload
    headerAttribute: x-token # attribute name which come in http header
headersToPass: # headers going to pass with event
  - Authorization
  - Private-Token

Manage Routes with quebic cli

• quebic route create --file [route spec file]

• quebic route update --file [route spec file]

• quebic route ls

• quebic route inspect --name [route name]

Asynchronous invocation from API Gateway

• Quebic provides way to invoke function Asynchronous way from API Gateway.
• After client send his request through the apigateway, He immediately gets a reference id (request-id) to track the request.
• Then client can check the request by using that request-id from request-tracker endpoint of API Gateway, If function already completed the task client will get the result of request, otherwise he will get request-still-processing message.

<api-gateway>/request-tracker/{request-id}

Logs

• Quebic provides way to access function-container's native logs by using quebic cli.
• quebic function logs --name [function name]
• Instead of accessing native logs quebic also provides way to attach logs for particular request context.

context.logger().info("log info");

• You can inspect these logs by using cli
• quebic request-tracker logs --request-id [request id]

Configurations

• Quebic cli config file is located at $HOME/.quebic-faas/cli-config.yml
• Also you can pass arguments to the quebic cli in runtime.
• Run quebic -h to list down all available commands.

Authors

• Tharanga Thennakoon - tharanganilupul@gmail.com
• Linkedin

License

• This project is licensed under the Apache Licensed V2