Ubuntu的cloud-init初始化配置未生效,如何检查数据源与运行日志
在已有 Ubuntu 云主机或模板环境中调整 cloud-init 后,如果 hostname、用户、SSH 密钥、软件包或启动脚本没有按预期生效,先不要直接删除 /var/lib/cloud 或反复重启。应先确认本次启动识别到的数据源,再检查实际接收到的 user-data、cloud-init 服务阶段和对应日志,最后判断是“没有拿到配置”“配置解析失败”还是“模块已执行但目标状态被后续服务覆盖”。

cloud-init 的初始化内容通常只在特定阶段、特定频率下执行一次。cloud-init status 显示完成,并不等于每一项配置都成功;数据源识别成功,也不代表云平台一定传入了 user-data。因此,排错时要把数据源、输入文件、执行日志和最终系统状态分别验证。
现状与条件:先确定实例当前处于什么状态
记录 Ubuntu、cloud-init 和启动状态
先在故障实例上保留基础信息。以下命令只读系统状态,不会重新执行初始化模块:
lsb_release -ds
uname -a
cloud-init --version
dpkg-query -W -f='${Package} ${Version}\n' cloud-init
sudo cloud-init status --long
重点关注以下结果:
status: done:cloud-init 的主要阶段已经结束,但仍需继续检查模块是否报错或跳过。status: running:初始化仍在执行,先查看实时日志,不要重复启动 cloud-init。status: error或degraded:通常可以在日志中找到失败模块、数据源访问失败或配置解析错误。- 找不到
cloud-init命令:可能是镜像未安装该软件包,也可能是当前系统使用了其他初始化机制,此时不能按 cloud-init 的路径继续判断。
Ubuntu 上常见的阶段服务包括:
for unit in cloud-init-local.service cloud-init.service cloud-config.service cloud-final.service; do
systemctl --no-pager --full status "$unit" || true
done
cloud-init-local.service 通常负责本地早期初始化和数据源的初步识别,cloud-init.service 与网络和实例信息有关,cloud-config.service 执行配置模块,cloud-final.service 通常处理用户脚本、软件包安装和收尾动作。具体阶段会随 Ubuntu 和 cloud-init 包版本变化,因此以当前系统中的 systemd 单元和日志为准。
识别实际使用的数据源
数据源是 cloud-init 获取实例元数据和用户配置的入口。常见来源包括:
- 云平台提供的实例元数据服务;
- NoCloud 本地目录或远程 seed URL;
- ConfigDrive 或类似的配置介质;
- 虚拟化环境挂载的配置盘。
先执行:

sudo cloud-id
sudo cloud-init query --all | sed -n '1,160p'
readlink -f /var/lib/cloud/instance
sudo find /var/lib/cloud/seed -maxdepth 3 -type f -print 2>/dev/null
cloud-id 能返回具体数据源名称时,说明 cloud-init 至少完成了数据源识别。cloud-init query --all 可以查看已缓存的实例信息;其中可能包含实例 ID、主机名、网络信息等敏感内容,不要直接发布到工单、论坛或公共日志中。
/var/lib/cloud/instance 通常是指向当前实例目录的软链接。该目录中经常可以看到以下文件:
/var/lib/cloud/instance/
/var/lib/cloud/instance/user-data.txt
/var/lib/cloud/instance/vendor-data.txt
/var/lib/cloud/instance/obj.pkl
/var/lib/cloud/instance/sem/
/var/lib/cloud/instance/boot-finished
不同发行版包版本和数据源可能存在文件差异,文件不存在本身不一定表示失败,但 user-data.txt、实例 ID 和执行标记对判断输入是否到达很有帮助。
日常操作:从数据源、输入文件到执行日志逐层检查
检查数据源配置是否被本地文件限制
查看 Ubuntu 当前的 cloud-init 配置和 drop-in 文件:
sudo grep -RnsE '^[[:space:]]*(datasource_list|datasource):' \
/etc/cloud/cloud.cfg /etc/cloud/cloud.cfg.d/ 2>/dev/null
sudo find /etc/cloud/cloud.cfg.d -maxdepth 1 -type f -name '*.cfg' \
-printf '%f\n' | sort
如果配置中存在类似内容:
datasource_list: [ NoCloud, ConfigDrive, None ]
表示 cloud-init 只会按指定范围尝试数据源。将列表限制为某一种数据源后,实例迁移到其他平台、模板复制到不同虚拟化环境,或者云平台更换配置介质,都可能导致初始化内容不再生效。
某些环境还会使用如下形式指定 NoCloud:
datasource:
NoCloud:
seedfrom: file:///var/lib/cloud/seed/nocloud/
或:
datasource:
NoCloud:
seedfrom: http://192.0.2.10/cloud-seed/
检查本地 seed 文件时,可以执行:
sudo find /var/lib/cloud/seed -maxdepth 3 -type f -exec sh -c '
for f do
printf "%s: " "$f"
stat -c "%s bytes, mode=%a" "$f"
done
' sh {} +
NoCloud 配置通常至少需要 meta-data 和 user-data。meta-data 中一般需要有稳定的 instance-id,例如:
instance-id: ubuntu-example-001
local-hostname: ubuntu-example
远程 seed URL 还需要在 cloud-init 所处的启动阶段可访问。系统启动后手工执行 curl 能访问,并不能证明早期初始化阶段也具备同样的 DNS、路由和认证条件。
检查 cloud-init 实际收到的 user-data
不要只检查准备发送给云平台的原始文件,应优先查看实例缓存的实际输入:
sudo ls -l /var/lib/cloud/instance/
sudo sed -n '1,220p' /var/lib/cloud/instance/user-data.txt 2>/dev/null
sudo sed -n '1,160p' /var/lib/cloud/instance/vendor-data.txt 2>/dev/null
配置文件通常需要以 cloud-config 头部开始:

