Orbis Usage Guide for Software¶

This guide explains how to use Orbis to generate compute reports for Astronomer Software deployments.

Prerequisites¶

Docker installed (recommended)
Houston API token with SYSTEM_ADMIN role (or WORKSPACE_ADMIN role if only 1 workspace is specified)
Organization domain for Astronomer Software
Start and end dates for the report period

Using Docker (Recommended)¶

Create a .env file with your configuration:

ASTRO_SOFTWARE_API_TOKEN=your_token_here

Run Orbis using Docker:

docker run --pull always --rm -it \
  --env-file .env \
  -v $(pwd)/output:/app/output \
  quay.io/astronomer/orbis:0.7.0 orbis compute-software \
  -s START_DATE \
  -e END_DATE \
  -o ORGANIZATION_ID \
  [-v] [-w WORKSPACES] [-z] [-r] [-p]

Using Orbis CLI¶

Check installation guide for Orbis CLI here

Create a .env file with your configuration:

ASTRO_SOFTWARE_API_TOKEN=your_token_here

Run Orbis using the Orbis CLI:

orbis compute-software \
  -s START_DATE \
  -e END_DATE \
  -o ORGANIZATION_ID \
  [-v] [-w WORKSPACES] [-z] [-r] [-p]

Command Options¶

Option	Description
`-s, --start_date`	Start date for the report in UTC [format: YYYY-MM-DD]
`-e, --end_date`	End date for the report in UTC [format: YYYY-MM-DD] (End date is not inclusive. Example for report till 12th Dec 2024 use 2024-12-13)
`-o, --organization_id`	Astronomer organization domain
`-v, --verbose`	Enable verbose logging (use -v, -vv, or -vvv for more detailed logging) [Optional]
`-w, --workspaces`	Comma-separated list of Workspace IDs [optional]
`-z, --compress`	Compress the output reports [optional]
`-r, --resume`	Resume report generation from the last saved state [optional]
`-p, --persist`	Persist temporary files in output folder [optional]
`-u, --url`	Pre-signed URL (in quotes) to upload report [Optional]
`--verify-ssl`	Enable or disable SSL verification for requests. Default is `True`. Set to `False` when using self-signed certificates [optional]

Example Usage¶

docker run --pull always --rm -it \
  --env-file .env \
  -v $(pwd)/output:/app/output \
  quay.io/astronomer/orbis:0.7.0 orbis compute-software \
  -s 2024-01-01 \
  -e 2024-01-31 \
  -o org-abcd1234 \
  -v

Generate System Admin Level API Token¶

Orbis won't be able to query Prometheus without the SYSTEM_ADMIN token.
Go to https://houston.<organization_domain>/v1.

Execute the following query to get create the SYSTEM_ADMIN service account and API token.

mutation create_system_service_account {
    createSystemServiceAccount(label: "serv-acc", role: SYSTEM_ADMIN){
            apiKey
        roleBindings{
            role
        }
    }
}

Sample Response:

{
    "data": {
        "createSystemServiceAccount": {
            "apiKey": "<GENERATED_TOKEN>",
            "roleBindings": [
                {
                    "role": "SYSTEM_ADMIN"
                }
            ]
        }
    }
}

Add the API token to the .env file ASTRO_SOFTWARE_API_TOKEN=<GENERATED_TOKEN>

Output¶

The command generates a comprehensive PDF report in the output directory with metrics as below for the given duration:

Scheduler CPU and Memory
Worker CPU and Memory
KPO’s CPU and Memory
Task Trends
Worker (Celery/Kubernetes) Pod Counts