Elastic Compute Service:Install cloud-init

For more information about cloud-init, see the official cloud-init documentation.

Step 1: Check whether to install or upgrade cloud-init

1. Log on to the source server.

2. Run the following command to check whether cloud-init is installed.

   CentOS series

   rpm -qa | grep -i cloud-init 
   pip list | grep -i cloud-init

   Ubuntu series

   dpkg -l | grep -i cloud-init 
   pip list | grep -i cloud-init

   • If no output is returned or the version is earlier than 0.7.9: Proceed to Step 2: Install cloud-init.

     Important

     Version 0.7.9 is an early community version of cloud-init that is not suitable for initializing ECS instances. You must upgrade it to a later version.

   • If the version is 18 or later: You do not need to install cloud-init. However, cloud-init automatically configures the network during instance initialization. If the default configuration does not meet your needs, you can disable the network initialization feature. For more information, see Disable automatic network initialization by Alibaba Cloud.

   • If the version is 19.1.21: Upgrade to Alibaba Cloud cloud-init 23.2.2. Alibaba Cloud cloud-init 23.2.2 provides the following improvements and new features compared with version 19.1.21:

     • Instances that use cloud-init 23.2.2 support access to metadata in security hardening mode. For more information about instance metadata, see Instance metadata.

     • Other changes include feature enhancements, performance improvements, bug fixes, and community contributions. For more information, see the ChangeLog file.

   • Other versions: You do not need to install cloud-init. Proceed to What to do next.

3. To prevent data loss from incorrect operations during the installation, we recommend that you first back up your source server data. For example, you can create a snapshot.

Step 2: Install cloud-init

• (Recommended) Alibaba Cloud cloud-init 23.2.2: Requires Python 3.6 or later. The data source is Aliyun.

• Alibaba Cloud cloud-init 19.1.21: Requires Python 3.6 or later. The data source is Aliyun.

• Alibaba Cloud cloud-init 0.7.6a17: This version is required for some earlier operating systems, such as CentOS 6, Debian 9, and SUSE Linux Enterprise Server 12. It requires Python 2.7. The data source is Aliyun.

  Important

  Because the Python community no longer provides technical support for Python 2.7, we recommend that you use a later version of cloud-init to avoid potential issues with dependency libraries.

• Community version of cloud-init: The community version is maintained by the cloud-init community. The latest version of Alibaba Cloud cloud-init is 23.2.2. If you need a later version, you can install the community version. For more version information, see the official cloud-init website.

The community version of cloud-init is the official version from the project. The Alibaba Cloud version is optimized for the Alibaba Cloud platform and provides better support for its services. Therefore, we recommend that you use the Alibaba Cloud version of cloud-init. You can select a version to install based on your needs.

# Check and install python3-pip.
if ! python3 -c 'import setuptools' >& /dev/null; then
  yum -y install python3-pip
fi
# Back up the old version of cloud-init.
test -d /etc/cloud && mv /etc/cloud /etc/cloud-old
# Download and decompress the Alibaba Cloud cloud-init package.
wget https://ecs-image-tools.oss-cn-hangzhou.aliyuncs.com/cloudinit/cloud-init-19.1.21.tgz
tar -zxvf ./cloud-init-19.1.21.tgz
# Install cloud-init.
issue_major=$( cat /etc/redhat-release | grep -Eo '[0-9]+\.?[0-9]+' | head -1 | awk -F'.' '{printf $1}')
bash ./cloud-init-*/tools/deploy.sh centos "$issue_major"

# Check and install python3-pip.
if ! python3 -c 'import setuptools' >& /dev/null; then
  yum -y install python3-pip