#cloud-config
hostname: app-01
manage_etc_hosts: true
packages:
- nginx
write_files:
- path: /etc/example.conf
permissions: '0644'
content: |
enabled=true
runcmd:
- [ sh, -c, 'systemctl enable --now nginx' ]
常见输入问题包括:
- 文件没有
#cloud-config、#cloud-boothook等有效头部; - YAML 使用 Tab 缩进;
- 冒号、引号、列表缩进不正确;
runcmd中将 shell 语法误写成普通列表;- 云平台控制台的 user-data 字段被再次编码,实例收到的是编码后的文本;
- 配置只放在本地电脑或模板构建目录中,实际创建实例时没有传入;
- user-data 通过远程 URL 提供,但启动阶段 DNS、路由、证书或访问控制尚未准备好。
可以使用当前系统提供的 schema 检查工具:
sudo cloud-init devel schema \
--config-file /var/lib/cloud/instance/user-data.txt
部分 Ubuntu 版本的子命令参数会有差异,若提示命令不存在,先查看:
cloud-init devel --help
cloud-init --help
schema 校验通过只能说明结构基本符合 cloud-config 规范,不能证明软件包仓库可用、命令存在、目标目录可写,或数据源在下一次启动时仍能访问。
检查配置文件的覆盖和格式问题
修改 /etc/cloud/cloud.cfg 或 /etc/cloud/cloud.cfg.d/ 前,先备份当前配置。配置文件可能包含代理地址、凭据或内部服务地址,应限制备份目录权限:
stamp=$(date +%Y%m%d-%H%M%S)
backup_dir="/root/cloud-init-check-${stamp}"
sudo install -d -m 0700 "$backup_dir"
sudo cp -a /etc/cloud "$backup_dir/"
sudo find /etc/cloud -maxdepth 2 -type f -printf '%p\n' | sort
然后检查自定义文件:
sudo find /etc/cloud/cloud.cfg.d -maxdepth 1 -type f -name '*.cfg' \
-print -exec sed -n '1,220p' {} \;
重点关注以下情况:
- 同一个 YAML 键在多个文件中重复定义;
- 自定义
datasource_list排除了当前平台的数据源; cloud_final_modules、cloud_config_modules被整体覆盖,导致某些模块不再执行;- 文件扩展名不是
.cfg,或者文件权限、内容格式不符合 cloud-init 读取要求; - 修改的是镜像构建目录,而不是当前运行实例的
/etc/cloud/。
不建议为了验证配置而直接替换完整的 /etc/cloud/cloud.cfg。这类文件决定模块执行顺序,覆盖整段列表可能让用户管理、SSH、软件包或脚本模块一起消失。日常调整应优先新增一个内容范围明确的 drop-in 文件,并在变更记录中保留原文件和回滚方式。
结果检查:确认数据源、模块和目标状态分别成功
查看完整日志和服务日志
cloud-init 最有价值的两个日志文件通常是:
/var/log/cloud-init.log
/var/log/cloud-init-output.log
检查最近一次启动中的关键记录:
sudo grep -nEi \
'DataSource|datasource|Running module|Finished module|Skipping module|WARNING|ERROR|Traceback|Failed' \
/var/log/cloud-init.log /var/log/cloud-init-output.log 2>/dev/null
同时查看 systemd 日志:
sudo journalctl -b \
-u cloud-init-local.service \
-u cloud-init.service \
-u cloud-config.service \
-u cloud-final.service \
--no-pager
两个文件的用途有所不同:
| 检查位置 | 主要内容 | 适合判断的问题 |
|---|---|---|
/var/log/cloud-init.log | 数据源识别、模块加载、配置解析和模块执行 | 数据源是否找到、哪个模块失败或被跳过 |
/var/log/cloud-init-output.log | user-data 脚本和部分命令的标准输出、错误输出 | runcmd、包安装、脚本命令本身是否报错 |
journalctl -b -u cloud-init* | systemd 对各阶段服务的启动、退出和超时记录 | 阶段是否启动、服务是否失败或等待过久 |
/var/lib/cloud/instance/sem/ | 模块执行标记 | 一次性模块是否已经执行过 |
/var/lib/cloud/instance/boot-finished | 初始化完成标记 | 当前实例是否完成过 cloud-final 阶段 |
还可以使用 cloud-init 自带的执行分析:
sudo cloud-init analyze show
sudo cloud-init analyze blame
blame 可以帮助发现耗时较长的模块,例如软件包更新、远程 URL 访问或自定义脚本。耗时较长不一定是失败,但如果某阶段在启动期间持续等待网络或仓库,就要结合日志中的超时信息判断。
结合最终系统状态验证
配置是否生效,不能只看“服务执行成功”。应逐项验证目标状态:
hostnamectl
getent passwd appuser
sudo stat /etc/example.conf
sudo systemctl is-enabled nginx
sudo systemctl is-active nginx
sudo ss -lntp
如果目标是网络配置,需要根据当前网络栈分别检查:
networkctl status
ip address
ip route
resolvectl status
使用 NetworkManager 的系统则应额外检查:
nmcli general status
nmcli connection show
如果目标是创建用户,检查 getent passwd、用户组、SSH 目录权限和实际登录方式;如果目标是写入文件,检查路径、属主、权限、文件内容和修改时间;如果目标是执行服务,分别检查 enable 状态、active 状态和服务自身日志。
例如,cloud-init 日志显示 cc_write_files 成功,但目标文件不存在,可能是后续配置管理工具删除了文件,也可能是检查了错误的路径。日志成功和最终状态不一致时,应继续检查 systemd、配置管理客户端、启动脚本和定时任务,而不是立即重跑 cloud-init。
异常处理:根据结果选择低风险修复方式
看到 DataSourceNone 或 No datasource found
这类结果表示 cloud-init 没有找到可用数据源。先检查:
/etc/cloud/cloud.cfg.d/是否限制了datasource_list;- NoCloud 或 ConfigDrive 文件是否挂载、路径是否正确;
- 云平台实例是否实际启用了元数据服务或配置盘;
- 早期启动阶段是否有网络、DNS、路由或访问控制问题;
- 模板复制后是否保留了不适用于新平台的旧数据源设置。
如果是平台侧元数据服务不可用,应先修复实例创建参数、配置盘挂载或云平台权限。不要仅在系统内添加一个猜测的元数据地址,因为不同云平台的数据源协议、认证方式和启动时机并不通用。
数据源已识别,但 user-data 为空或内容不是预期配置
此时重点转向实例创建流程。检查云平台控制台、API 请求或模板生成程序中传入的字段名称、编码方式和内容类型。对于 NoCloud,确认 user-data 文件位于实际使用的 seed 目录中,并确认文件不是空文件。
如果当前实例已经完成首次初始化,仅修改云平台上的 user-data 通常不会让它自动重新执行。许多模块的频率是 once-per-instance,实例 ID 不变时,重新启动只会跳过这些模块。
日志出现 YAML 或 cloud-config 解析错误
常见表现包括 Invalid cloud-config、YAML、mapping values、found character 或 Traceback。先修复实际缓存文件或生成源文件中的格式,再使用 schema 命令验证。
检查时尤其注意:
sudo sed -n '1,220l' /var/lib/cloud/instance/user-data.txt
该命令会显示行尾和不可见字符,适合发现 Tab、回车符或异常空格。修复后不要直接删除实例状态。生产实例可以使用针对单个配置目标的人工变更完成恢复;需要验证首次启动行为时,应在克隆或临时实例中重新测试。
日志显示模块被跳过
如果日志出现 Skipping module,或在 sem/ 目录中看到对应模块标记,通常表示该模块已经按一次性频率执行过。此时需要先判断模块是否具有幂等性:
- 写入固定配置文件的模块,可能可以在备份后针对性重跑;
- 创建用户、修改 SSH 密钥、安装软件包的模块,重复执行可能改变权限或覆盖现有状态;
- 启动脚本、磁盘分区、网络和主机名相关操作,重复执行的影响范围更大。
可以在明确了解模块行为后,使用单模块方式验证。以下命令仅作为受控示例,不代表所有模块都适合重跑:
sudo cloud-init single --name cc_write_files --frequency always
执行前应确认目标文件已有备份、当前没有并发配置管理任务,并在日志中观察本次命令产生的结果。不要把单模块执行扩展成完整的 cloud-init init 或 cloud-init modules,后者可能重新触发更多初始化动作。
user-data 已执行,但其中命令失败
从 /var/log/cloud-init-output.log 和 journalctl 中定位具体命令,再单独验证:
- 软件包仓库是否可访问;
- 命令是否已经安装;
- 目标目录是否存在;
- 脚本使用的环境变量、工作目录和 PATH 是否正确;
- shell 命令的退出码是否被忽略;
- 依赖的磁盘、挂载点或网络服务是否在执行时已经准备好。
cloud-init 通常以 root 身份运行,手工以普通用户测试命令时,权限和环境并不完全相同。可以先用 sudo 复现单条命令,但不要为了“让脚本通过”而长期使用过宽权限。
必要恢复:配置变更和重新初始化的影响边界
回滚本地配置修改
如果问题由最近新增的 drop-in 文件引起,可以先恢复备份或移走该文件,而不是删除整个 cloud-init 状态目录。示例:
sudo mv /etc/cloud/cloud.cfg.d/99-custom.cfg \
/etc/cloud/cloud.cfg.d/99-custom.cfg.disabled
这会影响后续 cloud-init 读取配置,但不会自动撤销已经写入的 hostname、用户、文件或软件包。对已经发生的系统变更,需要根据具体对象单独恢复,例如还原配置文件、禁用新建服务或删除不再需要的用户;涉及删除和权限变更时,应先备份并确认影响范围。
生产实例不要直接清理 cloud-init 状态
以下操作会使 cloud-init 在下一次启动时重新判断实例,并可能再次执行创建用户、写入文件、安装软件包、执行脚本或调整网络等动作:
sudo cloud-init clean --logs --seed
sudo reboot
该命令只应在临时实例、可回滚快照或明确的维护窗口中使用。不同 Ubuntu 版本支持的参数可能不同,执行前先查看:
cloud-init clean --help
在生产环境中,如果只是配置文件改错,通常优先采用以下恢复顺序:

