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提供者一致。
安裝Google雲端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]
...
請參閱範例：
查看更多文件：
