# ma-cli image镜像构建支持的命令
ma-cli image命令支持：查询用户已注册的镜像、查询/加载镜像构建模板、Dockerfile镜像构建、查询/清理镜像构建缓存、注册/取消注册镜像、调试镜像是否可以在Notebook中使用等。具体命令及功能可执行**ma-cli image -h**命令查看。
#### 镜像构建命令总览
```
$ ma-cli image -h
Usage: ma-cli image [OPTIONS] COMMAND [ARGS]...
  Support get registered image list, register or unregister image, debug image, build image in Notebook.
Options:
  -H, -h, --help  Show this message and exit.
Commands:
  add-template, at  List build-in dockerfile templates.
  build             Build docker image in Notebook.
  debug             Debug SWR image as a Notebook in ECS.
  df                Query disk usage.
  get-image, gi     Query registered image in ModelArts.
  get-template, gt  List build-in dockerfile templates.
  prune             Prune image build cache.
  register          Register image to ModelArts.
  unregister        Unregister image from ModelArts.
```
表1镜像构建支持的命令 
| **命令**       | **命令详情**                                                    |
|:---|:---|
| get-template | 查询镜像构建模板。                                                   |
| add-template | 加载镜像构建模板。                                                   |
| get-image    | 查询ModelArts已注册镜像。                                           |
| register     | 注册SWR镜像到ModelArts镜像管理。                                      |
| unregister   | 取消注册ModelArts镜像管理中的已注册镜像。                                   |
| build        | 基于指定的Dockerfile构建镜像 （只支持ModelArts Notebook里使用）。             |
| df           | 查询镜像构建缓存（只支持ModelArts Notebook里使用）。                         |
| prune        | 清理镜像构建缓存 （只支持ModelArts Notebook里使用）。                        |
| debug        | 在ECS上调试SWR镜像是否能在ModelArts Notebook中使用 （只支持已安装docker环境的ECS）。 |
   
#### 使用ma-cli image get-template命令查询镜像构建模板
ma-cli提供了一些常用的镜像构建模板，模板中包含了在ModelArts Notebook上进行Dockerfile开发的牵引指导。
```
$ ma-cli image get-template -h
Usage: ma-cli image get-template [OPTIONS]
  List build-in dockerfile templates.
  Example:
  # List build-in dockerfile templates
  ma-cli image get-template [--filer <filter_info>]  [--page-num <yourPageNum>] [--page-size <yourPageSize>]
Options:
  --filter TEXT                   filter by keyword.
  -pn, --page-num INTEGER RANGE   Specify which page to query.  [x>=1]
  -ps, --page-size INTEGER RANGE  The maximum number of results for this query.  [x>=1]
  -D, --debug                     Debug Mode. Shows full stack trace when error occurs.
  -P, --profile TEXT              CLI connection profile to use. The default profile is "DEFAULT".
  -H, -h, --help                  Show this message and exit.
(PyTorch-1.4) [ma-user work]$
```
表2参数说明 
| **参数名**           | **参数类型** | **是否必选** | **参数说明**         |
|:---|:---|:---|:---|
| --filter          | String   | 否        | 根据模板名称关键字过滤模板列表。 |
| -pn / --page-num  | Int      | 否        | 镜像页索引，默认是第1页。    |
| -ps / --page-size | Int      | 否        | 每页显示的镜像数量，默认是20。 |
   
