Kubernetes

包含 TorchX Kubernetes 调度器，它可用于在 Kubernetes 集群上运行 TorchX 组件。

先决条件

TorchX Kubernetes 调度器依赖于 Volcano。如果您尝试进行升级，则需要完全删除所有非 Job Volcano 资源并重新创建。

安装 Volcano

kubectl apply -f https://raw.githubusercontent.com/volcano-sh/volcano/v1.6.0/installer/volcano-development.yaml

有关更多信息，请参阅 Volcano 快速入门。

class torchx.schedulers.kubernetes_scheduler.KubernetesScheduler(session_name: str, client: Optional[ApiClient] = None, docker_client: Optional[DockerClient] = None)

基类：DockerWorkspaceMixin，Scheduler[KubernetesOpts]

KubernetesScheduler 是 TorchX 的 Kubernetes 调度接口。

重要：Kubernetes 集群上需要安装 Volcano。TorchX 需要多副本/多角色执行的集群调度，Volcano 目前是 Kubernetes 上唯一支持的调度器。有关安装说明，请参阅：https://github.com/volcano-sh/volcano

已确认它适用于 Volcano v1.3.0 和 Kubernetes 版本 v1.18-1.21。请参阅 https://github.com/pytorch/torchx/issues/120，它跟踪 Kubernetes v1.22 的 Volcano 支持情况。

注意

如果 AppDefs 的重试次数大于 0，它们可能不会显示为 Pod。这是由于 Volcano 中已知错误（根据 1.4.0 版本）：https://github.com/volcano-sh/volcano/issues/1651

$ pip install torchx[kubernetes]
$ torchx run --scheduler kubernetes --scheduler_args namespace=default,queue=test utils.echo --image alpine:latest --msg hello
kubernetes://torchx_user/1234
$ torchx status kubernetes://torchx_user/1234
...

配置选项

    usage:
        queue=QUEUE,[namespace=NAMESPACE],[service_account=SERVICE_ACCOUNT],[priority_class=PRIORITY_CLASS],[image_repo=IMAGE_REPO],[quiet=QUIET]

    required arguments:
        queue=QUEUE (str)
            Volcano queue to schedule job in

    optional arguments:
        namespace=NAMESPACE (str, default)
            Kubernetes namespace to schedule job in
        service_account=SERVICE_ACCOUNT (str, None)
            The service account name to set on the pod specs
        priority_class=PRIORITY_CLASS (str, None)
            The name of the PriorityClass to set on the job specs
        image_repo=IMAGE_REPO (str, None)
            (remote jobs) the image repository to use when pushing patched images, must have push access. Ex: example.com/your/container
        quiet=QUIET (bool, False)
            whether to suppress verbose output for image building. Defaults to ``False``.

挂载

外部文件系统/卷的挂载通过 HostPath 和 PersistentVolumeClaim 支持。

• hostPath 卷：type=bind,src=<host path>,dst=<container path>[,readonly]

• PersistentVolumeClaim：type=volume,src=<claim>,dst=<container path>[,readonly]

• 主机设备：type=device,src=/dev/foo[,dst=<container path>][,perm=rwm] 如果指定主机设备，作业将在特权模式下运行，因为 Kubernetes 不提供将 –device 传递给底层容器运行时的机制。用户应优先使用设备插件。

有关更多信息，请参阅 torchx.specs.parse_mounts()。

外部文档：https://kubernetes.ac.cn/docs/concepts/storage/persistent-volumes/

资源/分配

要选择特定机器类型，可以在资源中添加具有 node.kubernetes.io/instance-type 的功能，这将限制已启动作业到该实例类型的节点。

>>> from torchx import specs
>>> specs.Resource(
...     cpu=4,
...     memMB=16000,
...     gpu=2,
...     capabilities={
...         "node.kubernetes.io/instance-type": "<cloud instance type>",
...     },
... )
Resource(...)

Kubernetes 可能会为主机预留一些内存。TorchX 假设您正在整个主机上进行调度，因此将自动减少资源请求量，以少量减少主机预留的 CPU 和内存。如果遇到调度问题，您可能需要减少主机值的请求 CPU 和内存。

兼容性

功能	调度器支持
获取日志	✔️
分布式作业	✔️
取消作业	✔️
描述作业	部分支持。KubernetesScheduler 将返回作业和副本状态，但不会提供完整的原始 AppSpec。
工作区/修补	✔️
挂载	✔️
弹性	需要 Volcano >1.6

describe(app_id: str) → Optional[DescribeAppResponse]

描述指定的应用程序。

返回：

