使用faasutil

重要

本文中含有需要您注意的重要提示信息,忽略该信息可能对您的业务造成影响,请务必仔细阅读。

本文主要介绍faasutil命令的用法和示例。

前提条件

  • 已获取faasutil命令行工具。具体操作,请参见获取faasutil

  • 已准备原始文件,该文件为FPGA设备开发的加速程序,用于编译生成FPGA镜像。

  • 已创建用于上传原始文件的OSS Bucket。具体操作,请参见控制台创建存储空间

  • 已为RAM用户创建AccessKey。具体操作,请参见创建AccessKey

    警告

    仅支持通过RAM用户的AccessKey使用FaaS服务,可有效降低AccessKey泄露的风险。强烈建议您不要将AccessKey ID和AccessKey Secret明文保存至工程代码里或者任何容易被他人明文获取到的地方,否则可能导致AccessKey泄露,威胁您账号下所有资源的安全。

基本概念

本文涉及的主要概念说明如下:

概念

说明

FPGA实例

您在阿里云控制台或者通过OpenAPI创建的FPGA实例。

该实例包括计算资源、ECS镜像、云盘等功能组件。

ECS镜像

FPGA实例使用的ECS镜像。

FPGA实例在提供FPGA加速能力的同时,保留了与普通ECS实例相同的使用体验。

原始文件

您为FPGA设备开发的加速程序,用于编译生成FPGA镜像。

例如,Intel FPGA的原始文件为.gbs格式,Xilinx FPGA的原始文件为脚本处理后得到的tar包。

FPGA镜像

FPGA设备使用的镜像。

原始文件编译后得到FPGA镜像,将FPGA镜像加载到FPGA设备后,FPGA设备即可按照您的设计提供加速服务。

说明

每个FPGA镜像拥有唯一的识别码UUID,不同FPGA镜像的UUID不会重复。

注意事项

使用faasutil时请注意以下事项:

  • 运行命令的方式:./faasutil [command]

  • faasutil命令及其参数严格区分大小写。

    例如,如果执行./faasutil Create_Image --Object=faasutiltest-forcompiling.tar.gz --Shell=f30010 --FPGAType=xilinx --Name=faasutiltest-image命令,会出现报错信息,您必须将命令及其参数的大小写与定义保持完全一致。

  • faasutil命令中的参数=以及取值间不能存在多余空格。

    例如,如果执行./faasutil create_image --object=faasutiltest-forcompiling.tar.gz --shell = f30010 --fpgatype=xilinx --name=faasutiltest-image命令时,会出现报错信息,您必须去掉shell参数=前后的空格。

  • 如果您为普通用户,请联系管理员给普通用户添加/dev/virtio-ports/FaaS.agent的使用权限。

faasutil命令概览

查看所有命令

查看faasutil版本以及所有命令的列表等信息。

命令格式

  • faasutil --help

  • faasutil -h

示例代码

[user1@i**** ~]# ./faasutil -h
faasutil [command] [optons]...
  DESCRIPTION
    faasutil is a fpga image management tool.
    version : 2.0.3a
    date    : 2020-07-08-11:04
  command list(use "faasutil [command] --help" for more infomation):
    config                  Config faasutil enviroment.
    list_instances          Print the instances base infomation.
    fpga_status             Check pointed fpga status.
    auth                    Authorize FAAS to read the oss bucket your specified.
    list_objects            List objects of the bucket you specified.
    put_object              Put local file to the bucket object, FAAS need download it from oss.
    get_object              Get object from oss bucket.
    list_policy             List the detailed information about oss policy authorize to FAAS.
    delete_policy           Delete the oss policy authorize to FAAS.
    list_images             List the fpga images
    create_image            Create fpga image.
    modify_image            Modify fpga image.
    delete_image            Delete fpga image.
    bind_image              Bind the FPGA image to ECS image.
    download_image          Download FPGA image to faas instance.
    download_status         The status of download image operation.
    copy_fpga_image         Copying images across regions.
    query_log               Get compiler log.

查看指定命令

查看指定命令的描述、参数说明等信息。

命令格式

  • faasutil [command name] --help

  • faasutil [command name] -h

示例代码

