Ubuntu的cloud-init初始化配置未生效,如何检查数据源与运行日志

发布人:A5数据发布时间:2026-10-25 15:45阅读量:205

在已有 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.loguser-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 没有找到可用数据源。先检查:

  1. /etc/cloud/cloud.cfg.d/ 是否限制了 datasource_list;
  2. NoCloud 或 ConfigDrive 文件是否挂载、路径是否正确;
  3. 云平台实例是否实际启用了元数据服务或配置盘;
  4. 早期启动阶段是否有网络、DNS、路由或访问控制问题;
  5. 模板复制后是否保留了不适用于新平台的旧数据源设置。

如果是平台侧元数据服务不可用,应先修复实例创建参数、配置盘挂载或云平台权限。不要仅在系统内添加一个猜测的元数据地址,因为不同云平台的数据源协议、认证方式和启动时机并不通用。

数据源已识别,但 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

在生产环境中,如果只是配置文件改错,通常优先采用以下恢复顺序:

必要恢复:配置变更和重新初始化的影响边界配图

  1. 备份并回滚最近修改的 /etc/cloud/ 配置;
  2. 修复已经被 cloud-init 写入的具体目标文件或服务;
  3. 使用单模块方式处理明确、可控且幂等的目标;
  4. 通过配置管理系统或常规运维流程完成后续修复;
  5. 只有在实例可重建、快照可恢复且明确接受重复初始化风险时,才测试完整清理和重启。

模板克隆场景还要额外核对实例 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

相关推荐