Commands supported by Image Builder - Elastic Compute Service

Learn the syntax and usage of YAML and Dockerfile commands for Image Builder components and templates.

Command syntax

Image Builder supports two command formats: YAML (Linux and Windows) and Dockerfile (Linux only).

Note

Dockerfile commands are less flexible and limited to Linux. Use the YAML format when possible.

YAML and Dockerfile formats use the following syntax:

YAML: Define the Parameters and Tasks sections:

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

Reference defined parameters in task properties:

{{taskName1.stdout}}

Dockerfile
- Each line contains one command.
- A command can span multiple lines. Add a backslash (\) at the end of each line to continue on the next line.

Supported commands

Image Builder supports the following commands for components and templates.

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. Linux 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. Windows 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 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 commands are allowed after RESTART.
RUN	`RUN echo hello;\ echo world;`	Runs a command in a new layer. Use a backslash (\) at the end of a line to continue on the next line.
ENV	`ENV key value` `ENV key1="value1" key2="value2"`	Configures system environment variables. Uses key-value pair format. Note In 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 Network files are downloaded with `wget`, which does not support `query string`s. The intermediate instance must have public network access.
USER	`USER <username>`	Sets the user for subsequent `RUN`, `CMD`, and `ENTRYPOINT` commands. Note `<username>` must be an existing OS user. Otherwise, the command fails.
LABEL	`LABEL user="username"\ date="2020-11-11" key="value"`	Adds metadata to the image. Use a backslash (\) at the end of a line to continue on the next 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 `CMD` and `ENTRYPOINT` both specify the startup command but differ in use cases. They can be used separately or combined. 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** Use a wildcard (*) for any part of the version number (<major>, <minor>, or <patch>) to select the latest matching version.	Specifies a system or custom image component. Applies only to image templates. Use this command to assemble one or more image components in a template. Supports components in both YAML and Dockerfile formats.
RESTART	`RESTART`	Reboots the instance. No commands are allowed after RESTART.
RUN	`RUN echo hello;\ echo world;`	Runs a command in a new layer. Use a backslash (\) at the end of a line to continue on the next line. Linux only.
ENV	`ENV key value` `ENV key1="value1" key2="value2"`	Configures system environment variables. Uses key-value pair format. Linux only. Note In the `ENV key1="value1" key2="value2"` format, do not omit the double quotation marks (").
WORKDIR	`WORKDIR /<path>` `WORKDIR <path1>/<path2>`	Sets the working directory. Linux only.
COPY	`COPY <source_web_file_URL> <destination_directory>` `COPY <source_local_file_path> <destination_directory>`	Copies files. Linux only. Note Network files are downloaded with `wget`, and `query string`s are not supported. The intermediate instance must have public network access.
USER	`USER <username>`	Sets the user for subsequent `RUN`, `CMD`, and `ENTRYPOINT` commands. Linux only. Note `<username>` must be an existing OS user. Otherwise, the command fails.
LABEL	`LABEL user="username"\ date="2020-11-11" key="value"`	Adds metadata to the image. Use a backslash (\) at the end of a line to continue on the next line. Linux only.
CMD	`CMD ["executable","param1","param2"]` `CMD command param1 param2`	Specifies the command to run on startup. Linux only.
ENTRYPOINT	`ENTRYPOINT ["executable","param1","param2"]` `CMD command param1 param2`	Specifies the command to run on startup. Linux only. Note `CMD` and `ENTRYPOINT` both specify the startup command but differ in use cases. They can be used separately or combined. See Dockerfile reference.

Command examples

The following examples show component and template commands for common use cases.

Component commands

Example 1: Use custom parameters

This component calculates (3x+2y+z)+(3x+2y+z) with custom parameters x, y, and z. See Example 1: Associate a template with a component and assign values to its custom parameters for the corresponding template command.

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

Build an image from a Linux script in OSS to create identically configured ECS instances. The OSSDownload and OSSUpload actions eliminate the need to hardcode AccessKey pairs.

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

Assign values to the x, y, and z parameters from Example 1: Use custom parameters in a component.

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

Example 2: Use the latest component version

For a component with versions 1.0.1, 1.0.2, and 1.0.3, specify 1.0.* to use the latest matching version (1.0.3).

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