[user1@i**** ~]# ./faasutil config --help
  COMMAND
    config
  SYNOPSIS
    config --id=[accessid] --key=[accesskey] --token=[sts-token] --bucket=[bucket] --regionId=[regionId] --ossEndpoint=[ossEndpoint] --popEndpoint=[popEndpoint]
  DESCRIPTION
    Config faasutil enviroment.
    /*Using config to save the value of these follow options.*/
    /*You can also set these options' value follow any command which need to specify.*/
  OPTIONS
    required
    --id
        User access id , using config to save this information.
    --key
        User access key, using config to save this information.
    optional
    --token
        User ststoken  , using config to save this information.
    --bucket
        Bucket used for upload image.
    --regionId
        The region of pop endpoint and oss endpoint.
        Default using ecs region of public network.
    --ossEndpoint
        Oss endpoint info.
        Specify the oss endpoint if you want to get/put files in different region or vpc network.
    --popEndpoint
        Pop endpoint info.
    --instanceId
        ECS instance ID.
        Default using the local ECS ID.
    --ecsImageId
        ECS image ID.
        Default using the image ID of the local ECS ID.
    --shell
        Specify the shell version you used.
        Default using the shell version of the ECS fpga card.
    --fpgatype
        Specify the FPGA device type.
        Default using the FPGA device type of belong to the local ECS.

配置用户信息

将用户信息写入默认的配置文件里。主要用户信息如下:

用户信息

说明

AccessKey ID

必填,用于身份认证。

AccessKey Secret

OSS Bucket名称

建议填写,用于指定上传原始文件的OSS Bucket,避免在运行某些命令时重复输入OSS Bucket名称。

命令格式

说明

您可以运行config命令查看支持配置的信息。

faasutil config --id=[accessid] --key=[accesskey] --token=[sts-token] --bucket=[bucket] --regionId=[regionId] --ossEndpoint=[ossEndpoint] --popEndpoint=[popEndpoint]

其中,上述命令中主要参数说明如下所示:

参数名称

说明

token

该参数与之前faascmd工具特性保持兼容,不建议您配置该参数。

regionId

该参数会在ECS实例中自动获取,您无需配置该参数。

ossEndpoint

该参数会在ECS实例中自动获取,您无需配置该参数。

popEndpoint

该参数会在ECS实例中自动获取,您无需配置该参数。

示例代码

[user1@i**** ~]# ./faasutil config --id=L**** --key=v**** --bucket=yk****
Your configuration is saved into /home/user1/.faascredentials.
1.057(s) elapsed

添加OSS Bucket读权限

添加OSS Bucket读权限,用于FPGA实例读取OSS Bucket中的文件。

命令格式

faasutil auth

示例代码

[user1@i**** ~]# ./faasutil auth
{
  "Statement": [
    {
      "Action": [
        "oss:GetObject",
        "oss:GetObjectMeta",
        "oss:ListObjects"
      ],
      "Effect": "Allow",
      "Principal": [
        "26143530338319****"
      ],
      "Resource": [
        "acs:oss:*:*:yk****/*"
      ]
    }
  ],
  "Version": "1"
}

0.223(s) elapsed

查看OSS Bucket读权限

查看已添加的OSS Bucket读权限。

命令格式

faasutil list_policy

示例代码

[user1@i**** ~]# ./faasutil list_policy
Get policy text:
{
  "Statement": [
    {
      "Action": [
        "oss:GetObject",
        "oss:GetObjectMeta",
        "oss:ListObjects"
      ],
      "Effect": "Allow",
      "Principal": [
        "26143530338319****"
      ],
      "Resource": [
        "acs:oss:*:*:yk****/*"
      ]
    }
  ],
  "Version": "1"
}
0.203(s) elapsed

删除OSS Bucket读权限

删除OSS Bucket读权限,禁止FPGA实例读取OSS Bucket中的文件。

命令格式

faasutil delete_policy

示例代码

[user1@i**** ~]# ./faasutil delete_policy
0.210(s) elapsed

获取FPGA实例的信息

获取FPGA实例的实例ID、ECS镜像、挂载的FPGA设备等信息。

命令格式

faasutil list_instances

示例代码

该示例以显示FPGA实例挂载了2个FPGA设备,对应的bdf分别为00:09.000:08.0为例。

[user1@i**** ~]# ./faasutil list_instances
instance_id          : i-uf616ov8zzwmiijb****
image_id             : centos_7_8_x64_20G_alibase_20200914.vhd
regionId             : cn-shanghai
fpga bdf             : ['00:09.0', '00:08.0']
shell version        : f30010
requestId            : x-7762368991973****
fpga type            : xilinx
1.054(s) elapsed