- 备份并回滚最近修改的
/etc/cloud/配置; - 修复已经被 cloud-init 写入的具体目标文件或服务;
- 使用单模块方式处理明确、可控且幂等的目标;
- 通过配置管理系统或常规运维流程完成后续修复;
- 只有在实例可重建、快照可恢复且明确接受重复初始化风险时,才测试完整清理和重启。
模板克隆场景还要额外核对实例 ID。如果新实例沿用了旧模板的 /var/lib/cloud/instance 状态,cloud-init 可能把它识别为已经初始化过的实例。此类问题应在模板制作阶段清理缓存,并在临时副本中验证首次启动流程,而不是在承载业务的实例上直接删除状态目录。
对于依赖 cloud-init 完成实例初始化的网站、业务后台和数据库,底层服务器的计算、存储与网络资源也是部署环境的一部分。A5数据提供中国香港、美国、日本、韩国、中国台湾、新加坡和马来西亚等地区的物理服务器,覆盖常规建站、AMD计算、存储及不同带宽线路需求;部分配置采用大内存与NVMe存储,可承载多类业务服务及数据工作负载。
上线或验收检查清单
- [ ] 已确认 Ubuntu 版本、cloud-init 包版本和四个主要 systemd 阶段的状态。
- [ ]
cloud-id返回了预期数据源,且没有出现DataSourceNone或数据源探测超时。 - [ ] 已检查
/etc/cloud/cloud.cfg与/etc/cloud/cloud.cfg.d/,确认没有错误限制datasource_list。 - [ ] 已确认 NoCloud、ConfigDrive 或云平台元数据入口在 cloud-init 所处启动阶段可访问。
- [ ] 已查看
/var/lib/cloud/instance/user-data.txt,确认实例实际收到的内容与预期一致。 - [ ] user-data 通过了 schema 或等效的 YAML 格式检查,没有 Tab、错误缩进和编码问题。
- [ ]
/var/log/cloud-init.log中没有数据源、模块或配置解析错误。 - [ ]
/var/log/cloud-init-output.log中的脚本、软件包和服务命令没有未处理的失败。 - [ ] 已确认一次性模块没有因旧实例 ID或
sem/标记而被误跳过。 - [ ] 主机名、用户、文件、网络、服务等目标状态已逐项通过命令验证。
- [ ] 修改
/etc/cloud/前已完成备份,并记录了回滚文件和影响范围。 - [ ] 未在生产实例上直接执行
cloud-init clean;如必须重跑,已完成快照、维护窗口和恢复方案确认。 - [ ] 修复后已在当前启动日志和最终系统状态中再次验证,而不是只依据
cloud-init status: done判断成功。
本文由A5数据原创发布,转载请注明出处:https://www.a5idc.com/helpcontent/5756.html