fi
# Back up the old version of cloud-init.
test -d /etc/cloud && mv /etc/cloud /etc/cloud-old
# Download and decompress the Alibaba Cloud cloud-init package.
wget https://ecs-image-tools.oss-cn-hangzhou.aliyuncs.com/cloudinit/cloud-init-19.1.21.tgz
tar -zxvf ./cloud-init-19.1.21.tgz
# Install cloud-init.
issue_major=$( cat /etc/os-release | grep VERSION_ID | grep -Eo '[0-9]+\.?[0-9]+' | head -1 | awk -F'.' '{printf $1}')
bash ./cloud-init-*/tools/deploy.sh rhel "$issue_major"

# Check and install python3-pip.
if ! python3 -c 'import setuptools' >& /dev/null; then
  apt-get install python36 python3-pip -y
fi
# Back up the old version of cloud-init.
test -d /etc/cloud && mv /etc/cloud /etc/cloud-old
# Download and decompress the Alibaba Cloud cloud-init package.
wget https://ecs-image-tools.oss-cn-hangzhou.aliyuncs.com/cloudinit/cloud-init-19.1.21.tgz
tar -zxvf ./cloud-init-19.1.21.tgz
# Install cloud-init.
issue_major=$( cat /etc/os-release | grep VERSION_ID | grep -Eo '[0-9]+\.?[0-9]+' | head -1 | awk -F'.' '{printf $1}')
bash ./cloud-init-*/tools/deploy.sh ubuntu "$issue_major"

# Check and install python3-pip.
if ! python3 -c 'import setuptools' >& /dev/null; then
  apt-get -y install python3-pip
fi
# Back up the old version of cloud-init.
test -d /etc/cloud && mv /etc/cloud /etc/cloud-old
# Download and decompress the Alibaba Cloud cloud-init package.
wget https://ecs-image-tools.oss-cn-hangzhou.aliyuncs.com/cloudinit/cloud-init-19.1.21.tgz
tar -zxvf ./cloud-init-19.1.21.tgz
# Install cloud-init.
issue_major=$( cat /etc/os-release | grep VERSION_ID | grep -Eo '[0-9]+\.?[0-9]+' | head -1 | awk -F'.' '{printf $1}')
bash ./cloud-init-*/tools/deploy.sh debian "$issue_major"

# Check and install python3-pip.
if ! python3 -c 'import setuptools'>& /dev/null; then
  zypper -n install python3-pip
fi
# Back up the old version of cloud-init.
test -d /etc/cloud && mv /etc/cloud/etc/cloud-old
# Download and decompress the Alibaba Cloud cloud-init package.
wget https://ecs-image-tools.oss-cn-hangzhou.aliyuncs.com/cloudinit/cloud-init-19.1.21.tgz
tar -zxvf ./cloud-init-19.1.21.tgz
# Install cloud-init.
issue_major=$( cat /etc/os-release | grep VERSION_ID | grep -Eo '[0-9]+\.?[0-9]+' | head -1 | awk -F'.' '{printf $1}')
bash ./cloud-init-*/tools/deploy.sh sles "$issue_major"

# Check and install python3-pip.
if ! python3 -c 'import setuptools'>& /dev/null; then
  zypper -n install python3-pip
fi
# Back up the old version of cloud-init.
test -d /etc/cloud && mv /etc/cloud/etc/cloud-old
# Download and decompress the Alibaba Cloud cloud-init package.
wget https://ecs-image-tools.oss-cn-hangzhou.aliyuncs.com/cloudinit/cloud-init-19.1.21.tgz
tar -zxvf ./cloud-init-19.1.21.tgz
# Install cloud-init.
issue_major=$( cat /etc/os-release | grep VERSION_ID | grep -Eo '[0-9]+\.?[0-9]+' | head -1 | awk -F'.' '{printf $1}')
bash ./cloud-init-*/tools/deploy.sh opensuse"$issue_major"

(Optional) Step 3: Configure cloud-init

FAQ

• What should I do if dependency libraries are missing when I install cloud-init using Python 3?

  The missing libraries may vary depending on the image. You can install them using pip and then install cloud-init again.

