Elastic Compute Service:Use instance user data to automatically run commands or scripts on instance startup

User-data script

• Introduction

  After a user-data script is passed to a Linux instance, the script is executed as a shell script and is run only once the first time the instance is started.

• Running frequency

  • Instance boot: The user-data script is run only once the first time an instance is started. The script is not run on instance restart.

  • Operating system replacement: The script is automatically run.

  • System disk re-initialization: The script is automatically run.

  Important

  The script is not automatically run in the following scenarios:

  • If you use a custom image to replace the operating system of the source instance from which the custom image was created, the system determines that the instance is not started for the first time and does not run the script.

  • If you use a custom image to create an instance, the system disk of the instance stores data. When you initialize the system disk, the system determines that the instance is not started for the first time and does not run the script.

• Format

  The first line starts with a number sign and an exclamation mark (#!).

• Sample user-data script

  #!/bin/sh
  echo "Hello World. The time is now $(date -R)!" | tee /root/userdata_test.txt

  The sample user-data script is run only once the first time the instance is started and writes the system time to the userdata_test.txt file.

Cloud-config data

• Introduction

  Cloud-init defines a series of functional modules to execute specific tasks and perform configurations, such as installing software packages and configuring network settings. Cloud-init obtains cloud-config data from vendor data, custom data, and kernel parameters. The cloud-config data determines which modules are involved in tasks and which actions to take. Before you create an ECS instance, you can configure custom cloud-config data by specifying the modules and tasks, and pass the cloud-config data to the instance as user data. When the instance is started, cloud-init reads and parses cloud-config data to run the modules as instructed in the configuration file and execute tasks to configure and deploy the instance.

• Running frequency

  • Instance boot: Whether to execute the tasks in the cloud-config data is determined by the running frequency of the modules corresponding to the tasks. For information about the modules, see Modules.

    • Once-per-instance: A module is run only once the first time the instance is started. For example, modules such as Apt and Set Passwords are configured and run at a frequency of Once-per-instance. The modules are not run when the instance is restarted.

    • Always: A module is run each time an instance is started. For example, when modules such as Bootcmd and Update Etc Hosts are run at a frequency of Always, the modules are run each time the instance is started.

  • Operating system replacement: The cloud-config data is automatically run.

  • System disk re-initialization: The cloud-config data is automatically run.

    Important

    The script is not automatically run in the following scenarios:

    • If you use a custom image to replace the operating system of the source instance from which the custom image was created, the system determines that the instance is not started for the first time and does not run the script.

    • If you use a custom image to create an instance, the system disk of the instance stores data. When you initialize the system disk, the system determines that the instance is not started for the first time and does not run the script.

• Format

  • The first line starts with #cloud-config, and the header does not contain spaces.

  • Cloud-config data must follow the Yet Another Markup Language (YAML) syntax.

• Sample cloud-config data

  #cloud-config
  apt:
   primary:
   - arches: [default]
   uri: https://us.archive.ubuntu.com/ubuntu/
  bootcmd:
  - echo "Hello World. The time is now $(date -R)!" | tee /root/userdata_test.txt

  In this example, cloud-config data is run each time an instance is started to change the default repository and write the latest system time to the userdata_test.txt file.

Include file

• Introduction

  An include file contains one or more links to user-data scripts or cloud-config data. Each link occupies a separate line. When an instance is started, cloud-init reads and parses the links one by one. If an error occurs when cloud-init reads a link, cloud-init stops reading the remaining links.

  Note

  You can use Alibaba Cloud Object Storage Service (OSS) to upload user-data scripts or cloud-config data to an instance, obtain links, and specify the validity period of links. For more information, see Get started by using the OSS console.

• Running frequency

  • Instance boot: The running frequency varies based on the content to which a link is directed. For example, if a link is directed to a user-data script, the script is run only once the first time an instance is started. If the link is directed to cloud-config data, the running frequency of cloud-config data prevails.

  • Operating system replacement: The include file is automatically run.

  • System disk re-initialization: The include file is automatically run.

    Important

    The script is not automatically run in the following scenarios:

    • If you use a custom image to replace the operating system of the source instance from which the custom image was created, the system determines that the instance is not started for the first time and does not run the script.

    • If you use a custom image to create an instance, the system disk of the instance stores data. When you initialize the system disk, the system determines that the instance is not started for the first time and does not run the script.

• Format

  The first line starts with #include, and the header does not contain spaces.

• Sample include file

  #include
  https://ecs-image-test.oss-cn-hangzhou.aliyuncs.com/userdata/myscript.sh

  In this example, the include file contains a link to a user-data script, and the script is run only once the first time the instance is started.

  Note

  If you use an include file or Gzip compressed content, use a storage service to upload the script, obtain the script link, and specify the validity period of the link. We recommend that you use Alibaba Cloud OSS. For more information, see Get started by using the OSS console.

Gzip compressed content

• Introduction

  If the size of a user-data script, cloud-config data, or an include file exceeds 32 KB, you can use Gzip to compress the content in an include file in the .gz format, generate a corresponding link, and then pass the include file to an instance. Cloud-init automatically decompresses the Gzip compressed content. The result of running the decompressed content is the same as the result of running uncompressed content that is passed directly to an instance.

  Note

  You can also use Alibaba Cloud OSS to upload user-data scripts or cloud-config data to an instance, obtain links, and specify the validity period of links. For more information, see Get started by using the OSS console.

• Running frequency

  • Instance boot: The running frequency varies based on the script type and module type. For example, if a link is directed to Gzip compressed content that is a user-data script, the Gzip compressed content is run only once the first time the instance is started.

  • Operating system replacement: Gzip compressed content is automatically run.

  • System disk re-initialization: Gzip compressed content is automatically run.

    Important

    The script is not automatically run in the following scenarios:

    • If you use a custom image to replace the operating system of the source instance from which the custom image was created, the system determines that the instance is not started for the first time and does not run the script.

    • If you use a custom image to create an instance, the system disk of the instance stores data. When you initialize the system disk, the system determines that the instance is not started for the first time and does not run the script.

• Format

  The first line starts with #include, and the header does not contain spaces.

• Sample code for Gzip compressed content

  #include
  https://ecs-image-test.oss-cn-hangzhou.aliyuncs.com/userdata/myscript.gz

  In this example, an include file contains a link to Gzip compressed content that is a user-data script. After cloud-init reads the user-data script that is Gzip compressed, the script is automatically decompressed and run only once the first time the instance is started.

Upstart job

• Introduction

  Upstart is an event-driven initialization system. An Upstart job is a configuration file that defines when to start or stop and how to run a service or task. An Upstart job file has a file extension of .conf and is located in the /etc/init/ directory.

• Running frequency

  • Instance boot: The Upstart job is automatically run each time an instance is started.

  • Operating system replacement: The Upstart job is automatically run.

  • System disk re-initialization: The Upstart job is automatically run.

    Important

    The script is not automatically run in the following scenarios:

    • If you use a custom image to replace the operating system of the source instance from which the custom image was created, the system determines that the instance is not started for the first time and does not run the script.

    • If you use a custom image to create an instance, the system disk of the instance stores data. When you initialize the system disk, the system determines that the instance is not started for the first time and does not run the script.

• Format

  The first line starts with #upstart-job, and the header does not contain spaces.

• Sample Upstart job

  #upstart-job
  description "upstart test"
  start on runlevel [2345] #Starts at run levels 2, 3, 4, and 5.
  stop on runlevel [!2345] #Stops at run levels other than 2, 3, 4, and 5.
  exec echo "Hello World. The time is now $(date -R)!" | tee /root/output.txt

  The sample Upstart job returns a message that contains a timestamp when the system runs at the specified run level and adds the message to the /root/output.txt file. The Upstart job stops when the system runs at a run level that is different from the preceding specified run levels.

Batch script

• Running frequency

  • Instance boot: The script is run only once the first time an instance is started. The script is not run on instance restart.

  • Operating system replacement: The script is automatically run.

  • System disk re-initialization: The script is automatically run.

    Important

    The script is not automatically run in the following scenarios:

    • If you use a custom image to replace the operating system of the source instance from which the custom image was created, the system determines that the instance is not started for the first time and does not run the script.

    • If you use a custom image to create an instance, the system disk of the instance stores data. When you initialize the system disk, the system determines that the instance is not started for the first time and does not run the script.

• Format

  • The first line is [bat], and the header does not contain spaces.

  • Only half-width characters can be entered.

  • The data writing path cannot be defined as the C:\Users directory, otherwise user data execution will fail.

    Note

    In the Windows operating system, the user configuration files and data are stored in the C:\Users directory and its subdirectories by default. You can access the directory and its subdirectories only after you log on to the operating system. You have not logged on to the operating system when the operating system runs the user data in the initialization stage. Data cannot be written to the C:\Users directory or its subdirectories in the stage.

• Sample batch script

  [bat]
  echo "bat test" > C:\userdata_test.txt

  In this example, the batch script is run only once the first time the instance is started and writes "bat test" to the userdata_test.txt file.

PowerShell script

• Running frequency

  • Instance boot: The script is run only once the first time an instance is started. The script is not run on instance restart.

  • Operating system replacement: The script is automatically run.

  • System disk re-initialization: The script is automatically run.

    Important

    The script is not automatically run in the following scenarios:

    • If you use a custom image to replace the operating system of the source instance from which the custom image was created, the system determines that the instance is not started for the first time and does not run the script.

    • If you use a custom image to create an instance, the system disk of the instance stores data. When you initialize the system disk, the system determines that the instance is not started for the first time and does not run the script.

• Format

  • The first line is [powershell], and the header does not contain spaces.

  • Only half-width characters can be entered.

  • The data writing path cannot be defined as the C:\Users directory, otherwise user data execution will fail.

    Note

    In the Windows operating system, the user configuration files and data are stored in the C:\Users directory and its subdirectories by default. You can access the directory and its subdirectories only after you log on to the operating system. You have not logged on to the operating system when the operating system runs the user data in the initialization stage. Data cannot be written to the C:\Users directory or its subdirectories in the stage.

• Sample PowerShell script

  [powershell]
  write-output "powershell test" | Out-File C:\userdata_test.txt

  In this example, the PowerShell script is run only once the first time the instance is started and writes powershell test to the userdata_test.txt file.