Usage Quota Dashboard Service

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

Installation¶

Install the package with the service extra:

pip install "jupyterhub-usage-quotas[service]"

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_gibibyte_hours and jupyterhub_memory_limit_gibibyte_hours (provided by jupyterhub-usage-quotas)

• 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.UsageConfig.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: