UserLabState#
- pydantic model controller.models.v1.lab.UserLabState#
Current state of the user’s lab.
This model is returned by the
/spawner/v1/labs/usernameand/spawner/v1/user-statusroutes.- Parameters:
data (
Any) –
Show JSON schema
{ "title": "UserLabState", "description": "Current state of the user's lab.\n\nThis model is returned by the :samp:`/spawner/v1/labs/{username}` and\n``/spawner/v1/user-status`` routes.", "type": "object", "properties": { "options": { "allOf": [ { "$ref": "#/$defs/UserOptions" } ], "description": "Represents the choices made on the spawner form", "title": "User-chosen lab options" }, "env": { "additionalProperties": { "type": "string" }, "description": "Environment variables from JupyterHub. The variable `JUPYTERHUB_SERVICE_PREFIX` must be set.", "title": "Environment variables", "type": "object" }, "user": { "allOf": [ { "$ref": "#/$defs/UserInfo" } ], "description": "Metadata for the user who owns the lab", "title": "Owner" }, "status": { "allOf": [ { "$ref": "#/$defs/LabStatus" } ], "description": "Current status of the user's lab. This is primarily based on the Kubernetes pod phase, but does not have a one-to-one correspondence. Labs may be in `failed` state for a variety of reasons regardless of the pod phase, and completed pods are shown as `terminated`.", "examples": [ "running" ], "title": "Status of user lab" }, "internal_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "URL used by JupyterHub and its proxy to access the user's lab. This is a cluster-internal URL that will not be meaningful outside of the cluster.", "examples": [ "http://nublado-ribbon.nb-ribbon:8888" ], "title": "URL for user's lab" }, "resources": { "allOf": [ { "$ref": "#/$defs/LabResources" } ], "description": "Resource limits and requests for the lab pod", "title": "Lab resource limits and requests" }, "quota": { "anyOf": [ { "$ref": "#/$defs/ResourceQuantity" }, { "type": "null" } ], "default": null, "description": "Namespace quota for the user. Unlike `resources`, these limits are applied to the entire namespace, including worker pods spawned by the user.", "title": "Quota for all user resources" } }, "$defs": { "ImageClass": { "description": "Supported classes of images.\n\nThese keywords can be passed into the spawn form to spawn whatever image\nmatches this class, as determined by the lab controller. This is primarily\nused when spawning notebooks for bot users.", "enum": [ "recommended", "latest-release", "latest-weekly", "latest-daily" ], "title": "ImageClass", "type": "string" }, "LabResources": { "description": "Resource requests and limits for a lab.", "properties": { "limits": { "allOf": [ { "$ref": "#/$defs/ResourceQuantity" } ], "description": "If the user's pod exceeds this CPU limit, it will be throttled. If it exceeds this memory limit, it will usually be killed with an out-of-memory error.", "title": "Maximum allowed resources" }, "requests": { "allOf": [ { "$ref": "#/$defs/ResourceQuantity" } ], "description": "Guaranteed minimum resources available to the user's lab. If these resources are not available, the cluster will autoscale or the lab spawn will fail.", "title": "Minimum requested resources" } }, "required": [ "limits", "requests" ], "title": "LabResources", "type": "object" }, "LabSize": { "description": "Allowable names for pod sizes.\n\nTaken from `d20 creature sizes`_.", "enum": [ "fine", "diminutive", "tiny", "small", "medium", "large", "huge", "gargantuan", "colossal", "custom" ], "title": "LabSize", "type": "string" }, "LabStatus": { "description": "Possible states the user's lab may be in.\n\nThis is not directly equivalent to pod phases. It is instead intended to\ncapture the status of the lab from an infrastructure standpoint,\nreflecting the current intent of the controller. Most notably, labs that\nhave stopped running for any reason (failure or success) use the\nterminated status. The failed status is reserved for failed Kubernetes\noperations or missing or invalid Kubernetes objects.", "enum": [ "pending", "running", "terminating", "terminated", "failed" ], "title": "LabStatus", "type": "string" }, "ResourceQuantity": { "description": "A Kubernetes resource request or limit.", "properties": { "cpu": { "description": "Number of CPU cores", "examples": [ 1.5 ], "title": "CPU", "type": "number" }, "memory": { "description": "Amount of memory in bytes. Also accepts strings with SI suffixes, which will be converted to bytes. Be sure to use the suffix with `i` to indicate powers of two (1024 rather than 1000) if that is desired.", "examples": [ 1073741824, "1Gi" ], "title": "Memory", "type": "integer" } }, "required": [ "cpu", "memory" ], "title": "ResourceQuantity", "type": "object" }, "UserGroup": { "description": "Gafaelfawr's representation of a single group.", "properties": { "name": { "description": "Should follow Unix naming conventions", "examples": [ "ferrymen" ], "pattern": "^[a-zA-Z][a-zA-Z0-9._-]*$", "title": "Group to which lab user belongs", "type": "string" }, "id": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "description": "32-bit unsigned integer", "examples": [ 2023 ], "title": "Numeric GID of the group (POSIX)" } }, "required": [ "name" ], "title": "UserGroup", "type": "object" }, "UserInfo": { "description": "Metadata about the user who owns the lab.", "properties": { "username": { "description": "Username of the owner of this lab", "examples": [ "ribbon" ], "pattern": "^[a-z0-9](?:[a-z0-9]|-[a-z0-9])*[a-z](?:[a-z0-9]|-[a-z0-9])*$", "title": "Username", "type": "string" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Preferred human-readable name for the user. May contain spaces, capital letters, and non-ASCII Unicode characters. Should be the user's preferred representation of their name to other humans.", "examples": [ "Ribbon" ], "title": "Display name for user" }, "uid": { "description": "POSIX numeric UID for the user as a 32-bit unsigned integer", "examples": [ 1104 ], "title": "Numeric UID", "type": "integer" }, "gid": { "description": "POSIX numeric GID for user's primary group as a 32-bit unsigned integer", "examples": [ 1104 ], "title": "Numeric GID of primary group", "type": "integer" }, "groups": { "default": [], "description": "All POSIX group memberships of the user with associated GIDs, used to set the user's supplemental groups", "items": { "$ref": "#/$defs/UserGroup" }, "title": "User's group memberships", "type": "array" } }, "required": [ "username", "uid", "gid" ], "title": "UserInfo", "type": "object" }, "UserOptions": { "description": "User-provided lab configuration options.\n\nThis model represents the form submission to the spawner HTML form\npresented to the user by JupyterHub.\n\nAll values to this model can instead be given as lists of length one, with\nboolean values converted to the strings ``true`` or ``false``. This is the\nform in which the values are received by the JupyterHub spawner form\nprocessing code, and allows JupyterHub to pass its form submission\ndirectly to the lab controller without modifications.", "properties": { "image_list": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Selected image from the radio button part of the image menu, or the special value `use_image_from_dropdown`. If this is set, to a value other than `use_image_from_dropdown`, `image_dropdown` should not be set.", "examples": [ "lighthouse.ceres/library/sketchbook:w_2023_07@sha256:abcd" ], "title": "Image from selection radio button" }, "image_dropdown": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Selected image from the dropdown part of the image menu. If this is set, `image_list` should be omitted or set to `use_image_from_dropdown`.", "examples": [ "lighthouse.ceres/library/sketchbook:w_2022_40" ], "title": "Image from dropdown list" }, "image_class": { "anyOf": [ { "$ref": "#/$defs/ImageClass" }, { "type": "null" } ], "default": null, "description": "Spawn a class of image determined by the lab controller. Not used by the user form, but may be used by bots creating labs. Only one of `image_class` or `image_tag` may be given, and neither `image_list` nor `image_dropdown` should be set when using these options.", "examples": [ "recommended" ], "title": "Class of image to spawn" }, "image_tag": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Spawn the image with the given tag. Not used by the user form, but may be used by bots creating labs. Only one of `image_class` `image_tag` may be given, and neither `image_list` nor `image_dropdown` should be set when using these options.", "examples": [ "w_2023_07" ], "title": "Tag of image to spawn" }, "size": { "allOf": [ { "$ref": "#/$defs/LabSize" } ], "description": "Size of image, chosen from sizes specified in the controller configuration", "examples": [ "medium" ], "title": "Image size" }, "enable_debug": { "default": false, "description": "If true, set the `DEBUG` environment variable when spawning the lab, which enables additional debug logging", "examples": [ true ], "title": "Enable debugging in spawned Lab", "type": "boolean" }, "reset_user_env": { "default": false, "description": "If true, set the `RESET_USER_ENV` environment variable when spawning the lab, which tells the lab to move aside the user environment directories (`.cache`, `.conda`, `.jupyter`, `.local`) and files (`.user_setups`) . This can be used to recover from user configuration errors that break lab startup.", "examples": [ true ], "title": "Move aside user environment", "type": "boolean" } }, "required": [ "size" ], "title": "UserOptions", "type": "object" } }, "required": [ "options", "env", "user", "status", "resources" ] }
- Fields:
- Validators:
_validate_env»env
- field env: dict[str, str] [Required]#
Environment variables from JupyterHub. The variable JUPYTERHUB_SERVICE_PREFIX must be set.
- Validated by:
_validate_env
- field internal_url: str | None = None#
URL used by JupyterHub and its proxy to access the user’s lab. This is a cluster-internal URL that will not be meaningful outside of the cluster.
- field options: UserOptions [Required]#
Represents the choices made on the spawner form
- field quota: ResourceQuantity | None = None#
Namespace quota for the user. Unlike resources, these limits are applied to the entire namespace, including worker pods spawned by the user.
- field resources: LabResources [Required]#
Resource limits and requests for the lab pod
- field status: LabStatus [Required]#
Current status of the user’s lab. This is primarily based on the Kubernetes pod phase, but does not have a one-to-one correspondence. Labs may be in failed state for a variety of reasons regardless of the pod phase, and completed pods are shown as terminated.
- field user: UserInfo [Required]#
Metadata for the user who owns the lab
- classmethod from_request(user, lab, resources)#
Create state for a new lab that is about to be spawned.
- Parameters:
user (
GafaelfawrUserInfo) – Owner of the lab.lab (
LabSpecification) – Lab specification from JupyterHub.resources (
LabResources) – Resource limits and requests for the lab (normally derived from the lab size).
- Returns:
New user lab state representing a lab that’s about to be spawned.
- Return type: