Internal Nublado controller API¶
The Nublado controller is built as a Docker image intended for deployment in a Kubernetes cluster using Phalanx and is not supported as an installed Python module. This documentation therefore exists only to assist developers and code analysis and does not define a supported API.
controller Package¶
The Nublado controller service.
Variables¶
The application version string (PEP 440 / SemVer compatible). |
controller.background Module¶
Nublado controller background processing.
Classes¶
|
Manage Nublado controller background tasks. |
Class Inheritance Diagram¶
controller.config Module¶
Global configuration parsing.
Classes¶
Source of a volume to be mounted in the lab. |
|
Nublado controller configuration. |
|
Docker image that may be run as a container. |
|
Configuration when user file servers are disabled. |
|
Configuration for enabled user file servers. |
|
Base configuration for user file servers. |
|
Path on Kubernetes node to mount in the container. |
|
Configuration for spawning user labs. |
|
A container to run as an init container before the user's lab. |
|
Rules for |
|
A secret to make available to lab containers. |
|
Possible size of lab. |
|
NFS volume to mount in the container. |
|
Resources for a persistent volume claim. |
|
A PVC to create to materialize the volume to mount in the container. |
|
|
Whether |
|
Algorithm for building a user's home directory path. |
A volume that may be mounted inside a container. |
|
The mount of a volume inside a container. |
Class Inheritance Diagram¶
controller.constants Module¶
Global constants.
Variables¶
Annotations to add to most created objects. |
|
Default path to controller configuration. |
|
Default path to the Docker API secrets. |
|
Used in the lab form for |
|
Regex matching all valid group names. |
|
How frequently to refresh file server state from Kubernetes. |
|
How frequently to refresh the list of remote and cached images. |
|
Pattern matching valid Kubernetes names. |
|
How long to wait for generic sequences of Kubernetes API calls. |
|
How frequently to refresh user lab state from Kubernetes. |
|
Ratio of lab resource limits to requests. |
|
Ratio of maximum memory size to maximum size of |
|
Default path to injected pod metadata. |
|
How long to wait for a prepuller pod to spawn and finish running. |
|
Environment variables reserved to the controller or JupyterHub. |
|
Paths within the lab that are reserved for special purposes. |
|
Regex matching all valid usernames. |
controller.dependencies.config Module¶
Config dependency.
Classes¶
|
Dependency to manage a cached Nublado controller configuration. |
Class Inheritance Diagram¶
controller.dependencies.context Module¶
Request context management.
ContextDependency
is an all-in-one dependency, because managing individual
dependencies turned out to be a real pain. It’s designed to capture the
context of any request. It requires that a Config
object
has been loaded before it can be instantiated.
Classes¶
Provide a per-request context as a FastAPI dependency. |
|
|
Holds the incoming request and its surrounding context. |
Class Inheritance Diagram¶
controller.dependencies.user Module¶
User and authentication dependencies for FastAPI.
Functions¶
|
Return the validated user for the given request. |
|
Validate and return the username in the request path. |
controller.exceptions Module¶
Exceptions for the Nublado lab controller.
Classes¶
|
Wraps |
|
An API call to a Docker Registry failed. |
|
Multiple Kubernetes objects were found when one was expected. |
|
Unable to parse the reply from Gafaelfawr. |
|
An API call to Gafaelfawr failed. |
|
The user's quota is insufficient to satisfy this request. |
|
Docker reference does not contain a tag. |
|
The provided lab size is not one of the configured sizes. |
|
The delegated user token is invalid. |
|
An API call to Kubernetes failed. |
|
An error occurred when deleting a lab. |
|
Lab creation was attempted for a user with an active lab. |
|
An expected Kubernetes object is missing. |
|
Secret specified in the controller configuration was not found. |
|
No operation was in progress when attempting to wait. |
|
An attempt was made to use a disabled service. |
|
Attempt to perform an operation when another is in progress. |
|
Attempt to access a resource for another user. |
|
Cannot find a Docker image matching the requested parameters. |
|
No resource has been created for this user. |
Class Inheritance Diagram¶
controller.factory Module¶
Component factory and global and per-request context management.
Classes¶
|
Build lab controller components. |
|
Per-process global application state. |
Class Inheritance Diagram¶
controller.main Module¶
The main application factory for the Nublado controller service.
Functions¶
|
Create the FastAPI application. |
controller.models.domain.docker Module¶
Domain models for talking to the Docker API.
Classes¶
|
Holds the credentials for one Docker API server. |
|
Parses a Docker reference. |
Class Inheritance Diagram¶
controller.models.domain.fileserver Module¶
Models for the fileserver state.
Classes¶
|
All of the Kubernetes objects making up a user's fileserver. |
|
Kubernetes objects used for inspecting the state of a fileserver. |
Class Inheritance Diagram¶
controller.models.domain.gafaelfawr Module¶
Models for talking to Gafaelfawr.
Ideally, these should use the same models Gafaelfawr itself uses. Until that’s possible via a PyPI library, these models are largely copied from Gafaelfawr.
Classes¶
User information from Gafaelfawr supplemented with the user's token. |
|
User metadata from Gafaelfawr. |
|
Notebook Aspect quota information for a user. |
|
Gafaelfawr's representation of a single group. |
|
Quota information for a user. |
Class Inheritance Diagram¶
controller.models.domain.image Module¶
Internal models returned by image service methods.
Classes¶
|
A single spawnable image. |
|
All available spawnable images. |
Class Inheritance Diagram¶
controller.models.domain.kubernetes Module¶
Data types for interacting with Kubernetes.
Classes¶
Pod affinity rules. |
|
|
Protocol for Kubernetes object models. |
|
A cached image on a Kubernetes node. |
Rule for matching labels of pods or namespaces. |
|
|
Match operations for label selectors. |
Single rule for label matching. |
|
Node affinity rules. |
|
|
Match operations for node selectors. |
Individual match rule for nodes. |
|
Term to match nodes. |
|
Matching terms for nodes. |
|
|
Whether a single node is tolerated. |
Pod affinity rules. |
|
Pod matching term for pod affinity. |
|
|
Represents a change (not creation or deletion) of a pod. |
|
One of the valid phases reported in the status section of a Pod. |
Scheduling term with a weight, used to find preferred nodes. |
|
|
Possible values for the |
|
Pull policy for Docker images in Kubernetes. |
|
Possible effects of a pod toleration. |
Represents a single pod toleration rule. |
|
|
Possible operators for a toleration. |
|
Access mode for a persistent volume. |
Pod matching term for pod affinity with an associated weight. |
|
|
Possible values of the |
Class Inheritance Diagram¶
controller.models.domain.lab Module¶
Internal models related to user labs.
Classes¶
|
Type of message. |
One lab operation event for a user. |
|
|
Names for the key Kubernetes objects making up a user's lab. |
|
All of the Kubernetes objects making up a user's lab. |
|
All of the Kubernetes objects required to reconstruct lab state. |
Class Inheritance Diagram¶
controller.models.domain.rspimage Module¶
Abstract data types for handling RSP images.
Classes¶
|
A tagged Rubin Science Platform image. |
|
Provides operations on a collection of |
Class Inheritance Diagram¶
controller.models.domain.rsptag Module¶
Abstract data types for handling RSP image tags.
Classes¶
|
A sortable image tag for a Rubin Science Platform image. |
|
Hold and perform operations on a set of |
|
The type (generally, release series) of the identified image. |
Variables¶
Implicit tag used by Docker/Kubernetes when no tag is specified. |
Class Inheritance Diagram¶
controller.models.domain.volumes Module¶
Models for mounted volumes.
Classes¶
|
Represents a volume along with its corresponding mount. |
Class Inheritance Diagram¶
controller.models.index Module¶
Top-level request models for the Nublado controller.
Classes¶
Metadata returned by the external root URL of the application. |
Class Inheritance Diagram¶
controller.models.v1.fileserver Module¶
API-visible models for user file servers.
Classes¶
Status of a user's file server. |
Class Inheritance Diagram¶
controller.models.v1.lab Module¶
API-visible models for user lab environments.
Classes¶
Options shared by both the input and output model for lab options. |
|
|
Supported classes of images. |
Options for the lab, specified at creation time. |
|
User-provided lab configuration options. |
|
Resource requests and limits for a lab. |
|
|
Allowable names for pod sizes. |
Specification of lab to spawn, sent by the JupyterHub spawner. |
|
Current state of the user's lab. |
|
|
Possible states the user's lab may be in. |
A Kubernetes resource request or limit. |
|
Metadata about the user who owns the lab. |
Class Inheritance Diagram¶
controller.models.v1.prepuller Module¶
Models for prepuller.
Classes¶
Docker Registry from which to get images. |
|
Google Artifact Registry from which to get images. |
|
A single Docker image that is available or prepulled. |
|
Information about available images on a single Kubernetes node. |
|
An available image present on at least some Kubernetes nodes. |
|
Used to display available images. |
|
Status of the images being prepulled. |
|
Options for the prepuller. |
|
Status of the image prepuller. |
|
Images known to the Nublado controller and available for spawning. |
Class Inheritance Diagram¶
controller.services.builder.fileserver Module¶
Construction of Kubernetes objects for user fileservers.
Classes¶
|
Construct Kubernetes objects for user file servers. |
Class Inheritance Diagram¶
controller.services.builder.lab Module¶
Construction of Kubernetes objects for user lab environments.
Classes¶
|
Construct Kubernetes objects for user lab environments. |
Class Inheritance Diagram¶
controller.services.builder.prepuller Module¶
Construct Kubernetes objects used by the prepuller.
Classes¶
|
Construct Kubernetes objects used by the prepuller. |
Class Inheritance Diagram¶
controller.services.builder.volumes Module¶
Construction of Kubernetes objects for volumes and volume mounts.
Classes¶
Construct Kubernetes objects for volumes and volume mounts. |
Class Inheritance Diagram¶
controller.services.fileserver Module¶
Service to manage user fileservers.
Classes¶
|
Manage user file servers. |
Class Inheritance Diagram¶
controller.services.image Module¶
Container image service.
Classes¶
|
Service to track the available images for Jupyter labs. |
Class Inheritance Diagram¶
controller.services.lab Module¶
Service to manage user lab environments.
Classes¶
|
Manage user labs. |
Class Inheritance Diagram¶
controller.services.prepuller Module¶
Prepull images to Kubernetes nodes.
Classes¶
|
Prepull images to Kubernetes nodes. |
Class Inheritance Diagram¶
controller.services.source.base Module¶
Base class for image sources.
Classes¶
|
Base class for image sources. |
Class Inheritance Diagram¶
controller.services.source.docker Module¶
Image source using a Docker Registry.
Classes¶
|
Image source using a Docker Registry. |
Class Inheritance Diagram¶
controller.services.source.gar Module¶
Image source using a Google Artifact Registry.
Classes¶
|
Image source using a Google Artifact Registry. |
Class Inheritance Diagram¶
controller.storage.docker Module¶
Client for the Docker v2 API.
Classes¶
|
Read and write the |
|
Client to query the Docker API for image information. |
Class Inheritance Diagram¶
controller.storage.gafaelfawr Module¶
Client for talking to Gafaelfawr.
Classes¶
|
Get user information from Gafaelfawr. |
Class Inheritance Diagram¶
controller.storage.gar Module¶
Client for Google Artifact Registry.
Classes¶
|
Client for Google Artifact Registry. |
Class Inheritance Diagram¶
controller.storage.kubernetes.creator Module¶
Generic Kubernetes object storage supporting only create and read.
Provides a generic Kubernetes object management class and instantiations of that class for Kubernetes object types that only support create and read. This is sufficient for a lot of object types the lab controller manipulates. Storage classes for object types that only need those operations are provided here.
For object types that need to support other operations, see
KubernetesObjectDeleter
, which
subclasses KubernetesObjectCreator
and adds list and delete support, and its
subclasses.
Classes¶
|
Storage layer for |
|
Generic Kubernetes object storage supporting create and read. |
|
Storage layer for |
|
Storage layer for |
|
Storage layer for |
Variables¶
Type of Kubernetes object being manipulated. |
Class Inheritance Diagram¶
controller.storage.kubernetes.custom Module¶
Storage layer for Kubernetes custom objects objects.
Classes¶
|
Storage layer for Kubernetes custom objects. |
|
Storage layer for |
Class Inheritance Diagram¶
controller.storage.kubernetes.deleter Module¶
Generic Kubernetes object storage including list and delete.
Provides a generic Kubernetes object management class and instantiations of that class for Kubernetes object types that support list and delete (as well as create and read, provided by the superclass). Storage classes for object types that only need those operations are provided here; more complex storage classes with other operations are defined in their own modules.
Classes¶
|
Generic Kubernetes object storage supporting list and delete. |
|
Storage layer for |
|
Storage layer for |
|
Storage layer for |
Variables¶
Type of Kubernetes object being manipulated. |
Class Inheritance Diagram¶
controller.storage.kubernetes.fileserver Module¶
Kubernetes storage layer for user fileservers.
Classes¶
|
Kubernetes storage layer for file servers. |
Class Inheritance Diagram¶
controller.storage.kubernetes.ingress Module¶
Storage layer for Ingress
objects.
Functions¶
|
Check whether an ingress has an IP address assigned. |
Classes¶
|
Storage layer for |
Class Inheritance Diagram¶
controller.storage.kubernetes.lab Module¶
Kubernetes storage layer for user labs.
Classes¶
|
Kubernetes storage layer for user labs. |
Class Inheritance Diagram¶
controller.storage.kubernetes.namespace Module¶
Storage layer for Namespace
objects.
Classes¶
|
Storage layer for |
Class Inheritance Diagram¶
controller.storage.kubernetes.node Module¶
Storage layer for Kubernetes node objects.
Classes¶
|
Storage layer for Kubernetes node objects. |
Class Inheritance Diagram¶
controller.storage.kubernetes.pod Module¶
Storage layer for Pod
objects.
Classes¶
|
Storage layer for |
Class Inheritance Diagram¶
controller.storage.kubernetes.watcher Module¶
Watch a Kubernetes namespace or cluster for events.
Classes¶
|
Watch Kubernetes for events. |
|
Parsed event from a Kubernetes watch. |
Variables¶
Type of Kubernetes object being watched ( |
Class Inheritance Diagram¶
controller.storage.metadata Module¶
Storage layer for pod metadata.
Classes¶
|
Storage layer for pod metadata for the running pod. |
Class Inheritance Diagram¶
controller.templates Module¶
Template management.
Provides a shared Jinja template environment used whenever the Nublado controller generates responses based on templates.
Variables¶
The template manager. |
controller.timeout Module¶
Timeout class for Kubernetes operations.
Classes¶
|
Track a cumulative timeout on a series of operations. |
Class Inheritance Diagram¶
controller.units Module¶
Unit conversions for the Nublado controller.
Functions¶
|
Convert a string representatio of memory to a number of bytes. |