获取FPGA设备的状态信息

根据FPGA设备的bdf获取状态信息。您可以运行list_instances命令查看FPGA设备的bdf,具体操作,请参见获取FPGA实例的信息

命令格式

faasutil fpga_status --bdf=[bdf]
说明

命令中的[bdf]替换成FPGA设备的bdf,例如[bdf]00:09.0

示例代码

该示例以查看bdf为00:09.0的FPGA设备的状态信息为例。

其中imageuuid对应指定FPGA镜像的UUID,初次购买的FPGA实例imageuuid取值显示为NULL

[user1@i**** ~]# ./faasutil fpga_status --bdf=00:09.0
clock0               : 240
clock1               : 189
fpgaStatus           : valid
requestId            : x-1093970844245****
shellUUID            : f30010
imageuuid            : NULL
firewall             : ['mgmt : GOOD', 'user : GOOD', 'xdma : GOOD', 'dma : GOOD']
ddr                  : ['ddr0 : online', 'ddr1 : online', 'ddr2 : online', 'ddr3 : online']
message              : FPGA is working.
1.025(s) elapsed

上传文件至OSS Bucket

将FPGA实例上的文件上传至OSS Bucket,例如上传原始文件。

命令格式

faasutil put_object --bucket=[bucket_name] --object=[object_name] --file=[file_name]

其中,上述命令中主要参数说明如下所示:

  • [bucket_name]:OSS Bucket的名称。

    说明

    如果已经运行config命令在默认配置文件中指定了OSS Bucket,则可以不指定bucket参数。

  • [file_name]:待上传文件的名称。

  • [object_name]:上传文件后在OSS Bucket中的显示名称。

示例代码

[user1@i**** ~]# ./faasutil put_object --object=faasutiltest-forcompiling.tar.gz --file=faasutiltest.tar.gz
100%

539.171(s) elapsed

查看OSS Bucket中的文件

查看OSS Bucket中的文件。

命令格式

faasutil list_objects

示例代码

[user1@i**** ~]# ./faasutil list_objects
faasutiltest-forcompiling.tar.gz
0.288(s) elapsed

下载文件到FPGA实例

从OSS Bucket下载文件到FPGA实例。

命令格式

faasutil get_object --bucket=[bucket_name] --object=[object_name] --file=[file_name]

其中,上述命令中主要参数说明如下所示:

  • [bucket_name]:OSS Bucket的名称。

    说明

    如果已经运行config命令在默认配置文件中指定了OSS Bucket,则可以不指定bucket参数。

  • [file_name]:待下载文件的名称。

  • [object_name]:下载文件后在FPGA实例中的显示名称。

示例代码

[user1@i**** ~]# ./faasutil get_object --object=faasutiltest-forcompiling.tar.gz --file=faasutiltest-fordeveloping.tar.gz
100%

179.909(s) elapsed

创建FPGA镜像编译任务

使用原始文件编译生成FPGA镜像。

说明

编译需要一定时间,请耐心等待。如果已经创建了编译任务,无论是否编译成功,至少30分钟后才可以创建下个编译任务。

命令格式

faasutil create_image --object=[object_name] --shell=[shell_ver] --fpgatype=[fpga_type]

其中,上述命令中主要参数说明如下所示:

  • [object_name]:用于编译的原始文件的名称,请确保已将原始文件上传至OSS Bucket。

  • [shell_ver]:FPGA设备的Shell版本信息。您可以运行fpga_status命令查看FPGA设备的Shell版本信息,具体操作,请参见获取FPGA设备的状态信息

  • [fpga_type]:FPGA设备的类型,目前支持Xilinx FPGA(xilinx)、Intel FPGA(intel),请根据FPGA设备的实际类型来设置。

示例代码

[user1@i**** ~]# ./faasutil create_image --object=faasutiltest-forcompiling.tar.gz --shell=f30010 --fpgatype=xilinx --name=faasutiltest-image
{
  "CreateTime": "2020-12-04 14:48:13",
  "Description": "",
  "FpgaImageUniqueId": "xilinxb80832c9-1cd1-49a2-a7b4-7d3a5a4b****",
  "Name": "faasutiltest-image",
  "RequestId": "2E996CE5-F550-43E7-8016-DAF0D32A96BF",
  "ShellUniqueId": "f30010",
  "State": "queueing"
}
0.555(s) elapsed