• What should I do if cloud-init runs abnormally and returns an error message?

  If the default package manager (such as yum) and the pip manager have installed different versions of the same dependency library, version conflicts may occur and cause cloud-init to run abnormally. You can download the required dependency libraries based on the error message.

  Error message	Cause	Troubleshooting command
  no setuptools module in python	The python setuptools module is missing.	For Python 3.6: CentOS/Red Hat: yum -y install python3-pip Ubuntu/Debian: apt-get -y install python3-pip OpenSUSE/SUSE: zypper -n install python3-pip
  File "/home/testuser/cloud-init/cloudinit/log.py", line 19, in <module> import six ImportError: No module named six )	The six dependency library is missing.	pip3 install six
  File "/home/testuser/cloud-init/cloudinit/url_helper.py", line 20, in <module> import oauthlib.oauth1 as oauth1 ImportError: No module named oauthlib.oauth1 )	The oauthlib dependency library is missing.	pip3 install oauthlib
  The error message does not specify a missing dependency library.	The related error message is not mapped.	Based on the libraries listed in the requirements.txt file of cloud-init, run the following command to install all dependency libraries: pip3 install -r requirements.txt

• What should I do if cloud-init runs abnormally after a new version of Python 3 is installed on the instance?

  If you install a new version of Python 3, such as Python 3.9, on an instance and set it as the default version by creating a symbolic link (for example, ln -s /usr/bin/python3.9 /usr/bin/python3), the installed cloud-init may run abnormally. For example, when you run the cloud-init --version command, an error is reported:

  $cloud-init --version
  Traceback (most recent call last):
    File "/usr/local/bin/cloud-init", line 33, in <module>
      sys.exit(load_entry_point('cloud-init==19.1.9', 'console_scripts', 'cloud-init')())
    File "/usr/local/bin/cloud-init", line 22, in importlib_load_entry_point
      for entry_point in distribution(dist_name).entry_points
    File "/usr/lib64/python3.9/importlib/metadata.py", line 524, in distribution
      return Distribution.from_name(distribution_name)
    File "/usr/lib64/python3.9/importlib/metadata.py", line 187, in from_name
      raise PackageNotFoundError(name)
  importlib.metadata.PackageNotFoundError: cloud-init

  You can use one of the following methods to resolve this issue:

  • Method 1: Reinstall cloud-init using the new version of Python 3.

  • Method 2: Modify the cloud-init executable file to change the path of the Python interpreter to the path of the previous Python 3 version. The following example shows how to change the interpreter in the cloud-init executable file to Python 3.6:

    1. Run the following command to open the cloud-init file.

       vim   /usr/local/bin/cloud-init

    2. Press i to enter edit mode. At the beginning of the file, change the content after #! to the path where Python 3.6 is located.

       After the modification, the line that starts with #! appears as follows:

       #!/usr/bin/python3.6

    3. Press the Esc key to exit edit mode. Then, enter :wq and press the Enter key to save and close the file.

• After I install cloud-init, why does the instance user data that I set during instance creation fail to run?

  1. Run the following command on the instance to check whether user data exists in the instance metadata.

     curl http://100.100.100.200/latest/user-data

     Result description:

     • If user data is set, the user data is returned. You must proceed to the next step to troubleshoot the issue.

     • If no information is returned, you did not set user data.

  2. Use one of the following methods to identify the reason why the user data fails to run.

     • Check whether the user data is in the correct format.

       User data is executed by cloud-init. You must ensure that the data format is correct. For example, the first line of the user data must start with #!. For more information, see Customize instance initialization configurations.

     • Check the user data execution result in the /var/log/cloud-init.log log file of cloud-init and troubleshoot the issue based on the error message.

       The following is an example of the information recorded in the log file:

        util.py[DEBUG]: Running command ['/var/lib/cloud/instance/scripts/part-001'] with allowed return codes [0] (shell=False, capture=False)

     • View the standard output and standard error output of the user data execution process.

       In systemd, the Linux system initialization tool, user data is executed by the `cloud-final.service` system service. You can run the following command to view the standard output and standard error output of the user data execution process and troubleshoot the issue based on the output.

       journalctl -u cloud-final.service

     • If you cannot identify the reason why the user data fails to run using the preceding methods, you can copy the user data content to a local host for debugging to check whether it can be successfully executed.

