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

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 workload. 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 it 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 workload 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 workload. 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 Workload Templates

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

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

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

Request Launch Workload

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

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

Wait for Workload to Launch

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

# Wait for the workload to be ready
while True:
    rsp = requests.get(
        f'{server}/kuiper/{user}/all',
        headers={'Authorization': token}
    )
    data = rsp.json()
    for workload in data:
        name = workload["name"]
        if name != workload_name:
            continue
        state_object = workload['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_workload.py

---> 100%

Join Link: https://orion-install/viewer/your-workload-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 workload catalog
rsp = requests.get(
    f'{server}/kuiper/catalog',
    headers={'Authorization': token}
)

# Select first workload template and get its idx
idx = rsp.json()[0]['idx']

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

# Wait for the workload to be ready
while True:
    rsp = requests.get(
        f'{server}/kuiper/{user}/all',
        headers={'Authorization': token}
    )
    data = rsp.json()
    for workload in data:
        name = workload["name"]
        if name != workload_name:
            continue
        state_object = workload['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 workload. 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