**示例**：查看镜像构建模板。
```
ma-cli image get-template
```
![](https://support.huaweicloud.com/devtool-modelarts/figure/zh-cn_image_0000001972740749.png "点击放大")
#### 使用ma-cli image add-template命令加载镜像构建模板
ma-cli可以使用**add-template**命令将镜像模板加载到指定文件夹下，默认路径为当前命令所在的路径。
比如${current_dir}/.ma/${template_name}/。也可以通过--dest命令指定保存的路径。当保存的路径已经有同名的模板文件夹时，可以使用--force \| -f参数进行强制覆盖。
```
$ ma-cli image add-template -h
Usage: ma-cli image add-template [OPTIONS] TEMPLATE_NAME
  Add buildin dockerfile templates into disk.
  Example:
  # List build-in dockerfile templates
  ma-cli image add-template customize_from_ubuntu_18.04_to_modelarts --force
Options:
  --dst TEXT          target save path.
  -f, --force         Override templates that has been installed.
  -D, --debug         Debug Mode. Shows full stack trace when error occurs.
  -P, --profile TEXT  CLI connection profile to use. The default profile is "DEFAULT".
  -h, -H, --help      Show this message and exit.
```
表3参数说明 
| **参数名**      | **参数类型** | **是否必选** | **参数说明**              |
|:---|:---|:---|:---|
| --dst        | String   | 否        | 加载模板到指定路径，默认是当前路径。    |
| -f / --force | Bool     | 否        | 是否强制覆盖已存在的同名模板，默认不覆盖。 |
   
**示例** ：加载**customize_from_ubuntu_18.04_to_modelarts**镜像构建模板。
```
ma-cli image add-template customize_from_ubuntu_18.04_to_modelarts
```
![](https://support.huaweicloud.com/devtool-modelarts/figure/zh-cn_image_0000001945741684.png "点击放大")
#### 使用ma-cli image get-image查询ModelArts已注册镜像
Dockerfile一般需要提供一个基础镜像的地址，目前支持从docker hub等开源镜像仓拉取公开镜像，以及SWR的公开或私有镜像。其中ma-cli提供了查询ModelArts预置镜像和用户已注册镜像列表及SWR地址。
```
$ma-cli image get-image -h
Usage: ma-cli image get-image [OPTIONS]
  Get registered image list.
  Example:
  # Query images by image type and only image id, show name and swr_path
  ma-cli image get-image --type=DEDICATED
  # Query images by image id
  ma-cli image get-image --image-id ${image_id}
  # Query images by image type and show more information
  ma-cli image get-image --type=DEDICATED -v
  # Query images by image name
  ma-cli image get-image --filter=torch
Options:
  -t, --type [BUILD_IN|DEDICATED|ALL]
                                  Image type(default ALL)
  -f, --filter TEXT               Image name to filter
  -v, --verbose                   Show detailed information on image.
  -i, --image-id TEXT             Get image details by image id
  -n, --image-name TEXT           Get image details by image name
  -wi, --workspace-id TEXT        The workspace where you want to query image(default "0")
  -pn, --page-num INTEGER RANGE   Specify which page to query  [x>=1]
  -ps, --page-size INTEGER RANGE  The maximum number of results for this query  [x>=1]
  -C, --config-file PATH          Configure file path for authorization.
  -D, --debug                     Debug Mode. Shows full stack trace when error occurs.
  -P, --profile TEXT              CLI connection profile to use. The default profile is "DEFAULT".
  -H, -h, --help                  Show this message and exit.
```
表4参数说明 
| **参数名**              | **参数类型** | **是否必选** | **参数说明**                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
|:---|:---|:---|:---|
| -t / --type          | String   | 否        | 查询的镜像类型，支持BUILD_IN、DEDICATED和ALL三种查询类型。 - BUILD_IN：预置镜像  - DEDICATED：用户已注册的自定义镜像  - ALL：所有镜像   |
| -f / --filter        | String   | 否        | 镜像名关键字。根据镜像名关键字过滤镜像列表。                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| -v / --verbose       | Bool     | 否        | 显示详细的信息开关，默认关闭。                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| -i / --image-id      | String   | 否        | 查询指定镜像ID的镜像详情。                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| -n / --image-name    | String   | 否        | 查询指定镜像名称的镜像详情。                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| -wi / --workspace-id | String   | 否        | 查询指定工作空间下的镜像信息。                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| -pn / --page-num     | Int      | 否        | 镜像页索引，默认是第1页。                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| -ps / --page-size    | Int      | 否        | 每页显示的镜像数量，默认是20。                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
   
**示例** **：**查询ModelArts已注册的自定义镜像。
```
ma-cli image get-image --type=DEDICATED
```
![](https://support.huaweicloud.com/devtool-modelarts/figure/zh-cn_image_0000002174052285.png "点击放大")
#### 使用ma-cli image build命令在ModelArts Notebook中进行镜像构建
使用**ma-cli image build**命令基于指定的Dockerfile进行镜像构建，仅支持在ModelArts Notebook里使用该命令。
```
$ ma-cli image build -h
Usage: ma-cli image build [OPTIONS] FILE_PATH
  Build docker image in Notebook.
  Example:
  # Build a image and push to SWR
  ma-cli image build .ma/customize_from_ubuntu_18.04_to_modelarts/Dockerfile -swr my_organization/my_image:0.0.1
  # Build a image and push to SWR, dockerfile context path is current dir
  ma-cli image build .ma/customize_from_ubuntu_18.04_to_modelarts/Dockerfile -swr my_organization/my_image:0.0.1 -context .
  # Build a local image and save to local path and OBS
  ma-cli image build .ma/customize_from_ubuntu_18.04_to_modelarts/Dockerfile --target ./build.tar --obs-path obs://bucket/object --swr-path my_organization/my_image:0.0.1
Options:
  -t, --target TEXT       Name and optionally a tag in the 'name:tag' format.
  -swr, --swr-path TEXT   SWR path without swr endpoint, eg:organization/image:tag.  [required]
  --context DIRECTORY     build context path.
  -arg, --build-arg TEXT  build arg for Dockerfile.
  -obs, --obs-path TEXT   OBS path to save local built image.
  -f, --force             Force to overwrite the existing swr image with the same name and tag.
  -C, --config-file PATH  Configure file path for authorization.
  -D, --debug             Debug Mode. Shows full stack trace when error occurs.
  -P, --profile TEXT      CLI connection profile to use. The default profile is "DEFAULT".
  -H, -h, --help          Show this message and exit.
```
表5参数说明 
| **参数名**            | **参数类型** | **是否必选** | **参数说明**                                                           |
|:---|:---|:---|:---|
| FILE_PATH          | String   | 是        | Dockerfile文件所在的路径。                                                 |
| -t / --target      | String   | 否        | 表示构建生成的tar包保存在本地的路径，默认是当前文件夹目录。                                    |
| -swr / --swr-path  | String   | 是        | SWR镜像名称，遵循organization/image_name:tag格式，针对于构建保存tar包场景可以省略。         |
| --context          | String   | 否        | Dockerfile构建时的上下文信息路径，主要用于数据复制。                                    |
| -arg / --build-arg | String   | 否        | 指定构建参数，多个构建参数可以使用--build-arg VERSION=18.04 --build-arg ARCH=X86_64 |
| -obs / --obs-path  | String   | 否        | 将生成的tar包自动上传到OBS中。                                                 |
| -f / --force       | Bool     | 否        | 是否强制覆盖已存在的SWR镜像，默认不覆盖。                                             |
   
**示例**：在ModelArts Notebook里进行镜像构建。
```
ma-cli image build .ma/customize_from_ubuntu_18.04_to_modelarts/Dockerfile -swr notebook_test/my_image:0.0.1
```
其中".ma/customize_from_ubuntu_18.04_to_modelarts/Dockerfile"为Dockerfile文件所在路径，"notebook_test/my_image:0.0.1"为构建的新镜像的SWR路径。
![](https://support.huaweicloud.com/devtool-modelarts/figure/zh-cn_image_0000001945582352.png "点击放大")
#### 使用ma-cli image df命令在ModelArts Notebook中查询镜像构建缓存
使用**ma-cli image df**命令查询镜像构建缓存，仅支持在ModelArts Notebook里使用该命令。
```
$ ma-cli image df -h
Usage: ma-cli image df [OPTIONS]
  Query disk usage used by image-building in Notebook.
  Example:
  # Query image disk usage
  ma-cli image df
Options:
  -v, --verbose       Show detailed information on disk usage.
  -D, --debug         Debug Mode. Shows full stack trace when error occurs.
  
  -h, -H, --help      Show this message and exit.
```
表6参数说明 
| **参数名**        | **参数类型** | **是否必选** | **参数说明**        |
|:---|:---|:---|:---|
| -v / --verbose | Bool     | 否        | 显示详细的信息开关，默认关闭。 |
   
**示例** ：在ModelArts Notebook里查看所有镜像缓存。
```
ma-cli image df
```
![](https://support.huaweicloud.com/devtool-modelarts/figure/zh-cn_image_0000001972860505.png "点击放大")
**示例** ：显示镜像缓存占用磁盘的详细信息。
```
ma-cli image df --verbose
```
![](https://support.huaweicloud.com/devtool-modelarts/figure/zh-cn_image_0000001945741680.png "点击放大")
#### 使用ma-cli image prune命令在ModelArts Notebook中清理镜像构建缓存
使用**ma-cli image prune**命令清理镜像构建缓存，仅支持在ModelArts Notebook里使用该命令。
```
$ ma-cli image prune -h
Usage: ma-cli image prune [OPTIONS]
  Prune image build cache by image-building in Notebook.
  Example:
  # Prune image build cache
  ma-cli image prune
Options:
  -ks, --keep-storage INTEGER  Amount of disk space to keep for cache below this limit (in MB) (default: 0).
  -kd, --keep-duration TEXT    Keep cache newer than this limit, support second(s), minute(m) and hour(h) (default:   0s).
  -v, --verbose                Show more verbose output.
  -D, --debug                  Debug Mode. Shows full stack trace when error occurs.  
  -h, -H, --help               Show this message and exit.
```
表7参数说明 
| **参数名**               | **参数类型** | **是否必选** | **参数说明**                                               |
|:---|:---|:---|:---|
| -ks / --keep-storage  | Int      | 否        | 清理缓存时保留的缓存大小，单位是MB，默认是0，表示全部清理。                        |
| -kd / --keep-duration | String   | 否        | 清理缓存时保留较新的缓存，只清除历史缓存，单位为s（秒）、m（分钟）、h（小时），默认是0s，表示全部清理。 |
| -v / --verbose        | Bool     | 否        | 显示详细的信息开关，默认关闭。                                        |
   
**示例**：清理保留1MB镜像缓存。
```
ma-cli image prune -ks 1
```
![](https://support.huaweicloud.com/devtool-modelarts/figure/zh-cn_image_0000001972860509.png "点击放大")
#### 使用ma-cli image register命令注册SWR镜像到ModelArts镜像管理
调试完成后，使用**ma-cli image register**命令将新镜像注册到ModelArts镜像管理服务中，进而在能够在ModelArts中使用该镜像。
```
$ma-cli image register -h
Usage: ma-cli image register [OPTIONS]
  Register image to ModelArts.
  Example:
  # Register image into ModelArts service
  ma-cli image register --swr-path=xx
  # Share SWR image to DLI service
  ma-cli image register -swr xx -td
  # Register image into ModelArts service and specify architecture to be 'AARCH64'
  ma-cli image register --swr-path=xx --arch AARCH64
Options:
  -swr, --swr-path TEXT           SWR path without swr endpoint, eg:organization/image:tag.  [required]
  -a, --arch [X86_64|AARCH64]     Image architecture (default: X86_64).
  -s, --service [NOTEBOOK|MODELBOX]
                                  Services supported by this image(default NOTEBOOK).
  -rs, --resource-category [CPU|GPU|ASCEND]
                                  The resource category supported by this image (default: CPU and GPU).
  -wi, --workspace-id TEXT        The workspace to register this image (default: "0").
  -v, --visibility [PUBLIC|PRIVATE]
                                  PUBLIC: every user can use this image. PRIVATE: only image owner can use this image (Default: PRIVATE).
  -td, --to-dli                   Register swr image to DLI, which will share SWR image to DLI service.
  -d, --description TEXT          Image description (default: "").
  -C, --config-file PATH          Configure file path for authorization.
  -D, --debug                     Debug Mode. Shows full stack trace when error occurs.
  -P, --profile TEXT              CLI connection profile to use. The default profile is "DEFAULT".
  -h, -H, --help                  Show this message and exit.
```
表8参数说明 
| **参数名**                   | **参数类型** | **是否必选** | **参数说明**                                                                                                                 |
|:---|:---|:---|:---|
| -swr / --swr-path         | String   | 是        | 需要注册的镜像的SWR路径。                                                                                                           |
| -a / --arch               | String   | 否        | 注册镜像的架构，X86_64或者AARCH64，默认是X86_64。                                                                                       |
| -s / --service            | String   | 否        | 注册镜像的服务类型，NOTEBOOK或者MODELBOX，默认是NOTEBOOK。 可以输入多个值，如-s NOTEBOOK -s MODELBOX。 |
| -rs / --resource-category | String   | 否        | 注册镜像能够使用的资源类型，默认是CPU和GPU。                                                                                                |
| -wi / --workspace-id      | String   | 否        | 注册镜像到指定的工作空间，workspace ID默认是0。                                                                                           |
| -v / --visibility         | Bool     | 否        | 注册的镜像可见性，PRIVATE（仅自己可见）或者PUBLIC（所有用户可见），默认是PRIVATE。                                                                      |
| -td / --to-dli            | Bool     | 否        | 注册镜像到DLI服务。                                                                                                              |
| -d/ --description         | String   | 否        | 填写镜像描述，默认为空。                                                                                                             |
   
**示例**：注册SWR镜像到ModelArts。
```
ma-cli image register --swr-path=xx
```
![](https://support.huaweicloud.com/devtool-modelarts/figure/zh-cn_image_0000001945582356.png "点击放大")
#### 使用ma-cli image unregister命令取消已注册的镜像
使用**ma-cli image unregister**命令将注册的镜像从ModelArts中删除。
```
$ ma-cli image unregister -h
Usage: ma-cli image unregister [OPTIONS]
  Unregister image from ModelArts.
  Example:
  # Unregister image
  ma-cli image unregister --image-id=xx
  # Unregister image and delete it from swr
  ma-cli image unregister --image-id=xx -d
Options:
  -i, --image-id TEXT     Unregister image details by image id.  [required]
  -d, --delete-swr-image  Delete the image from swr.
  -C, --config-file PATH  Configure file path for authorization.
  -D, --debug             Debug Mode. Shows full stack trace when error occurs.
  -P, --profile TEXT      CLI connection profile to use. The default profile is "DEFAULT".
  -h, -H, --help          Show this message and exit.
```
表9参数说明 
| **参数名**                 | **参数类型** | **是否必选** | **参数说明**               |
|:---|:---|:---|:---|
| -i / -image-id          | String   | 是        | 需要取消注册的镜像ID。           |
| -d / --delete-swr-image | Bool     | 否        | 取消注册后同步删除SWR镜像开关，默认关闭。 |
   
#### 在ECS上调试SWR镜像是否能在ModelArts Notebook中使用
ma-cli支持在ECS上调试SWR镜像是否可以在ModelArts开发空间中运行，发现镜像中可能存在的问题。
![](https://support.huaweicloud.com/devtool-modelarts/figure/zh-cn_image_0000001972740753.png "点击放大")
表10参数说明 
| **参数名**           | **参数类型** | **是否必选** | **参数说明**                                  |
|:---|:---|:---|:---|
| -swr / --swr-path | String   | 是        | 需要调试的镜像的SWR路径。                            |
| -r / --region     | String   | 是        | 需要调试的镜像所在的区域。                             |
| -s / --service    | String   | 否        | 调试镜像的服务类型，NOTEBOOK或者MODELBOX，默认是NOTEBOOK。 |
| -a / --arch       | String   | 否        | 调试镜像的架构，X86_64或者AARCH64，默认是X86_64。        |
| -g / --gpu        | Bool     | 否        | 使用GPU进行调试开关，默认关闭。                         |