AppDef 描述或 None（如果应用程序不存在）。

list() → List[ListAppResponse]

对于在调度器上启动的应用程序，此 API 返回一个 ListAppResponse 对象列表，每个对象都包含应用程序 ID 及其状态。注意：此 API 处于原型阶段，可能会发生变化。

log_iter(app_id: str, role_name: str, k: int = 0, regex: Optional[str] = None, since: Optional[datetime] = None, until: Optional[datetime] = None, should_tail: bool = False, streams: Optional[Stream] = None) → Iterable[str]

返回第 k 个角色副本日志行的迭代器。当所有符合条件的日志行都被读取时，迭代器结束。

如果调度器支持基于时间的游标获取自定义时间范围内的日志行，则 since、until 字段将被遵守，否则会被忽略。不指定 since 和 until 等同于获取所有可用的日志行。如果 until 为空，则迭代器表现得像 tail -f，跟踪日志输出，直到作业进入终止状态。

构成日志的具体定义取决于调度器。一些调度器可能将 stderr 或 stdout 视为日志，而其他调度器可能从日志文件中读取日志。

行为和假设

1. 如果对不存在的应用调用，则会产生未定义的行为。调用者应该在调用此方法之前使用 exists(app_id) 检查应用是否存在。

2. 无状态，用相同的参数调用此方法两次会返回一个新的迭代器。之前的迭代进度将丢失。

3. 并不总是支持日志跟踪。并非所有调度器都支持实时日志迭代（例如，在应用运行时跟踪日志）。有关迭代器的行为，请参阅特定调度器的文档。

3.1 如果调度器支持日志跟踪，则应由

should_tail 参数控制。

4. 不保证日志保留。当调用此方法时，底层调度器可能已经清除了该应用程序的日志记录。如果是这样，此方法将引发任意异常。

5. 如果 should_tail 为 True，则该方法仅在可访问的日志行完全耗尽并且应用程序已进入最终状态时引发 StopIteration 异常。例如，如果应用程序卡住并且没有产生任何日志行，则迭代器将阻塞，直到应用程序最终被终止（通过超时或手动），此时它会引发 StopIteration。

   如果 should_tail 为 False，则该方法在没有更多日志时引发 StopIteration。

6. 并非所有调度器都需要支持。

7. 某些调度器可能通过支持 __getitem__ 来支持行游标（例如，iter[50] 会跳转到第 50 行日志）。

8. 保留空格，每行都应该包含 \n。为了

   支持交互式进度条，返回的行不需要包含 \n，但应该在没有换行符的情况下打印，以便正确处理 \r 回车符。

参数:

streams – 要选择的 IO 输出流。可以是：combined、stdout、stderr。如果调度器不支持所选流，则会引发 ValueError。

返回：

指定角色副本的日志行的 Iterator

引发:

NotImplementedError – 如果调度器不支持日志迭代

schedule(dryrun_info: AppDryRunInfo[KubernetesJob]) → str

与 submit 相同，只是它接受一个 AppDryRunInfo。鼓励实现者实现此方法，而不是直接实现 submit，因为 submit 可以通过

dryrun_info = self.submit_dryrun(app, cfg)
return schedule(dryrun_info)

class torchx.schedulers.kubernetes_scheduler.KubernetesJob(images_to_push: Dict[str, Tuple[str, str]], resource: Dict[str, object])

参考

torchx.schedulers.kubernetes_scheduler.create_scheduler(session_name: str, client: Optional[ApiClient] = None, docker_client: Optional[DockerClient] = None, **kwargs: Any) → KubernetesScheduler

torchx.schedulers.kubernetes_scheduler.app_to_resource(app: AppDef, queue: str, service_account: Optional[str], priority_class: Optional[str] = None) → Dict[str, object]

app_to_resource 使用提供的 AppDef 创建一个火山作业 Kubernetes 资源定义。该资源定义可用于在 Kubernetes 上启动应用程序。

为了支持宏，我们为每个副本生成一个任务，而不是使用火山 replicas 字段，因为宏在每个副本的基础上更改参数。

火山有两级重试：任务级别和作业级别。当使用 APPLICATION 重试策略时，作业级别的重试次数被设置为角色的 max_retries 的最小值。

torchx.schedulers.kubernetes_scheduler.pod_labels(app: AppDef, role_idx: int, role: Role, replica_id: int, app_id: str) → Dict[str, str]

torchx.schedulers.kubernetes_scheduler.role_to_pod(name: str, role: Role, service_account: Optional[str]) → V1Pod

torchx.schedulers.kubernetes_scheduler.sanitize_for_serialization(obj: object) → object