镜像构建服务支持的命令

镜像构建服务通过镜像模板实现对镜像内容的定制，镜像模板可以通过指定镜像组件或直接指定命令来创建，镜像组件本质是由一条或多条命令构成，因此最小单元是命令。本文提供了镜像构建服务的常用命令格式和示例供您参考。

命令语法说明

镜像构建服务支持YAML（适用于Linux和Windows）和Dockerfile（仅适用于Linux）两种格式的命令。

说明

使用Dockerfile格式的命令不够灵活且有操作系统限制，推荐您使用YAML格式。

YAML和Dockerfile两种格式的语法要求如下：

YAML：需要定义Parameters和Tasks，语法如下。

Parameters: # 用于定义自定义参数，可选
  param1: # 参数名，必填
    Type: String # 参数类型，必填，String/Number/Boolean之一
    DefaultValue: defaultValue #参数默认值，选填，当参数没有默认值时，使用的组件的模板需要显式传入
Tasks: # 用于定义组件的任务列表，依次执行, 至少包含一个task
  - Name: taskName1 # 任务名称，必填
    Action: RunShellCommand # 任务的动作，必填，可以参考YAML格式组件命令集
    Properties: # 动作参数，取决于具体选用的action
      commandContent: echo {{ param1 }} # 引用自定义参数
  - Name: taskName2
    Action: action2
    Properties:
      action2Property1: {{ taskName1.stdout }} # 引用taskName1的输出

说明

您可以在Tasks字段的属性内引用上述定义的参数。引用的语法如下：

{{taskName1.stdout}}

Dockerfile
- 每行一条命令。
- 同一个命令允许设置多行，换行需要在前一行的末尾添加换行符（\）。

镜像构建服务在控制台和API分别创建组件时，组件支持的命令格式说明如下。

组件命令（控制台和API均支持）

（推荐）YAML格式

命令	命令格式或示例	说明	输出
RunShellCommand	`Name: String Action: RunShellCommand Properties: commandContent: String #命令内容 workingDir: String,optional #运行目录 username: String,optional #执行命令的用户名称`	执行Shell脚本。仅适用于Linux系统。	`stdout: String#对应命令的执行输出`
RunPowerShellCommand	`Name: String Action: RunPowerShellCommand Properties: commandContent: String #命令内容 workingDir: String,optional #运行目录 username: String,optional #执行命令的用户名称 windowsPasswordName: String,optional #在Windows实例中执行命令的用户的密码名称`	执行PowerShell脚本。仅适用于Windows系统。
InvokeCommand	`Name: String Action: InvokeCommand Properties: commandId: String #命令ID username: String,optional #执行命令的用户名称 parameters: Json,optional #自定义参数的键值对`	执行一条公共命令。
OSSDownload	`Name: String Action: OSSDownload Properties: bucketName: String #OSS bucket名称 destinationDir: String #本地文件夹 objectName: String # OSS对象名称 ossRegion: String,optional # OSS地域 validTime: Number,optional #OSS文件链接有效期`	从OSS上下载文件到ECS实例。使用的Bucket必须要有allowImageBuilderAccess:true的标签。	无
OSSUpload	`Name: String Action: OSSUpload Properties: bucketName: String #OSS bucket名称 fileToUpload: String #本地文件路径 objectName: String # OSS对象名称 ossRegion: String,optional # OSS地域 validTime: Number,optional #OSS文件链接有效期`	上传实例文件到OSS上。使用的Bucket必须要有allowImageBuilderAccess:true的标签。
WebDownload	`Name: String Action: WebDownload Properties: sourcePath: String # 网络文件url tokenInfo: String,optional # 指定一个token来下载文件，只有从GitHub下载文件时会用到 destinationDir: String # 文件在实例中的下载目录 timeout: Number,option,default=600 # 超时时间`	从网络上下载文件。
Reboot	`Name: String Action: Reboot Properties: forceStop: Boolean,optional,default=false #是否强制重启`	重启服务器。

Dockerfile格式

命令	命令格式或示例	说明
RESTART	`RESTART`	重启服务器。该命令后不允许添加任何内容。
RUN	`RUN echo hello;\ echo world;`	镜像构建。同一个命令允许设置多行，换行需要在前一行的末尾添加换行符（\）。
ENV	`ENV key value` `ENV key1="value1" key2="value2"`	系统变量配置。命令以键值对的形式。说明使用`ENV key1="value1" key2="value2"`命令格式时，不能缺失双引号。
WORKDIR	`WORKDIR /<path>` `WORKDIR <path1>/<path2>`	设置工作目录。
COPY	`COPY <网络文件地址> 本地目录` `COPY <本地文件路径> 本地目录`	复制文件。说明网络文件统一使用`wget`下载，并且暂不支持`query string`，请确保中转实例可以访问公网。
USER	`USER <username>`	设置执行命令的用户。说明变量`<username>`必须是系统中已存在的用户，否则执行命令将会报错。
LABEL	`LABEL user="username"\ date="2020-11-11" key="value"`	定义模板元信息。同一个命令允许设置多行，换行需要在前一行的末尾添加换行符（\）。
CMD	`CMD ["executable","param1","param2"]` `CMD command param1 param2`	开机自启动。
ENTRYPOINT	`ENTRYPOINT ["executable","param1","param2"]` `CMD command param1 param2`	开机自启动。说明 `CMD`和`ENTRYPOINT`均是用来指定容器启动时执行的命令，它们有不同的使用场景和特性，可以单独使用，也可以组合使用以达到更灵活的效果。关于CMD与ENTRYPOINT命令的区别，请参见Dockerfile reference。

