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.16.3

 # 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 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: local-provider-function:latest

Run it:

Run docker compose

 docker-compose up

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"),
 )
 serverless

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

 serverless.upload(function_with_custom_image)

 functions = {f.title: f for f in serverless.list()}
 my_function = functions.get("custom-image-function")
 my_function

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

 job.result()