快速开始 (v1rc1)

使用 ECI

  • 以下所有访问都需要携带获取的 para_token，使用 HTTP Header Authorization: Bearer token * 获取 API 认证 Token

  1. 查询超算账号

    Request
    curl --request GET \
    --url https://eci.paracloud.com/api/v1rc1/clusters/-/accounts \
    --header 'Authorization: Bearer KT3eSNnsizsjDIOsn1kL6-12W38xZVTpnsPE59AWVBQ-705200301'
    Response
    {
    "accounts": [
        {
            "clusterID": "BSCC-N32-H",
            "accountID": "acct1"
        },
    ]
}

  2. 查询实例类型

    Request
    curl --request GET \
    --url https://eci.paracloud.com/api/v1rc1/clusters/-/instanceTypes \
    --header 'Authorization: Bearer KT3eSNnsizsjDIOsn1kL6-12W38xZVTpnsPE59AWVBQ-705200301'
    • URL path 中的 clusterID 可以指定具体值过滤集群，也可以指定为 - 表示查询所有集群下的实例类型
    Response
    {
    "instanceTypes": [
        {
            "id": "n30.xlarge",
            "clusterID": "NC-N30",
            "cpu": {
                "cores": 6,
                "model": "EPYC7452"
            },
            "memory": {
                "sizeGB": 60
            },
            "gpu": {
                "count": 1,
                "model": "RTX3090"
            }
        },
        {
            "id": "n30.2xlarge",
            "clusterID": "NC-N30",
            "cpu": {
                "cores": 12,
                "model": "EPYC7452"
            },
            "memory": {
                "sizeGB": 120
            },
            "gpu": {
                "count": 2,
                "model": "RTX3090"
            }
        },
        {
            "id": "n32h.xlarge",
            "clusterID": "BSCC-N32-H",
            "cpu": {
                "cores": 32,
                "model": "KUNPENG920"
            },
            "memory": {
                "sizeGB": 55
            },
            "gpu": {
                "count": 1,
                "model": "A100-PCIE-40G"
            }
        },
        {
            "id": "n32h.2xlarge",
            "clusterID": "BSCC-N32-H",
            "cpu": {
                "cores": 64,
                "model": "KUNPENG920"
            },
            "memory": {
                "sizeGB": 110
            },
            "gpu": {
                "count": 2,
                "model": "A100-PCIE-40G"
            }
        }
    ]
}
    • 选择一个实例类型，比如 n32h.xlarge 用于后续创建容器组申请资源
    • 如果需要使用持久 Volume，还需要获取对应实例类型所在 clusterID BSCC-N32-H

  3. 创建持久 Volume

    request
    curl --request POST \
    --url https://eci.paracloud.com/api/v1rc1/clusters/BSCC-N32-H/accounts/acct1/volumes?volumeID=4dmrgh9n \
    --header 'Authorization: Bearer KT3eSNnsizsjDIOsn1kL6-12W38xZVTpnsPE59AWVBQ-705200301' \
    --header 'Content-Type: application/json' \
    --data '{
        "service": {}
    }'
    • acct1 即用户绑定的超算账号
    • volumeID 可选为自定义有意义名字即可，支持字符集为 `[a-z0-9-]+
    • 由于不同间 Cluster 的网络和存储是完全独立的，创建 Volume 时需要明确指定在哪个 clusterID 下
    • 如果需要 Volume 提供通过互联网访问的数据传输服务, 还需要设置 service = {}
    Response
    {
    "id": "4dmrgh9n",
    "clusterID": "BSCC-N32-H",
    "accountID": "acct1",
    "service": {
        "username": "z47vmx-bsccn32h-4dmrgh9n",
        "password": "5gkxzjvbbcb7svbt9djbxp6rpvdcdsv9",
        "address": {
            "webdav": "https://webdav.eci.paracloud.com",
            "sftp": "sftp.eci.paracloud.com:2022"
        }
    }
}
    • 获取 Volume id 4dmrgh9n 用于后续挂载持久存储到容器中
    • 返回的 service 提供 WebDAV 和 SFTP 协议登陆信息 (password 只能在创建 Volume 返回时获取，后续无法再获取)
    • 通过 WebDAV/SFTP 上传完数据后即可执行下面的步骤

  4. 创建 Container

    Request
    curl --request POST \
    --url https://eci.paracloud.com/api/v1rc1/clusters/BSCC-N32-H/accounts/acct1/containers?containerID=dnfd42jl \
    --header 'Authorization: Bearer KT3eSNnsizsjDIOsn1kL6-12W38xZVTpnsPE59AWVBQ-705200301' \
    --header 'Content-Type: application/json' \
    --data '{
        "instanceType": "n32h.xlarge",
        "image": "jupyter/minimal-notebook",
        "command": ["jupyter", "lab", "--port", "$BAT_PORT_jupyter", "--NotebookApp.token", "AapayS", "--no-browser", "--allow-root"],
        "ports": {
            "jupyter": {,
                "https": {}
            }
        },
        "volumeMounts": {
            "4dmrgh9n": "/root",
        },
        "labels": {
            "from": "docs.scc.paracloud.com"
        },
        "envs": {
            "EXAMPLE_KEY": "EXAMPLE_VALUE"
        }
    }'
    • 在使用 Volume 时，必须明确指定 clusterID 为 BSCC-N32-H. 当不需要 Volume 时可以指定 clusterID 为 - 由系统根据实例类型选择 clusterID
    • instanceType 必须指定，用于申请资源类型和数量
    • containerID 可选，为自定义有意义名字即可，支持字符集为 [a-z0-9-]+
    • 目前受限集群不支持网络隔离，为了避免监听端口冲突需要使用随机端口, 这时添加一个 port, port 的名字 可以自定义（字符集同上），容器启动时会设置环境变量 BAT_PORT_<port-name>, 启动服务时引用这个值
    • 当需要把 http 服务暴露到互联网上时，需要设置 container.ports.<port-name>.https = {}, 可访问的 host 在创建容器组后会返回，要想访问容器提供的服务还需要启动容器组并等待其 Running
    • jupyter 访问 url 还需要提供 token, 可以创建资源前生成随机的 token 然后传递进去
    • 在挂载 Volume 时, 需要指定 name 即同 clusters/BSCC-N32-H/accounts/acct1/volumes 下的 Volume id 值 4dmrgh9n, 以及挂载到容器内的路径 /root
    • labels 可选, 不影响容器的运行，仅标记该容器
    • volumeMounts 中 key 为 volumeID, value 为 mountPoint。同时可以自定义挂载该 Volume 下的子目录或者文件，格式为 <volumeID>:<subPath>, 例如 "4dmrgh9n:data/subdir": "/root"。注意如果子路径是文件时，<mountPoint> 在容器镜像中不能是存在的目录，例如这样挂载子路径是文件时 "4dmrgh9n:data/subdir/myfile": "/root/myfile", 其中 /root/myfile 中的 myfile 可以使用自定义名称。同时可以使用选项 :dir 或 :file，格式为 <volumeID>:<subPath>:<opt>，在子路径文件或目录不存在时自动创建。
    • envs 可选，传递环境变量到容器内
    Response
    {
    "id": "dnfd42jl",
    "clusterID": "BSCC-N32-H",
    "accountID": "acct1",
    "instanceType": "n32h.xlarge",
    "image": "jupyter/minimal-notebook",
    "command": [
        "jupyter",
        "lab",
        "--port",
        "$BAT_PORT_http",
        "--NotebookApp.token",
        "AapayS",
        "--no-browser",
        "--allow-root"
    ],
    "ports": {
        "jupyter": {
            "port": 29648,
            "https": {
                "host": "z47vmx-bscc-n32-h-dnfd42jl-jupyter-http.eci.paracloud.com"
            }
        }
    },
    "volumeMounts": {
        "4dmrgh9n": "/root"
    },
    "labels": {
        "from": "docs.scc.paracloud.com"
    },
    "envs": {
         "EXAMPLE_KEY": "EXAMPLE_VALUE"
    }
}
    • 返回 id 值 dnfd42jl 用于后续状态查询

  5. 等待 Container 运行

    Request
    curl --request GET \
    --url https://eci.paracloud.com/api/v1rc1/clusters/BSCC-N32-H/accounts/acct1/containers/dnfd42jl \
    --header 'Authorization: Bearer KT3eSNnsizsjDIOsn1kL6-12W38xZVTpnsPE59AWVBQ-705200301'
    Response
    {
    "id": "dnfd42jl",
    "clusterID": "BSCC-N32-H",
    "accountID": "acct1",
    "instanceType": "n32h.xlarge",
    "image": "jupyter/minimal-notebook",
    "command": [
        "jupyter",
        "lab",
        "--port",
        "$BAT_PORT_http",
        "--NotebookApp.token",
        "AapayS",
        "--no-browser",
        "--allow-root"
    ],
    "ports": {
        "jupyter": {
            "port": 29648,
            "https": {
                "host": "z47vmx-bscc-n32-h-dnfd42jl-jupyter-http.eci.paracloud.com"
            }
        }
    },
    "volumeMounts": {
        "4dmrgh9n": "/root"
    },
    "labels": {
        "from": "docs.scc.paracloud.com"
    },
    "envs": {
        "MY_ENV1": "abc"
    },
    "phase": "Running",
    "state": "Running",
    "runID": "14081",
    "nodeID": "paraai-n32-h-01-agent-43",
    "createTime": "2023-08-07T10:13:47.796946Z",
    "startTime": "2023-08-07T18:13:50+08:00"
}
    • 需要等待 phase 值为 Running 时表明容器组处于运行并且对外提供的 https 服务已准备就绪
    • 其中的 ports.<port-name>.https.host 即对外提供服务的地址
    • 容器的状态
      • phase 容器运行的状态，主要用于程序作为判断条件使用，包含:
        • Creating: 容器正在创建, 通常包含创建工作目录和在 HPC 集群提作业等
        • Pending: 容器在运行前的状态，通常包含拉取镜像和调度 HPC 作业等
        • Running: 容器在运行中，如果设置暴露 https 服务表示已经添加配置到反向代理中
        • Exiting: 容器运行开始自己退出，以及去停止 https 服务等，如果退出成功会进入到 Succeeded 否则进入 Failed 或者 Unknown
        • Succeeded: 容器退出码是 0
        • Failed: 容器退出码是非 0
        • Unknown: 容器是由于底层系统故障退出，比如运行节点故障
        • Canceling: 容器被主动取消，如果已经开始运行则开始取消集群作业和停止 https 服务等
        • Canceled: 容器被取消掉
        • 在进入 Succeeded, Failed, Unknown 和 Canceled 后，API 系统会对任务记录和工作目录再保留 7 天，此 7 天期间内仍能查询到此任务
      • state: 具体原因，通常用于显示人类可读错误。比如 phase = Pending, state = ImagePulling 表示系统在拉取镜像
    • startTime 为作业开始时间，作业状态为 Running 后才显示
    • endTime 为作业结束时间，只有当作业结束时才显示
    • runTime 为作业运行时间，单位为 秒，只有当作业结束时才显示

  6. 从互联网访问容器服务

    https://z47vmx-bscc-n32-h-dnfd42jl-jupyter-http.eci.paracloud.com/lab?token=AapayS (opens in a new tab)

    • https:// 来自约定值, 目前暂时只提供 https 服务
    • z47vmx-bscc-n32-h-dnfd42jl-jupyter-http.eci.paracloud.com 从 containers.ports.<port-name>.https.host 获取
    • /lab?token= 为 jupyter 自身约定
    • AapayS 由 API 使用者生成，在启动 jupyter lab --NotebookApp.token 时指定

  7. 取消 Container

    Request
    curl -v --request POST \
    --url https://eci.paracloud.com/api/v1rc1/clusters/BSCC-N32-H/accounts/acct1/containers/dnfd42jl:cancel \
    --header 'Authorization: Bearer KT3eSNnsizsjDIOsn1kL6-12W38xZVTpnsPE59AWVBQ-705200301'
    • 取消容器会清理其他资源，工作环境会保留（默认保留 7 天），可以查看日志. Volume 会永久保留，需要单独控制
    • 在保留的 7 天内，无法创建同一个 ContainerID 的 Container。如果需要再创建请使用下面删除 Container 接口
    Response
    < HTTP/1.1 204 No Content
< Connection: close
< Date: Thu, 18 May 2023 03:41:38 GMT

常用 API

  • 列出所有 Container

    Request
    curl --request GET \
    --url https://eci.paracloud.com/api/v1rc1/clusters/BSCC-N32-H/accounts/acct1/containers?pageSize=100&nextPageToken=<---nextPageToken---> \
    --header 'Authorization: Bearer KT3eSNnsizsjDIOsn1kL6-12W38xZVTpnsPE59AWVBQ-705200301'
    Response
    {
  "containers": [
    {
      "id": "dnfd42jl",
      "clusterID": "BSCC-N32-H",
      "accountID": "acct1",
      "image": "jupyter/minimal-notebook",
      "phase": "Running",
      "state": "Running",
      "createTime": "2023-08-07T10:13:47.796946Z"
    }
  ],
  "nextPageToken": "<---nextPageToken--->"
}
    • 默认只列出运行中的 Container，加 all=ture 参数列出所有 Container
    • pageSize: 可选，默认值 100，查询 Container 的当前页的数量
    • nextPageToken: 可选，默认空，查询 Container 的下一页的令牌，由上一次 列出所有 Container 请求返回，响应体中 nextPageToken 为空则无下一页

  • 查看 Container 运行日志

    Request
    curl --request GET \
    --url https://eci.paracloud.com/api/v1rc1/clusters/BSCC-N32-H/accounts/acct1/containers/dnfd42jl/logs \
    --header 'Authorization: Bearer KT3eSNnsizsjDIOsn1kL6-12W38xZVTpnsPE59AWVBQ-705200301'
    • 可选参数:
      • tail: int，表示查看日志文件的倒数多少行，默认全文
      • follow: bool，是否保持连接持续查看日志

  • 删除 Container

    Request
    curl -v --request DELETE \
    --url https://eci.paracloud.com/api/v1rc1/clusters/BSCC-N32-H/accounts/acct1/containers/dnfd42jl \
    --header 'Authorization: Bearer KT3eSNnsizsjDIOsn1kL6-12W38xZVTpnsPE59AWVBQ-705200301'
    • 删除容器只有挂载 Volume 会保留，其他资源和工作环境都将被清理掉, 无法再查询到此 Container
    Response
    < HTTP/1.1 204 No Content
< Connection: close
< Date: Thu, 18 May 2023 03:41:38 GMT

  • 列出所有 Volume

    Request
    curl --request GET \
    --url https://eci.paracloud.com/api/v1rc1/clusters/-/accounts/-/volumes?pageSize=100&nextPageToken=<---nextPageToken---> \
    --header 'Authorization: Bearer KT3eSNnsizsjDIOsn1kL6-12W38xZVTpnsPE59AWVBQ-705200301' \
    --header 'Content-Type: application/json'
    Response
    {
    "volumes": [
        {
            "id": "4dmrgh9n",
            "clusterID": "BSCC-N32-H",
            "accountID": "acct1",
            "phase": "Available",
            "state": "Available",
            "createTime": "2023-08-07T10:13:47.796946Z"
        }
    ],
    "nextPageToken": "<---nextPageToken--->"
}
    • pageSize: 可选，默认值 100，查询 Container 的当前页的数量
    • nextPageToken: 可选，默认空，查询 Container 的下一页的令牌，由上一次 列出所有 Volume 请求返回，响应体中 nextPageToken 为空则无下一页
    • Volume 的状态
      • phase Volume 运行的状态，主要用于程序作为判断条件使用，包含:
        • Creating: Volume 正在创建
        • Pending: Volume 在运行前的状态，通常是在创建 service
        • Available: Volume 在运行中，此时 Volume 可用
        • Failed: Volume 创建失败
        • Deleting: Volume 在删除中，此时 Volume 不可用，可以撤销删除
        • Deleted: Volume 已删除，此时 Volume 不可用，不可以撤销删除
        • Unknown: 表示内部和底层系统故障
      • state: 具体原因，通常用于显示人类可读错误。比如 phase = Pending, state = ServiceCreating 表示系统正在创建 service

  • 删除指定的 Volume

    Request
    curl -v --request DELETE \
    --url https://eci.paracloud.com/api/v1rc1/clusters/BSCC-N32-H/accounts/acct1/volumes/4dmrgh9n?force=false \
    --header 'Authorization: Bearer KT3eSNnsizsjDIOsn1kL6-12W38xZVTpnsPE59AWVBQ-705200301'
    • 参数 force: 可选，默认为 false，会保留 Volume 7 天，可以通过撤销删除恢复，force=true 可以强制删除 Volume，此时无法通过撤销删除恢复
    Response
    HTTP/1.1 204 No Content
Connection: close
Date: Thu, 18 May 2023 06:14:36 GMT

  • 撤销删除指定的 Volume

    Request
    curl -v --request POST \
    --url https://eci.paracloud.com/api/v1rc1/clusters/BSCC-N32-H/accounts/acct1/volumes/4dmrgh9n:undelete \
    --header 'Authorization: Bearer KT3eSNnsizsjDIOsn1kL6-12W38xZVTpnsPE59AWVBQ-705200301'
    Response
    HTTP/1.1 204 No Content
Connection: close
Date: Thu, 18 May 2023 06:14:36 GMT
命令行[案例]构建推理服务