如示例所示,创建FPGA镜像编译任务后会返回FPGA镜像的FpgaImageUniqueIdState参数值。

  • 如果State显示为queueing状态,表示任务处于等待编译中。您可以运行list_images命令并查看FpgaImageUniqueId对应任务的状态。具体操作,请参见查看FPGA镜像

  • 如果待State显示为success状态,表示任务编译成功。

查询编译Log

查询指定FPGA镜像编译任务过程中记录的Log。其中,[fpgaImageUniqueId]为创建FPGA镜像编译任务后返回的FPGA镜像UUID。

命令格式

faasutil query_log --fpgaImageUniqueId=[fpgaImageUniqueId]

示例代码

[user1@i**** ~]# ./faasutil query_log --fpgaImageUniqueId=xilinxb80832c9-1cd1-49a2-a7b4-7d3a5a4b****
{
  "Log": "http://aliyun-faas-images-cn-shanghai.oss-cn-shanghai-internal.aliyuncs.com/27095692903785****%2Fxilinxb80832c9-1cd1-49a2-a7b4-7d3a5a4b****_log?Expires=160706****&OSSAccessKeyId=L****&Signature=1****",
  "RequestId": "07A744F5-422D-49AA-B69B-1AD898BBD1D8"
}
0.194(s) elapsed

