Usage Quota Dashboard Service

The usage quota dashboard service is a Tornado web application that lets users view their current home storage usage and quota directly within JupyterHub.

How it works¶

The service:

• Registers as a JupyterHub service and authenticates users via JupyterHub’s OAuth2 flow

• Queries Prometheus for storage metrics using the dirsize_hard_limit_bytes and dirsize_total_size_bytes metrics (provided by jupyterhub-home-nfs or equivalent)

• Queries Prometheus for compute metrics using the jupyterhub_memory_usage_byte_hours and jupyterhub_memory_limit_byte_hours emitted from the usage quota system

• Displays a usage dashboard embedded in JupyterHub via an iframe to show users their current usage and quota

When dev_mode is enabled (via --dev-mode flag), the service can return randomly generated mock data, which is useful for development without a Prometheus instance. Mock data is only used when ALL three conditions are met: (1) dev_mode is True, AND (2) prometheus_url is the default (http://127.0.0.1:9090), AND (3) hub_namespace is empty. If either prometheus_url or hub_namespace is configured, the service will query Prometheus even when dev_mode is True.

JupyterHub configuration for local development¶

# jupyterhub_config.py

from jupyterhub_usage_quotas import setup_usage_quotas

c = get_config()  # noqa

# Register the service as a JupyterHub-managed subprocess
c.JupyterHub.services = [
    {
        "name": "usage-quota",
        "url": "http://localhost:9000",
        "display": False,  # Don't show the inbuilt service link since we show a standalone link in the navbar
        "oauth_no_confirm": True,
        "oauth_redirect_uri": "/services/usage-quota/oauth_callback",
        "command": [
            "python",
            "-m",
            "jupyterhub_usage_quotas.services.usage_viewer",
            "--config-files=jupyterhub_config.py",
            "--config-files=jupyterhub_config_secret.py",
        ],
    }
]

c.JupyterHub.load_roles = [
    {
        "name": "usage-quota-service",
        "scopes": ["read:users"],
        "services": ["usage-quota"],
    },
    {
        "name": "user",
        "scopes": ["access:services!service=usage-quota", "self"],
    },
]

# Set up common usage quotas config
setup_usage_quotas(c)

# jupyterhub_config_secret.py
# Example config file for secret data, e.g. credentials and keys.
# Make sure you ignore/encrypt this file if using with a version control system.

c.UsageViewer.prometheus_auth = {"username": "", "password": ""}

c.UsageViewer.session_secret_key = "use-a-secure-random-key-in-production"

When a command is provided, JupyterHub launches and manages the service process automatically, injecting the necessary JUPYTERHUB_* environment variables.

CLI Flags¶

The service is configured via CLI flags (preferred) or traitlet configuration:

Environment Variables¶

All configuration options can be set via environment variables as alternatives to CLI flags: