Pyworker Hello World Guide

1) backend.py

2) launch.sh

Docs - Autoscaler

Pyworker Hello World Guide

Warning: The Autoscaler is currently in Beta, and is subject to changes, 'quirks', and downtime.

The vast-pyworker framework allows for the streamlined creation of an API server on your instance that can be connected to Vast's autoscaling service to automate the management of instances. We will go over a minimal "helloworld" example that uses the vast-pyworker to create a simple API. Note that this example doesn't provide enough functionality to intregrate with Vast's autoscaling service.

1) backend.py #

To integrate your application code with the API server on the instance, you must create a "backend" and write a launch script. Each "backend" lives in its own directory in the vast-pyworker repository, so you should fork the repo and make a new one. For this example we are implementing the "helloworld" backend, and you can see the directory we are creating for it here.

To implement the functionality for your server, you must write a "backend.py" file in the directory for your backend. We will look at the contents of this file piece by piece.

class Backend():
    def __init__(self, *args, **kwargs):
        self.count = 0

The first part of the file defines the Backend class, which is necessary to do. Since flask servers don't save automatically save state from request to request, this data structure is responsible for all state your application requires. Even if you don't need your application to save any state, you need to create this class, but you don't need to add any fields to it.

def increment_handler(backend, request):
    backend.count += request.json["amount"]
    return "Incremented"

def value_handler(backend, request):
    return {"value" : backend.count}

In this helloworld example, we provide two API endpoints, one to increment the count, and one to get the value of the count. For each endpoint you want to support, you must write a handler function in your backend.py file. A reference to an instance of your Backend object that persists throughout the lifetime of your application will be passed into as an argument to the handler function, along with the request object from flask. All your handler functions must have the (backend, request) function signature.

flask_dict = {
    "POST" : {
        "increment" : increment_handler
    },
    "GET" : {
        "value" : value_handler
    }
}

Finally, you need to allow your handler functions to be accessible by the flask server and tell it what endpoints are defined. To do this, you must create a flask_dict like so, where you should create an dictionary entry for each type of request you want to handle (such as POST or GET), and then within that dictionary map the endpoint name to the endpoint handler function.

2) launch.sh #

The other thing you must to do to make your backend server usable is create a launch script that starts up the flask server, along with other components of your server if applicable. You can see the launch script for the helloworld backend here.

start_server() {
    if [ ! -d "$1" ]
    then
        wget -O - https://raw.githubusercontent.com/vast-ai/vast-pyworker/main/start_server.sh | bash -s $2
    else
        $1/start_server.sh $2
    fi
}
start_server /home/workspace/vast-pyworker helloworld

For the minimal helloworld example, all this launch script does is call the main vast-pyworker start script start_server.sh. On instance creation, this will clone the vast-pyworker repo, and install general dependencies. What the start_server() function does is check if the vast-pyworker repo is already present in the expected location (which is /home/workspace/vast-pyworker), and if it isn't, it downloads the start script from github, and runs it directly. You can use this helper function for your server, and it can also be found in util.sh. The second argument to this function is the name of your backend, which is "helloworld" in this case. This is how the vast-pyworker server knows which directory your backend code can be found in. For more sophisticated servers, you can set up other components such as "metrics" and a "logwatch", but they aren't necessary and if your backend doesn't support them they just won't be activated.

To learn about how to integrate a vast-pyworker backend with Vast's Autoscaler, see the helloautoscaler follow-up guide.