cloud-init is an open source initialization tool that automates initialization operations for Linux operating systems, such as generating an initial password, configuring the hostname, and running user data scripts. If you want to migrate an on-premises custom image on which cloud-init is not installed to Alibaba Cloud, you can manually install cloud-init. If you do not install cloud-init, Elastic Compute Service (ECS) instances created from the custom image cannot automatically perform initialization tasks such as configuring the hostname and network settings. This may affect the efficiency of automated deployment and configuration of the ECS instances. This topic describes how to install cloud-init in Linux operating systems.
For more information about cloud-init, see Cloud-init documentation.
Scenarios
By default, cloud-init is installed on all Alibaba Cloud public images. To ensure that ECS instances created from on-premises custom images can automatically initialize system configurations, we recommend that you refer to the following suggestions and perform related operations based on your actual scenarios:
Cloud-init is not installed on the Linux servers that you want to migrate to Alibaba Cloud.
Before you migrate a Linux server on which cloud-init is not installed to Alibaba Cloud, install cloud-init on the server. This way, ECS instances that are created based on the Linux server can be automatically initialized during system boot.
NoteIf you do not want to migrate a Linux server to Alibaba Cloud, installing cloud-init on the server may cause unnecessary complexity or resource usage. Determine whether to install cloud-init based on your actual environment.
Cloud-init 0.7.9 or earlier is installed on Linux servers.
In most cases, more recent cloud-init versions include more features and fixes to ensure compatibility with the latest cloud platform features. If cloud-init of an outdated version is installed on your Linux server, we recommend that you upgrade cloud-init to a version later than 0.7.9 to maximize compatibility and security.
Cloud-init is not installed on ECS instances.
If cloud-init is not installed on an ECS instance, we recommend that you install cloud-init on the instance to ensure that the instance can be automatically initialized.
Step 1: Check whether cloud-init needs to be installed or upgraded
Log on to the source server.
Check whether cloud-init is installed on the source server.
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 version number is returned or the version of cloud-init is 0.7.9 or earlier, proceed to Step 2: Install cloud-init.
Importantcloud-init 0.7.9 is an initial version of the native cloud-init, which is not suitable for ECS instances and must be upgraded.
If cloud-init 18 or later is used, cloud-init can automatically configure networks during instance initialization. If the network configurations do not meet your business requirements, you can Customize network configurations based on your needs.
If cloud-init 19.1.21 is used, we recommend that you upgrade to Alibaba Cloud cloud-init 23.2.2. Compared with Alibaba Cloud cloud-init 19.1.21, Alibaba Cloud cloud-init 23.2.2 provides the following improvements and new features:
Cloud-init 23.2.2 allows you to access instance metadata in security hardening mode. For information about instance metadata, see Obtain instance metadata.
Other feature enhancements, performance improvements, error fixes, and community contributions. For more information, see ChangeLog.
If other version numbers of cloud-init are returned, perform the operations that are described in the What to do next section of this topic.
To prevent data loss caused by misoperations during cloud-init installation, we recommend that you back up the data of the source server in advance. For example, you can create snapshots to back up the data of the source server.
Step 2: Install cloud-init
(Recommended) Alibaba Cloud cloud-init 23.2.2: This version requires Python 3.6 or later and uses
Aliyun
as the data source.Alibaba Cloud cloud-init 19.1.21: This version requires Python 3.6 or later and uses
Aliyun
as the data source.Alibaba Cloud cloud-init 0.7.6a17: Install this version of cloud-init on specific earlier operating system versions, such as CentOS 6, Debian 9, and SUSE Linux Enterprise Server (SLES) 12. Alibaba Cloud cloud-init 0.7.6a17 requires Python 2.7 and uses
Aliyun
as the data source.ImportantThe Python community no longer provides technical support for Python 2.7. To prevent risks that are associated with dependency libraries, we recommend that you use more recent versions of cloud-init.
Native cloud-init: The community versions of cloud-init are official versions that are publicly available and maintained by the community of developers who contribute to the project. The most recent version of Alibaba Cloud cloud-init is 23.2.2. If you want to use a more recent version of cloud-init, install a community version of cloud-init. For more information, visit the official cloud-init website.
Alibaba Cloud cloud-init is optimized for and can provide better support for Alibaba Cloud services. To ensure compatibility, we recommend that you use Alibaba Cloud cloud-init. Select a cloud-init version to install based on your business requirements.
(Recommended) Install Alibaba Cloud cloud-init 23.2.2
The most recent version of Alibaba Cloud cloud-init is 23.2.2. Alibaba Cloud cloud-init 23.2.2 is maintained as a package. You can download a package that is suitable for your operating system version or use the source code package to install Alibaba Cloud cloud-init 23.2.2.
The following sections describe how to download the binary packages of cloud-init and install cloud-init on Debian 12 and CentOS Stream 9.
Debian 12
Run the following command to download the Alibaba Cloud cloud-init package:
wget https://ecs-image-tools.oss-cn-hangzhou.aliyuncs.com/cloudinit/debian12/cloud-init_23.2.2-5_all.deb
Run the following command to install the Alibaba Cloud cloud-init package:
sudo apt-get install -y ./cloud-init_23.2.2-5_all.deb
(Optional) To prevent the Alibaba Cloud cloud-init package from being automatically updated or upgraded to a more recent open source version, we recommend that you run the following command to hold the package at the current version:
sudo apt-mark hold cloud-init
Run the following command to check whether the cloud-init version is as expected:
cloud-init --version
CentOS Stream 9
Run the following command to download the Alibaba Cloud cloud-init package:
wget https://ecs-image-tools.oss-cn-hangzhou.aliyuncs.com/cloudinit/centosstream9/cloud-init-23.2.2-5.el9.noarch.rpm
Run the following command to install the Alibaba Cloud cloud-init package:
sudo yum install -y ./cloud-init-23.2.2-5.el9.noarch.rpm
(Optional) To prevent the Alibaba Cloud cloud-init package from being automatically updated or upgraded to a more recent open source version, we recommend that you run the following command to hold the package at the current version:
sudo sh -c 'echo "exclude=cloud-init" >> /etc/dnf/dnf.conf'
Run the following command to check whether the cloud-init version is as expected:
cloud-init --version
Alibaba Cloud cloud-init 23.2.2 no longer automatically adds hostname-to-private IPv4 address mappings to the /etc/hosts file. You can manually add the mappings to the file based on your business requirements. In recent operating system versions, the nss-myhostname module is used to provide hostname resolution. In Red Hat operating systems, the nss-myhostname module is included in the systemd-libs package. In Debian operating systems, the nss-myhostname module is included in the libnss-myhostname package. The /etc/nsswitch.conf configuration file is used to enable the nss-myhostname module. For more information, see nss-myhostname(8) - Linux manual page.
Install Alibaba Cloud cloud-init 19.1.21
Make sure that the python-pip dependency library is installed on the source server.
In the examples, the python3-pip dependency library is used. Run one of the following commands to install the python-pip dependency library based on the operating system of the source server.
CentOS and Red Hat Enterprise Linux (RHEL)
sudo yum -y install python3-pip
Ubuntu and Debian
sudo apt-get -y install python3-pip
openSUSE and SUSE
sudo zypper -n install python3-pip
Run the following command to download the Alibaba Cloud cloud-init installation package:
wget https://ecs-image-tools.oss-cn-hangzhou.aliyuncs.com/cloudinit/cloud-init-19.1.21.tgz
Run the following command to decompress the Alibaba Cloud cloud-init installation package to the current directory:
tar -zxvf cloud-init-19.1.21.tgz
Run the following commands to go to the cloud-init directory and install the dependency library:
cd ./cloud-init-19.1.21 pip3 install -r ./requirements.txt
Run the following command to go to the tools subdirectory of the cloud-init directory:
cd ./tools
Run the following command to execute the deploy.sh script to install Alibaba Cloud cloud-init:
sudo bash ./deploy.sh <issue> <major_version>
The following table describes the parameters and the corresponding 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 value of this parameter is case-sensitive. sles specifies SUSE or SLES.
NoteIf the operating system is CentOS Stream, set this parameter to centos.
centos
<major_version>
The major version number of the operating system.
NoteYou cannot install Alibaba Cloud cloud-init 19.1.21 on Ubuntu 14.
The major version number of CentOS 7.6 is 7.
For example, if the current operating system is CentOS 7, run the
sudo bash ./deploy.sh centos 7
command.Check whether Alibaba Cloud cloud-init is installed.
If Alibaba Cloud cloud-init is installed,
"description": "success"
is returned.Run the following command to check whether the cloud-init version is as expected:
cloud-init --version
The following section provides sample shell scripts that you can use to install Alibaba Cloud cloud-init on different Linux distributions. Modify the shell script based on the operating system.
CentOS 7 and CentOS 8
# Check whether the python3-pip dependency library is installed. If the python3-pip dependency library is not installed, install the dependency library.
if ! python3 -c 'import setuptools' >& /dev/null; then
yum -y install python3-pip
fi
# Back up cloud-init of an earlier version.
test -d /etc/cloud && mv /etc/cloud /etc/cloud-old
# Download and decompress the Alibaba Cloud cloud-init installation 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 Alibaba Cloud 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"
RHEL 7 and RHEL 8
# Check whether the python3-pip dependency library is installed. If the python3-pip dependency library is not installed, install the dependency library.
if ! python3 -c 'import setuptools' >& /dev/null; then
yum -y install python3-pip
fi
# Back up cloud-init of an earlier version.
test -d /etc/cloud && mv /etc/cloud /etc/cloud-old
# Download and decompress the Alibaba Cloud cloud-init installation 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 Alibaba Cloud 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 16, Ubuntu 18, and Ubuntu 20
# Check whether the python3-pip dependency library is installed. If the python3-pip dependency library is not installed, install the dependency library.
if ! python3 -c 'import setuptools' >& /dev/null; then
apt-get install python36 python3-pip -y
fi
# Back up cloud-init of an earlier version.
test -d /etc/cloud && mv /etc/cloud /etc/cloud-old
# Download and decompress the Alibaba Cloud cloud-init installation 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 Alibaba Cloud 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 9 and Debian 10
# Check whether the python3-pip dependency library is installed. If the python3-pip dependency library is not installed, install the dependency library.
if ! python3 -c 'import setuptools' >& /dev/null; then
apt-get -y install python3-pip
fi
# Back up cloud-init of an earlier version.
test -d /etc/cloud && mv /etc/cloud /etc/cloud-old
# Download and decompress the Alibaba Cloud cloud-init installation 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 Alibaba Cloud 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 12 and SUSE 15
# Check whether the python3-pip dependency library is installed. If the python3-pip dependency library is not installed, install the dependency library.
if ! python3 -c 'import setuptools'>& /dev/null; then
zypper -n install python3-pip
fi
# Back up cloud-init of an earlier version.
test -d /etc/cloud && mv /etc/cloud/etc/cloud-old
# Download and decompress the Alibaba Cloud cloud-init installation 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 Alibaba Cloud 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 15
# Check whether the python3-pip dependency library is installed. If the python3-pip dependency library is not installed, install the dependency library.
if ! python3 -c 'import setuptools'>& /dev/null; then
zypper -n install python3-pip
fi
# Back up cloud-init of an earlier version.
test -d /etc/cloud && mv /etc/cloud/etc/cloud-old
# Download and decompress the Alibaba Cloud cloud-init installation 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 Alibaba Cloud 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"
Install Alibaba Cloud cloud-init 0.7.6a17
By default, Alibaba Cloud cloud-init-0.7.6a17
is installed on Alibaba Cloud public images for CentOS 6, Debian 9, and SLES 12. If you want to test Alibaba Cloud cloud-init 0.7.6a17, run the sudo mv /etc/cloud/cloud.cfg /etc/cloud/cloud.cfg_bak
command to back up the configuration file first.
Run the following command to check whether the operating system version is CentOS 6, Debian 9, or SLES 12:
cat /etc/issue
Make sure that the python-pip dependency library is installed on the source server.
In this example, the python2-pip dependency library is used. Run the following command to install the python2-pip dependency library:
CentOS 6 and SLES 12
sudo yum -y install python2-pip
Debian 9
sudo apt-get -y install python2-pip
Run the following commands to download and decompress the Alibaba Cloud cloud-init 0.7.6a17 installation package:
wget https://ecs-image-tools.oss-cn-hangzhou.aliyuncs.com/cloud-init-0.7.6a17.tgz tar -zxvf cloud-init-0.7.6a17.tgz
Run the following command to go to the tools subdirectory of the cloud-init directory:
cd cloud-init-0.7.6a17/tools/
Run the following command to execute the deploy.sh script to install Alibaba Cloud cloud-init:
sudo bash ./deploy.sh <issue> <major_version>
For example, if the current operating system is CentOS 6, run the
sudo bash ./deploy.sh centos 6
command to install Alibaba Cloud cloud-init.The following table describes the parameters and the corresponding values in the deploy.sh script.
Parameter
Description
Example
<issue>
The type of the operating system. Valid values: centos, debian, and sles. The value of this parameter is case-sensitive. sles specifies SUSE or SLES.
centos
<major_version>
The major version number of the operating system.
The major version number of CentOS 6.5 is 6.
Run the following command to check whether the cloud-init version is as expected:
cloud-init --version
Install native cloud-init
Make sure that the Git, Python, and python-pip dependency libraries are installed on the source server.
In the examples, Git, Python 3.6, and python3-pip are used. Run the following commands to install Git, Python, and python-pip dependency libraries for specific Linux distributions.
CentOS and RHEL
sudo yum -y install git python36 python3-pip
Ubuntu and Debian
sudo apt-get -y install git python36 python3-pip
openSUSE and SUSE
sudo zypper -n install git python36 python3-pip
Run the following command to download the cloud-init source code repository from Git:
git clone https://git.launchpad.net/cloud-init
Run the following command to go to the cloud-init directory:
cd ./cloud-init
Run the following command to install all required dependency libraries:
sudo pip3 install -r ./requirements.txt
Run the following command to install cloud-init:
python3 setup.py install
Modify the cloud.cfg configuration file.
Open the cloud.cfg configuration file.
sudo vi /etc/cloud/cloud.cfg
Replace the content that precedes
cloud_init_modules:
with the following content:# 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:
Run the following command to check whether the cloud-init version is as expected:
cloud-init --version
(Optional) Step 3: Configure cloud-init
Customize network configurations
In cloud-init 18 and later versions, initialization is performed to automatically apply the following network settings: BOOTPROTO=dhcp DEVICE=eth0 ONBOOT=yes STARTMODE=auto TYPE=Ethernet USERCTL=no
. If the default network settings do not meet your business requirements, you can perform the following operations to modify the cloud-init configuration file to customize the network settings:
Run the following command to open the
cloud-init
default configuration file. Press theI
key to enter the insert mode.sudo vim /etc/cloud/cloud.cfg
Add the following disabled configuration before
Example datasource config
to disable automatic network configuration:network: config: disabled
After you add the configuration, you must manually manage the network configuration files such as
ifcfg-eth0
in the /etc/sysconfig/network-scripts/ directory because cloud-init does not manage the network configurations.Press the
Esc
key to exit the insert mode, enter:wq
, and then press theEnter
key to save and close the cloud-init configuration file.Customize the network settings in the /etc/sysconfig/network-scripts/ directory, such as the IP address, subnet mask, and gateway, based on your business requirements.
Retain the hostname and the /etc/hosts configuration file
By default, cloud-init automatically modifies the hostname and /etc/hosts
file of an ECS instance on instance startup. If you do not want to modify the hostname or /etc/hosts file of your ECS instance, you can perform the following operations to modify the cloud-init configuration file:
Run the following command to open the
cloud-init
default configuration file. Press theI
key to enter the insert mode.sudo vim /etc/cloud/cloud.cfg
Change
preserve_hostname: false
topreserve_hostname: true
.Press the
Esc
key to exit the insert mode, enter:wq
, and then press the Enter key to save and close the cloud-init configuration file.
What to do next
You can use Server Migration Center (SMC) to migrate Linux servers to Alibaba Cloud. For more information, see Migrate a server to an ECS instance.
After you install cloud-init on an ECS instance that runs a Linux custom image, you can restart the instance to check whether cloud-init is installed as expected. If the hostname, network settings, and Network Time Protocol (NTP) settings of the ECS instance can be automatically configured, cloud-init is installed as expected. For example, run the following cat command to view the network configuration file after the ECS instance is restarted:
sudo reboot cat /etc/sysconfig/network-scripts/ifcfg-eth0
The following command output shows that the system automatically configured network settings such as DHCP, network device, and device type, which indicates that cloud-init is installed as expected.
BOOTPROTO=dhcp DEVICE=eth0 ONBOOT=yes STARTMODE=auto TYPE=Ethernet USERCTL=no