User data allows you to customize the startup behaviors of ECS instances and pass data into instances.

Background information

Both Windows and Linux instances support the user data feature. You can use the feature in the following ways:
  • Run user data scripts upon instance startup.
  • Pass user data as common data into an ECS instance for future reference.

Prepare the user data of a Linux instance

You can configure the user data of a Linux instance by using multiple types of scripts such as the User-Data script, Cloud Config script, Include file, Gzip-compressed script, and Upstart Job script. User data of Linux instances adopts the open-source cloud-init architecture and takes metadata of instances as data sources to automatically configure attributes of Linux instances. For more information, visit User-Data Formats in the cloud-init documentation.

If you are creating an Include file or Gzip-compressed script, you must upload script files to available storage services, obtain the links, and set the validity period for the links. We recommend that you use Alibaba Cloud OSS to create links. For more information, see Upload objects and Configure lifecycle rules in the OSS documentation.

Perform the following operations to prepare the user data of a Linux instance:

  1. Use an editor to create a text file, such as Notepad++.
  2. Edit the script that is related to the user data in the text file.
    The first line of a script must meet the format requirements of this script type. The following section describes the format requirements of different scripts and the format examples:
    • User-Data script
      User-Data scripts can be shell scripts. The following section describes the characteristics of a User-Data script:
      • The first line must start with #!, such as #! /bin/sh.
      • The script size cannot exceed 16 KB before the script is encoded in Base64.
      • The script is run only when the instance is started for the first time.
      User-Data script example:
      #! /bin/sh
      echo "Hello World. The time is now $(date -R)!" | tee /root/output10.txt
      service httpd start
      chkconfig httpd on
      After the instance is created, start and connect to the instance. Run the cat [file] command to check the execution result of the script.
      [root@XXXXX2z ~]# cat output10.txt
      Hello World. The time is now Mon, 24 Jul 2017 13:03:19 +0800!
    • Cloud Config script
      Cloud Config scripts are a user-friendly and efficient way to implement user data. You can use Cloud Config scripts to configure services such as updating YUM sources, importing SSH keys, and installing dependency packages. The following section describes the characteristics of a Cloud Config script:
      • The first line must start with #cloud-config, and the header cannot have spaces.
      • The script must be a valid YAML file.
      • The script size cannot exceed 16 KB before the script is encoded in Base64.
      • The running frequency of the user data varies based on the service that you configured.
      Cloud Config script example:
      #cloud-config
      apt:
      primary:
      - arches: [default]
      uri: http://us.archive.ubuntu.com/ubuntu/
      bootcmd:
      - echo 192.168.1.130 us.archive.ubuntu.com >> /etc/hosts
      After the instance is created, start and connect to the instance. Check the execution result of the script.
    • Include file
      An Include file consists of script links. Each line consists of a link. When an ECS instance is started, cloud-init reads user data from script links of the Include file. If an error occurs on a line, the instance stops reading the user data. The following section describes the characteristics of an Include file:
      • The first line must start with #include, and the header cannot have spaces.
      • The file size cannot exceed 16 KB before the file is encoded in Base64.
      • The running frequency of the user data varies based on the type of the script that is configured in the Include file.
      Include file example:
      #include
      http://ecs-image-test.oss-cn-hangzhou.aliyuncs.com/UserData/myscript.sh

      After the instance is created, start and connect to the instance. Check the execution result of the script.

    • Gzip-compressed script
      When you use the User-Data script, Cloud Config script, or Include file, make sure that the script size is no more than 16 KB before the script is encoded in Base64. If your script size may exceed 16 KB, you can use the Gzip tool to compress the script. Compress the script files into script links. The script links constitute an Include file. The following section describes the characteristics of a Gzip-compressed script:
      • The first line must start with #include, and the header cannot start with spaces.
      • The running frequency of the user data varies based on the script type.
      Gzip-compressed script example:
      #include
      http://ecs-image-test.oss-cn-hangzhou.aliyuncs.com/userdata/config.gz

      If you are making a Gzip-compressed script file, you must compress the script file into the .gz format.

    • Upstart Job
      If you want to use an Upstart Job script, you must install the upstart service as the init system. The upstart service uses the CentOS 6, Ubuntu 10/12/14, or Debian 6/7 operating system. Upstart Job scripts put your user data in the /etc/init directory. The following section describes the characteristics of an Upstart Job script:
      • The first line must start with #upstart-job, and the header cannot start with spaces.
      • The script is run every time the instance is started.
      Upstart Job script example:
      #upstart-job
      description "upstart test"
      start on runlevel [2345]
      stop on runlevel [! 2345]
      exec echo "Hello World. The time is now $(date -R)!" | tee /root/output.txt
  3. Debug the script to make sure that the user data is correct.

Prepare the user data of a Windows instance

User Data is a feature developed by Alibaba Cloud and enables Windows instances to run initialized scripts. You can use the Bat and PowerShell scripts to configure the user data of a Windows instance.

Perform the following operations to prepare the user data of a Windows instance:

  1. Use an editor to create a text file, such as Notepad++.
  2. Edit the script that is related to the user data in the text file.
    The first line of a script must meet the format requirements of this script type. The following section describes the format requirements of different scripts and the format examples:
    • The following section describes the characteristics of a Bat script:
      • The first line must start with [bat], and the header cannot start with spaces.
      • The script size cannot exceed 16 KB before the script is encoded in Base64.
      • Only half-width letters can be entered, and no additional characters are allowed.
      Bat script example:
      [bat]
      echo "bat test" > c:\1.txt
      After the instance is created, start and connect to the instance. Check the execution result of the script. You can find that the 1.txt text file is added to the C:\ drive.
    • The following section describes the characteristics of a PowerShell script:
      • The first line must start with [powershell], and the header cannot start with spaces.
      • The script size cannot exceed 16 KB before the script is encoded in Base64.
      • Only half-width letters can be entered, and no additional characters are allowed.
      PowerShell script example:
      [powershell]
      write-output "Powershell Test" | Out-File C:\2.txt
  3. Debug the script to make sure that the user data is correct.

What to do next

After the script is prepared, you can use the script to configure the user data. For more information, see Manage user data.