dsub
Release 0.5.0
dsub是一个命令行工具，可以轻松在云中提交和运行批处理脚本。
dsub用户体验模仿了 Grid Engine 和 Slurm 等传统高性能计算作业调度程序。您编写一个脚本，然后从本地计算机上的 shell 提示符将其提交给作业调度程序。
如今， dsub支持 Google Cloud 作为后端批处理作业运行程序，以及用于开发和测试的本地提供商。在社区的帮助下，我们希望添加其他后端，例如 Grid Engine、Slurm、Amazon Batch 和 Azure Batch。
dsub是用 Python 编写的，需要 Python 3.7 或更高版本。
dsub 0.4.7。dsub 0.4.1。dsub 0.3.10。这是可选的，但无论是从 PyPI 还是从 github 安装，强烈建议您使用 Python 虚拟环境。
您可以在您选择的目录中执行此操作。
python3 -m venv dsub_libs
source dsub_libs/bin/activate
使用 Python 虚拟环境可将dsub库依赖项与系统上的其他 Python 应用程序隔离。
在运行dsub之前，在任何 shell 会话中激活此虚拟环境。要停用 shell 中的虚拟环境，请运行以下命令：
deactivate
或者，提供一组方便的脚本，用于在调用dsub 、 dstat和ddel之前激活 virutalenv 。它们位于 bin 目录中。如果您不想在 shell 中显式激活 virtualenv，则可以使用这些脚本。
虽然dsub不直接用于google-batch或google-cls-v2提供程序，但您可能希望安装 Google Cloud SDK 中的命令行工具。
如果您将使用local提供程序来加快作业开发速度，则需要安装 Google Cloud SDK，它使用gsutil来确保文件操作语义与 Google dsub提供程序一致。
安装谷歌云SDK
跑步
gcloud init
gcloud将提示您设置默认项目并向 Google Cloud SDK 授予凭据。
dsub选择以下选项之一：
如果需要，请安装 pip。
安装dsub
pip install dsub
确保你已经安装了 git
您的环境的说明可以在 git 网站上找到。
克隆这个存储库。
git clone https://github.com/DataBiosphere/dsub
cd dsub
安装 dsub （这也会安装依赖项）
python -m pip install .
设置 Bash 选项卡完成（可选）。
source bash_tab_complete
通过运行以下命令至少验证安装：
dsub --help
（可选）安装 Docker。
仅当您要创建自己的 Docker 映像或使用local提供程序时，才有必要这样做。
克隆 dsub 存储库后，您还可以通过运行以下命令来使用 Makefile：
make
这将创建一个 Python 虚拟环境并将dsub安装到名为dsub_libs的目录中。
我们认为您会发现local提供商在构建dsub任务时非常有帮助。 local提供商不会提交在云虚拟机上运行命令的请求，而是在本地计算机上运行dsub任务。
local提供商并不是为大规模运行而设计的。它旨在模拟在云虚拟机上运行，以便您可以快速迭代。您将获得更快的周转时间，并且使用它不会产生云费用。
运行dsub作业并等待完成。
这是一个非常简单的“Hello World”测试：
dsub
--provider local
--logging "${TMPDIR:-/tmp}/dsub-test/logging/"
--output OUT="${TMPDIR:-/tmp}/dsub-test/output/out.txt"
--command 'echo "Hello World" > "${OUT}"'
--wait
注意：在大多数 Unix 系统上， TMPDIR通常默认设置为/tmp ，尽管它也经常不设置。在某些版本的 MacOS 上，TMPDIR 设置为/var/folders下的位置。
注意：已知 Bash、zsh、ksh 支持上述语法${TMPDIR:-/tmp} 。 shell 将扩展TMPDIR ，但如果未设置，将使用/tmp 。
查看输出文件。
cat "${TMPDIR:-/tmp}/dsub-test/output/out.txt"
dsub目前支持 Google Cloud 的 Cloud Life Sciences v2beta API，并且正在开发对 Google Cloud 的 Batch API 的支持。
dsub通过google-cls-v2提供程序支持 v2beta API。 google-cls-v2是当前的默认提供程序。 dsub将在即将发布的版本中进行过渡，使google-batch成为默认设置。
入门步骤略有不同，如下所示：
注册一个Google帐户并创建一个项目。
启用 API：
v2beta API（提供者： google-cls-v2 ）：启用云生命科学、存储和计算 API
batch API（提供者： google-batch ）：启用批处理、存储和计算 API。
提供凭据，以便dsub可以调用 Google API：
gcloud auth application-default login
创建一个 Google Cloud Storage 存储桶。
dsub 日志和输出文件将写入存储桶。使用存储浏览器创建存储桶或运行 Cloud SDK 中包含的命令行实用程序 gsutil。
gsutil mb gs://my-bucket
将my-bucket更改为遵循存储桶命名约定的唯一名称。
（默认情况下，存储桶位于美国，但您可以使用-l选项更改或优化位置设置。）
运行一个非常简单的“Hello World” dsub作业并等待完成。
对于v2beta API（提供者： google-cls-v2 ）：
dsub
--provider google-cls-v2
--project my-cloud-project
--regions us-central1
--logging gs://my-bucket/logging/
--output OUT=gs://my-bucket/output/out.txt
--command 'echo "Hello World" > "${OUT}"'
--wait
将my-cloud-project更改为您的 Google Cloud 项目，将my-bucket更改为您在上面创建的存储桶。
对于batch API（提供者： google-batch ）：
dsub
--provider google-batch
--project my-cloud-project
--regions us-central1
--logging gs://my-bucket/logging/
--output OUT=gs://my-bucket/output/out.txt
--command 'echo "Hello World" > "${OUT}"'
--wait
将my-cloud-project更改为您的 Google Cloud 项目，将my-bucket更改为您在上面创建的存储桶。
脚本命令的输出将写入您指定的 Cloud Storage 中的OUT文件。
查看输出文件。
gsutil cat gs://my-bucket/output/out.txt
在可能的情况下， dsub尝试支持用户能够在本地开发和测试（以加快迭代速度），然后逐步进行大规模运行。
为此， dsub提供了多个“后端提供者”，每个“后端提供者”都实现了一致的运行时环境。目前的供应商有：
有关后端提供程序实现的运行时环境的更多详细信息可以在 dsub 后端提供程序中找到。
google-cls-v2和google-batch之间的差异google-cls-v2提供程序基于 Cloud Life Sciences v2beta API 构建。该 API 与其前身 Genomics v2alpha1 API 非常相似。有关差异的详细信息，请参阅迁移指南。
google-batch提供程序基于 Cloud Batch API 构建。 Cloud Life Sciences 与 Batch 的详细信息可以在本迁移指南中找到。
dsub在很大程度上隐藏了 API 之间的差异，但有一些差异需要注意：
google-batch要求作业在一个区域运行dsub的--regions和--zones标志指定任务应运行的位置。 google-cls-v2允许您指定多区域（例如US 、多个区域或跨区域的多个区域。对于google-batch提供程序，您必须指定一个区域或单个区域内的多个区域。
dsub功能以下部分展示如何运行更复杂的作业。
您可以直接在 dsub 命令行中提供 shell 命令，如上面的 hello 示例所示。
您还可以将脚本保存到文件中，例如hello.sh 。然后你可以运行：
dsub
...
--script hello.sh
如果您的脚本具有未存储在 Docker 镜像中的依赖项，您可以将它们转移到本地磁盘。请参阅下面有关使用输入和输出文件及文件夹的说明。
为了更轻松地开始， dsub使用库存 Ubuntu Docker 映像。此默认图像在未来版本中可能随时更改，因此对于可重复的生产工作流程，您应始终明确指定图像。
您可以通过传递--image标志来更改图像。
dsub
...
--image ubuntu:16.04
--script hello.sh
注意：您的--image必须包含 Bash shell 解释器。
有关使用--image标志的更多信息，请参阅脚本、命令和 Docker 中的图像部分
您可以使用--env标志将环境变量传递给脚本。
dsub
...
--env MESSAGE=hello
--command 'echo ${MESSAGE}'
当 Docker 容器运行时，环境变量MESSAGE将被分配值hello 。
您的脚本或命令可以像任何其他 Linux 环境变量一样引用该变量，如${MESSAGE} 。
请务必将命令字符串括在单引号中，而不是双引号中。如果使用双引号，该命令将在传递到 dsub 之前在本地 shell 中展开。有关使用--command标志的更多信息，请参阅脚本、命令和 Docker
要设置多个环境变量，您可以重复该标志：
--env VAR1=value1
--env VAR2=value2
您还可以使用单个标志设置多个以空格分隔的变量：
--env VAR1=value1 VAR2=value2
dsub 使用输入和输出文件及文件夹的云存储桶路径来模仿共享文件系统的行为。您指定云存储桶路径。路径可以是：
gs://my-bucket/my-filegs://my-bucket/my-foldergs://my-bucket/my-folder/*有关更多详细信息，请参阅输入和输出文档。
如果您的脚本希望读取尚未包含在 Docker 映像中的本地输入文件，则这些文件必须在 Google Cloud Storage 中可用。
如果您的脚本具有依赖文件，您可以通过以下方式使它们可供您的脚本使用：
要将文件上传到 Google Cloud Storage，您可以使用存储浏览器或 gsutil。您还可以使用公开数据或与您的服务帐户（您可以在 Google Cloud Console 中找到的电子邮件地址）共享的数据运行。
要指定输入和输出文件，请使用--input和--output标志：
dsub
...
--input INPUT_FILE_1=gs://my-bucket/my-input-file-1
--input INPUT_FILE_2=gs://my-bucket/my-input-file-2
--output OUTPUT_FILE=gs://my-bucket/my-output-file
--command 'cat "${INPUT_FILE_1}" "${INPUT_FILE_2}" > "${OUTPUT_FILE}"'
在这个例子中：
gs://my-bucket/my-input-file-1复制到数据盘上的某个路径${INPUT_FILE_1}中设置gs://my-bucket/my-input-file-2复制到数据盘上的某个路径${INPUT_FILE_2}中设置--command命令可以使用环境变量引用文件路径。
同样在这个例子中：
${OUTPUT_FILE}中设置${OUTPUT_FILE}指定的位置--command完成后，输出文件将被复制到存储桶路径gs://my-bucket/my-output-file
可以指定多个--input和--output参数，并且可以按任意顺序指定它们。
要复制文件夹而不是文件，请使用--input-recursive和output-recursive标志：
dsub
...
--input-recursive FOLDER=gs://my-bucket/my-folder
--command 'find ${FOLDER} -name "foo*"'
可以指定多个--input-recursive和--output-recursive参数，并且可以按任意顺序指定它们。
虽然显式指定输入可以改善数据来源的跟踪，但在某些情况下，您可能不希望将 Cloud Storage 中的所有输入显式本地化到作业虚拟机。
例如，如果您有：
或者
或者
那么您可能会发现通过安装只读来访问这些数据更有效或更方便：
google-cls-v2和google-batch提供程序支持这些提供对资源数据的访问的方法。
local提供程序支持以类似的方式挂载本地目录以支持本地开发。
要让google-cls-v2或google-batch提供商使用 Cloud Storage FUSE 挂载 Cloud Storage 存储桶，请使用--mount命令行标志：
--mount RESOURCES=gs://mybucket
该存储桶将以只读方式安装到运行--script或--command的 Docker 容器中，并且该位置通过环境变量${RESOURCES}提供。在脚本中，您可以使用环境变量引用安装路径。在使用 Cloud Storage FUSE 之前，请阅读 POSIX 文件系统的主要区别和语义。
要让google-cls-v2或google-batch提供程序挂载您预先创建和填充的永久磁盘，请使用--mount命令行标志和源磁盘的 url：
--mount RESOURCES="https://www.googleapis.com/compute/v1/projects/your-project/zones/your_disk_zone/disks/your-disk"
要让google-cls-v2或google-batch提供程序挂载从映像创建的永久磁盘，请使用--mount命令行标志和源映像的 url 以及磁盘的大小（以 GB 为单位）：
--mount RESOURCES="https://www.googleapis.com/compute/v1/projects/your-project/global/images/your-image 50"
该映像将用于创建新的永久性磁盘，该磁盘将附加到 Compute Engine 虚拟机。该磁盘将安装到运行--script或--command的 Docker 容器中，并且该位置由环境变量${RESOURCES}提供。在脚本中，您可以使用环境变量引用安装路径。
要创建图像，请参阅创建自定义图像。
local提供者）要让local提供程序以只读方式挂载目录，请使用--mount命令行标志和file://前缀：
--mount RESOURCES=file://path/to/my/dir
本地目录将被安装到运行--script或--command的 Docker 容器中，并且该位置通过环境变量${RESOURCES}提供。在脚本中，您可以使用环境变量引用安装的路径。
使用local提供程序运行的dsub任务将使用本地计算机上的可用资源。
使用google-cls-v2或google-batch提供程序运行的dsub任务可以利用各种 CPU、RAM、磁盘和硬件加速器（例如 GPU）选项。
有关详细信息，请参阅计算资源文档。
默认情况下， dsub生成格式为job-name--userid--timestamp job-id ，其中job-name被截断为 10 个字符， timestamp的格式为YYMMDD-HHMMSS-XX ，精确到百分之一秒。如果您同时提交多个作业，您仍然可能会遇到job-id不唯一的情况。如果您在这种情况下需要唯一的job-id ，则可以使用--unique-job-id参数。
如果设置了--unique-job-id参数，则job-id将是由 https://docs.python.org/3/library/uuid.html 创建的唯一 32 个字符 UUID。由于某些提供商要求job-id以字母开头，因此dsub将以保留唯一性的方式用字母替换任何起始数字。
上面的每个示例都演示了提交具有一组变量、输入和输出的单个任务。如果您有一批输入并且想要对它们运行相同的操作， dsub允许您创建批处理作业。
您可以创建一个包含每个任务的变量、输入和输出的制表符分隔值 (TSV) 文件，然后调用dsub一次，而不是重复调用dsub 。结果将是一个包含多个任务的job-id 。这些任务将独立计划和运行，但可以作为一个组进行监视和删除。
TSV 文件的第一行指定参数的名称和类型。例如：
--env SAMPLE_ID<tab>--input VCF_FILE<tab>--output OUTPUT_PATH
文件中的每个附加行应提供每个任务的变量、输入和输出值。标题之外的每一行代表单独任务的值。
可以指定多个--env 、 --input和--output参数，并且可以按任意顺序指定它们。例如：
--env SAMPLE<tab>--input A<tab>--input B<tab>--env REFNAME<tab>--output O
S1<tab>gs://path/A1.txt<tab>gs://path/B1.txt<tab>R1<tab>gs://path/O1.txt
S2<tab>gs://path/A2.txt<tab>gs://path/B2.txt<tab>R2<tab>gs://path/O2.txt
使用--tasks参数将 TSV 文件传递给 dsub。此参数接受文件路径和可选的要处理的任务范围。该文件可以从本地文件系统（在您调用dsub计算机上）或从 Google Cloud Storage 中的存储桶（文件名以“gs://”开头）读取。
例如，假设my-tasks.tsv包含 101 行：一行标题和 100 行用于运行任务的参数。然后：
dsub ... --tasks ./my-tasks.tsv
将创建一个包含 100 个任务的工作，同时：
dsub ... --tasks ./my-tasks.tsv 1-10
将创建一个包含 10 个任务的作业，第 2 行到第 11 行各有一个任务。
任务范围值可以采用以下任意形式：
m表示提交任务m （第m+1行）m-表示提交以任务m开头的所有任务mn表示提交从m到n （含）的所有任务。--logging标志指向dsub任务日志文件的位置。有关如何指定日志记录路径的详细信息，请参阅日志记录。
可以等待一项作业完成后再开始另一项作业。有关详细信息，请参阅使用 dsub 进行作业控制。
dsub可以自动重试失败的任务。有关详细信息，请参阅使用 dsub 重试。
您可以向作业和任务添加自定义标签，这样您就可以使用自己的标识符监控和取消任务。此外，对于 Google 提供商，标记任务将标记相关的计算资源，例如虚拟机和磁盘。
有关更多详细信息，请参阅检查状态和排除作业故障
dstat命令显示作业的状态：
dstat --provider google-cls-v2 --project my-cloud-project
如果没有其他参数， dstat 将显示当前USER正在运行的作业列表。
要显示特定作业的状态，请使用--jobs标志：
dstat --provider google-cls-v2 --project my-cloud-project --jobs job-id
对于批处理作业，输出将列出所有正在运行的任务。
dsub 提交的每个作业都会被赋予一组可用于作业识别和作业控制的元数据值。与每个作业相关的元数据包括：
job-name ：默认为脚本文件的名称或脚本命令的第一个单词；可以使用--name参数显式设置。user-id ： USER环境变量值。job-id ：作业的标识符，可在调用dstat和ddel时使用，分别用于作业监控和取消。有关job-id格式的更多详细信息，请参阅作业标识符。task-id ：如果使用--tasks参数提交作业，则每个任务都会获得“task- n ”形式的顺序值，其中n是从 1 开始的。请注意，作业元数据值将被修改，以符合检查状态和故障排除作业指南中列出的“标签限制”。
元数据可用于取消作业或批处理作业中的单个任务。
有关更多详细信息，请参阅检查状态和排除作业故障
默认情况下，dstat 每个任务输出一行。如果您使用包含许多任务的批处理作业，那么您可能会受益于--summary 。
$ dstat --provider google-cls-v2 --project my-project --status '*' --summary
Job Name Status Task Count
------------- ------------- -------------
my-job-name RUNNING 2
my-job-name SUCCESS 1
在此模式下，dstat 每对（作业名称、任务状态）打印一行。您可以一目了然地看到有多少任务已完成，有多少任务仍在运行，有多少任务失败/取消。
ddel命令将删除正在运行的作业。
默认情况下，只会删除当前用户提交的作业。使用--users标志指定其他用户，或使用'*'指定所有用户。
删除正在运行的作业：
ddel --provider google-cls-v2 --project my-cloud-project --jobs job-id
如果作业是批处理作业，则所有正在运行的任务将被删除。
删除特定任务：
ddel
--provider google-cls-v2
--project my-cloud-project
--jobs job-id
--tasks task-id1 task-id2
要删除当前用户的所有正在运行的作业：
ddel --provider google-cls-v2 --project my-cloud-project --jobs '*'
当您使用google-cls-v2或google-batch提供程序运行dsub命令时，需要考虑两组不同的凭据：
pipelines.run()请求以在虚拟机上运行命令/脚本的帐户用于提交pipelines.run()请求的帐户通常是您的最终用户凭据。您可以通过运行以下命令来设置它：
gcloud auth application-default login
VM 上使用的帐户是服务帐户。下图说明了这一点：
默认情况下， dsub将使用默认的 Compute Engine 服务帐户作为虚拟机实例上的授权服务帐户。您可以选择使用--service-account指定另一个服务帐户的电子邮件地址。
默认情况下， dsub将向服务帐户授予以下访问范围：
此外，API 始终会添加此范围：
您可以选择使用--scopes指定范围。
虽然使用默认服务帐户很简单，但该帐户还具有默认授予的广泛权限。遵循最小权限原则，您可能希望创建和使用仅授予运行dsub命令/脚本所需的足够权限的服务帐户。
要创建新的服务帐户，请按照以下步骤操作：
执行gcloud iam service-accounts create命令。服务帐户的电子邮件地址将为[email protected] 。
gcloud iam service-accounts create "sa-name"
向服务账户授予对存储桶等的 IAM 访问权限。
gsutil iam ch serviceAccount:[email protected]:roles/storage.objectAdmin gs://bucket-name
更新您的dsub命令以包含--service-account
dsub
--service-account [email protected]
...
请参阅示例：
查看更多文档：
