Creating a FaaS - Guide
- 13 Sep 2023
- DarkLight
- PDF
Creating a FaaS - Guide
- Updated On 13 Sep 2023
- DarkLight
- PDF
Article Summary
Share feedback
Thanks for sharing your feedback!
This tutorial helps you to learn how to use the Dataloop platform to push, deploy, execute, and trigger Functions.
SDK Tutorial
To learn how to set up and work with the FaaS module using Dataloop Python SDK, read here
1. Codebase
The following Python code consists of two image-manipulation functions:
- RGB to grayscale over an image: Turns a color image into an image composed of shades of gray.
- CLAHE (Contrast Limited Adaptive Histogram Equalization) Histogram Equalization over an image: Reduces noise amplification to improve the contrast of the image.
Each function receives a single item (image type), which later can be used as a trigger to invoke the function.
import dtlpy as dl
import cv2
import numpy as np
class ServiceRunner(dl.BaseServiceRunner):
@staticmethod
def rgb2gray(item: dl.Item):
"""
This function converts an RGB image to gray.
This will also add a modality to the original item.
:param item: dl.Item to convert
:return: None
"""
buffer = item.download(save_locally=False)
bgr = cv2.imdecode(np.frombuffer(buffer.read(), np.uint8), -1)
gray = cv2.cvtColor(bgr, cv2.COLOR_BGR2GRAY)
gray_item = item.dataset.items.upload(local_path=gray,
remote_path='/gray' + item.dir,
remote_name=item.filename)
# add modality
item.modalities.create(name='gray',
ref=gray_item.id)
item.update(system_metadata=True)
@staticmethod
def clahe_equalization(item: dl.Item):
"""
This function performs histogram equalization (CLAHE).
This will add a modality to the original item.
Based on opencv: https://docs.opencv.org/4.x/d5/daf/tutorial_py_histogram_equalization.html
:param item: dl.Item to convert
:return: None
"""
buffer = item.download(save_locally=False)
bgr = cv2.imdecode(np.frombuffer(buffer.read(), np.uint8), -1)
# create a CLAHE object (Arguments are optional).
lab = cv2.cvtColor(bgr, cv2.COLOR_BGR2LAB)
lab_planes = cv2.split(lab)
clahe = cv2.createCLAHE(clipLimit=2.0, tileGridSize=(8, 8))
lab_planes[0] = clahe.apply(lab_planes[0])
lab = cv2.merge(lab_planes)
bgr_equalized = cv2.cvtColor(lab, cv2.COLOR_LAB2BGR)
bgr_equalized_item = item.dataset.items.upload(local_path=bgr_equalized,
remote_path='/equ' + item.dir,
remote_name=item.filename)
# add modality
item.modalities.create(name='equ',
ref=bgr_equalized_item.id)
item.update(system_metadata=True)
To continue with the tutorial, save the code as a Python file (you may call it main.py) and then compress it to a zip file or upload it to your Git.
2. Environment
Since the code requires a Python library that is not a standard library (cv2 - opencv), it's essential to ensure its pre-installation before execution.
Two options are available:
- Use a custom Docker Image (For more details, read here).
- Upload a requirements file (.txt), separated from the codebase. For more details, read here.
Below you will find instructions on how to upload the codebase to Dataloop to create a FaaS application.
3. Push a Package of Multiple Functions
In this tutorial, you will learn how to create and push code as a package to the Dataloop FaaS library.
The code package will serve as an app that you can install/uninstall in your project.
From the left-side navigation menu, go to Application (FAAS) → Application hub.
Click Add Function.
Provide an app name. This name will serve as the service name. You can name our tutorial app image-process-app.
Select your preferred way of uploading the example code:
- Codebase Item type – for uploading a compressed folder (for example, “.zip”).
- Codebase Git type – to link a git code.
Environment: In our example, the package codebase utilizes a non-standard Python library (cv2 - openCV). Thus, it's mandatory to ensure its pre-installation before executing the entry point.
Two options are available:Use a custom Docker Image (details available here).
Upload a requirements file (Requirements.txt):
opencv-python==3.4.2.17
Requirements File UploadNotice that the 'Requirements.txt' file must be uploaded separately from the codebase. You'll find an exclusive button for the requirements file upload in the FaaS creation dialog.
Missing Python LybrariesUninstalled Python libraries will trigger an initialization error, leading to a "Crash Loop - Requirements Error," preventing your FaaS application service from start running.
Multiple functions may be defined in a single package under a module entity. This way you will be able to use a single codebase for various services (applications).
Define the module name (no limitations). Themain.pyfile you created should be defined as the module entry point.
- When ready, click Create and the new package will be listed in the table:
4. Deploy a Service
You can now create a service from the package. To do that, you need to define which module the service will serve. Notice that a service can only contain a single module. The module’s functions will be added to the service automatically.
Multiple services can be deployed from a single package. Each service can get its own configuration:
a different module and settings (computing resources, triggers, UI slots, etc.).
In our example, there is only one module in the package. Let’s deploy the service:
Install
Click the Install button of the code package (under the Library tab). An installation configuration popup will appear:
Set an Event-based Trigger to the Service
When creating a service, you can configure a trigger to automatically run the service functions. When you bind a trigger to a function, that function will execute when the trigger fires. The trigger is defined by a given time pattern or by an event in the Dataloop system.
An event-based trigger is related to a combination of resource and action. A resource can be several entities in our system (item, dataset, annotation, etc.) and the associated action will define a change in the resource that will prompt the trigger (update, create, delete).
The resource object that triggered the function will be passed as the function's parameter (input).
Separate triggers must be set for each function in your service.
Let’s set a trigger to invoke the rgb2gray function:
The trigger we set, invokes the function every time a new item is created.
We added a DQL filter, which monitors image items only, as well as a specific dataset (based on its dataset ID), rather than the entire project.
To find your dataset ID, go to the Dataset Browser → click on any item → the Dataset ID can be found in the right panel and copied by clicking the clipboard icon.
{
"$and": [{
"type": "file"
},
{
"hidden": false
},
{
"datasetId": "61e0349e9e3e2358d715ee06"
},
{
"metadata.system.mimetype": {
"$eq": "image/*"
}
}
]
}
Filters are created using the Dataloop Query Language (DQL).
You can also add filters to specify the item type (image, video, JSON, directory, etc.) or a certain format (jpeg, jpg, WebM, etc.).
To trigger the function only once (only on the first item event), set Execution Mode to Once, otherwise use Always.
Optional: Cron Trigger at Predefined Intervals
Click Cron to set a predefined interval for triggering the function, for example, processing image files once a day. For more specific scheduling, use regular CRON expressions.
Advanced Options – Compute Settings
By default, packages are deployed on Regular-S GCS instances. Click the ADVANCED button to change settings such as machine type, replicas, and concurrencies, and even apply a docker image.
Final Installation
Click Install to deploy the service.
Validation
Your service must now be listed on the INSTALLED apps list. Click the service to see the sidebar or click the 3-dot icon for more information and options.
5. Execute the Function
Once the service is ready, you may execute the available functions on an input.
An execution means running the function on a service with specific inputs (arguments). The execution input will be provided to the function that the execution runs.
Now that the service is up, it can be executed manually (on-demand) or automatically, based on a set trigger (time/event).
We will manually upload an item to the dataset we specified in the trigger’s DQL filter. You can use any image to upload. Once the image is uploaded, the item created trigger event invokes the rgb2gray function from our service. The transformed image will be saved in the same dataset.
Congratulations! You have successfully created, deployed, and executed a Dataloop function!
6. FaaS UI Slots – Optional
Add UI Slots (FaaS Package)
Assigning a function to UI slots creates a button in the Dataloop platform, allowing users to invoke the FaaS function when needed.
- Click the Library tab.
- Click the 3-dot icon to the right of your package and then click Add UI Slots.
- To define the slot:
- Pick the Module and Function, insert a Display Name.
- Select a Post Action to decide what to do with the function’s output (see the Post Action Options section below).
- Add your UI scopes – select the relevant Resource for the function and choose the Panel for the button to appear (the dataset dashboard or studio).
Post Action Options
The UI Slots Post-Action defines what to do with the function output. Currently, there are 3 available:
- drawAnnotation - for an annotation output, drawAnnotation Post-Action will draw on the item.
- download - for an item output, download Post-Action will download it.
- noAction - do nothing with output.
Activate UI Slots (FaaS Service installation)
To activate the UI button to enable you to invoke and execute the functions from different places in the platform:
- Go to the FaaS service that for which you want to activate the UI Slot
- In the service actions under the 3-dot icon, click "Activate UI Slots"
- Select the projects where you want to activate the UI slot buttons in, and the required slots you defined on the FaaS package. Make sure to have all required permissions (see below). Click OK.
- Execute the function through the UI-Slot in the dataset browser, task browser, or annotation studio, according to the UI Slot definition on the package.
Required Permissions
Certain permissions need to be set up to use UI slots of a FaaS service in projects other than the project where the FaaS service is located.
- FaaS Service Bot User:
To enable users to see and use the UI slot button in projects other than the FaaS service's project, the FaaS service user bot must be added as a user (developer) to those projects. Read more about bot users here. - User Access:
In addition to adding the FaaS service user bot to the relevant projects, the user who needs to access the UI slot button must also be added as a user to the project where the FaaS service is located, with any role.
Once these permissions are set up, users will be able to see and use the UI slot button for the FaaS service in projects other than the FaaS service's project.
7. Service Overview
The table listing and the sidebar panel provide you with information about the service status (running, paused, etc.), and allow you to pause/run the service by clicking the action button.
In addition, the side-bar panel provides access to information and tools:
Triggers: To see the triggers of your service, click VIEW Triggers. On this page, you can also create new triggers.
You can also see project-level triggers on the triggers page, which lists all triggers in the system, their type, settings, etc.Logs: To see the logs of your service, click VIEW LOGS. In the logs tab, filter your executions or sort the log in ascending/descending order to view the most recent or oldest content.
Executions History:
- Click EXECUTIONS to view the executions log.
- Click on any execution to see that execution’s details.
- Click the Repeat icon to rerun a failed execution.
You can also see project-level executions on the executions page, which lists all executions in the system, their statuses, services, etc.