Commands supported by Image Builder-Elastic Compute Service(ECS)-阿里云帮助中心

Image Builder uses an image template to customize image content. You can create an image template by specifying image components or by defining commands directly. An image component consists of one or more commands, making a command the most basic unit. This topic describes the syntax of Image Builder commands and provides examples.

Command syntax

Image Builder supports commands in two formats: YAML (for Linux and Windows) and Dockerfile (for Linux only).

Note

Dockerfile commands offer less flexibility and have operating system limitations. We recommend that you use the YAML format.

The following syntax is required for the YAML and Dockerfile formats:

YAML: You must define the Parameters and Tasks sections. The syntax is as follows:

Parameters: # Optional. Defines custom parameters.
  param1: # Required. The name of the parameter.
    Type: String # Required. The type of the parameter. Valid values: String, Number, and Boolean.
    DefaultValue: defaultValue # Optional. The default value of the parameter. If no default value is specified, you must explicitly pass a value when you use the image component in an image template.
Tasks: # Required. Defines a list of tasks for the image component. The tasks are run in sequence. At least one task must be included.
  - Name: taskName1 # Required. The name of the task.
    Action: RunShellCommand # Required. The action for the task. For more information, see the YAML-format component commands.
    Properties: # The properties of the action. The available properties depend on the specified action.
      commandContent: echo {{ param1 }} # References a custom parameter.
  - Name: taskName2
    Action: action2
    Properties:
      action2Property1: {{ taskName1.stdout }} # References the output of taskName1.

Note

You can reference defined parameters in the properties of a task as follows:

{{taskName1.stdout}}

Dockerfile
- Each line contains one command.
- A single command can span multiple lines. To continue a command on the next line, add an escape character (\) at the end of the current line.

Commands supported by Image Builder

This section describes the command formats that Image Builder supports for creating an image component in the console or via the API.

Component commands

YAML format

Command	Syntax	Description	Output
RunShellCommand	`Name: String Action: RunShellCommand Properties: commandContent: String # The command to run. workingDir: String,optional # The working directory. username: String,optional # The user to run the command.`	Runs a shell script. For Linux operating systems only.	`stdout: String # The standard output of the command.`
RunPowerShellCommand	`Name: String Action: RunPowerShellCommand Properties: commandContent: String # The command to run. workingDir: String,optional # The working directory. username: String,optional # The user to run the command. windowsPasswordName: String,optional # The name of the password for the user that runs commands in a Windows instance.`	Runs a PowerShell script. For Windows operating systems only.
InvokeCommand	`Name: String Action: InvokeCommand Properties: commandId: String # The ID of the command. username: String,optional # The user to run the command. parameters: Json,optional # The key-value pairs of custom parameters.`	Runs a common command.
OSSDownload	`Name: String Action: OSSDownload Properties: bucketName: String # The name of the OSS bucket. destinationDir: String # The destination folder in the instance. objectName: String # The name of the OSS object. ossRegion: String,optional # The region of the OSS bucket. validTime: Number,optional # The validity period of the OSS file link in seconds.`	Downloads a file from OSS to an ECS instance. The bucket must have the tag `allowImageBuilderAccess:true`.	None
OSSUpload	`Name: String Action: OSSUpload Properties: bucketName: String # The name of the OSS bucket. fileToUpload: String # The path to the local file. objectName: String # The name of the OSS object. ossRegion: String,optional # The region of the OSS bucket. validTime: Number,optional # The validity period of the OSS file link in seconds.`	Uploads a file from an instance to OSS. The bucket must have the tag `allowImageBuilderAccess:true`.
WebDownload	`Name: String Action: WebDownload Properties: sourcePath: String # The URL of the web file. tokenInfo: String,optional # A token for downloading the file. This property is used only when you download files from GitHub. destinationDir: String # The download directory in the instance. timeout: Number,optional,default=600 # The timeout period in seconds.`	Downloads a file from a web URL.
Reboot	`Name: String Action: Reboot Properties: forceStop: Boolean,optional,default=false # Specifies whether to forcibly reboot the instance.`	Reboots the instance.

Dockerfile format

