Kubernetes

这包含 TorchX 的 Kubernetes 调度程序，可以用于在 Kubernetes 集群上运行 TorchX 组件。

预备知识

TorchX 的 Kubernetes 调度器依赖于 volcano 并且需要安装 etcd 以支持分布式任务执行。

安装 volcano 1.4.0 版本

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

TorchX 使用 torch.distributed.run 运行分布式训练。 这需要在您的 Kubernetes 集群上安装 etcd 服务：

kubectl apply -f https://github.com/pytorch/torchx/blob/main/resources/etcd.yaml

了解有关运行分布式训练器的更多信息 torchx.components.dist

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

Bases: torchx.schedulers.api.Scheduler, torchx.workspace.docker_workspace.DockerWorkspace

KubernetesScheduler 是一个用于 Kubernetes 的 TorchX 调度接口。

重要：需要在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，该链接正在跟踪Volcano对Kubernetes v1.22的支持。

注意

重试次数大于0的AppDefs在失败后可能不会显示为pods。 这是由于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],[image_repo=IMAGE_REPO],[service_account=SERVICE_ACCOUNT]

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

    optional arguments:
        namespace=NAMESPACE (str, default)
            Kubernetes namespace to schedule job in
        image_repo=IMAGE_REPO (str, None)
            The image repository to use when pushing patched images, must have push access. Ex: example.com/your/container
        service_account=SERVICE_ACCOUNT (str, None)
            The service account name to set on the pod specs

挂载

通过主机路径和支持持久卷声明挂载外部文件系统/卷。

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

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

参见 torchx.specs.parse_mounts() 以获取更多信息。

外部文档： https://kubernetes.io/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。
工作区 / 补丁修复	✔️
挂载	✔️

describe(app_id: str) → Optional[torchx.schedulers.api.DescribeAppResponse]

描述指定的应用程序。

Returns

应用程序定义描述或 None 如果应用程序不存在。

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

返回一个迭代器，用于获取满足条件的日志行。k``th replica of the ``role。 迭代器在所有符合条件的日志行都被读取后结束。

如果调度程序支持基于时间指针获取日志行，则since，until字段会被遵循，否则会被忽略。不指定since和until相当于获取所有可用的日志行。如果until为空，则迭代器的行为就像tail -f一样，跟随日志输出直到作业达到终端状态。

日志的确切定义取决于调度程序的具体设置。有些调度程序可能会将标准错误或标准输出视为日志，而其他调度程序则可能从日志文件中读取日志。

行为和假设：

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

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

3. 不一定始终支持日志追尾功能。并非所有调度器都支持实时日志迭代（例如，在应用程序运行时追尾日志）。有关迭代器的行为，请参阅特定调度器的文档。

3.1 If the scheduler supports log-tailing, it should be controlled

by``should_tail``参数。

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

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

   如果 should_tail 是 False，该方法在没有更多日志时抛出 StopIteration。

6. 不一定由所有调度器支持。

7. 某些调度器可能通过支持 __getitem__ （例如，iter[50] 寻找第 50 行日志）来支持行光标。

8. Whitespace is preserved, each new line should include \n. To

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

Parameters

流 – 要选择的IO输出流。 选项之一：combined、stdout、stderr。 如果所选流不被调度程序支持，它将抛出一个ValueError异常。

Returns

一个指定角色副本的日志行上的 Iterator

Raises

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

run_opts() → torchx.specs.api.runopts

返回调度程序所期望的运行配置选项。 基本上是--help的run API。

schedule(dryrun_info: torchx.specs.api.AppDryRunInfo[torchx.schedulers.kubernetes_scheduler.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, **kwargs: Any) → torchx.schedulers.kubernetes_scheduler.KubernetesScheduler

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

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

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

Volcano 有两个级别的重试：一个是任务级别，另一个是作业级别。当使用 APPLICATION 重试策略时，作业级别的重试次数被设置为角色的最大重试次数中的最小值。

torchx.schedulers.kubernetes_scheduler.cleanup_str(data: str) → str

调用 lower 在这些字符串上，并移除所有不满足 [a-z0-9] 模式的字符。 此方法主要用于确保 Kubernetes 调度器获得不会违反其验证的作业名称。

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

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

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