快速开始 (v1beta2)

基本概念

User: 使用服务前必须注册一个并行账号, 一个 User 下可以创建多个 Namespace
Namespace: 面向个人的资源都组织在 Namespace 下, 使用个人的资源前都必须创建一个 Namespace, 是 API 资源的逻辑隔离用于权限控制
Cluster: 对应一个物理集群即一组网络和存储互通的节点，由 ECI 服务提供商预定义
InstanceType: 每个 Cluster 下有 ECI 服务提供商预定义多种资源类型, 用于提交容器任务时申请资源类型
Volume: 管理在 Namespace/Cluster 下的持久存储, 用于挂载进容器内
ContainerGroup: 管理在 Namespace/Cluster 下的容器组, 用于运行基于容器的任务

使用 ECI

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

创建 Namespace

Request

curl --request POST \
    --url https://eci.paracloud.com/api/v1beta2/namespaces \
    --header 'Content-Type: application/json' \
    --header 'Authorization: Bearer KT3eSNnsizsjDIOsn1kL6-12W38xZVTpnsPE59AWVBQ-705200301' \
    --data '{}'

Response

{
    "id": "z47vmx"
}

所有资源组织在 Namespace 下，一个用户可用创建多个 Namespace
获取的 id z47vmx 用于后续访问 API 资源使用

查询实例类型

Request

curl --request GET \
    --url https://eci.paracloud.com/api/v1beta2/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

创建持久 Volume

request

curl --request POST \
    --url https://eci.paracloud.com/api/v1beta2/namespaces/z47vmx/clusters/BSCC-N32-H/volumes \
    --header 'Authorization: Bearer KT3eSNnsizsjDIOsn1kL6-12W38xZVTpnsPE59AWVBQ-705200301' \
    --header 'Content-Type: application/json' \
    --data '{
        "service": {}
    }'

由于不同间 Cluster 的网络和存储是完全独立的，创建 Volume 时需要明确指定在哪个 clusterID 下
如果需要 Volume 提供通过互联网访问的数据传输服务, 还需要设置 service = {}

Response

{
    "id": "4dmrgh9n",
    "clusterID": "BSCC-N32-H",
    "namespaceID": "z47vmx",
    "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 上传完数据后即可执行下面的步骤

创建容器组

Request

curl --request POST \
    --url https://eci.paracloud.com/api/v1beta2/namespaces/z47vmx/clusters/BSCC-N32-H/containerGroups \
    --header 'Authorization: Bearer KT3eSNnsizsjDIOsn1kL6-12W38xZVTpnsPE59AWVBQ-705200301' \
    --header 'Content-Type: application/json' \
    --data '{
        "instanceType": "n32h.xlarge",
        "containers": [
            {
                "name": "jupyter",
                "image": "jupyter/minimal-notebook",
                "command": ["jupyter", "lab", "--port", "$BAT_PORT_http", "--NotebookApp.token", "AapayS", "--no-browser", "--allow-root"],
                "ports": [
                    {
                        "name": "http",
                        "https": {}
                    }
                ],
                "volumeMounts": [
                    {
                        "name": "4dmrgh9n",
                        "mountPath": "/root"
                    }
                ]
            }
        ]
    }'

在使用 Volume 时，必须明确指定 clusterID 为 BSCC-N32-H. 当不需要 Volume 时可以指定 clusterID 为 - 由系统根据实例类型选择 clusterID
instanceType 必须指定用于申请资源类型和数量
containers.name 可选为自定义有意义名字即可，支持字符集为 [a-z0-9-]+
目前受限集群不支持网络隔离，为了避免监听端口冲突需要使用随机端口, 这时添加一个 port 其中 name 可以自定义（字符集同上），容器启动时会设置环境变量 BAT_PORT_<port-name>, 启动服务时引用这个值
当需要把 http 服务暴露到互联网上时，需要设置 containers.ports.https = {}, 可访问的 host 在创建容器组后会返回，要想访问容器提供的服务还需要启动容器组并等待其 Running
jupyter 访问 url 还需要提供 token, 可以创建资源前生成随机的 token 然后传递进去
在挂载 Volume 时, 需要指定 name 即同 namespace/clusterID 下的 Volume id 值 4dmrgh9n, 以及挂载到容器内的路径 mountPath 值 /root

