鏡像構建服務支援的命令

鏡像構建服務通過鏡像模板實現對鏡像內容的定製，鏡像模板可以通過指定鏡像組件或直接指定命令來建立，鏡像組件本質是由一條或多條命令構成，因此最小單元是命令。本文提供了鏡像構建服務的常用命令格式和樣本供您參考。

命令文法說明

鏡像構建服務支援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。

命令樣本

通過具體情境為您展示組件命令和模板命令的樣本。

組件命令

樣本一：在組件中使用自訂入參

例如將函數 (3x+2y+z)+(3x+2y+z)配置到鏡像組件中，實現在每次建立鏡像模板時給x，y，z賦不同的值。如下為組件命令樣本，模板樣本可參見樣本一：在構建模板中關聯自訂入參組件並為入參賦值。

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}}))

樣本二：將儲存在OSS的指令檔配置到鏡像組件

將存放在OSS Bucket上Linux指令碼通過鏡像組件構建到鏡像中，以便企業內部可以使用同一個鏡像建立相同配置的ECS執行個體。由於鏡像組件OSSDownload、OSSUpload命令，所以不需要您在組件代碼中明文寫入程式碼AK。

Tasks:
  - Name: ossdownload
    Action: OSSDownload
    Properties:
      bucketName: <替換為您的OSS Bucket名稱>
      destinationDir: /home
      objectName: <您OSS Bucket上的指令檔>
  - Name: setpermissions
    Action: RunShellCommand
    Properties:
      commandContent: sudo chmod +x /home/<您OSS Bucket上的指令檔>
  - 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/<您OSS Bucket上的指令檔> &> /home/output.txt
  - Name: ossupload
    Action: OSSUpload
    Properties:
      bucketName: <替換為您的OSS Bucket名稱>
      fileToUpload: /home/output.txt
      objectName: output.txt

模板命令

樣本一：在構建模板中關聯自訂入參組件並為入參賦值

為樣本一：在組件中使用自訂入參中的x，y，z賦值，您可以在每次設定模板命令時給x，y，z賦不同的值。

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

樣本二：在構建模板中通過組件版本自動關聯最新組件

當存在多個組件版本時，例如組件1.0.1、組件1.0.2、組件1.0.3，通過在模板命令中指定模糊版本1.0.*，可以自動關聯最新的組件版本1.0.3。

COMPONENT acs:ecs:cn-hangzhou:<替換為阿里雲帳號ID>:imagecomponent/<替換為自訂入參的組件名稱>/1.0.*