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 grant yourself 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 role.

Open Settings

Open the settings page by clicking on your user icon in the top right corner and selecting Settings

Image title

Open Users and Groups

Open the Users and Groups section in the Settings

Image title

Assign Kuiper Role

Assign yourself to the Kuiper Role by clicking on the Assign Group button and selecting the kuiper role

Image title

Verify Access

Make sure you have the kuiper role assigned to your user

Image title

Now that we have the proper permissions, we can move on to the next step.


Generating API Key

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

Open Settings

Open the settings page by clicking on your user icon in the top right corner and selecting Settings

Image title

Open Users and Groups

Open the Users and Groups section in the Settings

Image title

Warning

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

Generate API Key

Click the key icon next to your user to generate an API key.

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 on Hubble.

Note

To view the documentation, you will need to have the titan role assigned to your user. titan handles all authorization for Orion and its services, by default it will block access to the documentation.

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

Install Requests

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

pip install requests

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