broadinstitute/dsp-toolbox

dsp-toolbox

镜像概述和主要用途

dsp-toolbox是一个面向DevOps的脚本工具箱，主要用于生成部署所需的元数据文件、管理FiaB（Firecloud in a Box）主机生命周期（创建、停止、重启、销毁等）以及处理GitHub子模块依赖关系。该工具支持GCE（Google Compute Engine）环境部署，并针对Firecloud项目提供特定的部署流程。

核心功能和特性

• 部署元数据生成：生成*.properties文件，供Jenkins作业或其他脚本执行部署使用
• FiaB主机管理：支持FiaB主机的创建、停止、重启、重置、销毁和列表查询
• GitHub子模块操作：列出指定分支的所有子模块依赖，更新Firecloud服务的子模块哈希
• 环境适配：支持"kdux"和"firecloud"项目，可配置用于其他团队；兼容GCE环境及Firecloud特定部署流程

使用场景和适用范围

• DevOps团队生成部署元数据，辅助自动化部署流程
• 开发和测试环境中管理FiaB主机生命周期
• GitHub项目中子模块依赖的批量查询和更新
• Firecloud项目的特定环境（dev、alpha、staging、prod）部署管理

详细使用方法和配置说明

构建容器

bash
docker build . 

部署功能（Deploys）

部署脚本不会实际执行部署，而是生成元数据*.properties文件，供后续部署流程使用。

配置参数

示例标签文件

json
{ 
  "ENV": "dev",
  "VERSION": "v1"
}

使用示例

bash
docker run --rm -v $PWD:/app \
    -e OUTPUT_DIR=/app/properties \
    -e ENVIRONMENT=$ENVIRONMENT \
    -e GOOGLE_PROJ=$GOOGLE_PROJ \
    -e SERVICE_ACCT=/app/$SERVICE_ACCT \
    -e TAGS=$TAGS \
    -e NOT_TAGS=$NOT_TAGS \
    broadinstitute/dsp-toolbox deploy $PROJECT $SERVICE

上述命令将在OUTPUT_DIR目录中为GOOGLE_PROJ中所有标记有SERVICE、ENVIRONMENT及指定TAGS的主机生成属性文件。

Firecloud部署

Firecloud通过环境分支（dev、alpha、staging、prod）检测服务变更并仅部署变更内容。可仅指定环境（不指定服务）运行部署：

bash
docker run --rm -v $FC_DEVELOP:/app \
    -e OUTPUT_DIR=/app/properties \
    -e ENV=$ENV \
    -e GOOGLE_PROJ=$GOOGLE_PROJ \
    -e SERVICE_ACCT=/app/$SERVICE_ACCT \
    -e TAGS=$TAGS \
    broadinstitute/dsp-toolbox deploy firecloud

也可指定具体服务名称（如deploy firecloud rawls），或使用all关键字部署所有项目（忽略SCM变更）：deploy firecloud all。

运维操作（Ops）

执行以下操作需具备FiaB分配器的有效服务账号及分配器URL。开发和QA环境的FiaB分配器URL为https://fiab-allocator.dsp-techops.broadinstitute.org，可使用broad-dsde-dev或broad-dsde-qa项目中具有"Project Editor"权限的服务账号认证。

创建FiaB主机

Python方式：

bash
python -m src.main.ops.fiab --command create --user <username> --project <google-proj> --allocator <allocator url> --serviceAcct <service acct filepath> --diskSize <(optional)> --machineType <(optional)> 

Docker方式：

bash
docker run --rm -v $PWD:/app \
    -e ALLOCATOR_URL=$ALLOCATOR_URL \
    -e SERVICE_ACCT=$SERVICE_ACCT \
    -e GOOGLE_PROJ=$GOOGLE_PROJ \
    -e USERNAME=$USERNAME \
    -e DISK_SIZE=100 \
    -e MACHINE_TYPE=n1-standard-1 \
    broadinstitute/dsp-toolbox fiab create

DISK_SIZE（默认100）和MACHINE_TYPE（默认n1-standard-1）为可选参数。

停止FiaB主机

Python方式：