Response

{
    "id": "dnfd42jl",
    "clusterID": "BSCC-N32-H",
    "namespaceID": "z47vmx",
    "instanceType": "n32h.xlarge",
    "containers": [
        {
            "name": "jupyter",
            "image": "jupyter/minimal-notebook",
            "command": [
                "jupyter",
                "lab",
                "--port",
                "$BAT_PORT_http",
                "--NotebookApp.token",
                "AapayS",
                "--no-browser",
                "--allow-root"
            ],
            "ports": [
                {
                    "name": "http",
                    "port": 29648,
                    "https": {
                        "host": "z47vmx-bscc-n32-h-dnfd42jl-jupyter-http.eci.paracloud.com"
                    }
                }
            ],
            "volumeMounts": [
                {
                    "name": "4dmrgh9n",
                    "mountPath": "/root"
                }
            ]
        }
    ],
    "userID": "1024",
    "status": {
        "state": "Pending",
        "reason": "Creating"
    }
}

返回 id 值 dnfd42jl 用于后续状态查询

等待容器组运行

Request

curl --request GET \
    --url https://eci.paracloud.com/api/v1beta2/namespaces/z47vmx/clusters/BSCC-N32-H/containerGroups/dnfd42jl \
    --header 'Authorization: Bearer KT3eSNnsizsjDIOsn1kL6-12W38xZVTpnsPE59AWVBQ-705200301'

Response

{
    "id": "dnfd42jl",
    "clusterID": "BSCC-N32-H",
    "namespaceID": "z47vmx",
    "instanceType": "n32h.xlarge",
    "containers": [
        {
            "name": "jupyter",
            "image": "jupyter/minimal-notebook",
            "command": [
                "jupyter",
                "lab",
                "--port",
                "$BAT_PORT_http",
                "--NotebookApp.token",
                "AapayS",
                "--no-browser",
                "--allow-root"
            ],
            "ports": [
                {
                    "name": "http",
                    "port": 29648,
                    "https": {
                        "host": "z47vmx-bscc-n32-h-dnfd42jl-jupyter-http.eci.paracloud.com"
                    }
                }
            ],
            "volumeMounts": [
                {
                    "name": "4dmrgh9n",
                    "mountPath": "/root"
                }
            ]
        }
    ],
    "userID": "1024",
    "runID": "14081",
    "nodeID": "paraai-n32-h-01-agent-43",
    "status": {
        "state": "Running",
        "reason": "Running",
        "startTime": "2023-12-05T15:07:42+08:00"
    }
}

需要等待 status.state 值为 Running 时表明容器组处于运行并且对外提供的 https 服务已准备就绪
status.startTime 为作业开始时间，作业状态为 Running 后才显示
status.endTime 为作业结束时间，只有当作业结束时才显示
status.runTime 为作业运行时间，单位为 秒，只有当作业结束时才显示
其中的 containers.ports.https.host 即对外提供服务的地址

从互联网访问容器服务

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.https.host 获取
- /lab?token= 为 jupyter 自身约定
- AapayS 由 API 使用者生成，在启动 jupyter lab --NotebookApp.token 时指定

取消容器组

Request

curl -v --request DELETE \
    --url https://eci.paracloud.com/api/v1beta2/namespaces/z47vmx/clusters/BSCC-N32-H/containerGroups/dnfd42jl:cancel \
    --header 'Authorization: Bearer KT3eSNnsizsjDIOsn1kL6-12W38xZVTpnsPE59AWVBQ-705200301'

取消容器组只有挂载 Volume 会保留，其他资源和工作环境都将被清理掉

Response

< HTTP/1.1 204 No Content
< Connection: close
< Date: Thu, 18 May 2023 03:41:38 GMT

常用 API

列出指定 Namespace 下的所有容器组

Request

curl --request GET \
    --url https://eci.paracloud.com/api/v1beta2/namespaces/z47vmx/clusters/-/containerGroups \
    --header 'Authorization: Bearer KT3eSNnsizsjDIOsn1kL6-12W38xZVTpnsPE59AWVBQ-705200301'

