This topic describes how to use faasutil commands. This topic also provides examples for these commands.
Prerequisites
- faasutil is obtained. For more information, see Obtain faasutil.
- A raw file is prepared. For more information, see the term description in the Context section in this topic.
- An Object Storage Service (OSS) bucket is created. The bucket is used to upload raw files. For more information, see Create buckets.
- An AccessKey pair is created for a Resource Access Management (RAM) user. For more
information, see Create an AccessKey pair.
Note FaaS supports only the AccessKey pair of RAM users. You can only access Functions as a Service (FaaS) using the Accesskey pair as an RAM user. This minimizes the risk that the AccessKey pair is exposed.
Background information
- FPGA-accelerated instance: the FPGA-accelerated instance that you create by using the Alibaba Cloud console or calling API operations. FPGA-accelerated instances include computing resources, Elastic Compute Service (ECS) images, and disks.
- ECS image: the image used by an FPGA-accelerated instance. FPGA-accelerated instances provide FPGA acceleration capabilities and the same user experience as regular ECS instances.
- Raw file: the acceleration program that you developed for FPGA devices and is used to compile and generate FPGA images. For example, the raw file of an Intel FPGA is in the .gbs format. The raw file of a Xilinx FPGA is a tar package that is generated from processed scripts.
- FPGA image: the image used by an FPGA device. A raw file is compiled to generate an FPGA image. After you load the FPGA image to an FPGA device, the FPGA device can provide acceleration services based on your design. Each FPGA image has a UUID.
- Use the following method to run faasutil commands:
./faasutil [command]
. - faasutil commands and their parameters are case-sensitive. For example, errors occur
when you run the
./faasutil Create_Image --Object=faasutiltest-forcompiling.tar.gz --Shell=f30010 --FPGAType=xilinx --Name=faasutiltest-image
command. The command and its parameters must be spelled in the same way as they are defined. - Make sure that no spaces exist between parameters, equal signs (=), and values. For
example, error occurs when you run the
./faasutil create_image --object=faasutiltest-forcompiling.tar.gz --shell = f30010 --fpgatype=xilinx --name=faasutiltest-image
command. You must remove the spaces before and after the equal sign (=
) of the shell parameter.
- Obtain help information
- Configure the environment
- Configure user information
- Grant the read permissions on OSS buckets
- View the read permissions on OSS buckets
- Delete the read permissions on OSS buckets
- Obtain information about FPGA-accelerated instances
- Obtain the status information of an FPGA device
- Upload files to an OSS bucket
- View files in an OSS bucket
- Download files to an FPGA-accelerated instance
- Manage FPGA images
View all commands
View the faasutil version and the list of commands.
faasutil --help
faasutil -h
[root@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.
View specified commands
View the description of specified commands and their parameters.
faasutil [command name] --help
faasutil [command name] -h
[root@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.
Configure user information
- AccessKey ID and AccessKey secret: required. The AccessKey ID and AccessKey secret are used for authentication.
- OSS bucket name: optional. The name of the OSS bucket to which raw files are uploaded. We recommend that you specify this parameter. This way, you do not need to enter the OSS bucket name when you run commands that require this parameter.
faasutil config --id=[accessid] --key=[accesskey] --token=[sts-token] --bucket=[bucket] --regionId=[regionId] --ossEndpoint=[ossEndpoint] --popEndpoint=[popEndpoint]
[root@i**** ~]# ./faasutil config --id=L**** --key=v**** --bucket=yk****
Your configuration is saved into /root/.faascredentials .
1.057(s) elapsed
Grant the read permissions on OSS buckets
Grant the read permissions on OSS buckets for FPGA-accelerated instances to read files from OSS buckets.
faasutil auth
[root@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
View the read permissions on OSS buckets
View the granted read permissions on OSS buckets.
faasutil list_policy
[root@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
Delete the read permissions on OSS buckets
Delete the read permissions on OSS buckets to prohibit FPGA-accelerated instances from reading files from OSS buckets.
faasutil delete_policy
[root@i**** ~]# ./faasutil delete_policy
0.210(s) elapsed
Obtain information about FPGA-accelerated instances
Obtain information about FPGA-accelerated instances, such as instance IDs, ECS images, and attached FPGA devices.
faasutil list_instances
[root@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
In this example, an FPGA-accelerated instance is attached with two FPGA devices whose bdf is set to 00:09.0 and 00:08.0.
Obtain the status information of an FPGA device
Obtain the status information based on bdf of an FPGA device. You can run the list_instances command to view bdf of an FPGA device.
faasutil fpga_status --bdf=[bdf]
[root@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
This example shows the status information of an FPGA device whose bdf is set to 00:09.0. imageuuid specifies the UUID of the specified FPGA image. For a newly purchased FPGA-accelerated instance, the value of imageuuid is null.
Upload files to an OSS bucket
Upload files such as raw files on an FPGA-accelerated instance to an OSS bucket.
faasutil put_object --bucket=[bucket_name] --object=[object_name] --file=[file_name]
- [bucket_name]: the name of the OSS bucket.
Note If you have run the config command to specify an OSS bucket in the default configuration file, you do not need to specify the bucket parameter.
- [file_name]: the name of the file to be uploaded.
- [object_name]: the displayed name of the uploaded file in the OSS bucket.
[root@i**** ~]# ./faasutil put_object --object=faasutiltest-forcompiling.tar.gz --file=faasutiltest.tar.gz
100%
539.171(s) elapsed
View files in an OSS bucket
View files in an OSS bucket.
faasutil list_objects
[root@i**** ~]# ./faasutil list_objects
faasutiltest-forcompiling.tar.gz
0.288(s) elapsed
Download files to an FPGA-accelerated instance
Download files from an OSS bucket to an FPGA-accelerated instance.
faasutil get_object --bucket=[bucket_name] --object=[object_name] --file=[file_name]
- [bucket_name]: the name of the OSS bucket.
Note If you have run the config command to specify an OSS bucket in the default configuration file, you do not need to specify the bucket parameter.
- [file_name]: the name of the file to be downloaded.
- [object_name]: the displayed name of the downloaded file in the FPGA-accelerated instance.
[root@i**** ~]# ./faasutil get_object --object=faasutiltest-forcompiling.tar.gz --file=faasutiltest-fordeveloping.tar.gz
100%
179.909(s) elapsed
Create tasks to compile FPGA images
faasutil create_image --object=[object_name] --shell=[shell_ver] --fpgatype=[fpga_type]
- [object_name]: the name of the raw file used for compilation. Make sure that the raw file has been uploaded to the OSS bucket.
- [shell_ver]: the shell version of the FPGA device. You can run the fpga_status command to view the shell version of the FPGA device.
- [fpga_type]: the type of the FPGA device. Xilinx FPGAs (xilinx) and Intel FPGAs (intel) are supported. Specify this parameter based on the type of your FPGA device.
[root@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
This example shows that the FpgaImageUniqueId parameter is returned for an FPGA image after an FPGA image compilation task is created. In this example, the value of State is queueing, which indicates that the task is waiting for compilation. You can run the list_images command and view the status of the task to which FpgaImageUniqueId corresponds. When State becomes success, the compilation is complete.
Query compilation logs
Query the logs generated when the specified FPGA image compilation task is executed. [fpgaImageUniqueId] specifies the UUID of an FPGA image returned after an FPGA image compilation task is created.
faasutil query_log --fpgaImageUniqueId=[fpgaImageUniqueId]
[root@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
-internal
from the URL.
View FPGA images
View existing FPGA images. You can filter images by image owner. [owner] specifies the image owner. Alibaba Cloud Marketplace images (market) and local images (self) are supported.
faasutil list_images --owneralias=[owner]
[root@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
Modify FPGA image information
Modify the information of an existing FPGA image, such as its name and description.
faasutil modify_image --fpgaImageUniqueId=[fpgaImageUniqueId] --name=[name] --description=[description] --tags=[tags]
[root@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": ""
}
[root@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
Bind FPGA images to ECS images
After you bind FPGA images to ECS images, you can publish the ECS images to Alibaba Cloud Marketplace. When your ECS images are used by another user, the user can also use the FPFA images bound to the ECS images.
faasutil bind_image --fpgaImageUniqueId=[fpgaImageUniqueId] --ecsImageId=[ecsImageId]
- [fpgaImageUniqueId]: the UUID of the FPGA image.
- [ecsImageId]: the ID of the ECS image. By default, the ID of the ECS image on the current FPGA-accelerated instance is used.
[root@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
Copy FPGA images across regions
If you want to use an existing FPGA image in a new region, you do not need to create a new image compilation task in this region. You can copy the existing FPGA image to this region.
faasutil copy_fpga_image --fpgaImageUniqueId=[fpgaImageUniqueId] --targetRegion=[target region id]
[root@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
Load FPGA images
Load FPGA images to FPGA devices. You can run the list_instances command to view the ID of an FPGA-accelerated instance and bdf of an FPGA device. You can run the list_images command to view the UUID of an FPGA image.
faasutil download_image --bdf=[bdf] --fpgaImageUniqueId=[fpgaImageUniqueId] --instanceId=[instanceId] --owneralias=[owner]
[root@i**** ~]# ./faasutil download_image --bdf=00:09.0 --fpgaImageUniqueId=xilinx5395ad11-edb9-4d93-964d-12c59a07****
null
status : operating
info : download task is operating
requestId : x-84128618168241720
1.165(s) elapsed
Query the loading status of FPGA images
Query the loading status of FPGA images on FPGA devices. You can run the list_instances command to view bdf of an FPGA device or run the list_images command to view the UUID of an FPGA image.
faasutil download_status --bdf=[bdf] --fpgaImageUniqueId=[fpgaImageUniqueId] --owneralias=[owner]
[root@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
Delete FPGA images
--owneralias=market
.
faasutil delete_image --fpgaImageUniqueId=[fpgaImageUniqueId] --owneralias=[owner]
[root@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
[root@i**** ~]# ./faasutil list_images
{
"FpgaImages": [],
"RequestId": "30B73A5B-99FC-4920-8B90-4BA08A075040"
}
0.049(s) elapsed