DOCSEARCHbyAlgolia
Submit Docs

KubeSpawner

repository·main·Indexed 20 days ago

https://github.com/jupyterhub/kubespawner

A JupyterHub spawner that manages and scales single-user notebook servers as pods within a Kubernetes cluster. It provides features for elastic scaling, resource control (CPU/RAM), persistent storage via Kubernetes Persistent Volumes, and multi-tenancy using namespaces. KubeSpawner supports internal SSL for mutual TLS communication and utilizes a flexible string templating system for dynamic pod and resource naming. Requires JupyterHub 4.0+ and Kubernetes v1.24+.

Tokens
5.5K
Snippets
8
Records
18
Agent score
69%

What's inside kubespawner

  1. What is KubeSpawner?

    main
    KubeSpawner (also known as the JupyterHub Kubernetes Spawner) is a spawner for JupyterHub that enables the spawning of single-user notebook servers on a Kubernetes cluster. It is designed for scaling JupyterHub deployments, particularly for environments with more than ~50 simultaneous users, by leveraging Kubernetes' automation, scaling, and resource management capabilities.

  2. Use KubeSpawner to spawn JupyterHub single-user servers on Kubernetes

    main
    KubeSpawner is a JupyterHub spawner that allows you to spawn single-user JupyterHub servers as pods in a Kubernetes cluster. It is designed to integrate JupyterHub with Kubernetes, providing features like resource limits, environment variable injection, and pod configuration via JupyterHub's configuration system.

  3. Key features of KubeSpawner and Kubernetes integration

    main

    KubeSpawner leverages Kubernetes to provide several advanced capabilities for JupyterHub users:

    • Elastic Scaling: Run between 2 and thousands of nodes by adding or removing nodes as required.
    • Hub Deployment: Run JupyterHub itself inside Kubernetes for integrated monitoring and failover.
    • Multi-tenancy via Namespaces: Spawn multiple hubs in the same cluster using Kubernetes namespaces to limit resource usage per hub.
    • Resource Control: Provide strict guarantees and limits on CPU and RAM for single-user notebooks.
    • Persistent Storage: Mount various types of Kubernetes Persistent Volumes onto single-user notebook containers.
    • Security Control: Manage security parameters (such as userid/groupid and SELinux) via Pod Security Policies.

  4. Rules of the 'safe' slug scheme

    main

    The safe scheme is designed to produce valid Kubernetes labels and object names. It follows these rules:

    • Character Set: Only lowercase ASCII letters, numbers, and - are allowed.
    • Start/End: The result must always start and end with a letter or number.
    • Length: The length of any single template field is limited to 48 characters (the total string length is not enforced).
    • Escaping Mechanism: If a name is already 'safe', it is used unmodified. If escaping is required, a truncated safe subset of characters is used, followed by ---{hash} (where {hash} is a checksum of the original input).
    • Hyphens: A single - is allowed, but sequences of more than one consecutive - are only permitted when inserted by the escaping mechanism.
    • Fallback: If no safe characters are present in the input, x is used for the 'safe' subset.

  5. How string templates work in KubeSpawner

    main

    KubeSpawner allows several fields to be resolved as string templates, enabling each user server to receive distinct values from a single configuration.

    Templates use the Python f-string convention: f"{fieldname}". For example, the default pod_name_template of "jupyter-{user_server}" will resolve to unique strings based on the user and server name.

    Example resolutions:

    usernameserver namepod name
    user''jupyter-user
    userserverjupyter-user--server
    user@email.comSome Namejupyter-user-email-com--some-name---0c1fe94b
    pod_name_template = "jupyter-{user_server}"

  6. Key features of Kubespawner

    main

    Kubespawner provides several capabilities for managing JupyterHub workloads on Kubernetes:

    • Elastic Scaling: Run anywhere from a few nodes to thousands of nodes by adding or removing nodes in the cluster.
    • Hub Deployment: Run JupyterHub itself inside Kubernetes for integrated monitoring, failover, and simplified management without external configuration scripts.
    • Multi-tenancy via Namespaces: Spawn multiple hubs in the same cluster using Kubernetes namespaces to isolate resources and limit usage per organization.
    • Resource Control: Set guarantees and limits on CPU and RAM for single-user notebooks using Kubernetes resource control mechanisms.
    • Persistent Storage: Mount various types of Kubernetes Persistent Volumes onto single-user notebook containers.
    • Security Control: Manage security parameters like userid/groupid and SELinux via Pod Security Policies.
    • Cloud Agnostic: Run on any cloud provider or on-premises hardware, supporting multi-cloud federation.
    • SSL Support: Includes support for internal SSL configuration.

  7. Enable Internal SSL for mutual TLS communication

    main

    JupyterHub 1.0+ supports internal_ssl for encrypting and authenticating all internal communication via mutual TLS. When enabled, KubeSpawner automatically mounts the necessary internal SSL certificates as Kubernetes secrets into the user's pod.

    To enable this feature, set c.JupyterHub.internal_ssl = True in your JupyterHub configuration.

    c.JupyterHub.internal_ssl = True
c.JupyterHub.spawner_class = 'kubespawner.KubeSpawner'

  8. Requirements for using KubeSpawner

    main

    To use KubeSpawner, ensure your environment meets the following version requirements:

    JupyterHub

    • Requires JupyterHub 4.0+

    Kubernetes

    • Requires Kubernetes v1.24+
    • The Kube DNS addon is not strictly required as the spawner uses environment variable-based discovery.
    • Your Kubernetes cluster must be configured to support the specific types of persistent volumes you intend to use.

  9. Best practices for choosing template fields

    main

    When selecting fields for your template strings, follow these guidelines:

    • Use {user_server} when the string must be unique per server (e.g., pod_name_template).
    • Use {username} when the string should be unique per user but shared across all of that user's named servers (e.g., some PVC configurations).
    • Use the {escaped_} prefix if you are upgrading a deployment from a version older than KubeSpawner 7 and need to maintain existing resource names.
    • Use {pod_name} as a reusable reference when creating other resources associated with a specific pod to avoid redundancy.

  10. Manage PVC name persistence when changing templates

    main

    Changing properties like pvc_name or working_dir can disconnect a user's server from their existing data.

    KubeSpawner has a special mechanism for the default pvc_name to prevent accidental data loss. If KubeSpawner.remember_pvc_name is set to True (the default), once a server has started, its PVC name cannot be changed via configuration; any future launches will use the previous pvc_name even if the configuration is updated.

    To allow changing the names of mounted PVCs via configuration, set remember_pvc_name to False.

    Note: This special handling only applies to the default pvc_name. If you have defined custom volumes, you must manage changes to those names manually.

    c.KubeSpawner.remember_pvc_name = False

  11. Upgrade slug schemes in KubeSpawner 7

    main

    KubeSpawner 7 introduced a new safe slug scheme to ensure that templated fields produce valid Kubernetes object names and labels. The previous escape scheme (default in version 6) ensured uniqueness but could produce invalid labels (e.g., starting with capital letters or exceeding length limits).

    Slug Schemes

    • safe: The default in KubeSpawner 7. Guarantees valid lowercase ASCII, numbers, and -, ensures the string starts/ends with a letter or number, and enforces a 48-character limit per field.
    • escape: The legacy scheme used prior to version 7. Use this if you need to maintain exact compatibility with KubeSpawner 6 behavior.

    Migration Strategy

    If you have existing infrastructure (like NFS mounts or PVCs) that relies on specific naming patterns generated by the old scheme, you can use specific template fields to maintain compatibility:

    • Use {escaped_username} to match the behavior of {username} in KubeSpawner 6.
    • Use {escaped_user_server} to match the behavior of {username}--{servername} in KubeSpawner 6.
    # Use the new default (KubeSpawner 7+)
c.KubeSpawner.slug_scheme = "safe"

# Revert to legacy behavior (KubeSpawner 6 style)
c.KubeSpawner.slug_scheme = "escape"

# Maintain legacy volume mount paths during upgrade
c.KubeSpawner.volume_mounts = {
    "name": "home",
    "mountPath": "/home/jovyan",
    "subPath": "{escaped_username}",  # matches "{username}" in kubespawner 6
}

  12. Kubespawner requirements

    main

    To use Kubespawner, ensure your environment meets the following requirements:

    • Kubernetes Version: Kubernetes v1.6 or newer.
    • Service Discovery: The spawner uses environment variable-based discovery, so the Kube DNS addon is not strictly required.
    • Storage Configuration: Your Kubernetes cluster must be configured to support the specific types of Persistent Volumes you intend to mount to the notebook containers.