如果需要查询特定的 clusterID 下的容器组，可以替换 - 为具体值比如 BSCC-N32-H

Response

{
    "containerGroups": [
        {
            "id": "dnfd42jl",
            "clusterID": "BSCC-N32-H",
            "namespaceID": "z47vmx",
            "instanceType": "n32h.xlarge",
            "containers": [
                {
                    "name": "jupyter",
                    "image": "jupyter/minimal-notebook",
                    "command": [
                        "jupyter",
                        "lab",
                        "--port",
                        "$BAT_PORT_http",
                        "--NotebookApp.token",
                        "AapayS",
                        "--no-browser",
                        "--allow-root"
                    ],
                    "ports": [
                        {
                            "name": "http",
                            "port": 29648,
                            "https": {
                                "host": "z47vmx-bscc-n32-h-dnfd42jl-jupyter-http.eci.paracloud.com"
                            }
                        }
                    ],
                    "volumeMounts": [
                        {
                            "name": "4dmrgh9n",
                            "mountPath": "/root"
                        }
                    ]
                }
            ],
            "userID": "1024",
            "runID": "14081",
            "nodeID": "paraai-n32-h-01-agent-43",
            "status": {
                "state": "Running",
                "reason": "Running",
                "startTime": "2023-12-05T15:07:42+08:00"
            }
        }
    ]
}

容器组中的 status 包含以下 3 个字段
- state 容器组运行的状态，主要用于程序作为判断条件使用，包含:
  - Pending: 容器组在运行前的状态，通常包含调度和拉取镜像等阶段
  - Running: 容器组在运行中，如果设置暴露 https` 服务表示已经添加配置到反向代理中
  - Succeeded: 所有容器退出码是 0
  - Failed: 至少一个容器退出码是非 0
  - Unknown: 表示内部和底层系统故障，比如运行节点故障
- reason: state 下具体原因，通常用于显示人类可读错误。比如 state = Pending, reason = ImagePulling 表示系统在拉取镜像
- message: reason 下详情，通常用于描述更加详细的信息，一般在产生错误时才设置值

列出指定 Namespace 下所有 Volume

Request

curl --request GET \
    --url https://eci.paracloud.com/api/v1beta2/namespaces/z47vmx/clusters/-/volumes \
    --header 'Authorization: Bearer KT3eSNnsizsjDIOsn1kL6-12W38xZVTpnsPE59AWVBQ-705200301' \
    --header 'Content-Type: application/json'

Response

{
    "volumes": [
        {
            "id": "4dmrgh9n",
            "clusterID": "BSCC-N32-H",
            "namespaceID": "z47vmx"
        }
    ]
}

删除指定的 Volume

Request

curl -v --request DELETE \
    --url https://eci.paracloud.com/api/v1beta2/namespaces/z47vmx/clusters/BSCC-N32-H/volumes/4dmrgh9n \
    --header 'Authorization: Bearer KT3eSNnsizsjDIOsn1kL6-12W38xZVTpnsPE59AWVBQ-705200301'

Response

HTTP/1.1 204 No Content
Connection: close
Date: Thu, 18 May 2023 06:14:36 GMT

列出并行账号下所有 Namespace

Request

curl --request GET \
    --url https://eci.paracloud.com/api/v1beta2/namespaces \
    --header 'Authorization: Bearer KT3eSNnsizsjDIOsn1kL6-12W38xZVTpnsPE59AWVBQ-705200301'

Response

{
    "namespaces": [
        {
            "id": "z47vmx"
        }
    ]
}

删除并行账号下指定的 Namespace

Request

curl -v --request DELETE \
    --url https://eci.paracloud.com/api/v1beta2/namespaces/z47vmx \
    --header 'Authorization: Bearer KT3eSNnsizsjDIOsn1kL6-12W38xZVTpnsPE59AWVBQ-705200301' \

Response

HTTP/1.1 204 No Content
Connection: close
Date: Thu, 18 May 2023 06:08:23 GMT

[案例]构建推理服务