如示例所示,访问返回结果中的链接(例如http://aliyun-faas-images****-internal.aliyuncs****&Signature=1****)即可获取到Log。

说明

如果您不需要在FPGA实例中查看Log,请去掉链接中的-internal

查看FPGA镜像

查看已有的FPGA镜像,支持按镜像所有者过滤结果。其中,[owner]为镜像所有者,目前支持市场镜像(market)、本地自制镜像(self)。

命令格式

faasutil list_images --owneralias=[owner]

示例代码

[user1@i**** ~]# ./faasutil list_images
{
  "FpgaImages": [
    {
      "CreateTime": "2020-12-04 14:48:14",
      "Description": "faasutil test round 1",
      "Encryption": false,
      "FpgaImageUniqueId": "xilinxb80832c9-1cd1-49a2-a7b4-7d3a5a4b****",
      "Name": "faasutiltest-image",
      "OwnerId": "27095692903785****",
      "ShellUniqueId": "f30010",
      "State": "success",
      "Tags": "",
      "UpdateTime": "2020-12-04 15:02:05"
    }
  ],
  "RequestId": "C85DD548-9B3D-463E-BE25-316FF7288CEB"
}
0.087(s) elapsed

修改FPGA镜像的信息

修改已有FPGA镜像的名称、描述等信息。

命令格式

faasutil modify_image --fpgaImageUniqueId=[fpgaImageUniqueId] --name=[name] --description=[description] --tags=[tags]

示例代码

[user1@i**** ~]# ./faasutil modify_image --fpgaImageUniqueId=xilinxb80832c9-1cd1-49a2-a7b4-7d3a5a4b*** --name="faasutiltest-image" --description="faasutil test round 2"
{
  "Description": "faasutil test round 2",
  "FpgaImageUniqueId": "xilinxb80832c9-1cd1-49a2-a7b4-7d3a5a4b****",
  "Name": "faasutiltest-image",
  "RequestId": "AED50829-B84A-42F9-9891-E1EE9821DA33",
  "Tags": ""
}

查看修改后的信息:

[user1@i**** ~]# ./faasutil list_images
{
  "FpgaImages": [
    {
      "CreateTime": "2020-12-04 14:48:14",
      "Description": "faasutil test round 2",
      "Encryption": false,
      "FpgaImageUniqueId": "xilinxb80832c9-1cd1-49a2-a7b4-7d3a5a4b****",
      "Name": "faasutiltest-image",
      "OwnerId": "27095692903785****",
      "ShellUniqueId": "f30010",
      "State": "success",
      "Tags": "",
      "UpdateTime": "2020-12-04 15:02:05"
    }
  ],
  "RequestId": "C85DD548-9B3D-463E-BE25-316FF7288CEB"
}
0.087(s) elapsed

绑定FPGA镜像和ECS镜像

绑定FPGA镜像和ECS镜像后,您可以将ECS镜像发布至镜像市场,第三方在使用您发布的ECS镜像时即可使用与之绑定的FPGA镜像。

命令格式

faasutil bind_image --fpgaImageUniqueId=[fpgaImageUniqueId] --ecsImageId=[ecsImageId]
  • [fpgaImageUniqueId]:FPGA镜像的UUID。

  • [ecsImageId]:ECS镜像的ID,默认使用当前FPGA实例所用ECS镜像的ID。

示例代码

[user1@i**** ~]# ./faasutil bind_image --fpgaImageUniqueId=xilinx5395ad11-edb9-4d93-964d-12c59a07****
{
  "FpgaImageUniqueId": "xilinx5395ad11-edb9-4d93-964d-12c59a07****",
  "ImageId": "",
  "Message": "publish succeed!",
  "RequestId": "966883DD-6A6F-456A-8894-8FB7FA8A321C"
}
0.119(s) elapsed

跨地域拷贝FPGA镜像

如果您需要在新的地域使用一个其他地域已有的FPGA镜像,无需在目标地域重新创建镜像编译任务,将已有的FPGA镜像拷贝至目标地域即可。

命令格式

faasutil copy_fpga_image --fpgaImageUniqueId=[fpgaImageUniqueId] --targetRegion=[target region id]

示例代码

[user1@i**** ~]# ./faasutil copy_fpga_image --fpgaImageUniqueId=xilinx5395ad11-edb9-4d93-964d-12c59a07**** --targetRegion=cn-hangzhou
{
  "CreateTime": "2020-12-04 17:46:04",
  "Description": "",
  "FpgaImageUniqueId": "xilinx5395ad11-edb9-4d93-964d-12c59a07****",
  "Name": "faasutiltest-image",
  "RequestId": "3AAEC35C-2FB2-4DBA-A982-7A8219055D60",
  "ShellUniqueId": "f30010",
  "State": "committed"
}
0.309(s) elapsed

加载FPGA镜像

将FPGA镜像加载至FPGA设备。您可以运行list_instances命令查看FPGA实例的ID、FPGA设备的bdf;运行list_images命令查看FPGA镜像的UUID。

命令格式

faasutil download_image --bdf=[bdf] --fpgaImageUniqueId=[fpgaImageUniqueId] --instanceId=[instanceId] --owneralias=[owner]

示例代码

[user1@i**** ~]# ./faasutil download_image --bdf=00:09.0 --fpgaImageUniqueId=xilinx5395ad11-edb9-4d93-964d-12c59a07****
{"TaskId":45331,"RequestId":"073431C2-857A-470D-9543-D1D89FC10D54","FpgaImageUniqueId":"xilinx5395ad11-edb9-4d93-964d-12c59a07****","InstanceId":"i-uf616ov8zzwmiijb****","BDFInECS":"","TaskStatus":"committed"}
status               : operating
info                 : download task is operating
requestId            : x-84128618168241720
1.165(s) elapsed

查询FPGA镜像加载状态

查询FPGA镜像在FPGA设备上的加载状态。您可以运行list_instances命令查看FPGA设备的bdf,运行list_images命令查看FPGA镜像的UUID。

命令格式

faasutil download_status --bdf=[bdf] --fpgaImageUniqueId=[fpgaImageUniqueId] --owneralias=[owner]

示例代码

[user1@iZ**** ~]# ./faasutil download_status --bdf=00:09.0 --fpgaImageUniqueId=xilinx5395ad11-edb9-4d93-964d-12c59a07****
status               : done
info                 : download task finish
requestId            : x-42850294908763910
time                 : 2020-12-04 17:50:48
1.026(s) elapsed

删除FPGA镜像

删除不再需要的FPGA镜像。

说明

如果FPGA镜像已发布至镜像市场,必须指定--owneralias=market

命令格式

faasutil delete_image --fpgaImageUniqueId=[fpgaImageUniqueId] --owneralias=[owner]

示例代码

[user1@i**** ~]# ./faasutil delete_image --fpgaImageUniqueId=xilinxe27832a0-7c1c-4d6d-80b8-435253e9****
{
  "FpgaImageUniqueId": "xilinxe27832a0-7c1c-4d6d-80b8-435253e9****",
  "RequestId": "F2F481F5-B0E3-4009-9AF4-CF4BFC00458A"
}
0.157(s) elapsed

查看删除结果:

[user1@i**** ~]# ./faasutil list_images
{
  "FpgaImages": [],
  "RequestId": "30B73A5B-99FC-4920-8B90-4BA08A075040"
}
0.049(s) elapsed