模板命令（Dockerfile格式，仅API支持）

命令	命令格式或示例	说明
COMPONENT	`COMPONENT ic-bp18hy47cqavewsb**` `COMPONENT ic-bp18hy47cqavewsb** --paramName1 paramValue1 --paramName2 paramValue2` `COMPONENT acs:ecs:<RegionId>:<AliUid>:imagecomponent/<ComponentName>:<major>.<minor>.<patch>` 说明其中<major>、<minor>、<patch>中的任意一项都可以使用*作为通配符替代，选取版本最高的组件。	指定镜像组件，支持指定系统组件或您创建的自定义组件。该命令仅适用于镜像模板。当您创建镜像模板时，可以使用该命令，以一个或多个镜像组件拼装的方式快速完成镜像模板的定义。支持调用YAML格式和Dockerfile格式的组件。
RESTART	`RESTART`	重启服务器。该命令后不允许添加任何内容。
RUN	`RUN echo hello;\ echo world;`	镜像构建。同一个命令允许设置多行，换行需要在前一行的末尾添加换行符（\）。仅支持Linux系统。
ENV	`ENV key value` `ENV key1="value1" key2="value2"`	系统变量配置。命令以键值对的形式。仅支持Linux系统。说明使用`ENV key1="value1" key2="value2"`命令格式时，不能缺失双引号。
WORKDIR	`WORKDIR /<path>` `WORKDIR <path1>/<path2>`	设置工作目录。仅支持Linux系统。
COPY	`COPY <网络文件地址> 本地目录` `COPY <本地文件路径> 本地目录`	复制文件。仅支持Linux系统。说明网络文件统一使用`wget`下载，并且暂不支持`query string`，请确保中转实例可以访问公网。
USER	`USER <username>`	设置执行命令的用户。仅支持Linux系统。说明变量`<username>`必须是系统中已存在的用户，否则执行命令将会报错。
LABEL	`LABEL user="username"\ date="2020-11-11" key="value"`	定义模板元信息。同一个命令允许设置多行，换行需要在前一行的末尾添加换行符（\）。仅支持Linux系统。
CMD	`CMD ["executable","param1","param2"]` `CMD command param1 param2`	开机自启动。仅支持Linux系统。
ENTRYPOINT	`ENTRYPOINT ["executable","param1","param2"]` `CMD command param1 param2`	开机自启动。仅支持Linux系统。说明 `CMD`和`ENTRYPOINT`均是用来指定容器启动时执行的命令，它们有不同的使用场景和特性，可以单独使用，也可以组合使用以达到更灵活的效果。关于CMD与ENTRYPOINT命令的区别，请参见Dockerfile reference。

组件命令示例

您在创建镜像组件时可以选择构建组件（Build）或测试组件（Test），可以直接拷贝如下示例模板命令并根据实际业务场景进行修改。

构建组件（Build）用于自定义您的镜像内容，只能在构建模板中使用。
测试组件（Test）用于测试您的镜像是否符合预期，只能在测试模板中使用。

构建组件（Build）

Linux系统

Parameters:
  message:
    Type: String
    DefaultValue: hello world
Tasks:
  - Name: HelloWorld
    Action: RunShellCommand
    Properties:
      commandContent: echo {{messgae}}
  - Name: HelloWorldAgain
    Action: RunShellCommand
    Properties:
      commandContent: echo {{HelloWorld.stdout}}

Windows系统

Parameters:
  message:
    Type: String
    DefaultValue: hello world
Tasks:
  - Name: HelloWorld
    Action: RunPowerShellCommand
    Properties:
      commandContent: echo {{messgae}}
  - Name: HelloWorldAgain
    Action: RunPowerShellCommand
    Properties:
      commandContent: echo {{HelloWorld.stdout}}

测试组件（Test）

Linux系统

Parameters:
  message:
    Type: String
    DefaultValue: hello world
Tasks:
  - Name: HelloWorld
    Action: RunShellCommand
    Properties:
      commandContent: echo {{messgae}}
  - Name: HelloWorldAgain
    Action: RunShellCommand
    Properties:
      commandContent: |-
        echo {{HelloWorld.stdout}}
        exit 0

Windows系统

Parameters:
  message:
    Type: String
    DefaultValue: hello world
Tasks:
  - Name: HelloWorld
    Action: RunPowerShellCommand
    Properties:
      commandContent: echo {{messgae}}
  - Name: HelloWorldAgain
    Action: RunPowerShellCommand
    Properties:
      commandContent: |-
        echo {{HelloWorld.stdout}}
        exit 0