Jupyter Application Programming Interfaces

A Golang replacement for the Kubeflow Jupyter Web APIs.

How to Contribute

Development Environment

Note that the frontend will report errors when calling /api/namespaces when run locally. This issue does not arise in production, as the /api/namespaces endpoint is unused.

To initialize the .env file for the development environment, use task env. You will need to fill out your kubeflow cloud account and kubeflow namespace information manually. The thunder-tests folder contains configuration for testing requests against the backend. Use the vscode THUNDER CLIENT extension to load the tests.

Run API Server

The API server will connect to the Kubeflow cluster from your current kubectl context. See Connecting a Kubeflow cluster below for options.

Install Go
Change directory to project root: cd jupyter-apis
Run go run . -spawner-config samples/spawner_ui_config.yaml

Alternatively,

task go:dev -w -- -spawner-config samples/spawner_ui_config.yaml will live-reload the Go server upon changes.

Recommended

You can use the vscode debugger to run the backend, just copy the below contents to a file at path .vscode/launch.json.

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Debug jupyter-api backend",
            "type": "go",
            "request": "launch",
            "mode": "debug",
            "program": ".",
            "args": [
                "-spawner-config",
                "samples/spawner_ui_config.yaml",
            ],
            "envFile": "${workspaceFolder}/.env"
        }
    ]
}

Run Front-End

The front-end is configured to proxy requests to the local API server. It requires an environment variable (KF_USER_ID) to specify the current user – this is passed to the API server as an HTTP header.

The following can be pasted in a script and executed. This uses the latest node lts version(v16.16.0). NOTE: user is when using vagrant. Use the email adress if it is the dev cluser (please never connect to prod directly)

cd frontend/common/kubeflow-common-lib
npm i
npm run build
cd dist/kubeflow
npm link

cd ../../../../jupyter
npm i
npm link kubeflow --legacy-peer-deps
KF_USER_ID=user npm start

For the kubecost data to be retrievable, the following will need to be executed kubectl port-forward -n kubecost-system deployment/kubecost-cost-analyzer 9090

Older instructions

~~Change directory to front-end folder: cd frontend~~
~~Install dependencies: npm install~~
~~Run the front-end KF_USER_ID=<cloud_email> npm start~~

The front-end is now available at http://localhost:4200/jupyter/. Since it is disconnected from the centraldashboard component, you need to type your desired namespace in the UI rather than selecting it from a dropdown.

Connecting a Kubeflow Cluster

The API server will connect to the Kubeflow cluster from your current kubectl context. Here are a couple options for setting that up.

Local MiniKF Cluster

This deploys a Kubeflow cluster on your local machine and requires at least 50GB of disk space and the recommanded RAM is 12 Gb. First, create the miniKF cluster:

Install Vagrant and Virtual Box.
Create a new directory and run vagrant init arrikto/minikf and then vagrant up (takes about 20 minutes to boot).
Navigate to http://10.10.10.10.
Follow on-screen steps to start Kubeflow and Rok (takes about another 20 minutes).
From here, you can use Kubeflow and Rok.

Then configure kubectl to connect to your new cluster:

Download the miniKF kubectl config file from http://10.10.10.10.
Use the downloaded configuration for kubectl, either replacing, or merging it into, ~/.kube/config.
Ensure kubectl config current-context is pointing to your local cluster.

Your KF_USER_ID can be the default user that was created for your miniKF cluster (typically user).

Each time you need to start the cluster, navigate to the directory you created and run vagrant up.

Note: after some experimentation, it was found that the vagrant file could be modified on line 57 to use 8gb instead of the default 12.

  config.vm.provider "virtualbox" do |vb|
    # Display the VirtualBox GUI when booting the machine
    #vb.gui = true

    # Customize the amount of memory on the VM:
    vb.memory = "8192"
  end

Remote AKS Cluster

Install Azure CLI az and kubectl
Login with az and set your subscription
Run az aks get-credentials for the desired remote cluster
Ensure kubectl config current-context is pointing to correct cluster

On platform testing

Any push to an open PR that has the auto-deploy label on it allows developers to opt-in to on-platform testing. For example, when you need to build in github and test on platform (or want someone else to be able to pull your image):

open a PR and add the auto-deploy label
push to your PR and watch the GitHub Action CI
access your image in Kubeflow DEV via a custom image from any of:
- k8scc01covidacrdev.azurecr.io/IMAGENAME:SHA
- k8scc01covidacrdev.azurecr.io/IMAGENAME:SHORT_SHA

Whats Different?

Routes are defined in this repository here.

Upstream, the endpoints are structures via request type (e.g. GET, PUT, DELETE).

Note

that not all endpoints are included in the golang implementation
to find the upstream endpoint, load the Upstream and use search with the endpoint text!

Request Type	Golang Endpoint	Upstream Python Endpoint	Purpose
GET	/api/config	/api/config
GET	/api/gpus	/api/gpus
GET	/api/storageclasses/default	/api/storageclasses/default
GET	/api/namespaces/{namespace}/cost/allocation	Not found	Get the kubecost Allocation API
GET	/api/namespaces	/api/namespaces	Get the list of namespaces
GET	/api/namespaces/{namespace}	Not found	Get namespace metadata
GET	/api/namespaces/{namespace}/notebooks	/api/namespaces/<namespace>/notebooks	Get the list of notebooks
POST	/api/namespaces/{namespace}/notebooks	/api/namespaces/<namespace>/notebooks	Create a notebook
DELETE	/api/namespaces/{namespace}/notebooks/{notebook}	/api/namespaces/<namespace>/notebooks/	Update a notebook
PATCH	/api/namespaces/{namespace}/notebooks/{notebook}	/api/namespaces/<namespace>/notebooks/<notebook	Delete a notebook
GET	/api/namespaces/{namespace}/pvcs	/api/namespaces/<namespace>/pvc	List `PVC`s
DELETE	/api/namespaces/{namespace}/pvcs/{pvc}	/api/namespaces/<namespace>/pvcs/	Delete a `PVC`
GET	/api/namespaces/{namespace}/poddefaults	/api/namespaces/<namespace>/poddefaults	Get `PodDefault`s for a given namespace

bryanpaget / jupyter-apis