Command	Syntax	Description
RESTART	`RESTART`	Reboots the instance. No content is allowed after this command.
RUN	`RUN echo hello;\ echo world;`	Runs a command in a new layer. A single command can span multiple lines. To continue a command on the next line, add an escape character (\) at the end of the current line.
ENV	`ENV key value` `ENV key1="value1" key2="value2"`	Configures system environment variables. The command uses a key-value pair format. Note When you use the `ENV key1="value1" key2="value2"` format, do not omit the double quotation marks (").
WORKDIR	`WORKDIR /<path>` `WORKDIR <path1>/<path2>`	Sets the working directory.
COPY	`COPY <source_web_file_URL> <destination_directory>` `COPY <source_local_file_path> <destination_directory>`	Copies files. Note All network files are downloaded using `wget`, which does not currently support `query string`s. Ensure that the intermediate instance can access the public network.
USER	`USER <username>`	Sets the user for subsequent `RUN`, `CMD`, and `ENTRYPOINT` instructions. Note The `<username>` must be an existing user in the operating system. Otherwise, an error occurs when the command runs.
LABEL	`LABEL user="username"\ date="2020-11-11" key="value"`	Adds metadata to the image. A single command can span multiple lines. To continue a command on the next line, add an escape character (\) at the end of the current line.
CMD	`CMD ["executable","param1","param2"]` `CMD command param1 param2`	Specifies the command to run on startup.
ENTRYPOINT	`ENTRYPOINT ["executable","param1","param2"]` `CMD command param1 param2`	Specifies the command to run on startup. Note The `CMD` and `ENTRYPOINT` instructions both specify the command to run when a container starts. They have different use cases and features, and can be used separately or in combination for greater flexibility. For more information about their differences, see Dockerfile reference.

Template commands

Command	Syntax	Description
COMPONENT	`COMPONENT ic-bp18hy47cqavewsb**` `COMPONENT ic-bp18hy47cqavewsb --paramName1 paramValue1 --paramName2 paramValue2` `COMPONENT acs:ecs:<RegionId>:<AliUid>:imagecomponent/<ComponentName>:<major>.<minor>.<patch>` Note** You can use a wildcard character (*) for any part of the version number (<major>, <minor>, or <patch>) to select the latest matching component version.	Specifies an image component. You can specify a system or custom image component. This command applies only to image templates. In an image template, use this command to assemble one or more image components. Supports components in both YAML and Dockerfile formats.
RESTART	`RESTART`	Reboots the instance. No content is allowed after this command.
RUN	`RUN echo hello;\ echo world;`	Runs a command in a new layer. A single command can span multiple lines. To continue a command on the next line, add an escape character (\) at the end of the current line. For Linux operating systems only.
ENV	`ENV key value` `ENV key1="value1" key2="value2"`	Configures system environment variables. The command uses a key-value pair format. For Linux operating systems only. Note When you use the `ENV key1="value1" key2="value2"` format, do not omit the double quotation marks (").
WORKDIR	`WORKDIR /<path>` `WORKDIR <path1>/<path2>`	Sets the working directory. For Linux operating systems only.
COPY	`COPY <source_web_file_URL> <destination_directory>` `COPY <source_local_file_path> <destination_directory>`	Copies files. For Linux operating systems only. Note All network files are downloaded by using `wget`, and `query string`s are not currently supported. Ensure that the intermediate instance can access the public network.
USER	`USER <username>`	Sets the user for subsequent `RUN`, `CMD`, and `ENTRYPOINT` instructions. For Linux operating systems only. Note The `<username>` must be an existing user in the operating system. Otherwise, an error occurs when the command runs.
LABEL	`LABEL user="username"\ date="2020-11-11" key="value"`	Adds metadata to the image. A single command can span multiple lines. To continue a command on the next line, add an escape character (\) at the end of the current line. For Linux operating systems only.
CMD	`CMD ["executable","param1","param2"]` `CMD command param1 param2`	Specifies the command to run on startup. For Linux operating systems only.
ENTRYPOINT	`ENTRYPOINT ["executable","param1","param2"]` `CMD command param1 param2`	Specifies the command to run on startup. For Linux operating systems only. Note The `CMD` and `ENTRYPOINT` instructions both specify the command to run when a container starts. They have different use cases and features, and can be used separately or in combination for greater flexibility. For more information about their differences, see Dockerfile reference.

Command examples

This section provides examples of component and template commands for specific use cases.

Component commands

Example 1: Use custom parameters

In this example, the function (3x+2y+z)+(3x+2y+z) is configured in an image component. This lets you assign different values to x, y, and z each time you use the component in an image template. The following code shows an example of the component command. For an example of the corresponding template command, see Example 1: Associate a template with a component and assign values to its custom parameters.

Parameters:
  x:
    Type: String
  y:
    Type: String
  z:
    Type: String
Tasks:
  - Name: count
    Action: RunShellCommand
    Properties:
      commandContent: echo $((3 * {{x}} + 2 * {{y}} + {{z}}))
  - Name: result
    Action: RunShellCommand
    Properties:
      commandContent: echo $(({{count.stdout}}+{{count.stdout}}))

Example 2: Configure a script from OSS

You can use an image component to build an image from a Linux script stored in an OSS bucket. This lets you create multiple ECS instances with identical configurations from the same image. Because the image component uses the OSSDownload and OSSUpload actions, you do not need to hardcode an AccessKey pair in the component.

Tasks:
  - Name: ossdownload
    Action: OSSDownload
    Properties:
      bucketName: <your_oss_bucket_name>
      destinationDir: /home
      objectName: <your_script_object_name>
  - Name: setpermissions
    Action: RunShellCommand
    Properties:
      commandContent: sudo chmod +x /home/<your_script_object_name>
  - Name: createfile
    Action: RunShellCommand
    Properties:
      commandContent: sudo touch /home/output.txt
  - Name: setfilepermissions
    Action: RunShellCommand
    Properties:
      commandContent: sudo chmod 666 /home/output.txt
  - Name: result
    Action: RunShellCommand
    Properties:
      commandContent: sudo bash /home/<your_script_object_name> &> /home/output.txt
  - Name: ossupload
    Action: OSSUpload
    Properties:
      bucketName: <your_oss_bucket_name>
      fileToUpload: /home/output.txt
      objectName: output.txt

Template commands

Example 1: Associate a component and assign parameters

This example assigns values to the x, y, and z parameters from Example 1: Use custom parameters in a component. You can assign different values each time you use the template command.

COMPONENT i-xxxxxxxxx --x 1 --y 2 --z 3

Example 2: Use the latest component version

If a component has multiple versions, such as 1.0.1, 1.0.2, and 1.0.3, you can specify a version pattern such as 1.0.* in the template command. This associates the template with the latest matching version (1.0.3 in this case).

COMPONENT acs:ecs:cn-hangzhou:<alibaba_cloud_account_id>:imagecomponent/<your_component_name>/1.0.*