云服务器 Cloud-Init 和 Cloudbase-Init

Cloud-Init
什么是 Cloud-Init？
Cloud-Init 是一个开源工具，运行在云服务器实例内部的一个非常驻服务，在开机启动时执行，执行完成立即退出，不会监听任何端口。
腾讯云的 Linux 公有镜像都预安装了 Cloud-Init 服务。由于 Cloud-Init 服务主要用于实现对 CVM 实例的初始化操作（例如，对 DNS，Hostname，IP 等信息的配置），以及执行一些用户在创建 CVM 实例时指定首次开机启动要执行的自定义脚本，因此需要以 root 用户运行 Cloud-Init 服务。
如何确认 Linux 实例内部的 Cloud-Init 服务是否正常运行？
Cloud-Init 服务运行排查方案
参见 使用标准登录方式登录 Linux 实例（推荐） 登录实例，并依次执行以下命令。观察是否报错，若显示执行结果则服务正常运行，否则会提示错误原因，请根据提示进行问题排查。
说明：
该步骤仅适用于使用 Linux 公共镜像创建的云服务器实例。若您自行安装了 Cloud-Init，请结合实际情况调整执行命令。
1. 删除 cloud-init 缓存目录。
rm -rf /var/lib/cloud
2. 执行完整的 cloud-init 初始化。
/usr/bin/cloud-init init --local
3. 根据配置的数据源拉取数据。
/usr/bin/cloud-init init
4. Cloud-Init 初始化分为多个 stage，为保证各个 stage 的依赖充分，cloud-init modules 指定运行 config stage。
/usr/bin/cloud-init modules --mode=config
5. cloud-init modules 指定运行 final stage。
/usr/bin/cloud-init modules --mode=final
Cloud-Init 执行了哪些实例初始化的操作？
腾讯云通过 Cloud-Init 实现了实例的所有初始化操作，使得整个实例内部的操作更加的透明。以下内容简单介绍了相关操作情况，更多详情可参见 Cloud-init 官方文档。
初始化类型
默认行为
禁用方式
注意事项
hostname 的初始化
实例首次启动时，Cloud-Init 会根据     vendor_data.json 中的 hostname 信息来设置实例的 hostname。
当您使用自定义镜像创建或重装实例时，如需保持自定义镜像内部自定义的 hostname    设置，则请在制作自定义镜像之前将 /etc/cloud/cloud.cfg 中的 preserve_hostname 设置为 true，并删除 - scripts-user 这行配置。    
若 preserve_hostname 为 true 且 - scripts-user 配置被禁用，则实例内部的     /var/lib/cloud/instance/scripts/runcmd初始化脚本将不会被执行，并会同时影响其他子项的初始化（主要涉及：云监控、云安全的安装、软件源的设置）。    
同时，在您创建子机时，自定义脚本也不会被执行。
/etc/hosts 的初始化
实例首次启动时，Cloud-Init 会默认将 /etc/hosts 初始化为     127.0.0.1 $hostname。
当您使用自定义镜像创建或重装实例时，您想保持自定义镜像内部自定义的 /etc/hosts    设置，可以在制作自定义镜像之前在     /etc/cloud/cloud.cfg 里面删除 - scripts-user 与 - ['update_etc_hosts', 'once-per-instance'] 这两行配置。
﻿
﻿
如果您禁用了 - scripts-user 这行配置，实例内部的  /var/lib/cloud/instance/scripts/runcmd初始化脚本将不会被执行，并会同时影响其他子项的初始化（主要涉及：云监控、云安全的安装、软件源的设置）。同时，在您创建子机时，自定义脚本也不会被执行。
每当子机重启时，部分存量机器  /etc/hosts 的设置都会被覆盖。解决方案请参见 如何有效的修改 Linux 实例的 etc hosts 配置。
﻿
﻿
DNS 的初始化（非 DHCP 场景）
实例首次启动时，Cloud-Init 会根据     vendor_data.json 中的 nameservers 信息来设置实例的 DNS。
当您使用自定义镜像创建或重装实例时，您想保持自定义镜像内部自定义的 DNS    设置，可以在制作自定义镜像之前在     /etc/cloud/cloud.cfg 里面删除 - resolv_conf 与 unverified_modules: ['resolv_conf'] 两行配置。
无。
软件源的初始化
实例首次启动时，Cloud-Init 会根据     vendor_data.json 中的 write_files 信息来设置实例的软件源。
当您使用自定义镜像创建或重装实例时，您想保持自定义镜像内部自定义的软件源设置，可以在制作自定义镜像之前在 /etc/cloud/cloud.cfg 里面删除 - write-files 这行配置。
无。
NTP 的初始化
实例首次启动时，Cloud-Init 会根据     vendor_data.json 中的 NTP Server 信息来设置实例的 NTP 服务器配置，并拉起 NTP Service。
当您使用自定义镜像创建或重装实例时，您想保持自定义镜像内部自定义的 NTP 设置，可以在制作自定义镜像之前在 /etc/cloud/cloud.cfg 里面删除 - ntp 这行配置。
无。
密码的初始化
实例首次启动时，Cloud-Init 会根据 vendor_data.json 中的 chpasswd 信息来设置实例的默认账号密码。
当您使用自定义镜像创建或重装实例时，您想保持自定义镜像内部自定义的默认账号密码，可以在制作自定义镜像之前在 /etc/cloud/cloud.cfg 里面删除 - set-passwords 这行配置。
无。
密钥绑定
实例首次启动时，Cloud-Init 会根据     vendor_data.json 中的 ssh_authorized_keys 信息来设置实例的默认账号密钥。
当您使用自定义镜像创建或重装实例时，您想保持自定义镜像内部自定义的密钥，可以在制作自定义镜像之前在 /etc/cloud/cloud.cfg 里面删除 - users-groups 这行配置。
如果您通过手工的方式在实例内部自行绑定密钥，在通过控制台下发密钥绑定的操作时，系统会将此密钥覆盖。
网络初始化（非 DHCP 场景）
实例首次启动时，Cloud-Init 会根据 network_data.json 中的信息来设置实例的 IP、GATEWAY、MASK 等。
当您使用自定义镜像创建或重装实例时，您想保持自定义镜像内部自定义的网络信息，可以在制作自定义镜像之前在 /etc/cloud/cloud.cfg 里面增加     network: {config: disabled} 这行配置。
无。
如何排查 Cloud-Init 常见问题？
因卸载 Cloud-Init 的依赖包导致报错
问题现象：
在使用命令确认 Cloud-Init 服务是否正常运行时，收到如下的错误：
Traceback (most recent call last):
File "/usr/bin/cloud-init", line 5, in 
  ********
  raise DistributionNotFound(req)
