Cloud-Init 初始化成功需满足三前提:系统已安装并启用 cloud-init 服务、user-data 文件符合 #cloud-config YAML 规范、平台正确注入数据;验证用 sudo cloud-init status --long,调试查日志、/var/lib/cloud/instances/ 和 /var/log/cloud-init-output.log。

Cloud-Init 在 Linux 启动时自动初始化,核心不是“写脚本”,而是按规范组织 user-data 并确保系统已安装且启用 cloud-init 服务。
确认 cloud-init 是否已就绪并处于 active 状态
很多问题其实卡在第一步:系统根本没跑起 cloud-init。它不是默认所有 Linux 都启用的,尤其非云环境(如本地 VirtualBox、Proxmox 或裸机装的 Ubuntu/Debian)容易漏掉这步。
执行以下命令验证:
sudo cloud-init status --long
若报错 Command 'cloud-init' not found,先装包:
- Ubuntu/Debian:
sudo apt install cloud-init - CentOS/RHEL 8+:
sudo dnf install cloud-init - Alpine:
apk add cloud-init
装完必须启用服务并重启才能生效:
sudo systemctl enable cloud-initsudo systemctl reboot
注意:cloud-init 依赖 systemd-networkd 或 NetworkManager,若你禁用了这些网络管理器,cloud-init 的网络配置阶段会失败或跳过。
编写合法的 user-data 文件(YAML 格式最常用)
Cloud-Init 不解析任意 shell 脚本——它只认特定格式的 user-data,开头必须是 #cloud-config,且 YAML 缩进严格(用空格,不能用 Tab)。
常见错误现象:Invalid yaml format 或 No user data provided,往往因为:
- 文件保存为 Windows 换行(CRLF),改用 LF;
- 缩进混用空格与 Tab;
- 漏了
#cloud-config行,或写成#!/bin/bash(那是x-shellscript类型,需额外声明 MIME type); - 在 OpenStack / Proxmox 中上传时未勾选 “Use as cloud-init user data” 类选项。
一个最小可用示例(设置主机名、创建用户、写入文件):
#cloud-config
hostname: web01
users:
- name: deploy
sudo: ALL=(ALL) NOPASSWD:ALL
ssh_authorized_keys:
- ssh-rsa AAAAB3NzaC1yc2E... user@host
write_files:
- path: /etc/motd
content: |-
Welcome to cloud-init managed instance.
owner: root:root
permissions: '0644'
区分不同平台的注入方式(AWS/Azure/OpenStack/Proxmox/LXC)
同一份 user-data 文件,在不同平台加载路径和限制完全不同:
- AWS EC2:通过 Launch Template 或 CLI 的
--user-data参数传入,内容需 base64 编码(CLI 自动处理); - Azure:用
az vm create --custom-data,支持直接传文件路径; - OpenStack:上传镜像时指定
--property os-cloud-init=enabled,再通过openstack server create --user-data注入; - Proxmox VE:在 Web UI 创建 VM 时,“Options → Cloud-Init” 下勾选启用,并粘贴到
User data文本框; - LXC 容器(如 Ubuntu Core):需配合
lxc launch ubuntu:22.04 myapp --config=user.user-data="$(cat user-data)"。
关键差异点:
- AWS 不支持
write_files写入/root下文件(权限受限),但可写/tmp或用runcmd执行命令绕过; - Azure 对
user-data大小限制为 64KB,超限会静默截断; - Proxmox 默认只挂载
config-drive,若未勾选 “Use config drive”,cloud-init将完全收不到数据。
调试失败时查哪几个日志和状态点
初始化失败不报错、不提示、不重试——这是 cloud-init 最让人头疼的地方。别猜,直接看三处输出:
-
sudo cloud-init status --long:看各模块(init, modules:config, modules:final)是否 success 或 error; -
sudo journalctl -u cloud-init* -n 100 --no-pager:重点扫DataSource(是否识别到数据源)、Running module、Failed关键词; -
ls -l /var/lib/cloud/instances/:若目录为空,说明 cloud-init 根本没读到任何 user-data(平台注入失败或 DataSource 不匹配); -
cat /var/log/cloud-init-output.log:包含所有模块 stdout/stderr 输出,比如runcmd中命令的真实报错。
一个典型坑:你在 Proxmox 里改了 VM 配置加了 user-data,但没关机就“重置”启动——cloud-init 会跳过初始化(认为是已有实例),必须彻底关机再开机,或手动清空 /var/lib/cloud/instances/ 并运行 sudo cloud-init clean && sudo cloud-init init 强制重跑。











