Elastic Compute Service:Initialize an instance by using instance user data

User-data scripts

• Overview

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

• Running frequency

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

  • Operating system replacement: A user-data script is automatically run.

  • System disk re-initialization: A user-data script is automatically run.

  Important

  A script is not automatically run in the following scenarios:

  • If you use a custom image to replace the operating system of the source ECS 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 ECS 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 point (#!).

• Sample user-data scripts

  • Run a custom 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 an ECS instance is started, and writes the system time to the userdata_test.txt file.

  • Customize software repository, Domain Name System (DNS) resolution, and time synchronization service configurations for an ECS instance

    When you create an ECS instance, you can use a user-data script to customize software repository, DNS resolution, and time synchronization service configurations for the instance. In the following sample code, CentOS Stream 9 is used. Replace the configurations based on your operating system.

    Important

    When an ECS instance is started, the system configures the default Yellowdog Updater Modified (YUM) repository, Network Time Protocol (NTP) service, and DNS service. You can use instance user data on the instance to change the default YUM repository, NTP service, and DNS service that are configured. Take note of the following items:

    • If you use a custom YUM repository, Alibaba Cloud stops providing YUM repository support.

    • If you use a custom NTP service, Alibaba Cloud stops providing time synchronization services.

    #!/bin/sh
    # Modify DNS
    echo "nameserve 114.114.114.114" | tee /etc/resolv.conf
    # Modify yum repo and update
    cp /etc/yum.repos.d/centos.repo /etc/yum.repos.d/centos.repo.bak
    cp /etc/yum.repos.d/centos-addons.repo /etc/yum.repos.d/centos-addons.repo.bak
    sed -i "s@http://mirrors.cloud.aliyuncs.com/centos-stream/@https://mirror.stream.centos.org/@g" /etc/yum.repos.d/centos.repo
    sed -i "s@http://mirrors.cloud.aliyuncs.com/centos-stream/@https://mirror.stream.centos.org/@g" /etc/yum.repos.d/centos-addons.repo
    yum update -y
    # Modify NTP Server
    echo "server ntp1.aliyun.com" | tee /etc/ntp.conf
    systemctl restart ntpd.service

    Note

    Replace 114.114.114.114 with the actual DNS server address, https://mirror.stream.centos.org with the actual YUM repository address of CentOS Stream, and server ntp1.aliyun.com with the actual NTP server address of Alibaba Cloud.

    You can also use cloud-config data to change the YUM repository. However, cloud-config data is less flexible than user-data scripts and is unsuitable for scenarios in which specific YUM repositories are preconfigured by Alibaba Cloud. We recommend that you use user-data scripts.

  • Specify an administrator account

    By default, Linux instances use the root account as the administrator account. You can use instance user data on an instance to specify another account as the administrator account.

    #!/bin/sh
    useradd test-user
    echo "test-user   ALL=(ALL)        NOPASSWD:ALL" | tee -a /etc/sudoers
    mkdir /home/test-user/.ssh
    touch /home/test-user/.ssh/authorized_keys
    echo "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQCRnnUveAis****" | tee -a /home/test-user/.ssh/authorized_keys

    Note

    Replace ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQCRnnUveAis**** in the preceding code with your actual public key.

Cloud-config data

• Overview

  Cloud-init defines a series of functional modules to execute specific tasks and 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 what 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 instance 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 startup: 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 an ECS 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 on instance restart.

    • Always: A module is run each time an ECS 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 an ECS instance is started.

  • Operating system replacement: A module is automatically run.

  • System disk re-initialization: A module is automatically run.

    Important

    A script is not automatically run in the following scenarios:

    • If you use a custom image to replace the operating system of the source ECS 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 ECS 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

  • Specify a software repository for an ECS instance

    In the User Data field for an ECS instance, enter the following content to specify a software repository for the instance. In this example, an Ubuntu image is used to create the ECS instance. If you use another image, replace the configurations in the sample code with the actual configurations for the image.

    #cloud-config
    apt:
      preserve_sources_list: false
      disable_suites:
        - $RELEASE-updates
        - backports
        - $RELEASE
        - mysuite
      primary:
        - arches:
            - amd64
            - i386
            - default
          uri: http://us.archive.ubuntu.com/ubuntu

  • Configure automatic installation for the NGINX service

    In the User Data field for an ECS instance, enter the following content to allow the instance to automatically install the NGINX service:

    #cloud-config
    packages: 
     - nginx 
    runcmd: 
     - systemctl start nginx.service

  • Specify a hostname

    In the User Data field for an ECS instance, enter the following content to specify a hostname for the instance:

    #cloud-config
    hostname: my-instance
    fqdn: my-instance.localdomain

  • Allow a custom script to automatically run

    In the User Data field for an ECS instance, enter the following content to allow a shell script to automatically run each time the instance is started:

    #cloud-config
    bootcmd:
    - echo "Hello World. The time is now $(date -R)!" | tee /root/userdata_test.txt

Include files

• Overview

  An include file contains one or more links to user-data scripts or cloud-config data. Each link occupies a separate line. When an ECS 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 ECS instance, obtain links, and specify the validity period of links. For more information, see Get started by using the OSS console.

• Running frequency

  • Instance startup: 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 ECS instance is started. If the link is directed to cloud-config data, the running frequency of cloud-config data prevails.

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

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

    Important

    A script is not automatically run in the following scenarios:

    • If you use a custom image to replace the operating system of the source ECS 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 ECS 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 an ECS 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

• Overview

  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 ECS 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 directly passed to an ECS instance.

  Note

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

• Running frequency

  • Instance startup: 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 an ECS instance is started.

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

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

    Important

    A script is not automatically run in the following scenarios:

    • If you use a custom image to replace the operating system of the source ECS 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 ECS 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 an ECS instance is started.

Upstart jobs

• Overview

  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 startup: An Upstart job is automatically run each time an ECS instance is started.

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

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

    Important

    A script is not automatically run in the following scenarios:

    • If you use a custom image to replace the operating system of the source ECS 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 ECS 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 scripts

• Running frequency

  • Instance startup: A batch script is run only once the first time an ECS instance is started. The script is not run on instance restart.

  • Operating system replacement: A batch script is automatically run.

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

    Important

    A script is not automatically run in the following scenarios:

    • If you use a custom image to replace the operating system of the source ECS 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 ECS 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 path to which the instance user data is written cannot be C:\Users. Otherwise, the instance user data fails to be run.

    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

  • Run a custom script

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

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

PowerShell scripts

• Running frequency

  • Instance startup: A PowerShell script is run only once the first time an ECS instance is started. The script is not run on instance restart.

  • Operating system replacement: A PowerShell script is automatically run.

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

    Important

    A script is not automatically run in the following scenarios:

    • If you use a custom image to replace the operating system of the source ECS 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 ECS 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 path to which the instance user data is written cannot be C:\Users. Otherwise, the instance user data fails to be run.

    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

  • Run a custom 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 an ECS instance is started and writes powershell test to the userdata_test.txt file.