• After I install cloud-init, why don't the system initialization configurations and instance user data script run as expected?

  1. Run the following commands to check whether the four cloud-init services are enabled to start on boot.

     systemctl is-enabled cloud-init-local.service
     systemctl is-enabled cloud-init.service
     systemctl is-enabled cloud-config.service
     systemctl is-enabled cloud-final.service

     If an error message or the disabled message is returned, cloud-init is not enabled to start on boot.

  2. Run the following commands to enable cloud-init to start on boot.

     systemctl enable cloud-init-local.service
     systemctl enable cloud-init.service
     systemctl enable cloud-config.service
     systemctl enable cloud-final.service

• I resized the system disk when I created an instance, but the root partition was not automatically resized. What should I do?

  Automatic partition resizing for Linux instances is supported by cloud-init. Ensure that the `growpart` tool is installed on the system and that the cloud.cfg file is correctly configured.

  1. Run the following command to check whether the `growpart` tool is installed on the system.

     which growpart

  2. (Required if applicable) If the tool is not installed, run one of the following commands to install it.

     • RHEL series:

       sudo yum -y install cloud-utils-growpart

     • Debian series:

       sudo apt -y install cloud-guest-utils

  3. Run the following command to check whether the /etc/cloud/cloud.cfg file contains the content shown in the following figure.

     cat /etc/cloud/cloud.cfg

     

  4. (Required if applicable) If the content does not exist, add it to the /etc/cloud/cloud.cfg file.

• For an ECS instance with cloud-init 0.7.6a16 or earlier, the hostname is not updated after I change it in the console and restart the instance. What should I do?

  • Problem description

    After you update the hostname in the ECS console and restart the ECS instance, the new hostname does not take effect. When you run the cloud-init --version command, the output shows that the cloud-init version is 0.7.6a16 or earlier.

  • Cause

    When cloud-init uses the update_hostname module to update the hostname, it runs the hostname command to obtain the current system hostname and reads the /var/lib/cloud/data/previous-hostname file to obtain the hostname from the cloud-init data cache. It then compares the two hostnames. If they are the same, it updates the hostname. If they are different, it assumes the hostname was manually changed and does not update it.

    In Red Hat-based operating systems, the content read from /var/lib/cloud/data/previous-hostname is processed with a line feed, but the output of the hostname command is not. This causes a mismatch, and the hostname is not updated.

  • Solution

    You can use one of the following solutions to resolve this issue:

    • Upgrade the cloud-init version. For more information, see Step 2: Install cloud-init.

      • If you are using CentOS 6 or an earlier operating system, use cloud-init 0.7.6a17.

      • If you are using CentOS 7, use cloud-init 19.1.21.

      • If you are using CentOS 8 or a later operating system, we recommend that you use cloud-init 23.2.2 or a later version.

    • Manually handle the line feed.

      Manually modify the defective file cloudinit/distros/rhel.py in cloud-init (use the find / -name rhel.py command to find the file path). Refer to distros/rhel.py: _read_hostname() missing strip on "hostname" to process the line feed in the output of the hostname command. The following example shows how to process the line feed:

      diff --git a/cloudinit/distros/rhel.py b/cloudinit/distros/rhel.py
      index 0b68414e..65176e99 100644
      --- a/cloudinit/distros/rhel.py
      +++ b/cloudinit/distros/rhel.py
      @@ -143,6 +143,7 @@ class Distro(distros.Distro):
                   return util.load_file(filename).strip()
               elif self.uses_systemd():
                   (out, _err) = util.subp(['hostname'])
      +            out = out.strip()
                   if len(out):
                       return out
                   else: