Skip to content

Getting Started

Orion is an API first platform. Each service ships with its own REST API and OpenAPI documentation. This allows you to interact with the services directly and build your own custom integrations. Getting Started is quick and easy.

Goal

We will follow the process of creating a python script that will communicate with Orion's Kuiper API to launch a workstation.

Permissions

Orion is a role-based system. To get started, you will need to have proper permissions. In this example, we are going to interact with Kuiper to launch a workstation. To do this, you will need to have the kuiper or admin role. If you aren't assigned to either role. You'll need to have an admin or titan user add you to the needed group. See User Management documentation for details.

Generating API Key

Juno uses standard API keys that are passed to the API in the Authorization header.

Warning

API keys are sensitive information. Do not share them with anyone.

Generate API Token

In Genesis click on your user icon in the top right corner select Create API Token.

Image title

Warning

API keys are only displayed once. If you lose your API key, you will need to generate a new one.

Warning

Only one API key exists per user. If you generate a new API key, the old one will be invalidated.

Copy API Key

Your API key will be displayed. Copy it to your clipboard.

Image title

Now that we have our API key, save is some place safe and let's move on to the next step.


OpenAPI Swagger

Orion ships with OpenAPI documentation for each service that is actively installed. This documentation is custom tailored to your installation and will provide you with the necessary information to interact with the service. To access the documentation, you will need to navigate to the integrated documentation section either in Hubble or Genesis. Hubble will have API documentation for project level services, such as Kuiper workstation management. While Genesis will have API documentation for cluster level services such as Genesis, Titan, and Terra.

Open Development

Open the documentation page by clicking on your user icon in the top right corner and selecting Development

Image title

Open Integrated OpenAPI Documentation

Open the documentation section in the Development page for Kuiper. Here you can find the OpenAPI documentation for each service and even try them out.

Image title

Now we know where to find our API's documentation, let's move on to the next step and start writing our script.


Writing Our Integration

We are going to write a simple python script that will interact with Kuiper to launch a workstation. We will use the requests library to make the API calls.

Warning

If you get a requests.exceptions.SSLError you can pass in the verify=False parameter to the request to disable SSL verification.

Setup Virtual Environment

We will be using Python 3.11 and a virtual environment to manage our dependencies. Then we will activate it. 

$ python3.11 -m venv venv && source venv/bin/activate

---> 100%

Install Requests

We will be using the python requests library to make our API calls. Let's install it. 

$ pip install requests

---> 100%

Import Credentials

We will be passing our API key and server URL as environment variables. Let's import them. 

import os
import requests
from time import sleep

server = os.environ['SERVER']
token = os.environ['TOKEN']

Identify Ourselves

Since we will be triggering this from a different application, we need to be able to identify ourselves. 

# Identify the user via token
rsp = requests.get(
    f'{server}/titan/identity',
    headers={'Authorization': token}
)
user = rsp.json()['name']  # provides the user's name associated with the token

Get Available Workstation Templates

Now we need to get the catalog of available workstation types that we can launch. We will then select the first one for now. 

# Get workstation catalog
rsp = requests.get(
    f'{server}/kuiper/catalog',
    headers={'Authorization': token}
)

# Select first workstation template and get it's idx
idx = rsp.json()[0]['idx']  # the idx is a unique identifier for the workstation template that is used to launch it

Request Launch Workstation

Now we have everything we need to request the workstation to launch. 

# Create a new workstation
rsp = requests.post(
    f'{server}/kuiper/request',
    headers={'Authorization': token},
    json={'instance_type': idx, 'user': user},
)
workstation_name = rsp.json()['name']  # the name of the workstation that was launched

Wait for Workstation to Launch

Now that the request has been put in, we now can watch for the API to flag that the workstation has been launched and is ready. We do this by entering a loop that will check the status of the workstation every 5 seconds. Once the workstation is ready, it will print the join link which consists of the workstations name and your servers url. Once clicked, it should open your browser and take you to the workstation where you will need to log in. 

# Wait for the workstation to be ready
while True:
    rsp = requests.get(
        f'{server}/kuiper/{user}/all',
        headers={'Authorization': token}
    )
    data = rsp.json()
    for workstation in data:
        name = workstation["name"]
        if name != workstation_name:
            continue
        state_object = workstation['state'][0]
        message = state_object['message']
        state = state_object['state']

        if message:
            print(f'{name}: {message}')
        if state == 'running':
            print(f'{name}: {state}')
            print(f"Join Link: {server}/viewer/{name}")
            break

        print(f'{name}: {state} (checking again in 5 seconds)')
    else:
        sleep(5)
        continue
    break

Run Your Integration

Now we run it and see the results! 

$ export TOKEN="your-token"
$ export SERVER="https://orion-install"
$ python launch_workstation.py

---> 100%

Join Link: https://orion-install/viewer/your-workstation-name

Full Script 

import os
import requests
from time import sleep

server = os.environ['SERVER']
token = os.environ['TOKEN']


# Identify the user via token
rsp = requests.get(
    f'{server}/titan/identity',
    headers={'Authorization': token}
)
user = rsp.json()['name']

# Get workstation catalog
rsp = requests.get(
    f'{server}/kuiper/catalog',
    headers={'Authorization': token}
)

# Select first workstation template and get it's idx
idx = rsp.json()[0]['idx']

# Create a new workstation
rsp = requests.post(
    f'{server}/kuiper/request',
    headers={'Authorization': token},
    json={'instance_type': idx, 'user': user},
)
workstation_name = rsp.json()['name']

# Wait for the workstation to be ready
while True:
    rsp = requests.get(
        f'{server}/kuiper/{user}/all',
        headers={'Authorization': token}
    )
    data = rsp.json()
    for workstation in data:
        name = workstation["name"]
        if name != workstation_name:
            continue
        state_object = workstation['state'][0]
        message = state_object['message']
        state = state_object['state']

        if message:
            print(f'{name}: {message}')
        if state == 'running':
            print(f'{name}: {state}')
            print(f"Join Link: {server}/viewer/{name}")
            break

        print(f'{name}: {state} (checking again in 5 seconds)')
    else:
        sleep(5)
        continue
    break


Summary

We have successfully written a python script that interacts with Kuiper to launch a workstation. As you can imagine, this is just the beginning, and the possibilities are endless. Orion can be integrated with any system that can make HTTP requests. This allows you to build custom integrations with your existing tools and services.

Examples