pkg_resources.DistributionNotFound: pyyaml
问题分析：
“pkg_resources.DistributionNotFound: xxxxx ” 表示 Cloud-Init 的安装依赖包被卸载。
解决方案：
1.1 重新安装该依赖包。
1.2 根据 Cloud-Init 服务运行排查方案 执行操作，直至全部执行完无错误为止。
修改默认 Python 解释器导致报错
问题现象：
在开机启动执行 Cloud-Init 时报错。
问题分析：
安装 Cloud-Init 时，Python 解释器默认使用 Python2（即 /usr/bin/python 与 /bin/python 这两个软链接指向 Python2）。当用户业务有需要时，可能会在实例内部把 Python 的默认解释器改为 Python3（即修改 /usr/bin/python 与 /bin/python 这两个软链接，使其指向 Python3）。由于兼容性问题，导致在开机启动执行 Cloud-Init 时报错。
解决方案：
1.1 以 Python2.7为例，修改 /usr/bin/cloud-init 文件中指定的 Python 解释器，将 #!/usr/bin/python 或 #!/bin/python 修改为 #!/usr/bin/python2.7。
注意：
不要使用软链接，直接指向具体的解释器。
1.2 根据 Cloud-Init 服务运行排查方案 执行操作，直至全部执行完无错误为止。
Linux 系统 Cloud-Init 组件管理指引
为什么无法升级 Cloud-Init？
在腾讯云 Linux 云服务器上，当您尝试更新 Cloud-Init 时可能会遇到无法正常升级的情况。例如：
在 Ubuntu 系统下，执行 apt upgrade 后 Cloud-Init 版本未更新。
在 CentOS 或 OpenCloud OS 系统下，执行 yum 或 dnf 进行升级提示“已安装的版本被锁定”或“已安装的版本来自已启用的特定仓库”。
根本原因：为确保实例初始化过程的高度可靠性与全面兼容性，腾讯云针对公共镜像中的 Cloud-Init 组件实施了版本锁定。该机制的核心目的是防止该核心组件被系统常规更新意外升级，从而避免因版本不匹配导致的实例初始化失败、网络配置错误或元数据服务不可用等问题。
锁定机制的具体实现：
基于 APT 的系统 (Ubuntu, Debian)：
通过 /etc/apt/preferences.d/ 目录下的配置文件（如 Cloud-Init）设置较高的“软件包优先级”（Pin-Priority，例如 900），使当前安装版本优先级最高，从而阻止自动升级。例如，在腾讯云 Ubuntu 22.04 镜像中，该锁定配置示例如下：
# 配置文件示例内容
Package: cloud-init
Pin: version 20.1.0011-1
Pin-Priority: 900
基于 YUM/DNF 的系统 (CentOS, OpenCloud OS, TencentOS 等)：
通常通过启用特定版本锁定的腾讯云定制仓库，或使用 yum versionlock 插件来实现。您可能会在仓库配置中看到相关标识，或通过 yum versionlock list 命令查看。
如何手动调整或升级？
腾讯云官方建议您不要手动升级公共镜像中的 Cloud-Init。腾讯云负责该组件在镜像层面的安全与兼容性更新，并通过发布新的公共镜像版本来提供包含修复的稳定版本。安全漏洞通常在镜像更新中统一修复。但是您可能存在以下必须升级 Cloud-Init 场景：
合规性需求：因安全扫描等合规要求必须处理，请 联系我们，获取针对特定漏洞的官方评估和解决方案，而非直接升级组件。
自定义需求：您的业务确实需要不同版本的 Cloud-Init，建议基于腾讯云公共镜像，在完成版本调整和充分测试后，自行制作并维护一个专属的、经过全面验证的自定义镜像，而非在生产实例上直接修改。
如您还需要手动升级 Cloud-Init，请参见以下注意事项及操作步骤。
警告：
升级或移除锁定可能导致服务初始化异常。在操作前，请务必根据您的实例类型评估风险，并创建 快照 备份。
实例/场景类型
升级风险等级
建议
云服务器 (CVM) 
中 
可能影响网络、主机名、用户数据注入。升级后务必重启测试。
裸金属实例 (BMS/CBSM)
极高 
强烈依赖定制驱动，升级极易导致无法启动。严禁在生产环境操作。
基于此镜像创建的自定义镜像 
高
升级后制作的新镜像可能存在兼容性问题，影响后续用此镜像创建的所有实例。
有自动伸缩组等自动化运维场景 
极高 
不统一的 Cloud-Init版本可能导致伸缩组实例启动状态不一致，引发运维故障。
操作步骤
注意：
软件仓库中的实际最新版本和当前锁定版本会随时间变化，以下命令中使用的版本号（例如20.1.0011-1, 25.2等）仅做示例。在开始任何操作前，请务必使用以下命令查询您实例中的实际情况，并以命令输出为准：
Ubuntu/Debian：apt policy cloud-init
CentOS/RHEL：yum list available cloud-init或 dnf list available cloud-init
基于 APT 的系统 (Ubuntu, Debian)
基于 YUM/DNF 的系统 (CentOS, OpenCloud OS, TencentOS 等)
1. 移除版本锁定，执行命令如下：
sudo rm -f /etc/apt/preferences.d/cloud-init*
2. 更新并升级 Cloud-Init。
sudo apt update 
# 使用以下命令升级，在配置文件冲突时尽量保持当前配置
sudo apt install -o Dpkg::Options::="--force-confdef" -o Dpkg::Options::="--force-confold" --only-upgrade cloud-init
1. 检查锁定状态。
# 检查是否有版本锁定
sudo yum versionlock list | grep cloud-init 
# 或检查已启用的仓库，关注是否有腾讯云特定版本仓库
sudo yum repolist
2. 移除锁定并升级 Cloud-Init。
如果被 versionlock 锁定，请先删除锁定：
sudo yum versionlock delete cloud-init
如果锁定来自特定仓库配置，请谨慎禁用该特定仓库（通常通过修改 /etc/yum.repos.d/ 下对应 .repo 文件的 enabled=0），然后启用标准仓库。
sudo yum update cloud-init
# 或
sudo dnf update cloud-init
常见问题
如果升级 Cloud-Init 后实例出现启动异常、网络不通或元数据获取失败，请参见以下方案进行版本回退。
1. 登录 云服务器控制台，进入救援模式。详情请参见 使用救援模式。
2. 根据不同操作系统，请参见以下方案进行版本回退。
基于 APT 的系统（Ubuntu, Debian）：在救援模式中，重新创建锁定文件，并降级安装。版本号需与原始版本一致（可从同类新购实例获取）。
echo -e "Package: cloud-init\\nPin: version 20.1.0011-1\\nPin-Priority: 900" | tee /mnt/etc/apt/preferences.d/cloud-init
chroot /mnt apt update 
chroot /mnt apt install cloud-init=20.1.0011-1
基于 YUM/DNF 的系统（CentOS, OpenCloud OS, TencentOS 等）：在救援模式中，重新启用腾讯云特定版本仓库，或重新添加版本锁定，然后降级安装。
说明：
如果使用以上方案无法快速修复，请使用操作前创建的快照回滚磁盘，或利用该快照创建新实例恢复服务，详情请参见 从快照回滚数据。
Cloudbase-Init
什么是 Cloudbase-Init？
与 Cloud-Init 相似，Cloudbase-Init 是与 Windows 云服务器实例通信的桥梁。 在实例首次启动的时候会执行 Cloudbase-Init 服务，该服务会读取出实例的初始化配置信息，并对实例进行初始化操作。同时包括后续的重置密码、修改 IP 等功能也都是通过 Cloudbase-Init 来实现的。
如何确认 Windows 实例内部的 Cloudbase-Init 服务是否正常运行？
Cloudbase-Init 服务运行排查方案
1. 登录实例。
说明：
若您忘记密码或因为 Cloudbase-Init 服务异常重置密码失败，可通过 步骤 2 进行密码重置。 
2. ﻿打开
控制面板，搜索并找到服务。
3. 找到 cloudbase-init 服务，并右键单击属性，打开 cloudbase-init 的属性窗口。
查看启动类型，确保启动类型为自动。如下图所示：
﻿
﻿
查看登录身份，确保登录身份为本地系统账户。如下图所示：
﻿
﻿
手动启动 cloudbase-init 服务并观察是否有相关报错。
如果有报错需要优先解决，并请确认是否安装相关安全软件拦截 cloudbase-init 执行的相关操作。 
﻿
﻿
打开注册表搜索并找到全部的 LocalScriptsPlugin，确保其值为2。如下图所示：
﻿
﻿
确认 CD-ROM 的加载是否被禁用。如下图所示，可以看到一个光驱设备，则表示正常加载；否则是被禁用了，需要取消禁用。
﻿
﻿
Cloudbase-Init  执行了哪些实例初始化的操作？
腾讯云通过 Cloudbase-Init 实现了实例的初始化操作，使得整个实例内部的操作更加透明。以下内容简单介绍了相关操作情况，更多详情可参见 Cloudbase-init 官方文档。
初始化类型
默认行为
禁用方式
注意事项
hostname 的初始化
实例首次启动时， Cloudbase-Init 根据元数据服务或用户数据设置主机名。
在cloudbase-init.conf中设置set_hostname为 false。   
主机名必须符合RFC 952规范。
配置网络
实例首次启动时， Cloudbase-Init 根据元数据服务或用户数据配置虚拟机的网络设置。
在cloudbase-init.conf中设置network_adapter为 none。
确保提供的网络配置是正确的。
﻿
生成新的 SSH 密钥对（仅适用于支持 SSH 的 Windows 系统）
实例首次启动时， Cloudbase-Init 生成新的 SSH 密钥对，并将公钥添加到用户数据中。
在cloudbase-init.conf中设置generate_ssh_keys为 false。
禁用此功能后，需要手动设置 SSH 密钥对。
设置用户密码
实例首次启动时， Cloudbase-Init 为新创建的用户账户设置一个随机密码。
在cloudbase-init.conf中删除 plugins 配置中的cloudbaseinit.plugins.common.setuserpassword.SetUserPasswordPlugin。
禁用此功能后，需要手动设置用户密码。
执行用户数据脚本
执行用户数据中包含的脚本。
在cloudbase-init.conf中删除 plugins 配置中的cloudbaseinit.plugins.common.userdata.UserDataPlugin。
用户数据脚本应该是可执行的，并且不应包含任何可能破坏虚拟机的操作。
如何查看 Cloudbase-Init 执行日志？
您可对应操作系统，查看以下日志文件：
Linux 系统：/var/log/cloud-init-output.log
Windows 系统：C:\\Program Files\\Cloudbase Solutions\\Cloudbase-Init\\log\\cloudbase-init.log
如何排查 Cloudbase-Init 常见问题？
初始化重置密码失败
可能原因：
手动修改 cloudbase-init 账号密码导致 cloudbase-init 服务启动失败，从而使得初始化重置密码等操作失败。
禁用了 cloudbase-init 服务，从而使得初始化重置密码等操作失败。
安装安全软件拦截了 cloudbase-init 服务重置密码的操作，从而使得重置密码流程返回成功但实际重置失败。
解决方案：
请针对可能原因，分别参考以下三点进行操作。
将 cloudbase-init 服务改为 LocalSystem 服务，具体操作方式请参见 Cloudbase-Init 服务运行排查方案 的 步骤 2。 
将 cloudbase-init 服务启动类型改为自动。 具体操作方式请参见 Cloudbase-Init 服务运行排查方案 的 步骤 2。
卸载对应的安全软件， 或在安全软件里面对 cloudbase-init 服务的相关操作加白名单。
﻿

