Architecture - jupyterhub-cost-monitoring

This document outlines the architecture of the project, including its dependencies, their interactions, and the overall design principles.

Overview¶

This architecture diagram outlines how the cost monitoring infrastructure sits in the wider Zero to JupyterHub deployment, which is divided into two main namespaces: Support and Hub, as well as the external AWS service.

The Support section is where the JupyterHub Cost Monitoring backend is deployed. This backend retrieves cost data from the AWS Cost Explorer API. Usage data is collected by a Prometheus server from various exporters, including kube-state-metrics, node_exporter, and a jupyterhub-groups-exporter. Prometheus stores metrics in an internal time series database which can be queried with PromQL and exposes to Grafana for visualization.

The Hub section represents the user-facing JupyterHub components where users can connect via a proxy to the JupyterHub instance. JupyterHub manages User Pods and stores state, such as users, groups, server sessions, in a dedicated database. The jupyterhub-groups-exporter extracts group-related information from JupyterHub and sends it to Prometheus.

Cost Monitoring¶

Cost data is exposed with jupyterhub-cost-monitoring via FastAPI that can be consumed by other applications in the cluster, such as Grafana. The following endpoints are available:

/index: Returns all available endpoints.
/ready: Returns a 200 OK response if the application is ready to serve requests.
/hub-names: Returns a list of all JupyterHub names in the cluster.
/component-names: Returns a list of all JupyterHub names in the cluster.
/total-costs: Returns daily total costs and divided into two types:
- Account: The total costs as reported by the cloud provider.
- Attributable: The total costs that can be attributed by the jupyterhub-cost-monitoring application. For example, the act of querying the totals costs reported by cloud provider incurs a cost and is not included in attributable costs but is included in account costs.
/total-costs-per-hub: Returns the daily total costs per hub listed in hub_names.
/total-costs-per-component: Returns the daily total costs per cloud component
/total-costs-per-group: Returns the daily total costs per user group.
/costs-per-user: Returns the daily costs per user, hub, and component. This endpoint supports filtering by hub_name and component_name via query parameters.
/total-usage: User-level costs are apportioned based on a cost factor that is derived from the component usage of each user.
/users-with-multiple-groups: Returns a list of users who belong to multiple groups.
/users-with-no-groups: Returns a list of users who do not belong to any group.

Reference documentation is available at the /docs FastAPI endpoint.