LabStorage

class controller.storage.kubernetes.lab.LabStorage(api_client, logger)

Bases: object

Kubernetes storage layer for user labs.

Parameters:

  • api_client (ApiClient) – Kubernetes API client.

  • logger (BoundLogger) – Logger to use.

Notes

This class isn’t strictly necessary; instead, the lab service could call the storage layers for individual Kubernetes objects directly. But there are enough different objects in play that adding a thin layer to wrangle the storage objects makes the lab service easier to follow.

Methods Summary

create(objects, timeout)

Create all of the Kubernetes objects for a user's lab.

delete_namespace(name, timeout)

Delete a namespace, waiting for deletion to finish.

delete_pod(names, timeout)

Delete a pod from Kubernetes with a grace period.

list_namespaces(prefix, timeout)

List all namespaces starting with the given prefix.

read_lab_objects(names, timeout)

Read the lab objects required to reconstruct state.

read_pod_phase(names, timeout)

Get the phase of a running user lab pod.

read_secret(name, namespace, timeout)

Read a secret from Kubernetes, failing if it doesn't exist.

wait_for_pod_start(name, namespace, timeout)

Wait for a pod to finish starting.

watch_pod_events(name, namespace, timeout)

Monitor the startup of a pod.

Methods Documentation

async create(objects, timeout)

Create all of the Kubernetes objects for a user’s lab.

Parameters:

  • objects (LabObjects) – Kubernetes objects making up the user’s lab.

  • timeout (Timeout) – Timeout on full operation.

Raises:

KubernetesError – Raised if there is some failure in a Kubernetes API call.

Return type:

None

async delete_namespace(name, timeout)

Delete a namespace, waiting for deletion to finish.

Parameters:

  • name (str) – Name of the namespace.

  • timeout (Timeout) – Timeout on operation.

Raises:

  • KubernetesError – Raised if there is some failure in a Kubernetes API call.

  • TimeoutError – Raised if the namespace deletion took longer than the Kubernetes delete timeout.

Return type:

None

async delete_pod(names, timeout)

Delete a pod from Kubernetes with a grace period.

Parameters:
Raises:

KubernetesError – Raised if there is some failure in a Kubernetes API call.

Return type:

None

async list_namespaces(prefix, timeout)

List all namespaces starting with the given prefix.

Used to discover all namespaces for running user labs when doing state reconciliation.

Parameters:

  • prefix (str) – String prefix of namespaces to return.

  • timeout (Timeout) – Timeout on operation.

Returns:

List of namespace names.

Return type:

list of str

Raises:

KubernetesError – Raised if there is some failure in a Kubernetes API call.

async read_lab_objects(names, timeout)

Read the lab objects required to reconstruct state.

Used during reconciliation to rebuild the internal mental model of the current state of a user’s lab.

Parameters:
Returns:

Lab objects required to reconstruct state, or None if any of the required objects were missing.

Return type:

LabStateObjects or None

Raises:

KubernetesError – Raised if there is some failure in a Kubernetes API call.

async read_pod_phase(names, timeout)

Get the phase of a running user lab pod.

Called whenever JupyterHub wants to check the status of running pods, so this will be called frequently and should be fairly quick.

Parameters:
Returns:

Phase of the pod or None if the pod does not exist.

Return type:

PodPhase or None

Raises:

KubernetesError – Raised if there is some failure in a Kubernetes API call.

async read_secret(name, namespace, timeout)

Read a secret from Kubernetes, failing if it doesn’t exist.

Parameters:

  • name (str) – Name of the secret.

  • namespace (str) – Namespace of the secret.

  • timeout (Timeout) – Timeout on operation.

Returns:

Secret object.

Return type:

kubernetes_asyncio.client.models.V1Secret

Raises:
async wait_for_pod_start(name, namespace, timeout)

Wait for a pod to finish starting.

Waits for the pod to reach a phase other than pending or unknown, and returns the new phase. We treat unknown like pending since we’re running with a timeout anyway, and will eventually time out if we can’t get back access to the node where the pod is running.

Parameters:

  • name (str) – Name of the lab pod.

  • namespace (str) – Namespace of the lab pod.

  • timeout (Timeout) – Timeout to wait for the pod to start.

Returns:

New pod phase, or None if the pod has disappeared.

Return type:

PodPhase

Raises:

KubernetesError – Raised if there is some failure in a Kubernetes API call.

async watch_pod_events(name, namespace, timeout)

Monitor the startup of a pod.

Watches for events involving a pod, yielding them. Must be cancelled by the caller when the watch is no longer of interest.

Parameters:

  • name (str) – Name of the lab pod.

  • namespace (str) – Namespace of the lab pod.

  • timeout (Timeout) – How long to watch pod startup events.

Yields:

str – The next observed event.

Raises:
Return type:

AsyncIterator[str]