Cloud-Init 和 Cloudbase-Init 问题

本页目录：

Cloud-Init

什么是 Cloud-Init？

如何确认 Linux 实例内部的 Cloud-Init 服务是否正常运行？

Cloud-Init 服务运行排查方案

Cloud-Init 执行了哪些实例初始化的操作？

如何排查 Cloud-Init 常见问题？

因卸载 Cloud-Init 的依赖包导致报错

修改默认 Python 解释器导致报错

Linux 系统 Cloud-Init 组件管理指引

为什么无法升级 Cloud-Init？

如何手动调整或升级？

操作步骤

常见问题

Cloudbase-Init

什么是 Cloudbase-Init？

如何确认 Windows 实例内部的 Cloudbase-Init 服务是否正常运行？

Cloudbase-Init 服务运行排查方案

Cloudbase-Init 执行了哪些实例初始化的操作？

如何查看 Cloudbase-Init 执行日志？

如何排查 Cloudbase-Init 常见问题？

初始化重置密码失败

初始化类型	默认行为	禁用方式	注意事项
hostname 的初始化	实例首次启动时，Cloud-Init 会根据 `vendor_data.json` 中的 hostname 信息来设置实例的 hostname。	当您使用自定义镜像创建或重装实例时，如需保持自定义镜像内部自定义的 hostname 设置，则请在制作自定义镜像之前将 `/etc/cloud/cloud.cfg` 中的 `preserve_hostname` 设置为 `true`，并删除 `- scripts-user` 这行配置。	若 `preserve_hostname` 为 `true` 且 `- scripts-user` 配置被禁用，则实例内部的 `/var/lib/cloud/instance/scripts/runcmd`初始化脚本将不会被执行，并会同时影响其他子项的初始化（主要涉及：云监控、云安全的安装、软件源的设置）。同时，在您创建子机时，自定义脚本也不会被执行。
/etc/hosts 的初始化	实例首次启动时，Cloud-Init 会默认将 `/etc/hosts` 初始化为 `127.0.0.1 $hostname`。	当您使用自定义镜像创建或重装实例时，您想保持自定义镜像内部自定义的 /etc/hosts 设置，可以在制作自定义镜像之前在 `/etc/cloud/cloud.cfg` 里面删除 `- scripts-user` 与 `- ['update_etc_hosts', 'once-per-instance']` 这两行配置。	如果您禁用了 `- scripts-user` 这行配置，实例内部的 `/var/lib/cloud/instance/scripts/runcmd`初始化脚本将不会被执行，并会同时影响其他子项的初始化（主要涉及：云监控、云安全的安装、软件源的设置）。同时，在您创建子机时，自定义脚本也不会被执行。每当子机重启时，部分存量机器 `/etc/hosts` 的设置都会被覆盖。解决方案请参见如何有效的修改 Linux 实例的 etc hosts 配置。
DNS 的初始化（非 DHCP 场景）	实例首次启动时，Cloud-Init 会根据 `vendor_data.json` 中的 nameservers 信息来设置实例的 DNS。	当您使用自定义镜像创建或重装实例时，您想保持自定义镜像内部自定义的 DNS 设置，可以在制作自定义镜像之前在 `/etc/cloud/cloud.cfg` 里面删除 `- resolv_conf` 与 `unverified_modules: ['resolv_conf']` 两行配置。	无。
软件源的初始化	实例首次启动时，Cloud-Init 会根据 `vendor_data.json` 中的 write_files 信息来设置实例的软件源。	当您使用自定义镜像创建或重装实例时，您想保持自定义镜像内部自定义的软件源设置，可以在制作自定义镜像之前在 `/etc/cloud/cloud.cfg` 里面删除 `- write-files` 这行配置。	无。
NTP 的初始化	实例首次启动时，Cloud-Init 会根据 `vendor_data.json` 中的 NTP Server 信息来设置实例的 NTP 服务器配置，并拉起 NTP Service。	当您使用自定义镜像创建或重装实例时，您想保持自定义镜像内部自定义的 NTP 设置，可以在制作自定义镜像之前在 `/etc/cloud/cloud.cfg` 里面删除 `- ntp` 这行配置。	无。
密码的初始化	实例首次启动时，Cloud-Init 会根据 `vendor_data.json` 中的 chpasswd 信息来设置实例的默认账号密码。	当您使用自定义镜像创建或重装实例时，您想保持自定义镜像内部自定义的默认账号密码，可以在制作自定义镜像之前在 `/etc/cloud/cloud.cfg` 里面删除 `- set-passwords` 这行配置。	无。
密钥绑定	实例首次启动时，Cloud-Init 会根据 `vendor_data.json` 中的 ssh_authorized_keys 信息来设置实例的默认账号密钥。	当您使用自定义镜像创建或重装实例时，您想保持自定义镜像内部自定义的密钥，可以在制作自定义镜像之前在 `/etc/cloud/cloud.cfg` 里面删除 `- users-groups` 这行配置。	如果您通过手工的方式在实例内部自行绑定密钥，在通过控制台下发密钥绑定的操作时，系统会将此密钥覆盖。
网络初始化（非 DHCP 场景）	实例首次启动时，Cloud-Init 会根据 `network_data.json` 中的信息来设置实例的 IP、GATEWAY、MASK 等。	当您使用自定义镜像创建或重装实例时，您想保持自定义镜像内部自定义的网络信息，可以在制作自定义镜像之前在 `/etc/cloud/cloud.cfg` 里面增加 `network: {config: disabled}` 这行配置。	无。

实例/场景类型	升级风险等级	建议
云服务器 (CVM)	中	可能影响网络、主机名、用户数据注入。升级后务必重启测试。
裸金属实例 (BMS/CBSM)	极高	强烈依赖定制驱动，升级极易导致无法启动。严禁在生产环境操作。
基于此镜像创建的自定义镜像	高	升级后制作的新镜像可能存在兼容性问题，影响后续用此镜像创建的所有实例。
有自动伸缩组等自动化运维场景	极高	不统一的 Cloud-Init版本可能导致伸缩组实例启动状态不一致，引发运维故障。