Topology 镜像文档

1. 镜像概述和主要用途

Topology镜像是基于OSG（Open Science Grid）Topology仓库构建的容器化解决方案，用于存储、管理和展示OSG生态系统中的关键注册信息，包括研究项目、虚拟组织（VO）、站点资源拓扑结构等。该镜像提供标准化的数据访问接口，支持直接读取YAML格式原始数据或通过XML接口查询过滤后的资源信息，旨在为OSG站点管理员、VO管理者及研究人员提供统一、便捷的资源信息检索与集成工具。

2. 核心功能和特性

2.1 数据组织与存储

• 结构化数据管理：采用YAML格式按类别存储信息，包括：
  • projects/：研究项目信息，每个项目对应<PROJECT>.yaml文件
  • virtual-organizations/：虚拟组织信息，每个VO对应<VO>.yaml文件，另有REPORTING_GROUPS.yaml存储WLCG metric报告组信息
  • topology/：站点资源拓扑信息，按设施（Facility）→站点（Site）→资源组（Resource Group）层级组织，文件路径格式为<FACILITY>/<SITE>/<RESOURCEGROUP>.yaml（如topology/University of Wisconsin/CHTC/CHTC.yaml）

2.2 多格式数据访问

• 原始数据访问：支持直接读取YAML文件（通过容器内路径或挂载卷访问）
• 标准化XML接口：提供与原myosg.grid.iu.edu兼容的XML格式数据接口，支持资源查询与过滤

2.3 灵活的查询过滤

• XML参数过滤：支持通过URL参数对资源拓扑、 downtime 等数据进行布尔条件过滤（如活跃状态、生产/非生产类型）和ID-based过滤（如按设施ID、站点ID筛选）
• 兼容性保障：XML接口格式及参数兼容原OIM站点（oim.grid.iu.edu）和myosg.grid.iu.edu的规范

3. 使用场景和适用范围

3.1 适用对象

• OSG站点管理员：管理和发布本地资源组信息（如HTCondor-CE、GridFTP等服务）
• 虚拟组织（VO）管理员：维护VO注册信息及报告组配置
• 研究人员/开发者：集成OSG资源数据到监控系统、报表工具或科研工作流中

3.2 典型场景

• 检索特定站点的活跃计算资源（如通过XML接口过滤设施ID和活跃状态）
• 批量获取VO列表及关联资源信息，用于资源分配分析
• 本地部署Topology数据服务，提供离线环境下的资源信息查询

4. 使用方法和配置说明

4.1 镜像获取

假设镜像已发布至容器仓库（如Docker Hub或OSG私有仓库），可通过以下命令拉取：

bash
docker pull opensciencegrid/topology:latest

4.2 基本部署（Docker Run）

以下示例通过容器内Nginx服务暴露XML接口，将仓库数据挂载为卷：

bash
docker run -d \
  --name osg-topology \
  -p 8080:80 \
  -v $(pwd)/topology-data:/app/topology \  # 挂载本地YAML数据目录（可选，默认使用镜像内置数据）
  -e XML_PORT=80 \                          # XML服务端口（容器内）
  -e DATA_REFRESH_INTERVAL=24h \            # 数据自动刷新间隔（默认24小时）
  opensciencegrid/topology:latest

4.3 Docker Compose部署

创建docker-compose.yml：

yaml
version: '3'
services:
  topology-service:
    image: opensciencegrid/topology:latest
    container_name: osg-topology
    ports:
      - "8080:80"
    volumes:
      - ./topology-data:/app/topology  # 本地数据卷（可选）
    environment:
      - XML_PORT=80
      - DATA_REFRESH_INTERVAL=12h      # 每12小时刷新数据
    restart: unless-stopped

启动服务：

bash
docker-compose up -d

4.4 数据访问方式

4.4.1 直接访问YAML文件

若挂载了本地数据卷，可通过容器内路径或宿主机挂载目录直接读取YAML文件：

bash
# 从宿主机访问挂载的YAML数据
cat ./topology-data/virtual-organizations/ATLAS.yaml

# 进入容器访问内置数据
docker exec -it osg-topology cat /app/topology/virtual-organizations/ATLAS.yaml

4.4.2 XML接口访问

服务启动后，通过http://<宿主机IP>:8080访问XML接口，支持以下端点：

示例：查询活跃的生产资源（设施ID为***、***）：

http://localhost:8080/rgsummary/xml?gridtype=on&gridtype_1=on&facility=on&facility_sel[]=***&facility_sel[]=***

5. 配置参数说明

5.1 环境变量配置

5.2 XML接口过滤参数

5.2.1 资源拓扑（rgsummary）与Downtime（rgdowntime）过滤

布尔过滤器：

ID-based过滤器：

支持按设施、站点、资源组等ID筛选，格式为<ATTRIB>=on&<ATTRIB>_sel[]=<ID1>&<ATTRIB>_sel[]=<ID2>，其中<ATTRIB>可取值：facility（设施ID）、site（站点ID）、rg（资源组ID）、service（服务ID）等。

示例：筛选设施ID为***（Fermilab）和***（UW-Madison）的资源：

/rgsummary/xml?facility=on&facility_sel[]=***&facility_sel[]=***

5.2.2 虚拟组织（vosummary）过滤

布尔过滤器：

ID-based过滤器：

按VO ID筛选，格式：vo=on&vo_sel[]=<ID1>&vo_sel[]=<ID2>
示例：筛选VO ID为13（GLOW）、67（HCC）、38（IceCube）：

/vosummary/xml?vo=on&vo_sel[]=13&vo_sel[]=67&vo_sel[]=38

6. 获取帮助

若在使用过程中遇到问题或有疑问，请根据支持对象提交工单：

或发送邮件至：***