如何使用faasutil工具？_FPGA云服务器(FaaS)-阿里云帮助中心

本文主要介绍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支持的命令主要用于获取帮助信息、配置环境以及管理FPGA镜像等，相关内容如下所示：

查看所有命令

查看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.0、00: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镜像的FpgaImageUniqueId和State参数值。

如果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

用途	相关文档
获取帮助信息	查看所有命令查看指定命令
配置环境	配置用户信息添加OSS Bucket读权限查看OSS Bucket读权限删除OSS Bucket读权限获取FPGA实例的信息获取FPGA设备的状态信息上传文件至OSS Bucket 查看OSS Bucket中的文件下载文件到FPGA实例
管理FPGA镜像	创建FPGA镜像编译任务查询编译Log 查看FPGA镜像修改FPGA镜像的信息绑定FPGA镜像和ECS镜像跨地域拷贝FPGA镜像加载FPGA镜像查询FPGA镜像加载状态删除FPGA镜像