bash
python -m src.main.ops.fiab --command stop --allocator <allocator url> --serviceAcct <service acct filepath> --hostName <host to stop> --project <google-proj>

Docker方式：

bash
docker run --rm -v $PWD:/app \
    -e ALLOCATOR_URL=$ALLOCATOR_URL \
    -e SERVICE_ACCT=$SERVICE_ACCT \
    -e GOOGLE_PROJ=$GOOGLE_PROJ \
    -e FIAB_HOST=$FIAB_HOST \
    broadinstitute/dsp-toolbox fiab stop

重启已停止的FiaB主机

Python方式：

bash
python -m src.main.ops.fiab --command restart --allocator <allocator url> --serviceAcct <service acct filepath> --hostName <host to restart> --project <google-proj>

Docker方式：

bash
docker run --rm -v $PWD:/app \
    -e ALLOCATOR_URL=$ALLOCATOR_URL \
    -e SERVICE_ACCT=$SERVICE_ACCT \
    -e GOOGLE_PROJ=$GOOGLE_PROJ \
    -e FIAB_HOST=$FIAB_HOST \
    broadinstitute/dsp-toolbox fiab restart

重置运行中的主机

Python方式：

bash
python -m src.main.ops.fiab --command reset --allocator <allocator url> --serviceAcct <service acct filepath> --hostName <host to reset> --project <google-proj>

Docker方式：

bash
docker run --rm -v $PWD:/app \
    -e ALLOCATOR_URL=$ALLOCATOR_URL \
    -e SERVICE_ACCT=$SERVICE_ACCT \
    -e GOOGLE_PROJ=$GOOGLE_PROJ \
    broadinstitute/dsp-toolbox instance reset <instance-name>

销毁FiaB主机

Python方式：

bash
python -m src.main.ops.fiab --command destroy --allocator <allocator url> --serviceAcct <service acct filepath> --hostName <host to destroy> --project <google-proj> 

Docker方式：

bash
docker run --rm -v $PWD:/app \
    -e ALLOCATOR_URL=$ALLOCATOR_URL \
    -e SERVICE_ACCT=$SERVICE_ACCT \
    -e GOOGLE_PROJ=$GOOGLE_PROJ \
    -e FIAB_HOST=$FIAB_HOST \
    broadinstitute/dsp-toolbox fiab destroy

列出FiaB主机

列出Google项目中所有FiaB主机，可选按标签过滤，返回包含InstanceName和IP的JSON列表。

Python方式：

bash
python -m src.main.ops.fiab --command list --allocator <allocator url> --serviceAcct <service acct filepath> --project <(optional) google-proj> --hostName <(optional) host to find>

Docker方式：

bash
docker run --rm -v $PWD:/app \
    -e ALLOCATOR_URL=$ALLOCATOR_URL \
    -e SERVICE_ACCT=$SERVICE_ACCT \
    -e GOOGLE_PROJ=$GOOGLE_PROJ \
    -e FIAB_HOST=$FIAB_HOST \
    broadinstitute/dsp-toolbox fiab list

GOOGLE_PROJ和FIAB_HOST为可选环境变量。

GitHub操作

列出子模块依赖

列出具有共同分支名称的所有子模块。

Python方式：

bash
python -m src.main.github.get_submodule_dependencies $BRANCH $GITHUB_TOKEN

Docker方式：

bash
docker run --rm -e GITHUB_BRANCH=$GITHUB_BRANCH \
    -e GITHUB_TOKEN=$GITHUB_TOKEN \
    broadinstitute/dsp-toolbox github dependencies

用于PR的自动化测试FiaB环境设置。

更新子模块哈希

在Firecloud服务的develop分支推送变更后，更新firecloud-develop中的子模块哈希。

bash
docker run --rm -e GITHUB_TOKEN=$GITHUB_TOKEN \
    -e ENV=$ENV \
    -e PROJECT=$PROJECT \
    -e GIT_SHA=$GIT_SHA \
    broadinstitute/dsp-toolbox:latest update-firecloud-service 

PROJECT为要更新的服务名称，GIT_SHA为提交哈希，需有效的GITHUB_TOKEN认证。用于update-submodule-hash Jenkins作业。