Building custom image for function¶

In this tutorial we will describe how you can build your custom docker image and execute it as a Qiskit Function.

You will be following 3 steps to deploy it:

implement function template
define dockerfile, build it
upload

You can find the example in docs/deployment/custom_function, which will have 2 files: Sample-Dockerfile and runner.py.

Custom image folder source files for the example¶

/custom_function
  /runner.py
  /Sample-Dockerfile

First, you will implement your function entrypoint following the template. All functions with custom docker images must follow same template structure.

We need to create class Runner and implement run method that will be called during invocation of the function and the results of the run method will be returned as result of the function.

Let’s create runner.py file with the following content:

runner.py - Runner class implementation. This is an entrypoint to you custom image function.¶

 class Runner:
     def run(self, arguments: dict) -> dict:
         # this is just an example
         # your function can call for other modules, function, etc.
         return {
             **arguments,
             **{
                 "answer": 42
             }
         }

As a next step let’s define and build our custom docker image.

Dockerfile will be extending base serverless node image and adding required packages and structure to it.

In our simple case it will look something like this:

Dockerfile for custom image function.¶

 FROM icr.io/quantum-public/qiskit-serverless/ray-node:0.18.1

 # install all necessary dependencies for your custom image

 # copy our function implementation in `/runner/runner.py` of the docker image
 USER 0

 WORKDIR /runner
 COPY ./runner.py /runner
 WORKDIR /

 USER 1000

and after that we need to build it:

Build image¶

 docker build -t test-local-provider-function -f Sample-Dockerfile .

We got to our final step of function development - uploading to serverless.

For a local development you can modify docker-compose.yaml ray image with the image that it was generated in the previous step:

Modify docker compose definition¶

 services:
     ray-head:
         container_name: ray-head
         image: test-local-provider-function:latest

Run it:

Run docker compose¶

 docker-compose up

Or if you are using kubernetes you will need to create the cluster and load the image in Kind:

Run your local cluster¶

 tox -e cluster-deploy
 kind load docker-image test-local-provider-function:latest

And that’s everything you need to take into account if you are using the k8s approach.

Once time the local environment is running, it only remains to run the code! For that you just need to define QiskitFunction

with the image that you just built, give it a name and upload it:

Uploading and using function with custom image.¶

 import os
 from qiskit_serverless import QiskitFunction, ServerlessClient

 serverless = ServerlessClient(
     token=os.environ.get("GATEWAY_TOKEN", "awesome_token"),
     host=os.environ.get("GATEWAY_HOST", "http://localhost:8000"),
     # If you are using the kubernetes approach the URL must be http://localhost
 )
 serverless

 function = QiskitFunction(
     title="custom-image-function",
     image="test-local-provider-function:latest",
     provider="mockprovider"
 )
 function

 serverless.upload(function)

 my_function = serverless.get("custom-image-function")
 my_function

 job = my_function.run(test_argument_one=1, test_argument_two="two")
 job

 job.result()