To ensure that the ECS instance running an image can complete the initialization configuration, we recommend that you install cloud-init on the on-premise server when you create a custom Linux image. This topic describes how to install Alibaba Cloud cloud-init and Community cloud-init.

Prerequisites

To install Alibaba Cloud cloud-init, ensure that the python-pip dependency library is installed on the source server.

To install the Community cloud-init, ensure that the Git, Python 2.7, and python-pip dependency libraries are installed on the source server.

Installation commands for some Linux distributions are shown as follows:
  • CentOS/Red Hat Enterprise Linux:
    yum -y install git python python-pip
  • Ubuntu/Debian:
    apt-get -y install git python python-pip
  • openSUSE/SUSE:
    zypper -n install git python python-pip

Background information

cloud-init is an open-source software used by cloud platforms to configure system initialization of Linux virtual machines. All major public cloud platforms such as Alibaba Cloud, Amazon Web Services (AWS), Microsoft Azure, and OpenStack support cloud-init. For more information, see cloud-init Documentation.

Alibaba Cloud cloud-init initializes the configurations of instances during their startup, including NTP, software source, hostname, and SSH key pair. It also executes user data scripts.
Note cloud-init later than v18 automatically initializes network configurations. The code for network configuration is BOOTPROTO=dhcp DEVICE=eth0 ONBOOT=yes STARTMODE=auto TYPE=Ethernet USERCTL=no. Some public images have been upgraded to v19.1. If you want to customize network configurations after you install cloud-init, see (Optional) Customize network configuration below in this topic.

Scenarios

By default, cloud-init is installed for all Alibaba Cloud public images. If you use a custom image in the following scenarios, we recommend that you install Alibaba Cloud cloud-init for your Linux server to ensure that the created instance can automatically initialize system configurations:
  • Linux servers that will be migrated to the cloud but are not installed with cloud-init.
  • Linux servers that are installed with cloud-init whose version is earlier than v0.7.9.
  • Alibaba Cloud ECS instances that are not installed with cloud-init.

Check the cloud-init version

Different cloud platforms may use different versions of cloud-init. Select the appropriate version and configure it with the appropriate data source (datasource). The version of Alibaba Cloud cloud-init is 0.7.6a, and the data source is Aliyun.

After cloud-init is installed, it starts automatically during startup by default. If the installed cloud-init version is not suitable or the data source is not configured properly, cloud-init may run abnormally and the instance may start slowly or even fail to be started the next time you restart the instance.

  1. Log on to the source server.
  2. Run the following command to check whether cloud-init is installed:
    which cloud-init

    If no information in the output indicates that cloud-init is installed, install Alibaba Cloud cloud-init.

  3. Run the following command to check the version of cloud-init:
    cloud-init --version

    If the version is earlier than the Community v0.7.9 (except for v0.7.6 a), you must install Alibaba Cloud cloud-init.

  4. Complete the data backup.
    Note We recommend that you proceed with caution when you install Alibaba Cloud cloud-init on servers that will not be migrated to the cloud.

(Recommended) Install Alibaba Cloud cloud-init

  1. Run the following command to download Alibaba Cloud cloud-init:
    wget http://ecs-image-utils.oss-cn-hangzhou.aliyuncs.com/cloudinit/ali-cloud-init-latest.tgz
  2. Run the following command to download and decompress the cloud-init installation package to the current directory.
    tar -zxvf ali-cloud-init-latest.tgz
  3. Access the tools directory of cloud-init.
  4. Run the following command to execute the deploy.sh script to install cloud-init:
    bash ./deploy.sh <issue> <major_version>
    The following table describes the parameters and values in the deploy.sh script.
    Parameter Description Example
    issue The type of the operating system. Valid values: centos, redhat, rhel, debian, ubuntu, opensuse, and sles. The parameter values are case-sensitive. sles stands for SUSE and SLES. centos
    major_version The major version number of the operating system. For example, the major version number of CentOS 6.5 is 6.
  5. Check whether cloud-init is installed.
    If "description": "success" is returned, Alibaba Cloud cloud-init is installed.Alibaba Cloud cloud-init is installed
Installation commands for different Linux distributions are shown as follows: You may need to adapt the script to your operating system.
  • CentOS 6 and 7
    # Check whether the python-pip dependency library is installed. If no, install it.
    if ! python -c 'import setuptools' >& /dev/null; then
      yum -y install python-pip
    fi
    # Back up cloud-init of the earlier version.
    test -d /etc/cloud && mv /etc/cloud /etc/cloud-old
    # Download and decompress Alibaba Cloud cloud-init.
    wget http://ecs-image-utils.oss-cn-hangzhou.aliyuncs.com/cloudinit/ali-cloud-init-latest.tgz
    tar -zxvf ./ali-cloud-init-latest.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"
  • Red Hat Enterprise Linux 6 and 7
    # Check whether the python-pip dependency library is installed. If no, install it.
    if ! python -c 'import setuptools' >& /dev/null; then
      yum -y install python-pip
    fi
    # Back up cloud-init of the earlier version.
    test -d /etc/cloud && mv /etc/cloud /etc/cloud-old
    # Download and decompress Alibaba Cloud cloud-init.
    wget http://ecs-image-utils.oss-cn-hangzhou.aliyuncs.com/cloudinit/ali-cloud-init-latest.tgz
    tar -zxvf ./ali-cloud-init-latest.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"
  • Ubuntu 14, 16, and 18
    # Check whether the python-pip dependency library is installed. If no, install it.
    if ! python -c 'import setuptools' >& /dev/null; then
      apt-get install python-pip -y
    fi
    # Back up cloud-init of the earlier version.
    test -d /etc/cloud && mv /etc/cloud /etc/cloud-old
    # Download and decompress Alibaba Cloud cloud-init.
    wget http://ecs-image-utils.oss-cn-hangzhou.aliyuncs.com/cloudinit/ali-cloud-init-latest.tgz
    tar -zxvf ./ali-cloud-init-latest.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"
  • Debian 8 and 9
    # Check whether the python-pip dependency library is installed. If no, install it.
    if ! python -c 'import setuptools' >& /dev/null; then
      apt-get -y install python-pip
    fi
    # Back up cloud-init of the earlier version.
    test -d /etc/cloud && mv /etc/cloud /etc/cloud-old
    # Download and decompress Alibaba Cloud cloud-init.
    wget http://ecs-image-utils.oss-cn-hangzhou.aliyuncs.com/cloudinit/ali-cloud-init-latest.tgz
    tar -zxvf ./ali-cloud-init-latest.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"
  • SUSE 11 and 12
    # Check whether the python-pip dependency library is installed. If no, install it.
    if ! python -c 'import setuptools'>& /dev/null; then
      zypper -n install python-pip
    fi
    # Back up cloud-init of the earlier version.
    test -d /etc/cloud && mv /etc/cloud/etc/cloud-old
    # Download and decompress Alibaba Cloud cloud-init.
    wget http://ecs-image-utils.oss-cn-hangzhou.aliyuncs.com/cloudinit/ali-cloud-init-latest.tgz
    tar -zxvf ./ali-cloud-init-latest.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"
  • openSUSE 13 and 42
    # Check whether the python-pip dependency library is installed. If no, install it.
    if ! python -c 'import setuptools'>& /dev/null; then
      zypper -n install python-pip
    fi
    # Back up cloud-init of the earlier version.
    test -d /etc/cloud && mv /etc/cloud/etc/cloud-old
    # Download and decompress Alibaba Cloud cloud-init.
    wget http://ecs-image-utils.oss-cn-hangzhou.aliyuncs.com/cloudinit/ali-cloud-init-latest.tgz
    tar -zxvf ./ali-cloud-init-latest.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) Install Community cloud-init

  1. Run the following command to download the cloud-init source code package from Git:
    git clone https://git.launchpad.net/cloud-init
  2. Access the cloud-init directory.
    cd ./cloud-init
  3. Run the following command to install all the dependency libraries:
    pip install -r ./requirements.txt
  4. Run the following command to install cloud-init:
    python setup.py install
  5. Modify the configuration file cloud.cfg.
    1. Open the configuration file.
      vi /etc/cloud/cloud.cfg
      vi /etc/cloud/cloud.cfg
    2. Modify the configuration before cloud_init_modules: as follows:
      # Example datasource config
      # The top level settings are used as module
      # and system configuration.
      # A set of users which may be applied and/or used by various modules
      # when a 'default' entry is found it will reference the 'default_user'
      # from the distro configuration specified below
      users:
         - default
      user:
          name: root
          lock_passwd: False
      # If this is set, 'root' will not be able to ssh in and they 
      # will get a message to login instead as the above $user
      disable_root: false
      # This will cause the set+update hostname module to not operate (if true)
      preserve_hostname: false
      syslog_fix_perms: root:root
      datasource_list: [ AliYun ]
      # Example datasource config
      datasource:
          AliYun:
              support_xen: false
              timeout: 5 # (defaults to 50 seconds)
              max_wait: 60 # (defaults to 120 seconds)
      #      metadata_urls: [ 'blah.com' ]
      # The modules that run in the 'init' stage
      cloud_init_modules:

(Optional) Customize network configuration

  1. After cloud-init is installed, open the /etc/cloud/cloud.cfg file.
    vim /etc/cloud/cloud.cfg
  2. Add the disabled configuration before Example datasource config.
    network:
      config: disabled
    Note After the configuration is added, cloud-init v19.1 does not manage the network configuration under /etc/sysconfig/network-scripts/ and you must manage the network configuration manually.
    cloud-init-disable-config

Troubleshooting

  • The libraries that are missing may vary with images. You can use pip to install the libraries and then install cloud-init again.
  • If the default software package manager (such as yum) and the pip manager have been installed with different versions of dependency libraries, library version conflicts may occur and cause cloud-init to run abnormally. We recommend that you download the dependency libraries as needed based on the error message.
Error message Cause Troubleshooting command
no setuptools module in python
The python setuptools module is not installed.
  • CentOS/Red Hat: yum -y install python-pip
  • Ubuntu/Debian: apt-get -y install python-pip
  • openSUSE/SUSE: zypper -n install python-pip
File "/root/cloud-init/cloudinit/log.py", line 19, in <module>
      import six
  ImportError: No module named six  )
The six dependency library is not installed.
pip install six
File "/root/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 not installed.
pip install oauthlib
Error messages do not indicate the libraries that are not installed. The error message is not mapped. Run the following command to install all dependency libraries that are listed in the requirements.txt file of cloud-init:
pip install -r requirements.txt

What to do next

  • For Linux servers that will be migrated to the cloud:

    You can migrate the server to the cloud by using the Cloud Migration tool or importing the custom image. For more information, see Migrate your server to Alibaba Cloud by using the Cloud Migration tool or Import custom images.

  • For Alibaba Cloud ECS instances that already run Linux custom images:
    You can restart the system to check the installation result. If the system automatically configures the hostname, software source, and NTP, cloud-init is installed. For example, if the network configuration file shows the following content, cloud-init is installed:
    [root@iZbp1ios3psx4hoi******Z ~]# cat /etc/sysconfig/network-scripts/ifcfg-eth0
    # Created by cloud-init on instance boot automatically, do not edit.
    #
    BOOTPROTO=dhcp
    DEVICE=eth0
    ONBOOT=yes
    STARTMODE=auto
    TYPE=Ethernet
    USERCTL=no