LabManager

class controller.services.lab.LabManager(*, config, image_service, lab_builder, metadata_storage, lab_storage, slack_client, logger)

Bases: object

Manage user labs.

The lab manager is a process singleton that manages user labs. This includes spawning them, deleting them, and tracking their state.

Parameters:

• config (LabConfig) – Configuration for user labs.

• image_service (ImageService) – Tracks all available images and resolves the parameters of a request for a new lab to a specific Docker image.

• lab_builder (LabBuilder) – Builder for Kubernetes lab objects.

• metadata_storage (MetadataStorage) – Storage for metadata about the running controller.

• lab_storage (LabStorage) – Kubernetes storage layer for user labs.

• slack_client (Optional[SlackWebhookClient]) – Optional Slack webhook client for alerts.

• logger (BoundLogger) – Logger to use.

Methods Summary

create_lab(user, spec)	Schedules creation of user lab objects/resources.
delete_lab(username)	Delete the lab environment for the given user.
events_for_user(username)	Construct an iterator over the events for a user.
get_lab_state(username)	Get lab state for a user.
list_lab_users(*[, only_running])	List all users with labs.
start()	Synchronize with Kubernetes and start a background refresh task.
stop()	Stop the background refresh task.

Methods Documentation

async create_lab(user, spec)

Schedules creation of user lab objects/resources.

Parameters:

• user (GafaelfawrUser) – User for whom the lab is being created.

• spec (LabSpecification) – Specification for lab to spawn.

Raises:

• InvalidDockerReferenceError – Raised if the Docker image reference in the lab specification is invalid.

• InvalidLabSizeError – Raised if the requested lab size is not one of the configured sizes.

• LabExistsError – Raised if this user already has a lab.

• OperationConflictError – Raised if some other operation (either spawn or delete) is already in progress on this user’s lab.

Return type:

None

async delete_lab(username)

Delete the lab environment for the given user.

This may be called multiple times for the same user, and all deletions will wait for the same underlying Kubernetes operation.

Parameters:

username (str) – Username whose environment should be deleted.

Raises:

• LabDeletionError – Raised if the lab deletion failed for any other reason.

• OperationConflictError – Raised if another operation is already in progress.

• UnknownUserError – Raised if no lab currently exists for this user.

Return type:

None

events_for_user(username)

Construct an iterator over the events for a user.

Parameters:

username (str) – Username for which to retrieve events.

Yields:

bytes – Next encoded server-sent event.

Raises:

UnknownUserError – Raised if there is no event stream for this user.

Return type:

AsyncIterator[bytes]

async get_lab_state(username)

Get lab state for a user.

This method underlies the API called by JupyterHub to track whether the user’s lab still exists. We want to update that state after Kubernetes changes faster than our reconciliation cycle, so ask Kubernetes directly for the pod phase each time we’re asked for the lab state.

Parameters:

username (str) – Username to retrieve lab state for.

Returns:

Lab state for that user, or None if that user doesn’t have a lab.

Return type:

UserLabState or None

Raises:

UnknownUserError – Raised if the given user has no lab.

async list_lab_users(*, only_running=False)

List all users with labs.

Parameters:

only_running (bool, default: False) – If set to True, only list users with running labs, not labs in other states.

Returns:

Users with labs.

Return type:

list of str

async start()

Synchronize with Kubernetes and start a background refresh task.

Examine Kubernetes for current user lab state, update our internal data structures accordingly, and then start a background refresh task that does this periodically. (Labs may be destroyed by Kubernetes node upgrades, for example.)

Return type:

None

async stop()

Stop the background refresh task.

Return type:

None