如何使用faasutil工具？ - FPGA as a Service

本文主要介紹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鏡像