Elastic Compute Service:Initialize an instance

A Linux instance uses the open source cloud-init tool to perform automatic initialization. For more information, see Cloud-init documentation.

Cloud-init

• Cloud-init defines a series of modules to execute tasks and configurations. Each module contains the following elements: name, running frequency, and configuration parameters. The running frequency indicates the frequency at which a module is run. In most cases, the once-per-instance and always running frequencies are used. The once-per-instance running frequency indicates that a module is run only once the first time an ECS instance is started. The always running frequency indicates that a module is run each time an ECS instance is started. For more information, see Module reference.

• Cloud-init uses the /etc/cloud/cloud.cfg configuration file to control the initialization behaviors of an ECS instance, such as determining which modules to run. Cloud-init can obtain metadata, such as the instance ID and hostname of an ECS instance, from the metadata service. For example, when an ECS instance is started, cloud-init runs the Set Hostname module to obtain the hostname of the instance from the metadata service and set the hostname of the instance to the obtained hostname.

  Note

  When you create an ECS instance, you can specify user data in the cloud-config format for the instance. When the ECS instance is started, cloud-init runs modules and executes configuration tasks based on the user data in the cloud-config format to automatically configure and deploy the instance. For more information, see Instance user data.

Install cloud-init

• Public images

  Cloud-init is installed in all Alibaba Cloud public images and the custom images that are created based on the public images. If you create ECS instances from these images, cloud-init is automatically installed on the instances. You do not need to manually install cloud-init on the instances.

• Custom images

  If you use custom images that are created based on on-premises devices to create ECS instances and cloud-init is not installed in the images, you must manually install cloud-init on the instances. This ensures that the ECS instances can complete initialization configurations. For more information, see Install cloud-init.

Customize the initialization capabilities of cloud-init

By default, an ECS instance automatically implements the initialization capabilities of cloud-init when the instance is created. If you create an ECS instance from a custom image and do not want to automatically perform specific operations on instance startup, you can define the modules that you want to run on instance startup in the image when you create the image.

You can delete or modify specific modules and configurations in the /etc/cloud/cloud.cfg configuration file of cloud-init to disable the initialization capabilities of the modules. For example, by default, cloud-init automatically specifies a hostname for an ECS instance and updates the /etc/hosts file when the instance is started. If you do not want to change the hostname of an ECS instance or update the /etc/hosts configuration file on instance startup, you can change the value of the preserve_hostname parameter from the default value false to true. For more information, see the Retain the hostname and the /etc/hosts configuration file section of the "Install cloud-init" topic.

Vminit

Vminit executes a series of plug-ins in sequence to complete system initialization configurations. Several plug-ins are executed only once the first time an ECS instance is started, and other plug-ins are executed each time the instance is started. The following table describes 10 Vminit plug-ins.

Install Vminit

• Public images

  Vminit is installed in the Windows public images released in September 2023 and later and the custom images created based on the Windows public images. If you create ECS instances from these images, Vminit is automatically installed on the instances. You do not need to manually install Vminit on the instances.

• Custom images

  If you use custom images that are created based on on-premises devices to create ECS instances and Vminit is not installed in the images, you must manually install Vminit on the instances. This ensures that the ECS instances can complete initialization configurations. For more information, see Install Vminit.

Customize the initialization capabilities of Vminit

By default, all Vminit plug-ins are automatically executed to initialize an ECS instance when the instance is created. If you create an ECS instance from a custom image and do not want to automatically perform specific operations on instance startup, you can disable the corresponding plug-ins when you create the image.

1. Create a file in the C:\ProgramData\aliyun\vminit directory. The file must meet the following requirements:

   • The file name must be customized_config.

   • No suffix is added to the file name.

   • The content that you want to add to the file must be in the JSON format.

   Note

   In most cases, the ProgramData directory is hidden. Before you access the directory, make sure that you select the Show hidden files, folders, and drives option in the operating system, which allows you to view and manage the hidden items.

2. Configure the parameters in the file to disable plug-ins. Examples:

   • To prevent Alibaba Cloud from assigning instance hostnames and allow custom hostnames, disable the Plugin_Main_ConfigHostname plug-in. Copy the following data in the JSON format to the customized_config file and then save the file:

     {
      "disabledPlugins": ["Plugin_Main_ConfigHostname"]
     }

   • To prevent Alibaba Cloud from assigning instance hostnames and initializing data disks, disable the Plugin_Main_ConfigHostname and Plugin_Main_ConfigDisk plug-ins. Copy the following data in the JSON format to the customized_config file and then save the file:

     {
      "disabledPlugins": ["Plugin_Main_ConfigHostname", "Plugin_Main_ConfigDisk"]
     }

     Note

     To re-enable a plug-in, delete the corresponding configuration of the plug-in from the customized_config file.

FAQ

• Why does the operating system restart when I create a Windows instance?

  • Cause: When you create an ECS instance, Alibaba Cloud automatically assigns a hostname to the instance even if you do not specify a hostname for the instance. If the ECS instance is a Windows instance, the operating system of the instance must restart to allow the hostname to take effect.

  • Solution: If you do not want Alibaba Cloud to modify the hostname of the ECS instance and you want to specify a hostname for the instance, disable the Plugin_Main_ConfigHostname plug-in. After you disable the plug-in, Alibaba Cloud does not automatically assign a hostname to the ECS instance.

    Note

    For a Linux instance, the hostname takes effect without the need to restart the instance.

• A custom image is used to create an ECS instance, and the custom image contains a script that can modify the hostname of the instance on instance startup. Why does the ECS instance indefinitely restart when the instance is created?

  • Cause: The script conflicts with the logic of the Vminit plug-in that automatically assigns a hostname to the ECS instance when the instance is created.

  • Solution: Disable the Plugin_Main_ConfigHostname plug-in.