LabState¶
- pydantic model controller.models.v1.lab.LabState¶
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": "LabState", "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": { "user": { "$ref": "#/$defs/UserInfo", "description": "Metadata for the user who owns the lab", "title": "Owner" }, "options": { "$ref": "#/$defs/LabOptions", "description": "Options for the lab, specified when it was requested", "title": "Lab options" }, "status": { "$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": { "$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": { "LabOptions": { "description": "Options for the lab, specified at creation time.\n\nThis model represents the configuration information about a running lab\nreturned by a JSON API query. It shares many attributes in common with the\ninput model, `LabRequestOptions`, but reduces the requested image to a\nDocker image reference and doesn't support the complex validation required\nby `LabRequestOptions`.", "properties": { "size": { "$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" }, "image": { "description": "Docker reference to image used by the lab", "examples": [ "lighthouse.ceres/library/sketchbook:w_2023_07@sha256:abcd" ], "title": "Lab image", "type": "string" } }, "required": [ "size", "image" ], "title": "LabOptions", "type": "object" }, "LabResources": { "description": "Resource requests and limits for a lab.", "properties": { "limits": { "$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": { "$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": { "description": "32-bit unsigned integer", "examples": [ 2023 ], "title": "Numeric GID of the group (POSIX)", "type": "integer" } }, "required": [ "name", "id" ], "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" } }, "required": [ "user", "options", "status", "resources" ] }
- Fields:
- field internal_url: Annotated[str | None, Field(title="URL for user's lab", 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'])] = 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: Annotated[LabOptions, Field(title='Lab options', description='Options for the lab, specified when it was requested')] [Required]¶
Options for the lab, specified when it was requested
-
field quota: Annotated[ResourceQuantity | None, Field(title='Quota for all user resources', description='Namespace quota for the user. Unlike
resources, these limits are applied to the entire namespace, including worker pods spawned by the user.')] = 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: Annotated[LabResources, Field(title='Lab resource limits and requests', description='Resource limits and requests for the lab pod')] [Required]¶
Resource limits and requests for the lab pod
-
field status: Annotated[LabStatus, Field(title='Status of user lab', 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
failedstate for a variety of reasons regardless of the pod phase, and completed pods are shown asterminated.", examples=[LabStatus.RUNNING])] [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
failedstate for a variety of reasons regardless of the pod phase, and completed pods are shown asterminated.
- field user: Annotated[UserInfo, Field(title='Owner', description='Metadata for the user who owns the lab')] [Required]¶
Metadata for the user who owns the lab
- classmethod from_request(*, user, spec, image, resources)¶
Create state for a new lab that is about to be spawned.
- Parameters:
user (
GafaelfawrUserInfo) – Owner of the lab.spec (
LabSpecification) – Lab specification from the request.image (
RSPImage) – Resolved image that the lab will run.resources (
LabResources) – Resource limits and requests for the lab.
- Returns:
New user lab state representing a lab that’s about to be spawned.
- Return type: