Volumes

Volume Class

class kubetorch.Volume(name: str, size: str, mount_path: str, storage_class: str | None = None, access_mode: str | None = None, namespace: str | None = None, volume_name: str | None = None)

Manages persistent storage for Kubetorch services and deployments.

__init__(name: str, size: str, mount_path: str, storage_class: str | None = None, access_mode: str | None = None, namespace: str | None = None, volume_name: str | None = None)

Kubetorch Volume object, specifying persistent storage properties.

Parameters:

• name (str) – Name of the volume/PVC.

• size (str) – Size of the volume.

• mount_path (str) – Mount path for the volume.

• storage_class (str, optional) – Storage class to use for the volume. Ignored if volume_name is specified.

• access_mode (str, optional) – Access mode for the volume.

• namespace (str, optional) – Namespace for the volume.

• volume_name (str, optional) – Name of an existing PersistentVolume (PV) to bind to. When specified, creates a PVC that binds to this specific PV instead of using dynamic provisioning via a storage class.

Example:

import kubetorch as kt

# Standard volume (ReadWriteOnce)
kt.Volume(name="my-data", size="5Gi", mount_path="/data")

# Shared volume (ReadWriteMany, requires JuiceFS or similar)
kt.Volume(
    name="shared-data",
    size="10Gi",
    mount_path="/shared",
    storage_class="juicefs-sc-shared",
    access_mode="ReadWriteMany"
)

# Bind to an existing PV
kt.Volume(
    name="team-nfs-pvc",
    size="20Gi",
    mount_path="/data",
    volume_name="team-nfs-pv",
    access_mode="ReadWriteMany"
)

# uv cache
compute = kt.Compute(
    cpus=".01",
    env_vars={
        "UV_CACHE_DIR": "/cache/uv_cache",
        "HF_HOME": "/cache/hf_cache",
    },
    volumes=[kt.Volume(name="kt-global-cache", size="10Gi", mount_path="/cache")],
)

Copied

property mount_path: str

Get the mount path for this volume

property storage_class: str

Get storage class - either specified or cluster default

classmethod from_name(name: str, namespace: str | None = None, mount_path: str | None = None) → Volume

Get existing volume by name

Parameters:

• name (str) – Name of the volume/PVC

• namespace (str, optional) – Kubernetes namespace

• mount_path (str, optional) – Override the mount path. If not provided, uses the annotation from the PVC

Returns:

Volume instance loaded from existing PVC

Return type:

Volume

config() → Dict[str, str]

Get configuration for this volume

pod_template_spec() → dict

Convert to Kubernetes volume spec for pod template

create() → Dict

Create PVC if it doesn’t exist

delete(wait: bool = True, timeout: int = 60) → None

Delete the PVC and optionally wait for deletion to complete.

Parameters:

• wait – Whether to wait for the PVC to be fully deleted (default: True)

• timeout – Maximum time to wait for deletion in seconds (default: 60)

exists() → bool

Check if the PVC exists

ssh(image: str = 'alpine:latest')

Launch an interactive debug shell with this volume mounted.

This method creates a temporary Kubernetes pod that mounts the PersistentVolumeClaim (PVC) backing this Volume at the same path (self.mount_path) used by Kubetorch services.

Parameters:

image (str, optional) – Container image to use for the debug pod. Must include a shell (e.g., alpine:3.18, ubuntu:22.04, or a custom tools image). Defaults to alpine:latest.

Example:

import kubetorch as kt

vol = kt.Volume.from_name("kt-global-cache")
vol.ssh()

Copied